Trace数据回流
当您的智能体上线运行后，平台的观测模块会通过Trace（调用链追踪）记录下每一次交互的底层埋点数据。
面对海量的Trace和几十个生涩的字段，我们该如何挑选？又该在什么场景下将它们回流到数据集？在操作之前，请先了解底层的核心概念与平台的评测机制。
读懂Trace与Span
把智能体处理用户请求的过程想象成一次“快递运输”，Trace就是这趟运输的完整物流总单，而Span就是途经的每一个监测节点。
在筛选数据时，您会看到三种Span类型，它们的含义截然不同：
- Root Span（根节点）
- 含义：代表从用户发起提问，到智能体给出最终回答的端到端完整生命周期。
- 作用：如果您想看用户最初问了什么（原始Input），以及智能体最终答了什么（最终Output），请筛选此项。
- Model Span（模型调用节点）
- 含义：这不是指画布上的某个功能节点，而是底层真实调用大模型（LLM）API的那一次精确埋点动作。
- 作用：它记录了系统经过知识库组装、Prompt模板拼接后，真实发给大模型的完整Prompt，以及大模型吐出的原始Output。用于排查“模型到底看到了什么上下文”。
- All Span（全量节点）
- 含义：包含当前Trace下的所有埋点记录汇总（包括Root、Model、以及底层的工具请求、知识检索等中间过程）。
- 作用：数据最为繁杂，通常仅供高级开发者在进行底层深级排障溯源时使用。
场景化选型：离线回流vs在线评估
针对不同类型的智能体的评估时，数据要求差异巨大。受限于平台当前的离线数据集形态（标准的Input/Output结构），并非所有场景都适合使用“Trace回流数据集”的方式进行评估。
请根据您需要评估的智能体类型，选择最科学的数据处理与评估方法：
场景一：评估智能创作智能体
- 评测特点：只需关注“输入的问题”和“输出的答案/分类标签”是否正确。
- 推荐：【离线评估+数据集回流】
- 操作策略：在Trace列表中筛选回流的数据，在导入配置页面勾选input和output字段回流至数据集。
- 自优化/评测前提：回流后，请务必人工将output列的数据修改为正确的标准答案，再进行常规的“正确性评估”。
场景二：评估RAG智能体（知识库问答）
- 评测特点：要评估RAG是否“胡编乱造（产生幻觉）”，评估器必须同时看到：
- 用户问题
- 预期答案
- 当时检索召回的知识库原文切片 (Context)
- 平台局限：目前的“Trace离线回流”功能，无法直接将知识库的中间召回片段映射到数据集的表格列中。
- 推荐：【在线评测】
- 操作策略：放弃构造繁琐的离线数据集。直接在平台的评估模块中创建一个“在线评估任务”。
- 优势：在线评估会直接与运行中的智能体绑定。当智能体进行实时问答时，系统会自动抓取底层的Root Span及调用链中的知识召回数据，传递给“幻觉评估器”进行实时打分。
场景三：评估工具调用智能体
- 评测特点：重点不在于最终回答，而在于“工具是否被正确触发”、“传入API的参数是否准确”。
- 平台局限：工具的原始请求体与返回结构极其复杂，无法通过简单的input/output回流到基础数据集中。
- 推荐：【在线评测】
- 操作策略：同样采用在线评估模式，在创建评估任务时，评估粒度选择“工具”维度。
- 优势：评估器会深入智能体的运行态，实时监测工具调用的中间过程（工具调用Span），评估工具选择准确率与入参规范性。
前提条件
已创建评测集。创建评测集请参考评测集。
使用限制
|
限制 |
说明 |
|---|---|
|
单次回流的数据量 |
单次回流最多选择200条数据。如需导入更多数据，建议分批次进行。 |
|
数据类型 |
配置数据字段和评测集字段的映射关系时，应确认前后的数据类型完全一致，否则可能因数据类型不匹配导致数据回流失败。 |
|
评测集数据条数上限 |
每个评测集的数据条目数量上限为500条。 |
|
数据上报限制 |
仅通过API调用产生的数据才会上报到运营运维。使用API调用智能体，请参考《最佳实践》中“API调用实践”章节。 |
步骤一：选择Trace数据
- 登录AgentArts智能体开发平台。
- 在左侧导航栏中选择“运营运维 > 观测”。
- 在“调用链分析”页面中，筛选出目标Trace数据。
- 勾选需要回流的Trace数据，单击右上角的“添加到评测集”。
图1 添加至评测集
步骤二：配置回流规则
在“添加到评测集”的对话框中，配置Trace数据回流的规则。
数据导出到评测集时，请遵循评测集的约束与限制，具体说明请参见约束与限制。
|
参数 |
说明 |
示例 |
|---|---|---|
|
目标评测集 |
数据需要添加到哪个评测集，目前仅支持选择已有评测集。 |
已有评测集 |
|
目标评测集名称 |
选择Trace数据具体要添加到目标评测集的名称。 |
企业知识数据集 |
|
目标评测集列 |
展示已选择的目标评测集中已有的列名。 |
input reference_output |
|
导入方式 |
Trace数据导入评测集的方式，支持追加数据或全量覆盖。
|
选择“追加数据” |
|
字段映射 |
设置需要回流的数据字段和评测集字段的映射关系。 在执行“回流至评测集”时，系统会提供众多可选字段。请不要全部勾选，建议根据您的用途进行“准确提取”，详细信息请参考表2。
注意：
请确保回流的Trace字段与评测集字段的数据类型一致，否则将导致回流失败。 |
配置示例请参考图2 |
|
字段类别 |
字段名称 |
说明 |
|---|---|---|
|
核心问答类 (最常用) |
input |
用户提问或当前节点的上游输入。 |
|
output |
智能体的回答或当前节点的输出结果。 |
|
|
性能类 |
duration |
当前Span执行花费的时间（用于评估延迟）。 |
|
tokens |
大模型处理该次请求消耗的Token数量（用于评估成本与冗余度）。 |
|
|
input_tokens |
||
|
output_tokens |
||
|
start_time |
执行开始的时间戳，记录请求发起的具体时间。 |
|
|
溯源类 |
trace_id |
唯一追踪码。建议回流时带上trace_id。当发现评测BadCase时，可拿着该ID回到观测页面查看智能体的完整运行记录。 |
|
span_id |
||
|
session_id |
会话ID。多轮对话的追踪标识，用于将同一个用户的上下文串联起来。 |
|
|
is_error |
运行状态。记录该次调用是否发生了底层报错。 |
|
|
调用链上下文态类 |
call_type |
触发类型，表示当前数据产生时是通过什么方式触发的。 |
|
span_type |
Span类型，用于进一步细化分类操作的类别。 |
|
|
span_name |
Span名称，描述具体的操作动作或节点名称（如“调用大模型”、“搜索知识库”） |
|
|
status_code |
状态码，返回HTTP状态码或业务自定义错误码。 |
|
|
资源与扩展信息类 |
feedback_operation |
用户反馈操作，记录用户对结果的评价行为（如点赞、点踩）。 |
|
metadata |
元数据信息，以Key-Value形式存储额外的扩展信息。 |
|
|
resource_id |
产生该条Trace数据的智能体的ID。 |
|
|
resource_name |
产生该条Trace数据的智能体的名称。 |
|
|
resource_type |
产生该条Trace数据的智能体的类型。 |
步骤三：添加至评测集
- 单击“校验并预览”，查看字段映射的效果，确认无误单击“确定”。
图3 效果预览
- 单击“开始导入”，导入成功后，可以在“评估 > 评测集”页面中找到目标评测集，单击评测集名称进入详情页面查看导入的数据。
