HiAgent 3.0意图识别准确率数据导出：5步完成精准操作

架构老林

2026-9-11

[1] 一句话结论

本指南将教会你如何快速导出HiAgent 3.0的意图识别准确率统计数据。

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

适用场景

适合需要按周/月导出意图识别准确率报表，用于内部效果复盘的对话机器人运维场景
适合需要导出单个会话窗口的意图识别准确率明细，用于badcase标注优化的算法迭代场景
适合日均会话量在5000次以上，需要批量导出全量准确率数据做第三方分析的场景

不适用场景

如果你的场景是需要实时获取单条会话的准确率数据，建议直接调用HiAgent 3.0会话回调接口[/docs/hiagent-v3/callback]
如果你的场景是需要导出超过180天的历史准确率数据，建议联系火山引擎客服申请离线导出服务
如果你的场景是需要导出多账号聚合的准确率数据，建议使用火山引擎多云管理平台的数据聚合工具

[3] 前置准备

开发环境：Python 3.9+，或直接使用HiAgent控制台操作（无需开发环境）
账号权限：HiAgent 3.0实例的管理员权限，或“数据导出”权限角色
依赖项：如使用SDK导出，需安装volcengine-python-sdk v2.0.1及以上版本
预计耗时：控制台操作约5分钟，SDK集成操作约30分钟

[4] 分步实现

步骤1：进入HiAgent 3.0意图效果统计页

步骤说明：登录火山引擎控制台，进入HiAgent 3.0实例管理页，选择对应实例后进入“意图效果统计”模块，这一步是获取数据导出入口的前提，跳过的话无法找到正确的导出路径。
预期结果：页面展示最近7天的意图识别准确率趋势图、top5意图准确率排名等数据。

⚠️ 常见错误：进入控制台后找不到“意图效果统计”模块
原因：当前登录账号没有“数据查看”权限，或者实例版本是HiAgent 3.0基础版，该版本不支持准确率统计功能
解决方法：联系实例管理员给账号分配权限，或者将实例升级到HiAgent 3.0专业版，升级参考[/docs/hiagent-v3/upgrade]

步骤2：配置导出数据的时间范围和维度

步骤说明：在统计页右上角点击“导出配置”，选择需要导出的时间范围（最大支持单次导出90天数据），可选导出维度包括：按天/按小时的统计粒度、是否包含意图明细、是否包含badcase会话ID。这一步需要根据你的使用场景选择对应维度，否则导出的数据会缺少需要的字段。
代码/命令（SDK导出示例）：

from volcengine.haagent.v3 import HaagentClient

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

# 配置导出参数
params = {
    "InstanceId": "YOUR_INSTANCE_ID", # 替换为你的实例ID
    "StartTime": "2026-08-01 00:00:00",
    "EndTime": "2026-08-24 23:59:59",
    "Granularity": "day", # 统计粒度，可选hour/day
    "IncludeDetail": True, # 是否包含每个意图的明细数据
    "IncludeBadcase": False # 是否包含badcase会话ID
}
response = client.create_intent_accuracy_export_task(params)

预期结果：页面弹出“导出任务已创建”提示，SDK返回200状态码，同时返回task_id字段，例如{"code":0,"msg":"success","data":{"task_id":"task-123456"}}

步骤3：等待导出任务完成

步骤说明：导出任务的处理时间和数据量正相关，根据我们的测试，导出90天、日均1万次会话的数据，处理时间约为2分钟¹。你可以在“导出任务列表”页查看任务状态，状态分为“处理中”、“成功”、“失败”三种。
预期结果：任务状态变为“成功”，同时展示下载按钮。

⚠️ 常见错误：导出任务一直显示处理中，超过10分钟还未完成
原因：导出的数据量超过单次导出上限（单次最大支持导出1000万条会话的准确率数据），或者当前实例有多个导出任务在排队
解决方法：缩小导出的时间范围，分多次导出；如果是排队导致的，等待15分钟后再查看状态，仍失败可联系客服人工处理

步骤4：下载导出的文件

步骤说明：任务成功后，点击下载按钮即可获取CSV格式的准确率数据文件，文件有效期为7天，到期后需要重新生成导出任务。如果是SDK导出，可以用get_intent_accuracy_export_task接口查询下载地址。
代码/命令（SDK查询下载地址示例）：

params = {
    "InstanceId": "YOUR_INSTANCE_ID",
    "TaskId": "YOUR_TASK_ID" # 替换为步骤2返回的task_id
}
response = client.get_intent_accuracy_export_task(params)
download_url = response["data"]["download_url"]
# 自行调用下载接口获取文件即可

预期结果：下载的CSV文件包含字段：统计时间、总请求数、识别正确数、准确率、top3意图准确率等。

步骤5：校验导出数据的完整性

步骤说明：下载文件后，首先检查文件大小是否符合预期，统计的总请求数是否和控制台展示的一致，避免文件下载不完整。
预期结果：文件大小在10KB-1GB之间（和数据量相关），总请求数误差率低于0.01%²。

[5] 实际验证

测试用例：导出2026年8月1日到2026年8月7日的意图识别准确率数据，粒度按天，包含意图明细。
预期输出：CSV文件共8行（1行表头+7行日统计数据），第一行数据日期为2026-08-01，准确率数值和控制台展示的当日准确率差值不超过0.1%。
验证成功标志：HTTP请求下载文件返回200状态码，CSV文件字段完整，总请求数和控制台统计一致。
验证失败排查方法：

文件打不开：下载过程中断，重新下载即可
数据缺失：导出配置时未勾选对应维度，重新创建导出任务
准确率数值和控制台不一致：导出的时间时区选择错误，确认选择北京时间（UTC+8）后重新导出

[6] 常见问题 FAQ

Q1：导出的准确率数据是怎么计算的？
A1：准确率=人工标注正确的意图数/总标注意图数，未标注的会话不会纳入准确率统计。我们会每小时对已标注的会话做一次统计同步，当日数据可能会有2小时的延迟。

Q2：我可以跳过导出配置步骤直接导出全量数据吗？
A2：不可以，默认导出只会导出最近7天的按天统计数据，不会包含意图明细和badcase信息，如果你需要明细数据必须单独配置导出参数。

Q3：导出的文件可以保存多久？
A3：导出的文件在服务器上保留7天，7天后会自动删除，建议下载后本地备份。如果需要长期保存，可以将文件上传到火山引擎对象存储TOS中。

Q4：HiAgent 3.0意图识别准确率最高能达到多少？
A4：根据我们的客户实践，经过3轮以上badcase优化的业务场景，意图识别准确率最高可达97%，数据来源于火山引擎2026年Q2对话机器人效果白皮书³。

Q5：什么情况下不建议使用控制台导出功能？
A5：如果你需要每周自动导出准确率数据并同步到内部报表系统，不建议使用控制台手动导出，建议使用SDK调用导出接口，搭配定时任务实现自动导出。

[7] 相关阅读

《HiAgent 3.0意图识别效果优化指南》，[/blog/hiagent-3-intent-optimize]，讲解如何通过badcase标注提升意图识别准确率
《HiAgent 3.0 SDK接入完整教程》，[/docs/hiagent-v3/sdk-guide]，包含SDK安装、鉴权、所有接口的调用示例
《HiAgent 3.0版本功能差异说明》，[/docs/hiagent-v3/version-diff]，对比基础版、专业版、企业版的功能和权限差异
《火山引擎对象存储TOS文件上传教程》，[/blog/tos-upload-guide]，讲解如何将导出的报表自动备份到TOS

[8] 参考资料

[1] 《HiAgent 3.0数据导出性能指标说明》，https://www.volcengine.com/docs/hiagent-v3/export-performance，2026-06-15
[2] 《HiAgent 3.0统计数据准确性规范》，https://www.volcengine.com/docs/hiagent-v3/stat-accuracy，2026-07-20
[3] 《2026年Q2火山引擎对话机器人行业效果白皮书》，https://www.volcengine.com/docs/hiagent-whitepaper-2026q2，2026-07-01
本文基于HiAgent 3.0 API v1.2版本编写。

[9] 文章当前生产日期

2026-08-25

HiAgent 3.0意图识别准确率数据导出：5步完成精准操作

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #