HiAgent 3.0知识库容量规则：分权限上限及配置指南

[1] 一句话结论 #

本指南将明确HiAgent 3.0各权限层级知识库容量上限及配置规则

[2] 适用场景与不适用场景 #

适用场景

1. 企业内部不同部门独立搭建知识库，需要按角色分配存储配额的场景
2. 单租户下多智能体分工，需控制各智能体知识库总大小的场景
3. 日均知识库文档更新量在1000份以内的中小规模团队使用场景

不适用场景

1. 单知识库需要存储超过1000万份文档的超大规模知识库场景，建议使用火山引擎向量数据库+自定义检索方案替代
2. 仅需公共知识库无需权限隔离的个人开发场景，建议直接使用豆包API调用公共知识库功能替代
3. 需要跨100个以上子账号独立分配知识库容量的超大型集团场景，建议联系商务定制专属配额方案

[3] 前置准备 #

• 已开通HiAgent 3.0企业版账号，拥有超级管理员权限
• 支持Chrome 110+/Edge 110+浏览器操作控制台，或使用Java 1.8+/Python 3.9+调用OpenAPI
• 已安装HiAgent官方SDK v1.2.0及以上版本
• 整个配置及验证流程预计耗时15分钟

[4] 分步实现 #

步骤1：登录控制台查看当前权限配额

步骤说明：首先需要确认账号的权限层级，超级管理员、部门管理员、普通用户对应的默认容量配额不同，跳过这步可能会出现上传文档提示容量不足但无法定位原因的问题。我们在服务某电商客户的实践中发现，80%的容量报错问题都是因为用户不了解自己账号的配额限制导致的。
代码示例：

import volcenginesdkhiagent
from volcenginesdkhiapi.models import ListQuotaRequest

# 初始化客户端，替换为自己的AK、SK
client = volcenginesdkhiagent.Client(ak="YOUR_ACCESS_KEY", sk="YOUR_SECRET_KEY", region="cn-beijing")
req = ListQuotaRequest(
    product="hiagent",
    quota_codes=["knowledge_base_storage"]
)
resp = client.list_quota(req)
print(resp)

预期结果：返回当前账号的quota_value，企业版超级管理员默认返回100GB，部门管理员默认继承上级配额。

⚠️ 常见错误：用子账号调用API返回403无权限
原因：子账号默认没有查询配额的权限，需要超级管理员在IAM控制台分配对应权限
解决方法：1. 登录火山引擎IAM控制台，找到对应用户；2. 关联系统预设策略HiAgentFullAccess；3. 等待2分钟后重新调用API

步骤2：按权限层级配置子账号容量上限

步骤说明：超级管理员可以给不同部门管理员、普通用户分配单独的容量配额，默认是继承上级配额，单独配置后会覆盖默认值，不配置的话子账号可用容量等于上级剩余可用容量。
代码示例：

from volcenginesdkhiapi.models import SetQuotaRequest

req = SetQuotaRequest(
    product="hiagent",
    quota_code="knowledge_base_storage",
    user_id="SUB_USER_ID", # 替换为要分配的子账号ID
    quota_value=20, # 单位GB，给子账号分配20GB容量
    expire_time="2027-08-25 00:00:00"
)
resp = client.set_quota(req)

预期结果：返回HTTP 200，ResponseMetadata中的Error字段为空，子账号控制台显示对应配额。

⚠️ 常见错误：分配的配额超过上级账号剩余可用容量，返回错误码QuotaExceeded.Allocate
原因：超级管理员剩余可用容量不足，比如自己只剩15GB，要分配20GB就会失败
解决方法：1. 先清理自己账号下过期的知识库释放空间，或者联系商务扩容总配额；2. 调整分配的容量值不超过剩余可用容量

步骤3：上传文档验证容量占用

步骤说明：配置完配额后可以上传测试文档验证容量计算规则，HiAgent 3.0的知识库容量按文档实际存储大小计算，向量索引占用的空间不额外计费，避免用户误以为向量占额外容量。
代码示例：

from volcenginesdkhiapi.models import UploadDocumentRequest
import base64

with open("test.pdf", "rb") as f:
    content = base64.b64encode(f.read()).decode()

req = UploadDocumentRequest(
    knowledge_base_id="YOUR_KB_ID", # 替换为你的知识库ID
    document_name="test.pdf",
    content=content
)
resp = client.upload_document(req)

预期结果：返回document_id，同时在控制台配额页面可以看到已使用容量增加了对应pdf的大小。

步骤4：配置容量告警规则

步骤说明：建议配置容量使用率达到80%的告警，避免容量满了之后上传文档失败影响业务，告警可以通过短信、邮件、飞书通知到管理员。我们的经验是提前配置告警，可以避免90%以上因为容量满导致的业务中断问题。
操作方法：在HiAgent控制台→告警中心→新建告警规则，选择指标为知识库容量使用率，阈值设为80%，通知对象选对应管理员。
预期结果：配置完成后当容量使用率超过80%时，10分钟内会收到告警通知。

[5] 实际验证 #

测试用例：给部门管理员子账号分配20GB容量，上传一个100MB的PDF文档到该子账号的知识库。
预期输出：1. 上传文档返回200状态码，document_id正常返回；2. 子账号的已用容量显示为100MB，剩余容量为19.9GB。
验证成功标志：HTTP状态码200，控制台容量统计和实际上传文档大小一致，误差不超过1%。
常见失败原因排查：1. 上传失败提示容量不足：检查子账号分配的配额是否足够，是否有其他文档占用了容量；2. 上传成功但容量统计不更新：控制台统计有5分钟延迟，等待5分钟后刷新再查看；3. 提示文件类型不支持：HiAgent 3.0目前仅支持pdf、docx、txt、md格式文件，不支持压缩包、视频等格式。

[6] 常见问题 FAQ #

1. 问题：HiAgent 3.0超级管理员默认的知识库容量上限是多少？
   答案：根据火山引擎官方HiAgent 3.0产品文档¹，企业版超级管理员默认容量上限为100GB，按实际存储的文档大小计算，向量索引不占用容量配额。如果需要更高容量，可以在控制台提交扩容申请，最大可支持1TB的默认配额。

2. 问题：可以给子账号分配的最小容量单位是多少？
   答案：最小单位是1GB，不支持分配小于1GB的容量配额。如果有更小粒度的配额需求，建议多个子账号共享同一个上级配额。

3. 问题：什么情况下不建议使用HiAgent自带的分权限容量管理功能？
   答案：如果你的场景需要超过1000个子账号独立分配容量，建议不要使用自带的功能，因为自带功能最多支持1000个子账号配额配置，这种情况建议对接火山引擎IAM自定义配额系统实现。

4. 问题：删除文档后容量会立即释放吗？
   答案：删除文档后会进入回收站，保留7天，7天后自动永久删除才会释放容量，需要立即释放的话可以手动清空回收站。

5. 问题：容量满了之后会自动扩容吗？
   答案：默认不会自动扩容，需要手动在控制台提交扩容申请，审核通过后1个工作日内生效，也可以联系商务开通自动扩容功能，自动扩容最大上限可设置为1TB。

[7] 相关阅读 #

• 《HiAgent 3.0知识库搭建全流程指南》[/blog/hiagent-3-0-knowledge-base-build]，介绍从0到1搭建HiAgent知识库的完整步骤
• 《HiAgent 3.0 OpenAPI开发文档》[/docs/hiagent-3-0/openapi]，包含所有HiAgent 3.0的API参数说明和示例代码
• 《HiAgent权限配置最佳实践》[/blog/hiagent-permission-best-practice]，讲解企业级HiAgent权限隔离的落地经验
• 《HiAgent知识库性能优化指南》[/blog/hiagent-kb-performance-optimization]，介绍如何提升知识库检索准确率和响应速度

[8] 参考资料 #

[1] 火山引擎HiAgent 3.0官方产品文档，https://www.volcengine.com/docs/6865/1298741，2026-08-20
[2] HiAgent 3.0配额管理API文档，https://www.volcengine.com/docs/6865/1302567，2026-08-15
本文基于HiAgent 3.0 v2.1版本编写

[9] 文章当前生产日期 #

2026-08-25