# Trace数据回流 当您的智能体上线运行后，平台的观测模块会通过Trace（调用链追踪）记录下每一次交互的底层埋点数据。 面对海量的Trace和几十个生涩的字段，我们该如何挑选？又该在什么场景下将它们回流到数据集？在操作之前，请先了解底层的核心概念与平台的评测机制。 #### 读懂Trace与Span 把智能体处理用户请求的过程想象成一次"快递运输"，**Trace** 就是这趟运输的完整物流总单，而**Span**就是途经的每一个监测节点。 在筛选数据时，您会看到四种Span类型，它们的含义截然不同： - **Root Span（根节点）** - **含义** ：代表从用户发起提问，到智能体给出最终回答的**端到端完整生命周期**。 - **作用**：如果您想看用户最初问了什么（原始Input），以及智能体最终答了什么（最终Output），请筛选此项。 - **Model Span（模型调用节点）** - **含义** ：这不是指画布上的某个功能节点，而是底层**真实调用大模型（LLM）API**的那一次精确埋点动作。 - **作用** ：它记录了系统经过知识库组装、Prompt模板拼接后，**真实发给大模型的完整Prompt** ，以及大模型返回的原始**Output**。用于排查"模型到底看到了什么上下文"。 - **Tool Span（工具调用节点）** - **含义**：智能体中调用工具的执行节点。 - **作用**：记录工具调用的输入参数与返回结果。用于排查工具执行是否成功、参数传递是否正确。 - **All Span（全量节点）** - **含义**：包含当前Trace下的所有埋点记录汇总（包括Root、Model、以及底层的工具请求、知识检索等中间过程）。 - **作用**：数据最为繁杂，通常仅供高级开发者在进行底层深度排障溯源时使用。 #### 场景化选型：离线回流vs在线评估 针对不同类型的智能体的评估时，数据要求差异巨大。**受限于平台当前的离线数据集形态（标准的Input/Output结构），并非所有场景都适合使用"Trace回流数据集"的方式进行评估。** 请根据您需要评估的智能体类型，选择最科学的数据处理与评估方法。 #### 场景一：评估智能创作智能体 - **评测特点**：只需关注"输入的问题"和"输出的答案/分类标签"是否正确。 - **推荐：【离线评估+数据集回流】** - **操作策略** ：在Trace列表中筛选**需要** **回流的数据**，在导入配置页面勾选input和output字段回流至数据集。 ![](https://support.huaweicloud.com/ops-agentarts/public_sys-resources/note_3.0-zh-cn.png) **评测前提** ：回流后，请务必人工将output列的数据修改为**正确的标准答案**，再进行常规的"正确性"评估。 #### 场景二：评估RAG智能体（知识库问答） - **评测特点** ：要评估RAG是否"胡编乱造（产生幻觉）"，评估器必须同时看到： - 用户问题 - 预期答案 - **当时检索召回的知识库原文切片（Context）** - **平台局限**：目前的"Trace离线回流"功能，无法直接将知识库的中间召回片段映射到数据集的表格列中。 - **推荐：【在线评测】** - **操作策略** ：放弃构造繁琐的离线数据集。直接在平台的评估模块中创建一个**"在线评估任务"**。 - **优势**：在线评估会直接与运行中的智能体绑定。当智能体进行实时问答时，系统会自动抓取底层的Root Span及调用链中的知识召回数据，传递给"幻觉评估器"进行实时打分。 #### 场景三：评估工具调用智能体 - **评测特点**：重点不在于最终回答，而在于"工具是否被正确触发"、"传入API的参数是否准确"。 - **平台局限**：工具的原始请求体与返回结构极其复杂，无法通过简单的input/output回流到基础数据集中。 - **推荐：【在线评测】** - **操作策略** ：同样采用**在线评估** 模式，在创建评估任务时，评估粒度选择**"工具"**维度。 - **优势**：评估器会深入智能体的运行态，实时监测工具调用的中间过程（工具调用Span），评估工具选择准确率与入参规范性。 #### 前提条件 已创建评测集。创建评测集请参考[评测集](https://support.huaweicloud.com/ops-agentarts/agentarts_14_0026.html)。 #### 使用限制 | **限制** | **说明** | |:---|:---| | 单次回流的数据量 | 单次回流最多选择200条数据。如需回流更多数据，建议分批次进行。 | | 数据类型 | 配置数据字段和评测集字段的映射关系时，应确认前后的数据类型完全一致，否则可能因数据类型不匹配导致数据回流失败。 | | 评测集数据条数上限 | 每个评测集的数据条目数量上限为5000条。 | | 数据上报限制 | 仅通过**API调用** 产生的数据才会上报到运营运维模块。控制台调试和编排预览不计入统计。使用API调用智能体，请参考[API调用实践](https://support.huaweicloud.com/bestpractice-agentarts/agentarts_06_0020.html)。 | #### 步骤一：选择Trace数据 1. 登录[AgentArts智能体平台](https://console.huaweicloud.com/agentarts/#/home/overview)。 2. 在左侧导航栏中选择"运营运维 \> 观测"。 3. 在"调用链分析"页面中，筛选出目标Trace数据。 4. 勾选需要回流的Trace数据，单击右上角的"添加到评测集"。 图1添加至评测集 ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002687916062.png) #### 步骤二：配置回流规则 在"添加到评测集"的对话框中，配置Trace数据回流的规则。 ![](https://support.huaweicloud.com/ops-agentarts/public_sys-resources/caution_3.0-zh-cn.png) 数据导出到评测集时，请遵循评测集的约束与限制，具体说明请参见[约束与限制](https://support.huaweicloud.com/ops-agentarts/agentarts_14_0027.html#agentarts_14_0027__section1816414279312)。 图2配置回流规则 ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002717835531.png) 表1配置回流规则 | 参数 | 说明 | 示例 | |:---|:---|:---| | 目标评测集 | 数据需要添加到哪个评测集，目前仅支持选择已有评测集。如无可用评测集，请先创建评测集。 | 已有评测集 | | 目标评测集名称 | 选择Trace数据具体要添加到目标评测集的名称。 | 企业知识数据集 | | 目标评测集列 | 展示已选择的目标评测集中已有的列名。 | input，reference_output | | 导入方式 | Trace数据导入评测集的方式，支持追加数据或全量覆盖。 - **追加数据** **：**在评测集已有数据下新增Trace数据。应确保导入选择的数据后，评测集的数据不超过上限（5000条）。 - **全量覆盖：** 清除评测集已有数据后，新增数据。选择"全量覆盖"将清除目标评测集当前版本的所有已有数据，**如需恢复，可通过评测集的"版本历史"功能还原至覆盖前的版本。** | 选择"追加数据" | | 字段映射 | 设置需要回流的数据字段和评测集字段的映射关系。 在执行"回流至评测集"时，系统会提供众多可选字段。请不要全部勾选，建议根据您的用途进行"准确提取"，详细信息请参考[表2]。 1. **选择需要回流的Trace字段**。支持回流trace_id、span_id、input和output等信息。 2. **设置对应的评测集字段**，设置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 | 当前Span的唯一标识码。用于在调用链中精确定位具体节点。 | | 溯源类 | 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数据的智能体的类型。 | #### 步骤三：添加至评测集 1. 单击"校验并预览"，查看字段映射的效果。 预览页面将展示字段映射后的前几条数据样例，请核对Trace字段是否正确映射到评测集对应列，数据内容是否完整。 图3效果预览 ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002687916064.png) 2. 确认无误单击"确定"。 3. 单击"开始导入"，导入成功后，可以在"评估 \> 评测集"页面中找到目标评测集，单击评测集名称进入详情页面查看导入的数据。 请核对评测集中的数据条数是否与回流的Trace数据条数一致。 #### 常见问题 - **导入时提示"评测集数据条数上限"如何处理？** 每个评测集最多支持5000条数据。如果您选择"追加数据"时触发此提示，建议清理不使用的数据后重试。 - **导入数据时提示** **"数据类型解析错误，不支持当前类型 \[\], 期望类型 \[String\]"如何处理？** 检查需要导出的字段类型和评测集的字段类型是否一致。如果字段类型不一致，请更换或新建数据类型一致的评测集后重试。 图4报错信息 ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002717835535.png) - **回流操作完成后，评测集中没有数据怎么办？** 请按以下顺序排查： 1. 确认导入方式是否选择了"追加数据"且未超过评测集数据上限。 2. 确认字段映射的数据类型是否一致。 3. 确认选择的Trace数据是否在筛选时间范围内。 - **选择"全量覆盖"后，原有评测集数据还能恢复吗？** 可以。评测集支持版本历史管理，全量覆盖后，您可以通过评测集详情页面中"版本历史"功能还原至覆盖前的版本。操作方法：在评测集详情页面，单击右上角"版本历史"，在目标历史版本上单击"还原版本"即可。 图5评测集版本历史 ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002717675673.png)