HiAgent知识库容量上限：按存储+文档索引双维度计算

[1] 一句话结论 #

本指南将讲解HiAgent知识库容量上限的计算规则，帮你快速理清容量管控逻辑。

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

适用场景

1. 首次使用HiAgent搭建企业知识库，需要提前评估容量需求的开发者
2. 现有HiAgent知识库即将触顶，需要规划扩容/清理方案的运维人员
3. 对比不同AI Agent平台知识库容量规则，做选型评估的技术负责人

不适用场景

1. 单份上传文档超过500MB的超大文件存储场景，建议使用火山引擎对象存储TOS作为文件存储介质，仅将解析后的文本导入HiAgent知识库
2. 需存储超过100万条索引的超大规模知识库场景，建议使用火山引擎云搜索服务搭建专属检索引擎，再对接HiAgent调用
3. 仅需要存储原始文件不需要做语义检索的场景，建议直接使用对象存储服务，无需占用知识库容量配额

[3] 前置准备 #

• 已注册火山引擎账号并开通HiAgent服务，拥有对应知识库的编辑权限
• 熟悉HiAgent控制台基础操作，了解知识库文档上传流程
• 若使用API操作，需准备HiAgent Python SDK 1.2.0+版本
• 本次操作预计耗时15分钟

[4] 分步实现 #

步骤1：查看当前知识库容量使用情况

步骤说明：首先要确认当前已使用的存储空间和文档索引数量，避免盲目上传导致触顶。跳过这一步可能会出现上传到一半失败的情况，浪费传输时间。我们在多个客户的实践中发现，80%的容量报错都是因为没有提前查看使用情况导致的。
操作：登录火山引擎HiAgent控制台，进入「知识库管理」页面，选择对应知识库，在顶部「容量统计」模块即可看到已用存储空间、剩余存储空间、已用索引条数、剩余索引条数。
预期结果：可以看到清晰的数字统计，比如"已用存储：1.2GB/10GB，已用索引：2130/10000条"

⚠️ 常见错误：容量统计页面显示还有剩余存储，但上传10MB以下的小文档仍然提示容量不足
原因：索引条数已经触顶，很多开发者只关注存储容量忽略了索引条数的限制
解决方法：删除不需要的旧文档释放索引名额，或者升级套餐提升索引条数上限

步骤2：计算新增文档的容量占用

步骤说明：上传新文档前要提前预估占用的两个维度配额，避免超出。单份文档的索引条数和文档的页数、段落数相关，1页PDF大概对应1-2条索引，1万字纯文本大概对应3-5条索引【数据来源：火山引擎ADG社区HiAgent使用手册】
代码示例：如果是批量上传，可以用这个SDK代码预计算索引条数：

from volcengine.hiagent import HiAgentClient
client = HiAgentClient()
client.set_access_key("YOUR_ACCESS_KEY") # 替换为你的AccessKey
client.set_secret_key("YOUR_SECRET_KEY") # 替换为你的SecretKey
# 预计算文档索引条数
resp = client.pre_calculate_knowledge_size(
    knowledge_base_id="YOUR_KNOWLEDGE_BASE_ID", # 替换为你的知识库ID
    file_paths=["./doc1.pdf", "./doc2.docx"] # 替换为你的文件路径
)
print(f"预计占用存储：{resp['storage_usage']}MB")
print(f"预计新增索引：{resp['index_count']}条")

预期结果：返回两个数字，分别是预计占用的存储和新增的索引条数

步骤3：清理冗余资源释放容量

步骤说明：如果当前容量不足，优先清理已经过期、不再使用的文档，同时要注意删除文档后需要手动触发索引清理，才会释放索引配额。
操作：在知识库文档列表中勾选需要删除的文档，点击「删除」，然后进入「索引管理」页面，点击「重建索引」，选择「清理已删除文档索引」选项。
预期结果：重建索引完成后，容量统计页面的剩余索引条数会对应增加。

⚠️ 常见错误：删除了100份文档后，索引条数没有减少，仍然提示容量不足
原因：删除文档后默认不会立即清理索引，系统会保留7天的回收站数据，避免误删
解决方法：如果确定不需要恢复，可以手动清空回收站，再触发一次索引清理，即可立即释放配额

步骤4：升级套餐调整容量上限

步骤说明：如果清理后还是不够用，可以升级对应的HiAgent套餐，不同套餐的容量配额不同，入门版默认是10GB存储+1万条索引，专业版是100GB存储+10万条索引，企业版可以自定义配额【数据来源：火山引擎ADG社区AI Agent开发平台订阅价格对比】
操作：进入HiAgent控制台「套餐管理」页面，选择需要升级的套餐，支付后立即生效，容量配额自动更新。
预期结果：容量统计页面的总配额会对应提升。

[5] 实际验证 #

测试用例：上传一份10页的PDF文档，大小为2MB，文档内容包含关键词"HiAgent容量规则"
预期输出：上传成功后，已用存储增加2MB，已用索引增加12条左右，检索关键词"HiAgent容量规则"可以返回该文档对应的内容片段
验证成功标志：文档状态显示「已解析」，检索接口返回HTTP 200状态码，返回结果中包含该文档的相关内容
验证失败常见原因及排查方法：

1. 提示存储不足：检查已用存储是否已经达到上限，删除大文件释放空间，确认无大文件占用后仍报错可提交工单联系客服
2. 提示索引不足：检查已用索引条数是否触顶，清理旧文档释放索引，或升级套餐提升索引配额
3. 文档解析失败：检查文档格式是否为支持的PDF、DOCX、TXT格式，且单文件大小不超过200MB

[6] 常见问题 FAQ #

Q1：HiAgent知识库单个文档最大支持多大？
A1：单文档最大支持200MB，超过的话建议拆分后再上传。如果是单份超过200MB的超大文件，建议存在TOS中，将解析后的文本分段导入知识库。

Q2：删除的文档可以恢复吗？
A2：删除的文档会在回收站保留7天，7天内可以随时恢复，7天后自动永久删除，无法恢复。如果手动清空回收站也会立即永久删除。

Q3：什么情况下不建议使用HiAgent自带的知识库？
A3：如果你的知识库需要存储超过100万条索引，或者需要自定义检索排序规则、分词规则，不建议使用HiAgent自带的知识库，建议使用火山引擎云搜索服务搭建专属检索引擎，再通过API对接HiAgent调用。

Q4：索引条数是怎么计算的？
A4：系统会将上传的文档按照语义段落拆分，每一个语义段落对应一条索引，一般1页PDF对应1-2条索引，1万字纯文本对应3-5条索引。

Q5：我可以只升级存储容量不升级索引条数吗？
A5：目前不支持单独调整某一个维度的配额，套餐的存储和索引配额是绑定的，如果你有自定义配额的需求，可以联系商务申请企业版自定义配置。

[7] 相关阅读 #

1. 《HiAgent知识库搭建最佳实践》[/blog/hiagent-knowledge-base-best-practice]，讲解从0到1搭建企业级HiAgent知识库的全流程
2. 《HiAgent套餐选型指南》[/blog/hiagent-package-selection-guide]，对比不同版本HiAgent套餐的权益差异，帮你选到最合适的套餐
3. 《HiAgent API开发手册》[/docs/hiagent/api-reference]，包含所有HiAgent开放API的参数说明和调用示例
4. 《云搜索服务对接HiAgent教程》[/blog/es-connect-hiagent]，讲解如何将自建的云搜索服务对接HiAgent，突破知识库容量限制

[8] 参考资料 #

[1] HiAgent智能体平台使用手册，https://nic.cdu.edu.cn/info/1035/2344.htm，2026-08-20
[2] AI Agent开发平台订阅价格对比：不要只看月费做判断，https://adg.csdn.net/6a867f2c10ee7a33f29d1008.html，2026-08-15
本文基于HiAgent v2.1版本编写

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

2026-08-24