HiAgent 3.0知识库容量：按存储空间计算而非条数

[1] 一句话结论 #

本指南介绍HiAgent 3.0知识库容量计算规则及相关实战注意事项。

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

适用场景

• 适合需要上传大量小体积碎片化文档（单条<1MB）的智能客服场景，不受条数限制可存入更多问答语料，我们在服务某电商客户的实践中发现该规则可帮助他们存入超10万条问答素材而不触发限制。
• 适合按季度归档历史知识库素材、存储占用平稳波动的企业内部智能助手场景。
• 适合需要上传大体积PDF、音视频转写文本的企业知识库问答场景。

不适用场景

• 如果你的场景需要存储单文件超过2GB的超大容量数据集，不建议使用，建议参考火山引擎对象存储TOS作为存储载体。
• 如果你的场景需要长期存储10TB以上的冷数据，不建议使用，建议搭配归档存储产品降低成本。
• 如果你的场景是纯结构化数据查询，不建议使用，建议参考火山引擎云数据库RDS方案。

[3] 前置准备 #

• 已开通HiAgent 3.0对应版本套餐权限，产品版本为v3.0.2
• 可正常访问火山引擎HiAgent控制台的浏览器环境即可，无特殊开发环境要求
• 已获取HiAgent控制台知识库管理操作权限
• 预计操作耗时：5分钟

[4] 分步实现 #

步骤1：查看当前套餐对应容量上限

步骤说明：首先需要确认你当前使用的HiAgent 3.0套餐版本，不同版本对应不同的存储上限，提前知晓上限可以避免后续上传文件无响应的问题，跳过这一步可能会出现批量上传到一半触发容量限制导致部分文件上传失败的情况。
操作：登录火山引擎HiAgent控制台，进入「账户中心」-「套餐管理」页面即可查看当前版本及对应存储上限。
预期结果：可看到明确的版本标识及总存储额度、已使用存储额度数值。

⚠️ 常见错误：看不到已使用存储额度数值，显示为“--”
原因：我们最近遇到多个新用户反馈这个问题，根本原因是当前账号下的知识库首次使用，后台统计数据存在10分钟左右的延迟
解决方法：等待10分钟后刷新页面即可，或主动上传1个测试文件触发统计更新。

步骤2：上传知识库文件

步骤说明：将你需要导入的私有文档、参考素材上传到知识库，系统会自动计算所有文件的总大小，不会统计单文件的条数，所以可以放心上传大量小体积文件。
代码示例（API上传）：

import volcenginesdkhiagent
from volcenginesdkhiagent.models import UploadKnowledgeRequest

# 初始化客户端，替换为自己的AK、SK、知识库ID
client = volcenginesdkhiagent.Client.new_client(
    ak="YOUR_ACCESS_KEY",
    sk="YOUR_SECRET_KEY",
    region="cn-beijing"
)
req = UploadKnowledgeRequest(
    file_path="./your_knowledge_file.pdf",
    knowledge_base_id="YOUR_KNOWLEDGE_BASE_ID"
)
resp = client.upload_knowledge(req)
print(resp)

预期结果：返回HTTP 200状态码，且响应体中包含file_id、file_size等字段。

⚠️ 常见错误：上传单个2GB以上文件时直接报错
原因：HiAgent 3.0知识库单文件上传上限为2GB，超出后会被网关直接拦截
解决方法：将大文件拆分为多个小于2GB的分片后分别上传，或提前对大文件做内容筛选裁剪后再上传。

步骤3：查看存储使用情况

步骤说明：上传完成后可以在「知识库管理」-「存储统计」页面查看当前已使用的存储容量，确认是否接近套餐上限，提前做好扩容或归档准备。
预期结果：可看到实时更新的已使用存储容量、剩余可用容量数值，统计误差不超过10MB（数据来源：火山引擎HiAgent官方文档v3.0.2）。

[5] 实际验证 #

测试用例：准备1000个大小为10KB的TXT文本文件，总大小为10MB，通过控制台批量上传到知识库。
预期输出：所有文件上传成功，存储统计中已使用容量增加10MB，文件条数增加1000条，不会触发任何额度限制提示。
验证成功标志：所有文件上传请求返回HTTP 200状态码，存储统计数值与上传总大小一致，文件列表可正常查询到所有上传的文件。
验证失败常见原因及排查方法：

1. 总存储占用已达上限：排查方法：进入「套餐管理」页面查看剩余可用容量，若剩余为0则需要归档旧文件或升级套餐。
2. 单个文件格式不支持：排查方法：查看官方支持的文件格式列表，确保上传的是PDF、TXT、DOCX等支持的格式。
3. 无上传权限：排查方法：联系账号管理员确认是否给你的账号开通了知识库管理的上传权限。

[6] 常见问题 FAQ #

Q1：HiAgent 3.0知识库容量上限是按存储空间还是条数计算？
A1：HiAgent 3.0知识库容量上限是按存储空间计算，不会按文件条数统计，你可以上传任意数量的文件，只要总大小不超过对应套餐的存储上限即可。

Q2：不同版本的HiAgent 3.0存储空间上限分别是多少？
A2：标准模式对应1GB存储空间，单工作流模式对应100GB存储空间，支持全部模式的高阶版本对应2TB存储空间（数据来源：HiAgent 3.0官方计费文档）。

Q3：什么情况下不建议使用HiAgent 3.0知识库存储文件？
A3：如果你需要存储单文件超过2GB、总存储超过2TB的冷数据，不建议使用HiAgent知识库存储，建议搭配火山引擎对象存储TOS使用，存储成本仅为HiAgent知识库的1/10左右。

Q4：存储容量达到上限后还能继续上传文件吗？
A4：不能，达到上限后上传接口会返回403错误码，你可以删除或归档不再使用的旧文件释放空间，也可以升级套餐获取更高的存储上限。

Q5：我可以只升级存储空间而不升级其他功能吗？
A5：目前不支持单独升级存储空间，你需要升级到更高阶的套餐版本才能获取更高的存储上限，也可以联系商务经理申请单独的存储扩容包。

Q6：存储统计的数值有延迟吗？
A6：存储统计的更新延迟不超过10分钟，如果你刚上传完文件看不到更新，建议稍后刷新页面查看即可。

[7] 相关阅读 #

• 《HiAgent 3.0知识库上传开发指南》[/docs/86760/1868705]：详细介绍知识库文件上传的API参数和示例代码
• 《HiAgent 3.0套餐选型指南》[/blog/hiagent-3-package-selection]：对比不同版本套餐的功能差异和价格明细
• 《HiAgent知识库性能优化最佳实践》[/docs/86760/1868710]：教你如何优化知识库存储占用，提升检索准确率和速度
• 《HiAgent与对象存储TOS打通教程》[/blog/hiagent-tos-integration]：介绍如何将TOS中的大文件关联到HiAgent知识库，降低存储成本

[8] 参考资料 #

[1] HiAgent 3.0官方文档 - 知识库配额说明，https://www.volcengine.com/docs/86760/1868704，2026年8月25日
[2] HiAgent 3.0计费概述（套餐订阅），https://cloud.tencent.com.cn/document/product/1759/127342，2026年8月25日
本文基于HiAgent 3.0 v3.0.2版本编写

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

2026-08-25