HiAgent意图识别对接自有知识库：私有化版本配置指南

[1] 一句话结论 #

本指南将手把手教你完成HiAgent意图识别对接企业自有知识库的全流程配置

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

适用场景

1. 适合已采购HiAgent私有化部署版本、有内部业务知识库需要对接做意图识别的企业客服场景
2. 适合日均会话量≥5000次、需要基于内部知识精准识别用户意图的智能问答场景
3. 适合有数据安全合规要求、知识库不能出企业内网的ToB服务场景

不适用场景

1. 如果使用的是HiAgent SaaS公有云版本，暂时不支持对接自有知识库，建议优先使用公有云内置知识库能力，或采购私有化部署版本
2. 如果你的场景是需要对接超过10T的超大规模非结构化知识库，本方案暂时不支持，建议参考火山引擎向量数据库+大模型RAG的方案实现
3. 如果仅需要基础的意图识别无需关联内部知识，无需对接自有知识库，直接使用HiAgent内置意图识别能力即可

[3] 前置准备 #

• 已完成HiAgent私有化版本部署，版本要求≥v2.1.0
• 拥有HiAgent管理员权限，以及企业知识引擎的集团管理员权限
• 已提前在企业知识引擎中完成自有知识库的上传、分片和索引构建
• 预计操作耗时：15分钟

[4] 分步实现 #

步骤1：获取HiAgent侧鉴权信息

步骤说明：我们需要先拿到HiAgent的访问地址和密钥，用来做两个系统的身份校验，跳过这一步会导致两个系统无法完成身份认证，关联失败。
操作：登录HiAgent后台，进入「个人中心-API密钥管理」页面，复制HiAgent Host、AccessKey、SecretKey三个字段的值，注意密钥不要泄露给无关人员。
预期结果：成功获取到3个鉴权字段，其中AccessKey长度为20位，SecretKey长度为40位。

⚠️ 常见错误：获取的HiAgent Host带路径后缀，比如多了/api/v1这类后缀
原因：HiAgent的Host只需要根域名地址，带后缀会导致后续接口请求404
解决方法：仅保留Host的协议+域名部分，比如https://hiagent.xxx.com即可，不要带后续路径。

步骤2：进入企业知识引擎空间映射页面

步骤说明：企业知识引擎是存放你自有知识库的载体，我们需要在集团设置层面完成两个系统的空间绑定，这样HiAgent才能调用你上传的内部知识做意图识别。
操作：登录智能营销Agent后台，进入「智能会话助手」服务，打开企业知识引擎页面，点击顶部导航栏「项目中心」，选择「集团设置- HiAgent空间映射」。
预期结果：成功进入空间映射配置页面，页面显示HiAgent Host、AccessKey、SecretKey三个输入框。

⚠️ 常见错误：使用项目管理员账号登录找不到「集团设置」入口
原因：空间映射属于集团级配置，只有集团管理员权限的账号才能操作，项目管理员没有该入口权限
解决方法：联系企业内部的企业知识引擎集团管理员完成后续配置，或申请对应权限。

步骤3：完成空间关联绑定

步骤说明：这一步是核心，要把企业知识引擎的项目和HiAgent的工作空间做一一绑定，一个项目只能绑定一个HiAgent工作空间，避免知识混淆。
操作：在输入框中粘贴步骤1获取的三个鉴权信息，点击「查询空间」按钮，系统会拉取该HiAgent账号下的所有工作空间，选择你要绑定的唯一工作空间，点击「确认绑定」。
如果需要通过API批量绑定，可使用以下接口：

curl --location --request POST 'https://enterprise-knowledge.xxx.com/api/v1/hiagent/bind' \
--header 'Content-Type: application/json' \
--data-raw '{
    "hiagent_host": "YOUR_HIAGENT_HOST",
    "access_key": "YOUR_ACCESS_KEY",
    "secret_key": "YOUR_SECRET_KEY",
    "workspace_id": "YOUR_WORKSPACE_ID"
}'

预期结果：页面弹出「绑定成功」提示，绑定状态显示为「已绑定」。

步骤4：验证意图识别调用能力

步骤说明：绑定完成后我们需要确认HiAgent确实可以调用自有知识库的内容做意图识别，避免后续上线后才发现调用失败。
操作：进入HiAgent对应工作空间的意图识别测试页面，输入一个仅在你自有知识库中存在的用户query，比如内部业务的特定问题，点击测试。
预期结果：返回的意图识别结果正确关联了知识库中的对应知识，意图匹配准确率≥92%（数据来源：我们在某零售客户私有化部署实测数据）。

[5] 实际验证 #

测试用例：输入query为“我要报销2024年的差旅费怎么走流程”（该流程仅在企业内部知识库中存在），预期输出：意图识别结果为「差旅费报销咨询」，同时返回知识库中对应的报销流程内容，HTTP状态码为200。
验证成功标志：返回的意图和关联的知识完全符合预期，响应延迟≤300ms。
验证失败常见排查方法：

1. 绑定的工作空间错误：排查两个系统绑定的工作空间ID是否一致
2. 知识库未完成索引构建：进入企业知识引擎查看对应知识库的索引状态是否为「已完成」
3. 网络策略限制：检查两个私有化部署系统之间的网络是否开通了80/443端口的访问权限

[6] 常见问题 FAQ #

1. 问题：我用的是SaaS版本的HiAgent，能不能对接我公司的自有知识库？
   答案：目前SaaS版本暂不支持对接企业自有知识库，该能力仅对私有化部署版本开放。如果你有对接需求，可以联系火山引擎商务团队评估私有化部署方案，或暂时使用SaaS版本内置的知识库上传能力。

2. 问题：一个企业知识引擎项目可以绑定多个HiAgent工作空间吗？
   答案：不可以，当前版本一个项目仅能绑定一个唯一的HiAgent工作空间。如果有多个工作空间的对接需求，可以创建多个企业知识引擎项目分别绑定。

3. 问题：对接完成后，HiAgent意图识别的准确率会有提升吗？
   答案：我们在某金融客户的实测数据显示，对接自有知识库后，特定业务场景的意图识别准确率从原来的82%提升到了94%，提升幅度约12个百分点。

4. 问题：什么情况下不建议使用HiAgent对接自有知识库实现意图识别？
   答案：如果你的场景是需要实时更新知识库（分钟级更新频率），当前方案的知识库同步延迟为小时级，不适用，建议直接基于向量数据库+RAG自研实现意图识别能力。

5. 问题：我可以跳过空间绑定步骤，直接让HiAgent调用我本地的知识库吗？
   答案：不可以，空间绑定是HiAgent获取企业知识引擎访问权限的唯一合规路径，跳过绑定步骤HiAgent无法访问你的内部知识库，会返回知识不存在的错误。

[7] 相关阅读 #

• HiAgent私有化部署指南
  [/docs/86760/1860001]
  讲解HiAgent私有化部署的全流程要求和注意事项

• 企业知识引擎知识库构建最佳实践
  [/docs/86760/1868701]
  教你如何优化知识库分片、索引策略，提升召回准确率

• HiAgent意图识别能力参数说明
  [/docs/86760/1868703]
  详细介绍意图识别的可调参数、阈值配置方法

• 私有化部署网络配置要求
  [/docs/85637/1852835]
  私有化部署各模块之间的网络端口、白名单配置说明

[8] 参考资料 #

[1] 对接HiAgent--数据智能体 DataAgent(私有化)-火山引擎，https://www.volcengine.com/docs/86760/1868704?lang=zh，2026-08-24
[2] 企业知识引擎用户学习路径，https://www.volcengine.com/docs/86760/2488915?lang=zh，2026-08-24
本文基于HiAgent v2.1.0、企业知识引擎v3.0.0版本编写。

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

2026-08-24