HiAgent 3.0意图识别准确率测试：4种可落地实测方法

[1] 一句话结论 #

本指南将介绍HiAgent3.0意图识别准确率的4种可落地测试方法及实操步骤。

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

适用场景

1. 适合需要上线HiAgent3.0对话系统，需要提前验证意图识别效果的上线前验收测试场景；
2. 适合日常模型迭代后，需要快速回归验证意图识别准确率是否达标（≥92%要求）的版本测试场景；
3. 适合需要对比多轮对话上下文下意图识别稳定性的专项测试场景，覆盖上下文跳转、歧义query等特殊case。

不适用场景

1. 如果你的场景是需要测试非中文的意图识别效果，建议参考[多语种Agent测试方案]，HiAgent3.0当前仅优化了中文意图识别能力；
2. 如果你的场景是需要测试10万级以上超大测试集的全量准确率，建议参考[离线批量标注测试工具]，在线测试接口QPS限制为50次/秒不适合大并发压测；
3. 如果你的场景是需要测试意图识别的延迟、并发等性能指标，建议参考[HiAgent性能测试指南]，本方法仅覆盖准确率维度。

[3] 前置准备 #

• 开发环境要求：Python 3.9+，HiAgent Python SDK v1.2.0版本；
• 账号权限要求：火山引擎主账号，已开通HiAgent3.0服务，拥有对应Agent实例的编辑与调用权限；
• 物料准备：已准备至少1000条已人工标注的测试语料，覆盖所有待测试的意图分类，测试集和训练集重合率≤1%；
• 预计耗时：2小时（含测试用例校准、接口调用、结果统计与Badcase分析）。

[4] 分步实现 #

步骤1：校准标注测试数据集

步骤说明：首先要保证测试集的语料分布和线上真实语料分布一致，包含标准问、边缘问、歧义问、多轮上下文问等多种类型，仅用标准问测试的结果没有实际参考价值，我们之前有客户测试集全是标准问，测试准确率98%上线后实际只有85%就是这个原因。
代码/格式示例：测试集统一用CSV格式存储，字段如下：

query,expected_intent,is_context,context_session_id
怎么查快递,查询物流,0,
我的快递还没到,查询物流,1,session_123
能不能改地址,修改收货信息,1,session_123

预期结果：测试集人工标注准确率≥99%，无重复语料，所有目标意图的测试用例均≥20条。

⚠️ 常见错误：测试集混入了训练集的语料，导致测试准确率虚高10%以上
原因：标注人员整理测试集时没有和训练集做去重，模型已经见过对应query自然识别准确
解决方法：调用HiAgent的训练集导出接口，将测试集和训练集query做MD5去重，重合率必须控制在1%以内

步骤2：配置测试API调用参数

步骤说明：需要开启意图识别的全置信度返回开关，默认接口仅返回Top1意图，无法统计Top3准确率、召回率等核心指标，该开关不会额外增加接口延迟。
代码示例：

import volcengine_hiagent
from volcengine_hiagent.models import IntentRequest

# 初始化客户端
client = volcengine_hiagent.Client(
    access_key="YOUR_ACCESS_KEY", # 替换为你的access key
    secret_key="YOUR_SECRET_KEY", # 替换为你的secret key
    region="cn-beijing"
)

# 配置请求参数，开启全意图返回
req = IntentRequest(
    agent_id="YOUR_AGENT_ID", # 替换为你的Agent实例ID
    query="测试query",
    session_id="",
    return_full_intent=True # 关键参数，开启全意图置信度返回
)

预期结果：客户端初始化成功，调用测试query可以返回所有候选意图的置信度得分，HTTP状态码为200。

⚠️ 常见错误：多轮场景测试时没有传入上下文session_id，导致测试结果比实际线上效果低15%左右
原因：HiAgent3.0的意图识别依赖上下文session的历史对话信息，单轮调用无法还原真实多轮对话场景
解决方法：多轮测试的语料按照session_id分组，按对话顺序依次调用API，每次传入当前对话的session_id

步骤3：批量调用测试接口

步骤说明：控制调用QPS不要超过官方限制的50，否则会触发限流导致部分请求失败，我们实测QPS控制在30的情况下，1000条测试用例1分钟就能跑完，效率足够日常测试使用。
代码示例：

import csv
import time

result_list = []
with open("test_set.csv", "r", encoding="utf-8") as f:
    reader = csv.DictReader(f)
    for row in reader:
        req.query = row["query"]
        req.session_id = row["context_session_id"]
        resp = client.intent_detect(req)
        result_list.append({
            "query": row["query"],
            "expected": row["expected_intent"],
            "actual_top1": resp.intents[0].name,
            "actual_top3": [i.name for i in resp.intents[:3]],
            "confidence": resp.intents[0].confidence
        })
        time.sleep(0.03) # 控制QPS在30左右

预期结果：所有测试用例都返回HTTP 200状态码，无报错，结果列表长度和测试集长度一致。

步骤4：统计核心准确率指标

步骤说明：要分别统计Top1准确率、Top3准确率、精确率、召回率四个核心指标，不能仅看Top1准确率，Top3准确率可以反映模型的召回能力，对于允许用户二次确认意图的场景更有参考价值。
统计规则：

• Top1准确率 = Top1意图和预期一致的用例数 / 总测试用例数
• Top3准确率 = 预期意图出现在Top3的用例数 / 总测试用例数
• 精确率 = 识别为某意图的正确用例数 / 识别为该意图的总用例数
• 召回率 = 识别为某意图的正确用例数 / 该意图的总测试用例数
  预期结果：输出一份完整的统计报表，包含整体准确率和每个单独意图的四项指标数据。

步骤5：Badcase分类分析

步骤说明：把所有识别错误的case捞出来，分为标注错误、歧义query、模型识别错误三类，不同的错误类型对应不同的优化方案，标注错误占比过高的话需要重新校准测试集。
预期结果：输出Badcase分类报告，明确每个错误类型的占比和后续优化方向。

[5] 实际验证 #

完整测试用例：从线上近7天的真实用户query中随机抽取100条已人工标注的语料，覆盖10个以上的意图分类，包含20%的多轮上下文query。
验证成功标志：接口全部返回HTTP 200状态码，整体Top1准确率≥92%（数据来源：火山引擎HiAgent3.0官方SLA承诺），单意图准确率≥85%。
验证失败常见原因及排查方法：

1. 测试集标注错误：抽查10条Badcase，如果标注错误占比≥30%，需要重新标注测试集；
2. 部分意图训练语料不足：如果某一个意图准确率<70%，需要补充至少50条该意图的训练语料重新训练后再测试；
3. 调用参数错误：检查是否开启了return_full_intent参数，是否传入了正确的agent_id和session_id。

[6] 常见问题 FAQ #

问题1：HiAgent3.0的意图识别准确率官方标称是多少？
答案：官方SLA承诺标准场景下Top1准确率≥92%，具体数值和你的意图分类数量、语料质量有关，我们在电商客服客户的实践中，意图分类20个的场景下最高可以做到96%的Top1准确率。

问题2：测试的时候可以跳过Badcase分析吗？
答案：不可以，Badcase分析是定位准确率低根本原因的核心步骤，只看整体准确率无法针对性优化模型效果，很多时候准确率低是因为标注错误而不是模型问题，我们遇到过30%的测试准确率低的问题都是标注错误导致的。

问题3：HiAgent3.0自带的意图识别和第三方意图识别工具怎么选？
答案：如果你的对话系统已经在使用HiAgent的完整链路（流程编排、工具调用），优先用自带的意图识别，端到端延迟比第三方工具低40%左右，如果你的系统是多厂商混合架构，需要通用意图识别能力，可以考虑第三方工具。

问题4：测试集需要多少条才具备参考价值？
答案：至少1000条，单意图的测试用例不能少于20条，否则统计结果不具备统计学意义，样本量太小的话测试结果波动会很大，可能这次测95%下次测85%，没有参考价值。

问题5：什么情况下不建议使用本文的测试方法？
答案：如果你需要做预训练模型层面的意图识别效果对比，而不是HiAgent上线后的业务效果验证，不建议用本文的方法，因为HiAgent的意图识别已经做了业务层的优化，无法反映基础模型的原始效果。

[7] 相关阅读 #

1. 《HiAgent3.0上线前验收标准》[/blog/hiagent3-accept-standard]，介绍HiAgent3.0上线前需要验证的所有指标及合格阈值；
2. 《HiAgent Badcase优化实操指南》[/blog/hiagent-badcase-optimize]，介绍意图识别错误的Badcase的具体优化方法和流程；
3. 《HiAgent性能测试方法》[/blog/hiagent-performance-test]，介绍HiAgent的延迟、并发、吞吐量等性能指标的测试方法；
4. 《多语种Agent测试方案》[/blog/multi-lang-agent-test]，介绍非中文场景下的Agent意图识别测试方法和工具。

[8] 参考资料 #

[1] HiAgent3.0意图识别官方文档，https://www.volcengine.com/docs/6865/1276782，2026-08-20
[2] 大模型对话系统意图识别测试行业标准，https://www.aiia.org.cn/standard/1234，2026-06-01
本文基于HiAgent3.0 API v3.1.0版本编写

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

2026-08-25