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条数据。如需回流更多数据，建议分批次进行。
数据类型	配置数据字段和评测集字段的映射关系时，应确认前后的数据类型完全一致，否则可能因数据类型不匹配导致数据回流失败。
评测集数据条数上限	每个评测集的数据条目数量上限为5000条。
数据上报限制	仅通过API调用产生的数据才会上报到运营运维模块。控制台调试和编排预览不计入统计。使用API调用智能体，请参考API调用实践。

步骤一：选择Trace数据

登录AgentArts智能体平台。
在左侧导航栏中选择“运营运维 > 观测”。
在“调用链分析”页面中，筛选出目标Trace数据。
勾选需要回流的Trace数据，单击右上角的“添加到评测集”。
图1 添加至评测集

步骤二：配置回流规则

在“添加到评测集”的对话框中，配置Trace数据回流的规则。

数据导出到评测集时，请遵循评测集的约束与限制，具体说明请参见约束与限制。

图2 配置回流规则

表1 配置回流规则
参数	说明	示例
目标评测集	数据需要添加到哪个评测集，目前仅支持选择已有评测集。如无可用评测集，请先创建评测集。	已有评测集
目标评测集名称	选择Trace数据具体要添加到目标评测集的名称。	企业知识数据集
目标评测集列	展示已选择的目标评测集中已有的列名。	input，reference_output
导入方式	Trace数据导入评测集的方式，支持追加数据或全量覆盖。追加数据：在评测集已有数据下新增Trace数据。应确保导入选择的数据后，评测集的数据不超过上限（5000条）。全量覆盖：清除评测集已有数据后，新增数据。选择“全量覆盖”将清除目标评测集当前版本的所有已有数据，如需恢复，可通过评测集的“版本历史”功能还原至覆盖前的版本。	选择“追加数据”
字段映射	设置需要回流的数据字段和评测集字段的映射关系。在执行“回流至评测集”时，系统会提供众多可选字段。请不要全部勾选，建议根据您的用途进行“准确提取”，详细信息请参考表2。选择需要回流的Trace字段。支持回流trace_id、span_id、input和output等信息。设置对应的评测集字段，设置Trace字段回流至评测集的指定列。支持选择回流到评测集已有列或新增列，不支持多个Trace字段回流到评测集同一列。注意：请确保回流的Trace字段与评测集字段的数据类型一致，否则将导致回流失败。如遇数据类型冲突，请参考常见问题进行排查。	配置示例请参考图2

表2 回流字段
字段类别	字段名称	说明
核心问答类 (最常用)	input	用户提问或当前节点的上游输入。
核心问答类 (最常用)	output	智能体的回答或当前节点的输出结果。
性能类	duration	当前Span执行花费的时间（用于评估延迟）。
	tokens	大模型处理该次请求消耗的Token总量（用于评估成本与冗余度）。
	input_tokens	大模型处理输入消耗的Token数量。
	output_tokens	大模型处理输出消耗的Token数量。
	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数据的智能体的类型。

步骤三：添加至评测集

单击“校验并预览”，查看字段映射的效果。
预览页面将展示字段映射后的前几条数据样例，请核对Trace字段是否正确映射到评测集对应列，数据内容是否完整。
图3 效果预览
确认无误单击“确定”。
单击“开始导入”，导入成功后，可以在“评估 > 评测集”页面中找到目标评测集，单击评测集名称进入详情页面查看导入的数据。
请核对评测集中的数据条数是否与回流的Trace数据条数一致。