HiAgent私有化部署：知识库容量上限配置实战指南

[1] 一句话结论 #

本指南将介绍HiAgent私有化部署场景下知识库容量上限的配置规则、扩容方法及避坑要点。

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

适用场景

• 适合需要数据不出域、知识库文档量在500到1500万级的中大型企业内部知识问答场景
• 适合单项目检索QPS需求在1到1万之间的客服智能体、员工助手等场景
• 适合需要灵活调整知识库配额、适配不同业务团队资源分配的多租户部署场景

不适用场景

• 如果你只需要轻量试用、知识库文档量低于500且无私有化需求，建议使用HiAgent公有云标准版，成本更低
• 如果你的场景是单知识库需要存储超过2000万文档的超大规模知识底座，建议搭配火山引擎veGraph知识图谱产品使用，避免检索性能下降
• 如果你的业务QPS长期超过1.5万，建议拆分知识库部署或使用公有云弹性扩容方案，降低单实例运维成本

[3] 前置准备 #

• 开发环境：HiAgent私有化部署版本v2.5及以上，服务器操作系统为CentOS 7.9/Ubuntu 20.04+
• 账号权限：拥有HiAgent私有化部署后台超级管理员权限
• 依赖：已完成基础部署，存储集群可用容量≥预期知识库总容量的1.5倍
• 预计耗时：30分钟（不含扩容服务器资源的时间）

[4] 分步实现 #

步骤1：确认基础版本配额
步骤说明：首先需要确认你部署的HiAgent私有化版本对应的基线配额，不同版本的默认上限不同，跳过这一步会导致后续配置超过硬件承载能力。
预期结果：确认是标准版/旗舰版，对应基线配额为标准版单知识库500文档/10GB音视频，QPS1；旗舰版单知识库1500万文档/1000音视频，QPS1万。

⚠️ 常见错误：部署时直接套用旗舰版配额但实际服务器配置仅满足标准版要求，导致服务频繁崩溃
原因：配额上限和服务器CPU、内存、存储资源直接绑定，旗舰版默认需要至少16核32G内存的检索节点
解决方法：先通过后台资源监控确认当前服务器资源余量，再匹配对应版本的配额，资源不足时先扩容硬件

步骤2：登录管理后台调整配额
步骤说明：使用超级管理员账号登录HiAgent私有化部署的运营管理后台，进入【知识库配置】-【配额管理】页面，可分别调整全局知识库总数、单知识库文档上限、单知识库音视频上限、检索QPS上限四个参数。
代码/命令：如果需要通过API批量调整，可调用如下接口：

curl --location --request POST 'https://<你的私有化部署域名>/api/v1/admin/knowledge/quota/config' \
--header 'Authorization: Bearer <YOUR_ADMIN_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": "<目标项目ID>",
    "max_knowledge_count": 500, # 单项目最多知识库数量
    "max_doc_per_knowledge": 100000, # 单知识库最多文档数
    "max_video_per_knowledge": 200, # 单知识库最多音视频数
    "max_retrieve_qps": 100 # 检索QPS上限
}'

预期结果：接口返回HTTP 200，响应体中显示"code":0,"msg":"success"，后台配额页面显示修改后的数值。

步骤3：同步调整存储切片配置
步骤说明：如果单知识库文档量调整超过100万，需要同步修改知识库的分片数量，分片数不足会导致检索延迟升高到2s以上，影响使用体验。
代码/命令：修改配置文件/opt/hiagent/config/retrieve.yaml中的参数：

knowledge_shard_num: 8 # 单知识库分片数，每100万文档对应1个分片，最大支持32分片
shard_replica_num: 2 # 分片副本数，高可用场景建议设为2

修改后执行重启命令：systemctl restart hiagent-retrieve
预期结果：重启后检索服务状态正常，调用检索接口延迟保持在500ms以内（数据来源：火山引擎HiAgent官方性能测试报告）。

⚠️ 常见错误：调整了单知识库文档上限但没有同步增加分片数，上传10万以上文档时出现部分文档检索不到的问题
原因：分片容量达到上限后，新上传的文档无法被正常索引
解决方法：按照每100万文档对应1个分片的规则调整分片数，然后触发全量知识库重新索引即可恢复

步骤4：验证配额生效
步骤说明：配置完成后，上传测试文档验证上限是否生效，同时测试检索性能是否符合预期。
预期结果：上传文档数量达到配置的上限时，系统提示"知识库容量已达上限，请联系管理员扩容"，检索QPS达到配置上限时请求返回429状态码。

[5] 实际验证 #

测试用例：在目标知识库中上传100份测试文档，配置单知识库上限为100，然后尝试上传第101份文档，同时模拟100并发的检索请求。
预期输出：第101份文档上传失败，返回错误码KV-1001，提示容量不足；100并发检索请求全部返回200，平均延迟≤300ms。
验证成功标志：容量限制生效、检索性能符合预期、服务无崩溃或异常报错。
验证失败常见排查方法：

• 如果配置不生效：检查管理员账号是否有全局配置权限，是否在正确的项目下修改配额
• 如果检索延迟过高：检查分片数是否和文档量匹配，存储集群IO性能是否达标
• 如果文档上传后检索不到：检查索引服务状态，是否有未完成的索引任务

[6] 常见问题 FAQ #

Q1：私有化部署的知识库容量可以无上限扩容吗？
A1：不可以，当前单实例最高支持单知识库32分片，对应最大文档量为3200万，超过该上限建议拆分多个知识库。如果需要更大容量，可联系官方技术支持定制分布式部署方案。

Q2：我可以跳过调整分片数的步骤吗？
A2：如果单知识库文档量低于100万可以跳过，超过100万必须调整，否则会出现检索性能下降、文档索引失败的问题，影响业务使用。

Q3：HiAgent私有化和公有云的知识库配额规则一样吗？
A3：基线配额规则一致，但私有化部署支持管理员自主调整配额，公有云需要提交工单申请调整，私有化场景还可以通过扩容硬件进一步提升上限。

Q4：什么情况下不建议调整默认配额？
A4：如果你的服务器硬件资源余量不足30%，不建议上调配额，否则会导致服务稳定性下降，甚至出现数据丢失的风险，建议先扩容硬件再调整配额。

Q5：扩容存储后需要重启服务吗？
A5：如果是扩容对象存储容量不需要重启服务，如果是调整分片数、修改检索服务配置需要重启检索服务，重启过程中检索请求会有1-2分钟的不可用，建议在业务低峰期操作。

Q6：音视频的容量上限是怎么计算的？
A6：音视频的容量是按实际存储大小计算的，标准版默认10GB，旗舰版默认无存储上限，仅限制单知识库最多1000个音视频文件，你可以根据业务需求在后台调整上限。

[7] 相关阅读 #

• 《HiAgent私有化部署全流程指南》，[/docs/84313/1234567]，包含HiAgent私有化部署的环境要求、安装步骤、运维操作全流程
• 《HiAgent知识库检索性能优化最佳实践》，[/blog/hiagent-retrieve-optimize]，详解如何提升知识库检索的准确率和响应速度
• 《HiAgent配额管理API文档》，[/docs/84313/1339026]，包含配额配置相关的所有API接口参数说明和调用示例

[8] 参考资料 #

[1] 火山引擎《HiAgent知识库配额说明》，https://www.volcengine.com/docs/84313/1339026?lang=zh，2026-08-20
[2] InfoQ《2026年AI智能体开发平台深度解析》，https://xie.infoq.cn/article/5d9dfbc20393cfd9c6bf5ea4d，2026-06-15
本文基于HiAgent私有化部署版本v2.5编写

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

2026-08-24