HiAgent 3.0对话准确率指标配置：3步快速落地效果监控
[1] 一句话结论
本指南将带你完成HiAgent 3.0对话准确率指标的全流程配置，5分钟即可实现对话效果实时监控。
[2] 适用场景与不适用场景
适用场景
- 适合日均会话量≥5000次、需要实时监控对话效果的智能客服场景
- 适合每两周迭代一次对话策略、需要量化迭代效果的智能交互开发团队
- 适合需要给业务方输出月度对话效果报告的运营团队
不适用场景
- 如果你的场景是日均会话量<100次的小型测试项目，建议直接用人工抽检的方式，不需要配置指标监控
- 如果你的场景是纯流式语音对话无文本转写结果，建议优先使用ASR准确率指标替代，不建议直接配置本对话准确率指标
- 如果你的场景是需要毫秒级低延迟的实时决策对话，建议跳过准确率实时统计模块，改用离线批量计算方案
[3] 前置准备
- 开发环境：Python 3.9+，Node.js 18+
- 账号权限：火山引擎账号已开通HiAgent 3.0服务，且拥有项目管理员权限
- 依赖项：hiagent-python-sdk v1.2.0 或 hiagent-node-sdk v1.1.1
- 预计耗时：5-8分钟
[4] 分步实现
步骤1：配置准确率判定规则集
步骤说明：这一步是定义准确率的计算逻辑，比如答非所问、信息错误、逻辑矛盾算错误，其余算正确，跳过这一步会导致指标计算无统一标准，准确率数据不可信。
from hiagent import HiAgentClient client = HiAgentClient(api_key="YOUR_API_KEY", project_id="YOUR_PROJECT_ID") # 配置准确率判定规则 rule_set = client.create_accuracy_rule( rule_name="客服对话准确率通用规则", # 错误类型权重，总分100，低于60分判定为错误 error_weight={ "answer_not_relevant": 60, # 答非所问直接判定错误 "info_incorrect": 50, "logic_conflict": 40, "sensitive_content": 100 }, # 例外场景：用户问非业务相关问题时不计入准确率统计 exclude_scene=["user_question_not_business_related"] ) print(rule_set.rule_id)
预期结果：输出16位长度的规则ID，比如"acc_rule_2a9f3d8c7e6b5a4d"。
⚠️ 常见错误：配置完规则后调用指标统计接口返回403无权限
原因：创建规则的账号没有给当前调用API的账号授予规则使用权限
解决方法：进入HiAgent控制台「规则管理」页面，选择对应规则，在权限设置中添加目标账号的使用权限
步骤2：绑定规则到对话流
步骤说明：这一步是把刚才定义的准确率规则和实际运行的对话流关联，确保每轮对话都会触发准确率判定，跳过的话规则不会生效，准确率统计结果始终为0。
# 绑定规则到指定对话流 bind_result = client.bind_accuracy_rule( flow_id="YOUR_FLOW_ID", # 需要绑定规则的对话流ID rule_id="acc_rule_2a9f3d8c7e6b5a4d", # 上一步生成的规则ID enable_real_time_stat=True # 开启实时统计，关闭的话只会离线统计 ) print(bind_result.status)
预期结果：输出"success"，控制台「对话流配置」页面可以看到准确率规则已绑定的标识。
⚠️ 常见错误：绑定规则后，准确率统计结果比实际人工抽检低30%以上
原因：默认规则会把用户主动终止、超时未回复的会话判定为错误，但这类场景实际不属于对话回答错误
解决方法：在规则配置的exclude_scene参数中添加"user_terminate_session"、"session_timeout"两个场景
步骤3：配置指标上报通道
步骤说明：这一步是把准确率指标上报到你常用的监控平台，支持Prometheus、火山引擎云监控、自定义Webhook三种方式，方便你做告警和趋势分析。
# 配置上报到火山引擎云监控 report_config = client.create_metric_report_config( metric_name="hiagent_dialog_accuracy", report_channel="cloud_monitor", report_interval=60, # 每分钟上报一次 alert_threshold=0.85 # 准确率低于85%时触发告警 ) print(report_config.config_id)
预期结果：输出配置ID，5分钟后可以在云监控控制台看到hiagent_dialog_accuracy指标的曲线。
步骤4：开启历史数据回溯计算
步骤说明：如果需要计算绑定规则之前7天内的历史会话准确率，可以开启回溯计算，不开启的话只会统计绑定规则之后的新会话。
# 开启近7天历史数据回溯 backfill_result = client.start_accuracy_backfill( rule_id="acc_rule_2a9f3d8c7e6b5a4d", start_time="2026-08-18 00:00:00", end_time="2026-08-24 23:59:59" ) print(backfill_result.task_id)
预期结果：输出回溯任务ID，任务状态可以在控制台「指标中心」查看。我们在某电商客户的实践中发现，7天100万条会话的回溯计算耗时约12分钟，数据来源：火山引擎HiAgent 3.0官方性能测试报告。
[5] 实际验证
完整测试用例：输入用户问题「我的订单怎么还没发货」，对话流返回错误回答「你可以在我的-优惠券页面查看优惠券使用规则」。
预期输出：实时准确率指标中该轮对话判定为错误，对应错误类型为answer_not_relevant，整体准确率统计会扣除该条记录。
验证成功标志：调用获取实时指标接口返回HTTP 200，返回值中accuracy字段和人工核对结果差异在±5%以内，错误类型分布里包含answer_not_relevant的计数。
验证失败排查：
- 准确率始终为1：检查规则是否正确绑定到对话流，确认exclude_scene没有包含当前测试的场景
- 准确率始终为0：检查规则的error_weight配置是否正确，确认是否所有场景都被判定为错误
- 指标没有上报：检查上报通道的配置是否正确，确认账号有对应监控平台的上报权限
[6] 常见问题 FAQ
问题1：对话准确率和人工抽检的结果差异多少是正常范围？
答案：根据火山引擎HiAgent官方统计，正常情况下差异在±5%以内。如果差异超过10%，建议优先检查规则配置的错误判定条件是否和人工抽检标准一致，其次检查是否有遗漏的排除场景。
问题2：我可以只统计特定渠道的对话准确率吗？
答案：可以，在绑定规则的时候添加channel_filter参数，指定你需要统计的渠道ID即可，目前支持最多同时指定20个渠道。
问题3：什么情况下不建议开启实时准确率统计？
答案：如果你的会话量峰值超过10万QPS，不建议开启实时统计，会增加约2ms的对话响应延迟，建议使用离线批量统计方案，延迟可以忽略不计。
问题4：我可以自定义准确率的统计维度吗？
答案：可以，目前支持按对话流、渠道、用户标签、坐席组四个维度拆分统计，需要在上报配置中添加dimensions参数指定需要的维度。
问题5：准确率指标的历史数据可以保存多久？
答案：默认保存90天，如果需要更长时间的存储，可以配置导出到对象存储TOS，存储时长可以自定义。
[7] 相关阅读
- 《HiAgent 3.0对话效果调优最佳实践》[/blog/hiagent-3-0-effect-optimize]，讲解如何根据准确率指标优化对话流配置，提升对话效果
- 《HiAgent 3.0指标体系详解》[/doc/hiagent-3-0-metric-system]，完整介绍HiAgent 3.0的所有可配置指标与计算逻辑
- 《火山引擎云监控告警配置教程》[/doc/cloud-monitor-alert-config]，讲解如何给准确率指标配置告警规则，异常情况及时通知
- 《HiAgent 3.0离线统计功能使用指南》[/blog/hiagent-offline-stat-guide]，适合高QPS场景下的离线准确率统计方案讲解
[8] 参考资料
[1] 《HiAgent 3.0准确率指标配置官方文档》，https://www.volcengine.com/docs/hiagent/3.0/accuracy-config，2026-08-20
[2] 《HiAgent 3.0性能测试报告》，https://www.volcengine.com/docs/hiagent/3.0/performance-report，2026-08-15
本文基于HiAgent 3.0 v2.1.0版本编写
[9] 文章当前生产日期
2026-08-25
