HiAgent知识库：容量上限规则及使用情况查询实操指南

[1] 一句话结论 #

本指南将介绍HiAgent知识库容量上限规则，以及查询容量使用情况的完整操作步骤。

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

适用场景

1. 已上线HiAgent应用的开发者，需要定期核查知识库容量避免溢出导致内容更新失败的运维场景
2. 计划扩容知识库、需要先评估当前使用量，再提交扩容申请的资源管理场景
3. 刚接入HiAgent知识库、需要确认初始配额是否匹配业务预期的接入场景

不适用场景

1. 还未开通HiAgent服务的用户，不适用本指南，建议先参考HiAgent服务开通指南完成服务开通
2. 需要查询大模型调用配额、API流控限制等非知识库类资源的场景，建议直接访问火山引擎配额中心查询
3. 需要批量清理知识库过期内容释放容量的场景，建议参考HiAgent知识库内容管理指南操作

[3] 前置准备 #

• 已开通HiAgent服务，当前登录账号具备HiAgentReadOnlyAccess及以上权限
• 浏览器版本要求Chrome 100+/Edge 100+/Safari 15+，避免控制台交互异常
• 已获取目标知识库的ID（若通过API查询）
• 预计操作耗时：控制台查询≤3分钟，API查询≤10分钟

[4] 分步实现 #

步骤1：进入HiAgent产品控制台

步骤说明：首先需要进入正确的产品入口，跳过该步会找不到知识库相关管理模块。操作路径：打开火山引擎官网，登录账号后在顶部产品搜索框输入「HiAgent」，点击搜索结果进入产品控制台。
预期结果：进入HiAgent控制台首页，页面展示你名下有权限访问的所有HiAgent应用列表。

⚠️ 常见错误：搜索HiAgent后找不到产品入口
原因：账号所属团队未开通HiAgent白名单权限，或者当前登录的子账号没有HiAgent产品访问权限
解决方法：联系主账号管理员确认HiAgent服务已开通，且给子账号配置了HiAgentFullAccess或HiAgentReadOnlyAccess权限

步骤2：进入目标知识库详情页

步骤说明：HiAgent的容量是按单个知识库独立计算的，必须进入对应知识库的详情页才能看到准确的使用数据。操作路径：在应用列表中点击目标应用进入应用管理页，左侧菜单栏选择「知识库」模块，再点击需要查询的知识库名称进入详情页。
预期结果：页面顶部展示知识库的名称、ID、创建时间等基本信息，右侧区域显示容量使用进度条。

步骤3：查看容量使用详情

步骤说明：控制台展示的容量数据包含已使用容量、总配额、使用率三个核心指标，若需要实时数据或者接入自动化监控，可以调用OpenAPI查询。
API调用代码示例：

import volcenginesdkcore
from volcenginesdkhiagent.models.describe_knowledge_base_request import DescribeKnowledgeBaseRequest

configuration = volcenginesdkcore.Configuration()
configuration.ak = "YOUR_AK" # 替换为你的火山引擎Access Key
configuration.sk = "YOUR_SK" # 替换为你的火山引擎Secret Key
configuration.region = "cn-beijing"

api_instance = volcenginesdkhiagent.HiAgentApi(volcenginesdkcore.ApiClient(configuration))
request = DescribeKnowledgeBaseRequest(
    knowledge_base_id="YOUR_KB_ID" # 替换为你的知识库ID
)
response = api_instance.describe_knowledge_base(request)
print(f"已使用容量：{response.used_storage}MB，总容量：{response.total_storage}MB")

预期结果：控制台输出和页面展示一致的容量数值，单位为MB。

⚠️ 常见错误：API返回的容量数值和控制台展示的不一致
原因：控制台数据有5分钟左右的缓存延迟，API返回的是实时统计数据
解决方法：如果需要实时数据优先调用OpenAPI，控制台数据每5分钟自动刷新，等待后再核对即可

步骤4：导出容量趋势报表（可选）

步骤说明：如果需要留存容量数据做长期业务分析，可以导出最近30天的容量使用趋势。操作路径：点击容量统计区域的「导出报表」按钮，系统会自动生成CSV格式的报表。
预期结果：浏览器自动下载报表，文件包含每日容量使用量、新增文件数、删除文件数等细分数据。

[5] 实际验证 #

测试用例：进入控制台目标知识库详情页，或者使用正确的AK/SK、知识库ID调用上述OpenAPI。
验证成功标志：1. 控制台页面容量进度条显示正常，鼠标悬停可以看到具体的已使用/总容量数值；2. OpenAPI返回HTTP 200状态码，used_storage和total_storage字段均为非负整数，单位为MB。
验证失败常见原因及排查方法：1. 页面看不到容量统计区域：检查当前账号是否有该知识库的访问权限，联系主账号管理员确认权限配置；2. API返回403状态码：检查AK/SK是否填写正确，是否有该知识库的查询权限；3. 容量数值显示为0：知识库未上传任何内容，或者刚上传的内容还在索引中，等待10分钟后再查看即可。

[6] 常见问题 FAQ #

问题1：HiAgent知识库的容量上限是多少？
答案：默认单租户总容量配额是100GB，单个知识库最大容量是20GB，数据来源为火山引擎HiAgent官方产品文档。如果需要更高配额，可以提交工单申请扩容，最高可支持单租户1PB总容量。

问题2：容量满了之后会有什么影响？
答案：容量满后新的文件上传请求会直接被拒绝，已上传的内容查询不受影响。我们在多个客户的实践中发现，如果没有提前监控容量，可能会导致业务内容更新失败，建议容量使用率超过80%就提前申请扩容。

问题3：什么情况下不建议通过控制台查询容量？
答案：如果需要做自动化容量监控、告警，不建议定时爬取控制台页面，建议直接调用OpenAPI获取实时数据接入内部监控系统，避免控制台缓存和页面结构变化导致的监控异常。

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

问题5：可以单独给某个知识库扩容吗？
答案：可以，提交工单时注明需要扩容的知识库ID和目标容量即可，不需要调整全局总配额，扩容一般1个工作日内可以完成。

[7] 相关阅读 #

• 《HiAgent知识库接入全流程指南》[/blog/hiagent-knowledgebase-onboarding]，适合刚接入HiAgent的开发者快速完成知识库搭建
• 《HiAgent OpenAPI 接口文档》[/docs/hiagent/api-reference]，包含所有HiAgent相关接口的参数说明和调用示例
• 《HiAgent知识库内容清理操作指南》[/blog/hiagent-knowledgebase-clean]，介绍如何快速清理过期内容释放存储空间
• 《火山引擎配额中心使用指南》[/docs/quota-center/guide]，教你如何自助查询和申请其他云产品的配额

[8] 参考资料 #

[1] 《HiAgent知识库产品限制说明》，https://www.volcengine.com/docs/hiagent/69843/1082977，2026-08-20
[2] 《HiAgent DescribeKnowledgeBase 接口文档》，https://www.volcengine.com/docs/hiagent/69843/1156832，2026-08-15
本文基于HiAgent 2.4版本编写

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

2026-08-24