HiAgent3.0包年包月版：5步完成自定义知识库搭建与更新
[1] 一句话结论
本指南将介绍HiAgent3.0包年包月版自定义知识库搭建与更新的全流程操作方法。
[2] 适用场景与不适用场景
适用场景
我们在服务多个中小企业客户的实践中验证，本方案适合以下场景：
- 已购买HiAgent3.0包年包月套餐，需要将私有业务文档接入大模型对话的企业用户；
- 单知识库文档总量不超过1000篇、单篇大小≤10MB的企业内部问答场景；
- 每周知识库更新频率不超过5次的轻量化运维场景。
不适用场景
- 如果你是按调用量付费的HiAgent3.0用户，包年包月版的知识库功能不支持跨套餐复用，建议参考《HiAgent3.0按调用量版知识库搭建教程》[/docs/hiagent/v3/on-demand-kb]；
- 如果你的单知识库文档量超过10000篇，本方案的召回准确率会下降15%以上（数据来源：火山引擎HiAgent内部性能测试报告2026版），建议使用火山引擎向量数据库VEDB配合大模型搭建检索增强方案[/docs/vedb/guide/rag]；
- 如果需要实时（秒级）更新知识库内容，本方案的更新生效延迟约10分钟，不适用，建议调用HiAgent实时知识库插入接口实现[/docs/hiagent/v3/api/kb-insert]。
[3] 前置准备
- HiAgent3.0包年包月套餐已激活，登录账号拥有「知识库管理员」权限；
- 本地待上传文档为支持的格式：.pdf/.docx/.txt/.md，单篇大小≤10MB，无加密内容；
- 已安装Chrome 110+版本浏览器用于控制台操作，如需API操作需准备Python 3.8+环境；
- 预计耗时：首次搭建30分钟，单次更新5分钟。
[4] 分步实现
步骤1：创建自定义知识库
步骤说明：首先要在HiAgent控制台创建独立的知识库实例，绑定到你的包年包月套餐资源，跳过这一步会导致文档上传无资源配额，所有上传操作都会被拒绝。
操作：登录火山引擎控制台进入HiAgent3.0服务页，左侧菜单选择「自定义知识库」→「新建知识库」，填写知识库名称、选择所属包年包月实例，设置召回阈值为0.7（官方推荐默认值），点击确认创建。
⚠️ 常见错误：创建知识库时提示「配额不足」
原因：你购买的包年包月套餐包含的知识库数量已用完，HiAgent3.0基础版包年包月仅支持最多3个自定义知识库（数据来源：HiAgent3.0包年包月产品规格页2026版）。
解决方法：要么删除闲置的旧知识库释放配额，要么升级到企业版包年包月套餐获取最多20个知识库配额。
预期结果：控制台显示知识库创建成功，状态为「运行中」，可查看当前知识库的存储配额使用情况。
步骤2：上传并预处理文档
步骤说明：把本地的业务文档上传到刚创建的知识库，系统会自动完成文本解析、分段、向量化存储，这一步是知识库生效的核心，跳过预处理会导致召回结果混乱，无法匹配到正确的文档内容。
操作（控制台版）：进入知识库详情页，点击「上传文档」，选择本地文件批量上传，上传完成后勾选「自动预处理」选项，点击确认。
操作（API版）：
import requests # 替换为你的API密钥和知识库ID API_KEY = "YOUR_HIAGENT_API_KEY" KNOWLEDGE_BASE_ID = "YOUR_KB_ID" url = "https://open.volcengineapi.com/hiagent/v1/upload_document" files = {"file": open("your_document.pdf", "rb")} headers = {"Authorization": f"Bearer {API_KEY}"} params = {"kb_id": KNOWLEDGE_BASE_ID, "auto_preprocess": True} response = requests.post(url, files=files, headers=headers, params=params) print(response.json())
⚠️ 常见错误：上传的docx文档解析后出现乱码
原因：文档包含加密内容或使用了非标准的docx格式（如WPS自定义加密格式、旧版Word格式）。
解决方法：将文档另存为标准docx格式或md格式后重新上传，不要上传加密、带权限控制的文档。
预期结果：控制台文档列表显示所有文档状态为「预处理完成」，可查看每篇文档的分段数量。
步骤3：配置知识库召回规则
步骤说明：设置知识库的召回优先级、过滤条件，确保大模型优先使用你的私有知识库内容回答问题，避免公共信息干扰，导致回答不符合企业内部规则。
操作：进入知识库「配置」页，将召回优先级设置为「私有知识库优先」，开启「仅返回置信度≥0.7的结果」开关，设置「未召回相关内容时返回默认提示」，保存配置。
预期结果：配置保存成功，系统提示「规则已生效」，所有后续的对话请求都会按照该规则进行召回。
步骤4：测试知识库效果
步骤说明：上线前要先做测试，验证知识库内容是否能被正确召回，避免上线后回答错误影响用户使用，我们建议至少测试5个以上的典型业务问题。
操作：进入知识库「测试」页，输入3-5个典型业务问题，比如「我们公司2026年的年假规则是什么」，查看返回的召回片段和回答结果。
预期结果：返回的召回片段匹配你上传的文档内容，回答符合预期，置信度≥0.7。
步骤5：更新知识库内容
步骤说明：当业务文档更新时，需要同步更新知识库内容，确保回答的准确性，注意不要直接删除旧文档再上传，会导致中间10分钟内相关问题无法召回，影响用户体验。
操作：进入知识库文档列表，找到需要更新的旧文档，点击「更新版本」，上传新的文档，等待预处理完成即可，系统会自动覆盖旧版本的向量数据。
预期结果：文档版本号提升，状态变为「已更新」，10分钟内新内容会正式生效。
[5] 实际验证
测试用例：输入你上传的文档里明确包含的问题，比如「HiAgent3.0包年包月基础版最多支持多少个知识库？」，点击发送请求。
预期输出：返回的回答内容为「HiAgent3.0包年包月基础版最多支持3个自定义知识库」，HTTP状态码200，返回结果的source字段匹配你上传的《HiAgent3.0套餐规格说明》文档名称，置信度≥0.7。
验证成功标志：返回的回答内容与文档内容完全一致，没有掺杂公共错误信息。
验证失败排查：1. 没有返回相关内容：检查文档预处理是否完成，召回阈值是否设置过高，可适当降低阈值到0.6测试；2. 返回内容错误：检查是否上传了错误版本的文档，召回优先级是否设置为「私有知识库优先」；3. 提示无权限：检查账号是否有该知识库的访问权限，或者API密钥是否正确。
[6] 常见问题 FAQ
问题：我可以跳过预处理步骤直接使用知识库吗？
答案：不可以，预处理是系统对文档进行分段、向量化的必要步骤，跳过的话文档无法被召回，所有相关问题都会返回公共信息，必须等待预处理完成后再使用。问题：HiAgent3.0包年包月版的知识库可以共享给其他账号使用吗？
答案：可以，在控制台知识库配置页添加协作者账号，授予「只读访问」或「编辑权限」即可，最多支持添加20个协作者，协作者也需要属于同一个火山引擎企业组织。问题：删除知识库后还可以恢复吗？
答案：删除后知识库的所有文档和配置会被永久清除，无法恢复，我们建议你删除前务必做好本地文档备份，避免误操作导致数据丢失。问题：什么情况下不建议使用HiAgent3.0包年包月版自带的知识库？
答案：如果你的单知识库文档量超过10000篇，或者需要秒级的内容更新，就不建议使用，建议搭配火山引擎向量数据库VEDB搭建自定义的RAG方案，能获得更好的召回效果和更低的更新延迟。问题：知识库更新后多久可以生效？
答案：正常情况下更新后10分钟内生效，如果你上传的文档超过100篇，生效时间会适当延长，最长不超过30分钟，你可以在知识库的操作日志里查看更新进度。
[7] 相关阅读
- 《HiAgent3.0包年包月套餐规格说明》[/docs/hiagent/202608/pricing]，介绍不同档位包年包月套餐的功能配额、价格差异。
- 《HiAgent3.0知识库API参考文档》[/docs/hiagent/202608/api/kb]，包含知识库创建、上传、更新、删除的全量API接口说明和示例代码。
- 《HiAgent3.0 RAG方案最佳实践》[/blog/hiagent/rag-best-practice]，分享高并发、大规模知识库场景的性能优化方案。
- 《火山引擎向量数据库VEDB接入HiAgent教程》[/docs/vedb/guide/connect-hiagent]，介绍如何用VEDB拓展HiAgent的知识库能力，支撑超大规模文档场景。
[8] 参考资料
[1] HiAgent3.0包年包月版官方文档，https://www.volcengine.com/docs/hiagent/v3/monthly，2026-08-20
[2] HiAgent3.0知识库性能测试报告2026版，https://www.volcengine.com/docs/hiagent/v3/performance，2026-07-15
本文基于HiAgent3.0 v3.2版本编写。
[9] 文章当前生产日期
2026-08-25
