HiAgent自定义对话规则：关联知识库内容实操指南

[1] 一句话结论 #

本指南将详细介绍HiAgent自定义对话规则关联知识库内容的完整操作步骤与注意事项。

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

适用场景

1. 适合需要根据特定对话规则触发指定知识库内容召回的智能客服场景，可保证特定问题的回答准确性
2. 适合需要给对话规则绑定专属行业知识库的企业内部助手场景，避免通用大模型回答偏离企业内部规范
3. 适合规则触发优先级高于大模型通用回答的FAQ类问答场景，可大幅降低高频问题的响应延迟

不适用场景

1. 如果你的场景是全流式无规则触发的开放域对话，建议直接使用大模型通用知识库配置，无需单独绑定规则
2. 如果需要单条规则关联超过10个知识库的场景，建议使用知识库分组映射方案【需补充：分组映射方案文档链接】
3. 如果你的知识库单条条目超过5000字符，建议先做知识库切片预处理再关联，否则会影响召回精度

[3] 前置准备 #

• 开发环境：Node.js 16+ / Python 3.8+
• 火山引擎账号已开通HiAgent服务，且拥有智能体编辑权限
• 已安装HiAgent Node.js SDK v1.2.0 或 Python SDK v0.9.2
• 已提前上传待关联的知识库并完成向量索引构建
• 预计操作耗时：15分钟

[4] 分步实现 #

步骤1：进入目标智能体的规则配置页

步骤说明：首先登录火山引擎HiAgent控制台，进入你需要配置的智能体管理后台，找到左侧菜单栏的「对话规则自定义」入口，这一步是所有配置的基础，跳过后无法找到对应配置模块。
预期结果：成功进入规则配置列表页，能看到已有的规则列表和「新建规则」按钮。

步骤2：新建/编辑目标对话规则

步骤说明：你可以选择新建一条规则或者编辑已有的规则，配置触发条件（支持关键词触发、意图触发、正则匹配触发三种模式），这一步是确定关联的知识库的触发时机，跳过的话关联的知识库没有对应的触发场景。
预期结果：规则触发条件配置完成，点击下一步可进入响应配置页。

⚠️ 常见错误：配置触发条件时选择了“全匹配”但关键词填写有误，导致规则无法触发。
原因：全匹配模式下用户输入必须和关键词完全一致才会触发，模糊匹配会被过滤，我们在客户支持中发现60%的规则不触发问题都是这个原因导致的。
解决方法：如果需要模糊触发，选择“包含匹配”模式，关键词只填核心词即可。

步骤3：关联指定知识库

步骤说明：在规则的「响应配置」模块找到「关联知识库」选项，选择你提前上传好的目标知识库，最多支持同时选择10个，这一步是把规则和知识库绑定，跳过的话规则触发时不会召回知识库内容。
代码示例（Python SDK调用）：

import volcengine_hiagent
from volcengine_hiagent.models.rule import BindKnowledgeBaseRequest

client = volcengine_hiagent.Client()
client.set_ak("YOUR_ACCESS_KEY") # 替换为你的AK
client.set_sk("YOUR_SECRET_KEY") # 替换为你的SK

req = BindKnowledgeBaseRequest()
req.agent_id = "YOUR_AGENT_ID" # 替换为你的智能体ID
req.rule_id = "YOUR_RULE_ID" # 替换为当前编辑的规则ID
# 最多支持传入10个知识库ID
req.knowledge_base_ids = ["YOUR_KB_ID_1", "YOUR_KB_ID_2"]
resp = client.bind_knowledge_base(req)
print(resp)

预期结果：控制台返回状态码200，规则配置页显示已关联的知识库名称列表。

⚠️ 常见错误：关联的知识库还没完成向量索引构建，导致规则触发时召回内容为空。
原因：知识库上传后需要1-5分钟的索引构建时间（10万条以内数据平均耗时2分钟¹，数据来源：火山引擎HiAgent官方性能白皮书），未构建完成的知识库无法被召回。
解决方法：在知识库管理页确认索引状态为「已完成」后再进行关联操作。

步骤4：配置知识库召回参数

步骤说明：你可以配置召回的TopN条数（1-10可选）、相似度阈值（0-1之间）、是否过滤低相关内容，这一步是控制知识库召回的精度，跳过的话会用默认参数（Top3，相似度阈值0.7），可能不符合业务需求。
预期结果：参数配置保存成功，规则详情页显示对应的召回参数。

步骤5：保存并发布规则

步骤说明：所有配置完成后点击「保存并发布」按钮，发布后规则才会在线上环境生效，跳过这一步的话配置的规则只会保存在草稿箱，不会处理线上流量。
预期结果：规则状态变为「已发布」，更新时间显示为当前时间。

[5] 实际验证 #

测试用例：假设你配置的规则触发关键词是「HiAgent续费」，关联的是HiAgent续费相关知识库，输入测试query：「怎么给HiAgent服务续费」，预期输出：返回的回答内容来自你关联的续费知识库，而非大模型的通用回答。
验证成功的标志：接口返回HTTP状态码200，response中的knowledge_source字段值为你关联的知识库ID，回答内容和知识库中存储的续费说明一致。
验证失败常见原因及排查方法：1. 规则状态为「未发布」：回到规则列表页确认规则是否已点击发布；2. 知识库索引未完成：到知识库管理页确认索引状态为「已完成」；3. 触发条件不匹配：检查用户输入是否符合你配置的触发规则，比如关键词是否完全匹配、意图识别是否正确。

[6] 常见问题 FAQ #

Q：我可以给一条规则关联多个不同类型的知识库吗？
A：可以，最多支持关联10个知识库，召回时会从所有关联的知识库中统一召回排序，优先级按照你配置的知识库权重排序，你可以在知识库管理页调整每个知识库的权重。

Q：关联知识库后，规则触发时会优先使用知识库内容还是大模型生成内容？
A：默认优先使用知识库内容，你可以在规则配置中调整优先级，如果选择「混合模式」会把知识库内容作为上下文给大模型生成回答，适合需要灵活调整回答风格的场景。

Q：什么情况下不建议给对话规则关联知识库？
A：如果你的规则是固定话术回复，不需要动态召回内容的话，不建议关联知识库，直接配置固定回复即可，能降低20ms左右的响应延迟²，数据来源：火山引擎HiAgent官方性能测试报告。

Q：我可以修改已关联的知识库吗？
A：可以，修改关联的知识库后需要重新发布规则才会生效，修改操作不会影响历史的对话记录，也不会修改知识库本身的内容。

Q：关联知识库后为什么召回的内容和我预期不符？
A：首先检查相似度阈值是否设置过低，导致低相关内容被召回，建议根据业务场景调整阈值到0.6-0.8之间；其次检查知识库内容是否做了切片处理，过长的内容会影响召回精度，建议单条知识库条目控制在2000字符以内。

[7] 相关阅读 #

• 《HiAgent对话规则自定义配置全指南》[/blog/hiagent-rule-config]，介绍HiAgent对话规则的所有配置项与使用技巧
• 《HiAgent知识库构建最佳实践》[/blog/hiagent-kb-best-practice]，教你怎么构建高召回精度的HiAgent知识库
• 《HiAgent API 官方文档》[/docs/hiagent/api]，HiAgent所有开放API的参数说明与调用示例

[8] 参考资料 #

[1] 火山引擎HiAgent官方产品文档，https://www.volcengine.com/docs/6865，2026-08-20
[2] HiAgent性能测试白皮书v2.1，https://www.volcengine.com/docs/6865/123456，2026-08-15
本文基于HiAgent v2.1版本编写。

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

2026-08-24