HiAgent 3.0会话质检：支持自定义个性化质检维度

[1] 一句话结论 #

本指南将教你如何在HiAgent 3.0中配置个性化质检维度。

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

适用场景

1. 适合电商客服需要检测专属合规话术（如优惠券发放规则、退换货承诺）的场景；
2. 适合金融行业需要自定义敏感信息泄露检测维度的场景；
3. 适合教育机构需要检测客服是否违规承诺提分、保过的场景。

不适用场景

1. 如果你的场景是单账号日均质检会话量低于100次，不建议用HiAgent自定义质检，建议用轻量型人工抽检工具；
2. 如果你的质检规则需要实时响应延迟低于100ms的实时拦截场景，建议参考火山引擎内容安全API方案；
3. 如果你的会话数据完全存储在本地私有部署环境且不允许上云，建议使用本地部署的开源质检工具。

[3] 前置准备 #

• 已完成火山引擎HiAgent 3.0企业版账号开通，拥有质检配置管理权限；
• Python 3.9+ 或 Node.js 16+ 开发环境；
• HiAgent OpenAPI SDK v1.2.0及以上版本；
• 整体配置与测试预计耗时30分钟。

[4] 分步实现 #

步骤1：进入质检规则配置页面

步骤说明：首先要进入HiAgent控制台的会话质检模块规则管理页，这是所有自定义维度配置的入口，跳过将无法找到对应配置入口。
操作：登录火山引擎控制台，进入【HiAgent 3.0】-【会话质检】-【规则管理】，点击【新建规则】按钮。
预期结果：进入规则新建页面，能看到“自定义维度”配置选项。

⚠️ 常见错误：进入会话质检模块看不到规则管理菜单。
原因：当前账号只有质检查看权限，没有配置管理权限。
解决方法：联系企业主账号管理员在访问控制中为你的账号分配“HiAgent质检配置管理员”角色。

步骤2：创建自定义质检维度

步骤说明：需要先定义维度的基本信息，包括维度名称、权重、命中判定逻辑，这是确保个性化规则能被大模型正确识别的核心，跳过会导致规则无法生效。
代码示例：

from volcengine.hiagent import HiAgentClient

client = HiAgentClient()
client.set_access_key("YOUR_ACCESS_KEY") # 替换为你的AccessKey
client.set_secret_key("YOUR_SECRET_KEY") # 替换为你的SecretKey

# 创建自定义质检维度
resp = client.create_quality_dimension({
    "DimensionName": "是否违规承诺7天无理由退换",
    "Weight": 20, # 维度权重，单规则总分100
    "HitCondition": "客服在会话中明确告知用户非7天无理由商品可7天退换",
    "ExcludeCondition": "用户主动要求且客服明确告知需要申请特批",
    "RuleId": "YOUR_RULE_ID" # 替换为你的质检规则ID
})
print(resp)

预期结果：接口返回HTTP 200，响应体中包含DimensionId字段，代表维度创建成功。

步骤3：配置维度生效范围

步骤说明：需要指定该自定义维度适用的会话来源、客服组、时间范围，避免规则误命中无关会话，跳过会导致规则全量生效可能影响正常质检结果。
操作：在维度配置页的“生效范围”板块，选择对应的客服分组（如“电商售后组”），设置会话来源为“抖音小店咨询”，生效时间设置为永久生效。
预期结果：保存后规则列表中该维度的生效范围显示为你配置的内容。

⚠️ 常见错误：自定义维度配置后命中准确率低于60%。
原因：命中条件描述模糊，大模型无法准确判定。
解决方法：将命中条件细化到具体话术场景，补充3-5个正例和反例，我们在某电商客户实践中发现，补充示例后命中准确率可提升至92%（数据来源：火山引擎HiAgent客户落地案例2026）。

步骤4：测试并上线维度

步骤说明：配置完成后需要先在测试会话集上验证规则效果，确认无误后再全量上线，跳过可能导致错误的质检结果影响绩效统计。
操作：上传100条标注好的测试会话，选择“测试规则”功能，查看命中准确率，确认准确率达到90%以上后点击“上线”按钮。
预期结果：规则上线后，新产生的符合生效范围的会话会自动使用该自定义维度进行质检。

[5] 实际验证 #

测试用例：输入会话内容：用户问“这个家电拆封了还能退吗？”，客服答“可以的，我们这边支持7天无理由退换”（该家电实际不属于7天无理由商品）。
预期输出：质检结果中该自定义维度命中，扣20分，质检报告中明确标注命中原因。
验证成功标志：接口返回HTTP 200，返回的质检结果中对应DimensionId字段的Hit值为True，Score扣除对应权重分值。
常见排查方法：

1. 如果维度未命中：首先检查命中条件是否包含该场景，是否生效范围包含该客服所属分组；
2. 如果误命中：检查排除条件是否覆盖了例外场景，是否有多余的命中关键词；
3. 如果接口报错：检查API密钥是否正确，SDK版本是否为v1.2.0及以上。

[6] 常见问题 FAQ #

Q1：自定义质检维度最多可以添加多少个？
A：单条质检规则最多支持添加20个自定义维度，足够覆盖绝大多数企业的质检需求，如果需要更多维度可以拆分多条规则分别配置。

Q2：自定义维度支持实时质检吗？
A：支持，实时质检场景下自定义维度的判定延迟平均为800ms（数据来源：火山引擎HiAgent 3.0产品性能白皮书2026），满足绝大多数非拦截类实时质检需求。

Q3：什么情况下不建议使用自定义质检维度？
A：如果你的质检规则是通用的敏感词检测、规范话术检测，不建议自定义维度，直接使用系统内置的通用规则即可，准确率更高且配置成本更低。

Q4：我可以跳过测试步骤直接上线自定义维度吗？
A：不建议，未经过测试的自定义维度命中率误差可能超过30%，会导致质检结果失真，我们建议至少使用50条以上标注数据完成测试后再上线。

Q5：自定义质检维度可以导出配置吗？
A：支持，你可以通过OpenAPI导出所有自定义维度的配置，也可以在不同的质检规则之间复用同一个维度配置。

[7] 相关阅读 #

1. 《HiAgent 3.0会话质检快速入门》[/docs/hiagent/3.0/quickstart/quality-check]，带你快速了解HiAgent会话质检的基础功能与配置流程。
2. 《HiAgent OpenAPI 参考文档》[/docs/hiagent/3.0/api-reference/quality]，提供所有质检相关API的参数说明、调用示例与错误码详解。
3. 《电商行业会话质检最佳实践》[/blog/hiagent-ecommerce-quality-best-practice]，包含电商行业常用的12个自定义质检维度模板可直接复用。

[8] 参考资料 #

[1] 火山引擎HiAgent 3.0官方文档，https://www.volcengine.com/docs/hiagent/3.0/quality-check/custom-dimension，2026-08-20
[2] 火山引擎HiAgent 3.0性能白皮书，https://www.volcengine.com/docs/hiagent/3.0/performance-whitepaper，2026-07-15
本文基于火山引擎HiAgent 3.0 v2.6.1版本编写。

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

2026-08-24