HiAgent 3.0自定义话术：支持关联知识库配置全指南

[1] 一句话结论 #

本文介绍HiAgent 3.0自定义话术关联知识库的完整配置流程与注意事项。

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

适用场景

1. 适合企业AI客服场景，需要将自定义应答话术和企业内部产品知识库联动，日均调用量1万次以上的场景；
2. 适合私域运营智能助手场景，需要自定义活动话术关联活动规则知识库的场景；
3. 适合内部IT服务台场景，自定义报修话术关联常见故障排查知识库的场景。

不适用场景

1. 单一场景固定应答、无动态知识更新需求的场景，建议直接使用普通关键词回复工具即可，无需关联知识库；
2. 知识库文档单篇超过1000页、单次检索召回要求延迟低于50ms的场景，建议对接专用向量检索引擎而非使用HiAgent内置知识库关联能力；
3. 完全离线、无法连接火山引擎服务的本地化部署场景，建议自行搭建话术与知识库联动模块。

[3] 前置准备 #

• 开发环境：无特殊要求，只要能访问火山引擎HiAgent控制台的浏览器即可；
• 账号权限：火山引擎主账号或拥有HiAgent full access权限的子账号，已开通HiAgent 3.0服务；
• 依赖项：已提前在HiAgent知识库模块上传并完成向量化的目标知识库，向量化完成率100%；
• 预计耗时：15-30分钟。

[4] 分步实现 #

步骤1：进入自定义话术配置页

步骤说明：首先要进入HiAgent控制台的话术管理模块，选择需要配置的自定义话术分组，这一步是为了定位到需要关联知识库的具体话术集合，跳过的话会找不到关联入口。
操作：登录火山引擎控制台→搜索进入HiAgent 3.0→左侧菜单栏选择「话术管理」→点击目标话术分组的「配置」按钮。
预期结果：进入包含话术编辑、关联设置的配置页面。

⚠️ 常见错误：找不到「话术管理」菜单入口
原因：子账号没有HiAgent的话术管理权限，或者当前开通的是HiAgent 2.0版本未升级到3.0。
解决方法：联系主账号管理员在访问控制中给子账号添加HiAgentFullAccess权限，或在控制台升级HiAgent到3.0版本。

步骤2：开启知识库关联开关

步骤说明：在配置页的「高级设置」 tab 中找到「关联知识库」开关，开启后系统会在话术生成时自动检索关联的知识库内容作为应答依据，不开启的话话术不会调用知识库内容。
操作：切换到「高级设置」 tab →找到「关联知识库」选项→将开关切换为开启状态。
预期结果：开关显示为绿色，下方出现知识库选择下拉框。

步骤3：选择要关联的目标知识库

步骤说明：从下拉框中选择提前上传并完成向量化的知识库，支持多选最多5个知识库，还可以设置知识库检索的相似度阈值，阈值越高召回的内容越精准但召回率越低。我们在某电商客户实践中发现设置为0.75时兼顾准确率和召回率（数据来源：火山引擎HiAgent客户实战案例库）。
代码示例（API配置方式）：

# 安装HiAgent SDK
# pip install volcengine-hiagent==1.3.0
from volcengine.hiagent import HiAgentClient
client = HiAgentClient()
client.set_ak("YOUR_ACCESS_KEY") # 替换为你的AK
client.set_sk("YOUR_SECRET_KEY") # 替换为你的SK

# 配置自定义话术关联知识库
resp = client.update_script_config(
    ScriptId="YOUR_SCRIPT_ID", # 替换为你的话术ID
    KnowledgeBaseIds=["kb-xxxx1", "kb-xxxx2"], # 替换为目标知识库ID
    SimilarityThreshold=0.75 # 相似度阈值，推荐设置为0.75
)
print(resp)

预期结果：返回HTTP状态码200，Response中包含"Success":True的字段。

⚠️ 常见错误：选择知识库时下拉框为空
原因：所选区域的知识库还未完成向量化处理，或者知识库所属工作空间和当前话术所属工作空间不一致。
解决方法：进入「知识库管理」模块确认目标知识库的向量化状态为「已完成」，并检查两个模块的工作空间是否为同一个。

步骤4：保存配置并发布

步骤说明：配置完成后点击保存并发布，才能让配置生效，未发布的配置仅在草稿环境生效，不会对线上流量生效。
操作：点击页面右下角「保存」按钮→点击「发布」按钮→确认发布。
预期结果：页面顶部弹出「发布成功」提示，配置状态显示为「已生效」。

[5] 实际验证 #

测试用例：输入用户问题“你们的产品XX型号的保修期是多久？”，预期输出：“您好，XX型号的保修期为1年，自购买之日起计算，非人为损坏可免费维修”。
验证成功标志：返回的应答内容和知识库中存储的保修规则一致，且控制台的调用日志中显示「知识检索成功」的标记。
验证失败常见排查方法：

1. 应答未包含知识库内容：检查知识库是否已发布、关联开关是否开启；
2. 返回内容错误：检查相似度阈值是否设置过低，召回了无关内容；
3. 调用报错：检查知识库ID是否正确，账号是否有对应知识库的访问权限。

[6] 常见问题 FAQ #

问题1：自定义话术关联知识库后，会优先用自定义话术还是知识库内容？
答案：系统会优先匹配自定义话术的规则，当自定义话术未命中或需要补充信息时，会自动调用知识库内容作为补充，你也可以在编排面板中自定义优先级规则。

问题2：单组自定义话术最多可以关联多少个知识库？
答案：目前单组自定义话术最多支持关联5个知识库，单知识库最大支持1000个文档，单文档大小不超过10MB。

问题3：什么情况下不建议自定义话术关联知识库？
答案：如果你的场景是固定应答、完全不需要动态知识更新，关联知识库会额外增加约200ms的调用延迟，这种情况建议直接使用静态自定义话术即可。

问题4：关联的知识库更新后，需要重新配置话术吗？
答案：不需要，知识库内容更新并重新向量化后，会自动同步到关联的话术中，无需重新配置。

问题5：我可以跳过开启关联开关的步骤直接选择知识库吗？
答案：不行，不开启开关的话，即使选择了知识库也不会生效，系统会默认忽略知识库关联配置。

[7] 相关阅读 #

1. 《HiAgent 3.0知识库搭建全指南》，[/docs/86760/1868705]，讲解如何快速上传并向量化HiAgent知识库。
2. 《HiAgent 3.0自定义话术语法规则说明》，[/docs/86760/1868706]，详细介绍自定义话术的变量、条件判断等语法。
3. 《HiAgent 3.0 API 参考文档》，[/docs/86760/1868707]，包含所有HiAgent开放API的参数说明与调用示例。
4. 《HiAgent 3.0性能优化最佳实践》，[/blog/hiagent-performance]，分享降低调用延迟、提升准确率的实战技巧。

[8] 参考资料 #

[1] 火山引擎HiAgent官方文档：对接HiAgent，https://www.volcengine.com/docs/86760/1868704?lang=zh，引用日期2026-08-25。
[2] 基于Dify与HiAgent的智能体模块化搭建路径，https://segmentfault.com/a/1190000047477595，引用日期2026-08-25。
本文基于HiAgent 3.0版本编写。

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

2026-08-25