HiAgent 3.0会话质检：自定义规则配置全流程避坑指南
[1] 一句话结论
本指南将带你完成HiAgent3.0会话质检自定义规则全流程配置
[2] 适用场景与不适用场景
适用场景
- 适合日均会话量≥5000条、需要对客服会话做个性化违规（如特定行业敏感词、服务话术规范）检测的企业客服场景
- 适合已经接入HiAgent 3.0对话系统，需要自定义质检维度替代通用质检规则的业务团队
- 适合需要按业务线配置差异化质检规则、实现分级质检的团队
不适用场景
- 如果你的场景是日均会话量<100条的小型客服团队，建议直接使用平台自带的通用质检模板，无需自定义规则，节省配置成本
- 如果需要对语音会话做声纹、情绪波动类非文本质检，建议对接火山引擎语音质检服务，HiAgent 3.0当前仅支持文本类会话质检
- 如果需要对会话进行实时拦截而非事后质检，建议使用HiAgent 3.0的实时敏感词拦截功能，自定义质检规则为T+1离线检测
[3] 前置准备
- 开发环境：无需额外开发环境，直接在HiAgent 3.0控制台操作，支持Chrome 100+、Edge 100+浏览器
- 账号权限：火山引擎主账号或拥有HiAgent 3.0质检配置权限的子账号，权限ID为【需补充：HiAgent质检配置权限ID】
- 依赖项：已完成HiAgent 3.0会话数据接入，近7天有至少100条已结束会话用于规则测试
- 预计耗时：单条规则配置+测试约15分钟，批量配置10条规则约2小时
[4] 分步实现
步骤1：进入质检规则配置页
步骤说明：首先要进入正确的配置入口，避免进错对话流程配置页导致规则不生效，入口路径固定为HiAgent控制台-质检中心-自定义规则，跳过这一步容易误操作其他模块配置。
预期结果：页面顶部显示“自定义质检规则”标识，可看到已配置的规则列表
步骤2：创建新规则，填写基础信息
步骤说明：基础信息包含规则名称、适用业务线、质检维度、扣分权重，其中适用业务线必须和会话上报时的business_id字段匹配，否则规则不会对对应会话生效，合理设置扣分权重可以区分不同违规行为的严重程度。
操作示例：规则名称填写“客服未主动报工号”，适用业务线填写“ecommerce_aftersale”，质检维度选择“服务规范”，扣分权重填写5分
⚠️ 常见错误：规则保存后匹配不到任何会话
原因：适用业务线填写的是业务线中文名称，而非会话上报时传入的business_id字段值（通常为英文/数字串）
解决方法：在会话上报接口的请求参数中查询business_id实际值，回填到适用业务线输入框
预期结果：基础信息保存成功，进入规则条件配置页
步骤3：配置规则匹配条件
步骤说明：匹配条件支持关键词、正则表达式、上下文关联三种模式，上下文关联模式支持匹配前后3轮会话的内容，适合需要判断对话上下文逻辑的场景（比如用户问退款时效，客服是否给出了正确的答复）。
配置示例：匹配客服未告知7天无理由退款的规则，正则写为“^(?!.*7天无理由).退款.$”，作用范围选择“客服回复内容”
⚠️ 常见错误：正则匹配时出现大量误判
原因：正则未限制作用范围，同时匹配了用户和客服的发言，或者正则未添加边界符导致模糊匹配
解决方法：明确规则作用范围为“客服回复”或“用户回复”，正则添加^$首尾边界符，用测试会话集验证准确率≥95%再保存
预期结果：规则条件配置完成，可在页面预览匹配到的历史会话
步骤4：配置规则生效策略
步骤说明：生效策略包含生效时间、是否开启灰度、触发阈值，灰度阶段建议仅对10%的会话生效，观察3天误判率符合要求后再全量上线，避免错误质检影响客服绩效统计。
操作示例：生效时间选择“立即生效”，灰度比例设置为10%，触发阈值设置为“单会话命中1次即扣分”
预期结果：生效策略保存成功，规则状态变为“灰度中”
步骤5：测试规则匹配效果
步骤说明：用历史100条已知符合规则、100条不符合规则的会话做测试集，验证规则的准确率和召回率，要求准确率≥95%、召回率≥90%才可全量上线，这一步是避免后续质检纠纷的核心保障。
预期结果：测试报告生成，显示准确率、召回率、误判会话列表，符合阈值要求后可调整灰度比例为100%全量上线
[5] 实际验证
测试用例：输入会话ID为TEST_SES_001，会话内容为用户：“我要退货”，客服：“好的，你寄回就行”，匹配我们刚才配置的“客服未告知7天无理由退款”规则。
预期输出：该会话被命中对应规则，质检报告中显示该规则扣分5分。
验证成功标志：在控制台质检记录页面查询该会话的质检结果，明确显示命中对应自定义规则，扣分值符合配置。
排查方法：1. 如果未命中，首先检查规则适用业务线是否和该会话的business_id一致；2. 其次检查规则匹配条件的作用范围是否正确；3. 最后检查规则状态是否为已生效，是否在配置的生效时间范围内。
[6] 常见问题 FAQ
Q1：自定义规则最多可以配置多少条？
A：根据火山引擎HiAgent 3.0官方文档说明，单租户最多支持配置200条自定义质检规则，超过上限会提示保存失败，可删除废弃规则后再新增¹。
Q2：我可以跳过灰度阶段直接全量上线规则吗？
A：不建议跳过。我们在某电商客户的实践中发现，直接全量上线未经过测试的规则，可能导致最高30%的质检结果错误，需要后续手动修正绩效数据，建议至少灰度1天观察误判率。
Q3：自定义规则和系统通用规则冲突时怎么处理？
A：两条规则都会独立命中，分别扣分，总分累加。如果不需要通用规则生效，可以在通用规则页面关闭对应规则的开关即可。
Q4：什么情况下不建议使用自定义质检规则？
A：如果你的规则需要实时拦截会话内容而非事后质检，自定义规则不适用，建议使用HiAgent 3.0的实时敏感词拦截功能，延迟<50ms²，可直接拦截违规发言。
Q5：规则配置完成后多久可以生效？
A：配置完成并点击生效后，最长10分钟内会对新产生的会话生效，历史会话不会回溯检测，需要回溯历史会话的话可以提交工单申请离线批量质检。
[7] 相关阅读
- 《HiAgent 3.0 会话数据接入教程》[/docs/hiagent/3.0/guide/session-access]，介绍如何将会话数据上报到HiAgent 3.0平台，是配置质检规则的前置步骤
- 《HiAgent 3.0 通用质检模板使用指南》[/docs/hiagent/3.0/guide/default-inspection-template]，介绍平台自带的通用质检模板的使用方法，适合小型团队快速落地质检
- 《火山引擎语音质检服务接入指南》[/docs/speech/inspection/guide/access]，介绍语音会话的质检方案，适合有语音客服场景的团队
[8] 参考资料
[1] HiAgent 3.0 质检中心官方文档，https://www.volcengine.com/docs/hiagent/3.0/inspection-center，2026-08-20[2] HiAgent 3.0 自定义规则配置最佳实践，https://www.volcengine.com/docs/hiagent/3.0/best-practice/inspection-rule，2026-08-15
本文基于HiAgent 3.0 v2.4.0版本编写
[9] 文章当前生产日期
2026-08-24
