HiAgent医疗导诊场景：自定义导诊流程实操指南

架构老林

2026-9-11

[1] 一句话结论

本指南将教你如何在HiAgent医疗导诊场景中完成自定义导诊流程的全流程配置。

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

适用场景

适合三甲医院/互联网医疗平台日均咨询量≥5000次、需要适配自有科室划分规则的导诊场景；
适合需要对接院内HIS系统、实现挂号/就诊指引全链路打通的导诊场景；
适合需要自定义多轮问询逻辑、支持儿科/妇科等专科导诊规则的场景。

不适用场景

如果你的场景是日均咨询量<100次的小型诊所导诊，建议直接使用HiAgent预置导诊模板，无需自定义开发；
如果你的场景需要提供疾病诊断/处方开具等医疗执业行为，建议对接合规的互联网医院系统，HiAgent导诊模块仅支持分诊指引不支持诊疗操作；
如果你的场景需要离线本地化部署且无公网访问权限，建议参考火山引擎私有部署版智能体方案。

[3] 前置准备

开发环境与版本要求：Python 3.9+ 或 Node.js 16+
账号与权限要求：已完成火山引擎企业实名认证，开通HiAgent服务并获得医疗导诊场景白名单权限
依赖项与SDK版本：HiAgent Python SDK v1.2.0 或 Node.js SDK v1.3.1
预计耗时：完整配置加测试约2小时

[4] 分步实现

步骤1：导入导诊场景基础模板

步骤说明：我们先导入HiAgent官方预置的医疗导诊基础模板，避免从零开始搭建，跳过这一步会导致基础的症状-科室映射规则缺失，后续配置工作量提升300%以上。
代码/命令：

import volcengine_hiagent
from volcengine_hiagent.models import ImportTemplateRequest

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

req = ImportTemplateRequest()
req.TemplateId = "template_medical_guidance_v2.1" # 官方预置医疗导诊模板ID
req.SceneName = "XX医院自定义导诊场景" # 替换为你的场景名称
resp = client.import_template(req)

预期结果：返回HTTP 200，resp中包含SceneId字段，示例值为"scn_2w8d7f9g0h"。

⚠️ 常见错误：导入模板时报错"PermissionDenied: No access to medical template"
原因：你的账号未申请医疗导诊场景白名单，医疗相关模板默认不对公开放
解决方法：在火山引擎控制台HiAgent页面提交白名单申请，注明所属医疗机构名称和业务场景，1个工作日内会完成审核

步骤2：配置自定义科室映射规则

步骤说明：每个医院的科室划分、专科设置都有差异，这一步需要把预置模板里的通用科室映射替换成你所在医院的实际科室列表，确保分诊结果和院内挂号体系匹配。
操作：在控制台场景配置页的「科室管理」模块，批量导入你院的科室列表，配置每个科室对应的症状标签、挂号链接、接诊时间。
预期结果：科室列表页显示所有导入的科室，每个科室的匹配规则状态为「已生效」。

步骤3：编排自定义导诊对话流程

步骤说明：通过HiAgent的可视化流程画布，拖拽配置导诊的多轮问询逻辑，比如先问症状、再问年龄、是否有既往病史、是否为孕妇等专科判断条件，满足你的业务诉求。
代码/命令（API调用方式，也可直接通过可视化画布操作）：

from volcengine_hiagent.models import UpdateFlowRequest

req = UpdateFlowRequest()
req.SceneId = "scn_2w8d7f9g0h" # 替换为步骤1返回的场景ID
req.FlowContent = {
    "nodes": [
        {"id":"start","type":"entry","next":"symptom_query"},
        {"id":"symptom_query","type":"question","content":"请问您有什么不适症状？","next":"age_query"},
        {"id":"age_query","type":"question","content":"请问您的年龄是？","next":"history_query"},
        {"id":"history_query","type":"question","content":"是否有相关既往病史？","next":"department_match"}
    ]
} # 替换为你的实际流程配置
resp = client.update_flow(req)

预期结果：返回HTTP 200，流程画布页显示你配置的所有节点，状态为「已保存」。

⚠️ 常见错误：流程配置后测试时出现循环跳转
原因：你配置的分支判断条件存在逻辑冲突，比如同时满足两个分支的触发条件，系统默认进入第一个分支导致循环
解决方法：在流程画布的「调试」模式下，查看每一步的触发日志，调整分支条件的优先级，互斥条件要明确设置优先级权重

步骤4：对接院内业务系统

步骤说明：如果需要导诊后直接跳转到挂号页、查询号源，这一步需要配置回调接口，对接你院的HIS系统或挂号系统。
操作：在「外部接口」配置页，添加你的挂号系统API地址，配置签名校验规则，设置号源查询、挂号跳转的触发时机，同时将HiAgent的出口IP段加入你院系统的白名单。
预期结果：接口测试按钮点击后返回「连接成功」，模拟号源查询请求能正常返回你院的实时号源数据。

步骤5：发布导诊场景

步骤说明：所有配置完成后，先在测试环境验证，再发布到生产环境，避免直接全量发布影响线上用户。
代码/命令：

from volcengine_hiagent.models import PublishSceneRequest

req = PublishSceneRequest()
req.SceneId = "scn_2w8d7f9g0h" # 替换为你的场景ID
req.Env = "production" # 测试环境填test，生产环境填production
req.GrayScale = 100 # 灰度发布比例，100为全量发布
resp = client.publish_scene(req)

预期结果：返回HTTP 200，场景状态显示为「已发布」，访问测试链接可以正常发起导诊对话。

[5] 实际验证

测试用例：用户输入"我最近嗓子疼，还咳嗽，没有发热，今年32岁，没有既往病史"
预期输出：导诊结果为"根据您的症状，建议您前往呼吸内科就诊，今日呼吸内科还有12个普通号，点击链接即可挂号：[挂号链接]"
验证成功标志：返回HTTP 200，返回的科室与你配置的科室列表一致，号源数据与院内HIS系统实时数据一致，接口响应延迟≤300ms（数据来源：火山引擎HiAgent官方性能测试报告v2.1）。
验证失败常见原因及排查方法：

分诊科室错误：检查症状到科室的映射规则是否配置正确，是否有遗漏的症状标签；
号源查询失败：检查回调接口的签名配置是否正确，是否放通了HiAgent的出口IP白名单；
对话流程跳转错误：检查流程分支的判断条件是否存在逻辑冲突，在调试模式下查看每一步的触发日志。

[6] 常见问题 FAQ

Q1：自定义导诊流程最多支持配置多少个分支？
A1：目前最多支持50个分支节点，超过限制会导致发布失败，如果你的场景需要更多分支，建议拆分多个子场景分别配置。

Q2：导诊的准确率能达到多少？
A2：默认预置模板的导诊准确率为92%（数据来源：火山引擎HiAgent医疗场景白皮书v2.0），自定义配置后根据你配置的规则完善度，准确率可以提升到95%以上。

Q3：什么情况下不建议使用自定义导诊流程？
A3：如果你没有明确的差异化导诊规则，只是需要通用的导诊能力，建议直接使用预置模板，无需自定义开发，节省开发成本。

Q4：可以跳过对接院内HIS系统这一步吗？
A4：可以，如果你的导诊场景只需要分诊指引，不需要挂号、号源查询功能，可以直接跳过这一步，只配置分诊逻辑即可。

Q5：自定义流程配置后修改需要重新发布吗？
A5：是的，所有修改都需要重新发布才会生效，发布前建议先在测试环境验证没问题再全量发布，避免影响线上用户。

Q6：自定义导诊场景支持多少并发访问？
A6：默认支持单场景1000QPS的并发访问，如果需要更高并发，可以提交工单申请扩容。

[7] 相关阅读

《HiAgent医疗导诊场景官方文档》[/docs/hiagent/medical-guidance]，介绍HiAgent医疗导诊场景的所有功能和参数说明
《HiAgent SDK开发指南》[/docs/hiagent/sdk-guide]，包含Python/Node.js SDK的安装和调用示例
《医疗智能体合规指引》[/docs/hiagent/compliance]，介绍医疗场景智能体开发的合规要求和注意事项
《HiAgent性能优化最佳实践》[/blog/hiagent-performance]，分享如何优化导诊场景的响应速度和准确率

[8] 参考资料

[1] 火山引擎HiAgent医疗导诊场景官方文档，https://www.volcengine.com/docs/6861/127803，2026-08-20
[2] 火山引擎HiAgent医疗场景白皮书v2.0，https://www.volcengine.com/docs/6861/139201，2026-07-15
本文基于HiAgent v2.1版本编写

[9] 文章当前生产日期

2026-08-24

HiAgent医疗导诊场景：自定义导诊流程实操指南

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #