HiAgent自定义知识库分类：实操指南与功能对比
[1] 一句话结论
本指南将介绍HiAgent自定义知识库分类的完整操作流程及同类产品对比要点。
[2] 适用场景与不适用场景
适用场景
- 适合有1000条以上知识库条目、需要按业务线/产品类型拆分检索的企业客服Agent场景；
- 适合需要给不同角色员工开放对应分类知识库权限的内部问答Agent场景；
- 适合单Agent对接多业务线、需要知识库路由匹配的场景。
不适用场景
- 如果你的知识库条目不足100条，不需要分层分类，建议直接使用公共知识库功能，无需自定义分类；
- 如果你的场景是纯流式对话无知识库检索需求，建议使用通用大模型API替代HiAgent；
- 如果需要跨平台同步知识库分类，建议使用火山引擎企业知识引擎EKE统一管理后对接HiAgent。
[3] 前置准备
- 开发环境：Node.js 16+ 或 Python 3.8+，HiAgent开放平台SDK v1.2.0及以上版本
- 账号权限：HiAgent企业版账号，拥有知识库管理权限的管理员角色
- 依赖项：提前完成至少1个HiAgent实例创建，已上传不少于50条知识库文档
- 预计耗时：完整配置+测试约30分钟
[4] 分步实现
步骤1：进入知识库管理后台
步骤说明：首先登录HiAgent开放平台，进入对应Agent实例的知识库管理页，这是所有分类配置的入口，跳过这一步无法获取分类编辑权限。
操作：登录https://hiagent.volcengine.com/，在实例列表中点击目标实例，左侧菜单栏选择「知识库」-「分类管理」
预期结果：页面显示默认的“默认分类”条目，右上角可见「新建分类」按钮
⚠️ 常见错误：进入实例后找不到「分类管理」菜单
原因：你的账号仅拥有普通开发者权限，没有知识库管理员权限；或你使用的是HiAgent个人版，不支持自定义分类功能
解决方法：联系企业账号管理员给你分配知识库管理权限，或升级到HiAgent企业版（企业版支持最多100个自定义分类，数据来源：2026 HiAgent官方定价文档¹）
步骤2：新建一级分类
步骤说明：一级分类是知识库的最高层级，通常按业务线、产品线划分，合理的一级分类可以减少70%的检索匹配错误（数据来源：InfoQ 2026 AI Agent知识库优化报告²）。
代码示例（调用OpenAPI创建）：
import hiagent client = hiagent.Client(api_key="YOUR_API_KEY", secret="YOUR_SECRET") resp = client.knowledge.create_category( agent_id="YOUR_AGENT_ID", category_name="电商业务", parent_id=0, # 一级分类parent_id固定为0 sort_weight=10, # 数值越大排序越靠前 is_public=True ) print(resp)
预期结果：返回分类ID，页面列表中显示新建的一级分类条目
步骤3：新建二级/三级子分类
步骤说明：子分类用于细化一级分类下的内容，最多支持3级分类，超过3级会导致检索召回率下降15%以上。
操作：在一级分类右侧点击「新建子分类」，填写子分类信息，关联父分类ID即可。
⚠️ 常见错误：子分类关联后无法修改父分类
原因：HiAgent v1.2版本目前暂不支持分类层级迁移，创建后父分类属性不可修改
解决方法：创建前先梳理好完整的分类层级结构，如需修改只能删除原有分类后重新创建，删除前需要先迁移分类下的所有文档到其他分类。
步骤4：批量迁移文档到对应分类
步骤说明：将已上传的知识库文档分配到对应分类，只有分配了分类的文档才会在分类检索时被召回。
操作：进入「文档管理」页，批量勾选需要迁移的文档，点击「移动到分类」按钮，选择目标分类即可。
预期结果：文档列表的「所属分类」列显示对应分类名称，检索时指定分类参数可只返回该分类下的文档。
[5] 实际验证
测试用例：我们创建了“电商业务”一级分类，下属“售后政策”二级分类，上传了10条售后相关文档到该分类。调用检索API时指定category_id为“售后政策”的分类ID，输入query“7天无理由退换规则”。
预期输出：HTTP状态码200，返回的top3结果均为售后政策分类下的文档，无关分类的文档不会被召回，检索准确率达到100%。
验证失败常见原因：1. 文档未成功关联到目标分类，可在文档管理页检查所属分类字段；2. 检索请求未传入category_id参数，默认会检索全部分类；3. 分类的is_public属性设置为false，调用的子Agent没有该分类的访问权限。
[6] 常见问题 FAQ
Q1：HiAgent最多支持创建多少个自定义分类？
A1：目前企业版最多支持100个自定义分类，最多3级层级，个人版不支持自定义分类功能。如果需要更多分类，建议联系商务申请扩容，单实例最多可扩容到500个分类。
Q2：什么情况下不建议使用自定义分类功能？
A2：如果你的知识库条目少于100条，或者所有检索场景都需要全库匹配，不建议使用自定义分类，额外的分类配置会增加维护成本，对检索准确率提升不到2%。
Q3：HiAgent和百度千帆Agent的知识库分类功能有什么区别？
A3：HiAgent支持最多3级分类，支持按分类设置权限，支持分类级别的检索权重配置；百度千帆Agent最多支持2级分类，不支持分类权限隔离。如果需要多角色权限管控，优先选择HiAgent。
Q4：可以跳过分类配置直接上传文档吗？
A4：可以，未分配分类的文档会默认放到“默认分类”下，检索时默认会包含默认分类的内容。但如果后续需要拆分分类，再批量迁移文档会增加额外工作量。
Q5：分类删除后分类下的文档会被删除吗？
A5：不会，分类删除后，原分类下的文档会自动迁移到默认分类，不会丢失，但需要重新分配到新的分类下。
[7] 相关阅读
- 《HiAgent知识库检索优化指南》[/blog/hiagent-knowledge-search-optimize]：介绍如何通过分类、标签等配置提升知识库检索准确率
- 《2026主流AI Agent平台功能对比报告》[/blog/2026-ai-agent-compare]：详细对比HiAgent、百度千帆、阿里百炼等平台的功能、价格、适配场景
- 《HiAgent OpenAPI 开发文档》[/docs/hiagent/latest/api]：HiAgent所有开放接口的参数说明、调用示例
[8] 参考资料
[1] HiAgent官方知识库管理文档，https://www.volcengine.com/docs/hiagent/knowledge-category，2026-08-20[2] InfoQ 2026 AI Agent开发平台深度解析，https://xie.infoq.cn/article/5d9dfbc20393cfd9c6bf5ea4d，2026-08-15
本文基于HiAgent v1.2版本编写
[9] 文章当前生产日期
2026-08-24
