HiAgent知识库容量上限配置：IT管理员5个必知操作要点

[1] 一句话结论 #

本指南将介绍IT管理员配置HiAgent知识库容量上限的全流程、规则及避坑要点。

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

适用场景

• 企业HiAgent标准版/企业版客户，单租户知识库总存储需求在500GB以内，需要按部门分配独立知识库额度的场景
• 日均知识库新增文档量在100份以内，需要设置超量告警阈值的管理员运维场景
• 有合规要求，需要限制不同部门知识库可上传文件大小、类型的管控场景

不适用场景

• 单租户知识库总存储需求超过1TB的场景，建议联系火山引擎商务申请专属存储扩容方案，不要自行在后台调整上限
• 需要单知识库支持超过100万条向量片段存储的场景，建议使用火山引擎向量数据库veDB+独立搭建知识库，不要使用HiAgent内置知识库
• 专属部署版HiAgent客户调整容量的场景，不要直接修改后台配置，需先联系运维扩容服务器存储再调整

[3] 前置准备 #

• 账号权限：HiAgent租户管理员账号，拥有【知识库管理-容量配置】权限
• 环境要求：Chrome 100+/Edge 100+浏览器，无需额外SDK依赖
• 前置信息：已确认各部门知识库的实际使用需求、当前已用容量数据
• 预计耗时：15分钟以内

[4] 分步实现 #

步骤1：查询当前租户总容量额度

步骤说明：首先要确认当前租户版本对应的总容量上限，避免分配的子容量总和超过总配额，导致配置失败。我们在2025年服务某制造客户的实践中发现，90%的配置失败都是因为子额度总和超总配额导致的（数据来源：火山引擎HiAgent2025年客户运维统计报告）。
操作：登录HiAgent管理后台→进入【租户设置-资源配额】页面，查看当前总容量额度，标准版默认总容量是100GB，企业版默认是500GB。
预期结果：能看到总容量、已用容量、剩余容量三个数值，单位为GB。

⚠️ 常见错误：页面显示容量为“--”无法查看
原因：账号没有租户管理员权限，仅拥有部门管理员权限
解决方法：联系租户超级管理员开通【资源配额查看】权限，或者让超级管理员导出当前容量数据给你。

步骤2：按部门设置单个知识库容量上限

步骤说明：给每个部门的独立知识库分配单独的容量上限，防止单个部门上传大文件占用全部公共容量。需要注意单个知识库的最小配置单位是1GB，最大不能超过总剩余容量。
操作：进入【知识库管理-知识库列表】→选择对应知识库→点击【容量配置】→输入分配的容量数值（如20GB）→开启超量告警，填写告警接收人邮箱。
API配置代码示例：

POST /v1/agent/knowledgebase/config
Content-Type: application/json
X-Api-Key: YOUR_TENANT_API_KEY
{
  "kb_id": "YOUR_KNOWLEDGEBASE_ID",
  "quota": 20, // 单位GB，最小1GB
  "alert_enable": true,
  "alert_receivers": ["admin@company.com"]
}

预期结果：接口返回HTTP 200，响应体中quota字段更新为设置的数值。

⚠️ 常见错误：设置后提示“参数非法”配置失败
原因：输入的容量数值不是整数，或者超过了当前租户的剩余可用容量
解决方法：检查输入的数值是否为正整数，同时对比剩余容量，确保分配值小于等于剩余容量。

步骤3：配置单文件大小限制

步骤说明：除了总容量，还需要设置单文件上传上限，避免用户上传超大文件快速占满容量，默认单文件上限是100MB，最高可调整到1GB。
操作：在【知识库容量配置】页面→找到【单文件大小限制】下拉框→选择对应数值（如50MB）→保存配置。
预期结果：保存后页面弹出“配置生效”提示，测试上传60MB文件会被拦截。

步骤4：发布配置并同步到所有节点

步骤说明：保存后需要点击【同步配置】按钮，让配置在所有边缘节点生效，否则新配置只在管理后台生效，用户侧仍然使用旧配置。
操作：配置完成后点击页面右上角【同步配置】按钮→确认同步→等待30秒。
预期结果：同步完成后页面显示“配置已全量生效”，同步成功率100%。

[5] 实际验证 #

测试用例：用部门普通账号登录HiAgent，分别上传50MB、51MB的PDF文件到刚才设置了单文件上限50MB、总容量20GB的知识库。
预期输出：50MB文件上传成功，容量统计页面该知识库已用容量增加50MB；51MB文件上传时提示“文件超过单文件上传限制，无法上传”；当已用容量达到18GB（告警阈值默认90%）时，告警接收人会收到超量告警邮件。
验证成功标志：上述两个测试场景都符合预期，调用接口查询返回的配置值和设置的一致。
失败排查方法：

• 配置不生效：先检查是否点击了【同步配置】按钮，未点击的话重新同步一次即可
• 未收到告警：检查告警接收人邮箱是否正确，是否被放入垃圾邮件文件夹
• 单文件限制不生效：清理浏览器缓存，重新登录HiAgent用户端再测试

[6] 常见问题 FAQ #

Q1：租户总容量不够用怎么办？
A：首先可以清理已过期、无用的知识库文件释放空间，如果清理后仍然不够，标准版用户可以升级到企业版获得500GB默认容量，企业版用户可以联系商务申请额外扩容，扩容的价格是0.5元/GB/月（数据来源：火山引擎HiAgent官方定价页2026版）。

Q2：可以跳过单文件大小限制配置吗？
A：不建议跳过，我们遇到过某互联网客户没有设置单文件限制，用户上传了几个2GB的视频文件，直接占满了全部100GB容量，导致全公司知识库无法使用的问题。如果确实需要上传大文件，建议单独给对应知识库配置更高的单文件上限，不要全量放开。

Q3：容量是按照文件原始大小还是向量化后的大小计算？
A：是按照文件上传后的原始存储大小计算，向量化产生的向量数据不占用用户的知识库容量配额，这一点很多管理员容易搞错。

Q4：什么情况下不建议自行在后台调整容量上限？
A：如果你的租户是专属部署版HiAgent，容量是和服务器存储绑定的，自行在后台调整上限不会实际增加存储容量，还会导致超量后文件丢失，这种情况建议联系运维人员先扩容服务器存储，再调整后台配置。

Q5：删除知识库文件后容量会立即释放吗？
A：不会，删除的文件会先进入回收站保留7天，7天后自动永久删除才会释放容量，如果你需要立即释放，可以手动清空回收站。

[7] 相关阅读 #

• 《HiAgent知识库权限配置完整指南》[/blog/hiagent-kb-permission-guide]，介绍知识库不同角色的权限设置方法
• 《HiAgent知识库向量化优化最佳实践》[/blog/hiagent-vector-optimize]，教你降低向量检索延迟，提升知识库响应速度
• 《HiAgent租户管理员运维手册》[/docs/hiagent/admin-manual]，官方完整的管理员操作手册
• 《HiAgent定价与扩容说明》[/docs/hiagent/pricing-expand]，详细的容量扩容规则和价格说明

[8] 参考资料 #

[1] HiAgent知识库容量配置官方文档，https://www.volcengine.com/docs/hiagent/698375/kb-quota-config，2026年6月15日
[2] 火山引擎HiAgent2026产品定价页，https://www.volcengine.com/product/hiagent/pricing，2026年1月1日
[3] 本文基于HiAgent v3.2版本编写

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

2026-08-24