> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.
本文档介绍在扣子罗盘中评测扣子工作流的操作步骤。
## 功能概述 {#6599125f}
在扣子罗盘评测工作流时，你可以将工作流的线上 Trace 数据回流为评测集，也可以本地上传构造好的 CSV 文件、或者手动逐条创建评测数据。扣子罗盘会调用扣子[执行工作流](/developer_guides/workflow_run) OpenAPI 来获取工作流的输出结果，指定的评测集会作为 API 的请求参数。
## 场景描述 {#10c4c4da}
例如，你搭建了一个抖音爆款文案创作的工作流，希望验证该工作流生成的文案是否具有创造性和独特性。本文将演示如何通过评测集、LLM 评估器和实验来对该工作流进行评测。
## 前提条件 {#10a93521}
* 工作流已经过完善的试运行、调试，并已成功发布。
* 确保当前账号仍有足够的免费评测额度，或余额充足。
* 仅支持资源库中的工作流评测，暂不支持评测扣子应用工作流。
## 操作步骤 {#f79c8647}
### 步骤一：准备评测集 {#7bf6e1a1}
在评测场景中，评测集是一个精心设计的标准化测试数据集，通常包含输入样本和预期输出（可选）。输入样本作为评估对象的输入数据，预期输出提供了评估基准。在工作流评测中，准备评测集的本质是在构造[执行工作流](/developer_guides/workflow_run) OpenAPI 的请求数据，以便扣子罗盘成功调用 API 获取工作流的执行结果。你需要先新建评测集并声明[执行工作流](/developer_guides/workflow_run) OpenAPI 请求的数据结构，再将构造好的请求数据上传至评测集。
#### 工作流评测集要求 {#b09a9af4}
* 必须存在一个 Object 类型的字段，建议命名为 parameter。其中包含工作流开始节点定义的输入参数，尤其是必选参数；参数字段名称必须与工作流开始节点的变量名称完全匹配。
* 如果工作流输入参数为 Image 等类型的文件，可以直接使用公开可访问的文件 URL。
* 输入样本的数据类型应和工作流开始节点的变量类型匹配，同样地，输出样本的数据类型也应和结束节点的变量类型匹配。
* 如果工作流开始节点的输入参数是 Object 类型，还需要在评测集样本中增加对应的子字段。
#### 1 创建评测集 {#624f40ca}
1. 登录[扣子罗盘](https://loop.coze.cn)，在左侧导航栏顶部，选择一个工作空间。
2. 在左侧导航栏，选择**评测 > 评测集**，然后单击 **+ 新建评测集**。
3. 在**新建评测**集页面，填写评测集名称和描述。
4. 在配置列区域右侧，选择 **Coze 工作流**。
该操作可一键将评测集的列调整为兼容`执行工作流` OpenAPI 的数据格式。
5. 填写配置列，声明`执行工作流` OpenAPI 请求的数据结构，并单击**创建**。
参考以下信息配置评测集的输入数据列和输出列信息。创建成功后，系统会根据指定的数据列配置创建一个草稿版本的评测集。
| | | \
|**列名** |**配置说明** |
|---|---|
| | | \
|parameter |工作流开始节点的输入参数，你可以在指定工作流的编排页面查看参数列表。parameter 必须为 Object 格式，且必须包含所有必选参数、参数名称与类型和工作流完全一致。 |\
| |你可以在数据结构区域中单击 + 字段来新增输入参数，也可以导入一段 JSON 样例，扣子罗盘会自动解析 JSON 中的字段。如何为 parameter 构造 JSON 样例，并导入样例数据，可参考[配置列如何导入样例数据？](/cozeloop/evaluate_coze_workflow#d13d262a)。 |
| | | \
|bot_id |工作流需要关联的智能体 ID。部分工作流执行时需要指定关联的智能体，例如存在数据库节点、变量节点等节点的工作流。 |
| | | \
|ext |用于指定一些额外的字段，例如某些插件会隐式用到的经纬度等字段。目前仅支持latitude、longitude 和 user_id。 |
| | | \
|app_id |该工作流关联的应用的 ID。部分工作流执行时需要指定关联的应用，例如存在数据库节点、变量节点等节点的工作流。 |
| | | \
|reference_output |预期理想输出，可作为评估时的参考标准。 |
::::cols
@col 49
工作流设计：
@col 49
parameter 列配置：
::::
#### 2 准备评测数据 {#d55ab77e}
* **方式一：将 Trace 数据回流至评测集**
基于扣子罗盘支持的工作流 Trace 观测能力，你可以将 Workflow Trace Log 中的请求数据（调试日志、线上真实日志）回流到评测集中，作为回归测试数据。关于数据回流的详细说明，可参考[Trace 数据回流](/cozeloop/save-trace-to-dataset)。
此方式适用于对线上 BadCase 进行回归测试的场景。关于如何通过 Trace 数据识别 BadCase，可参考[Trace 自动评测](/cozeloop/auto-evaluation)。
1. 检索出工作流日志。
在**观测** > **Trace** 页面，设置过滤条件，检索出扣子工作流日志。
2. 添加到评测集。
点击**添加到评测集**，选择需要回流的 Trace Span 节点，再次确认添加到评测集。
::::cols
@col 50
@col 50
::::
3. 查看评测集样本 Span，配置映射的字段。
注意应确保字段映射中，左值 Span 变量的数据结构能够对应右值评测集列的数据结构，否则评测集将会根据[1 创建评测集](/cozeloop/evaluate_coze_workflow#624f40ca)时声明的校验规则（如字段必填）将不符合数据规范拦截下来。这可以帮你规范化评测集，过滤掉 Trace Log 中的噪音数据，避免在后续评测中引入额外的 Token 成本。
4. 点击预览并校验，查看回流到评测集后的效果。
::::cols
@col 50
进入预览页面
@col 50
查看预览数据
::::
5. 单击**开始导入**。
6. 进入此评测集的详情页，即可看到测试数据已经被成功回流至**草稿版本**，单击**提交新版本**。
* **方式二：本地上传**
如果你之前曾使用工作流的 API，平时在本地积累了一些调用 API 的测试数据，则可以将此类数据作为基础评测集，用于工作流每轮迭代前的准出基准评测集。
1. 本地准备测试数据，并导出为 CSV 文件。
列名与评测集列名对应，每列下每个单元格中的数据格式，对应你在[1 创建评测集](/cozeloop/evaluate_coze_workflow#624f40ca)中声明的工作流 API 请求数据结构一致。
2. 在评测集详情页面选择**添加数据** > **本地导入**，导入评测集，配置列映射。左侧为评测集列，右侧为 CSV 列。
* **方式三：手动添加**
在 parameter 中输入工作流开始节点的输入参数名称和待测试的参数值。目前 Object 仅支持 JSON 模式手动添加数据，您可以通过单击**字段补全** ，快速添加数据。
### 步骤二：准备评估器 {#b8caba11}
在评测过程中，评估器充当裁判的角色，通过量化评测对象的输出结果来评估其表现。在发起评测实验前，至少要创建一个评估器。在执行评测实验时，评估器会根据 Prompt 中预设的标准和规则对评估对象的输出进行打分，并提供得分原因。得分范围从 0.0 到 1.0，1.0 表示完全满足评分标准，0.0 表示完全不满足评分标准。
1. 在左侧导航栏选择**评测 > 评估器**，单击 **+ 新建评估器** > **LLM评估器**。
2. 在**评估器模板**页面，扣子罗盘提供了多个预置的模板，如果没有合适的模板，你也可以单击**自定义创建LLM评估器**创建评估器。
在本场景中，你需要评估爆款文案创作助手的创造性，因此选择**创造性**模板，单击**应用**。
3. 修改评估器的名称和模型，单击**调试**，测试一下评估器效果。
:::tip 说明
在调试评估器时，会产生 Token 消耗。
:::
4. 单击**创建**，单击**提交新版本**。完成评估器创建并提交评估器版本。
:::tip 说明
在创建评测实验时，只能使用已提交的评估器。
:::
### 步骤三：创建评测实验 {#35f2dedc}
在准备好评测集和评估器后，就可以发起实验来测试扣子工作流。每次评测实验仅支持评测一个工作流的一个指定版本，如需对比多个工作流版本，需要分别创建评测实验。
1. 在左侧导航栏，选择**评测 > 实验**，然后单击 **+ 新建实验**。
2. 输入一个实验名称，然后单击**下一步: 评测集**。
3. 选择已创建的评测集，并选择要使用的评测集版本，然后单击**下一步：评测对象**。
4. 配置评测对象，配置完成后单击**下一步：评估器**。
| | | \
|**配置** |**说明** |
|---|---|
| | | \
|类型 |评测对象的类型，此处应选择 **Coze 工作流**。 |
| | | \
|工作流名称 |选择待评测的工作流，仅支持选择当前工作空间资源库内**已发布的工作流**，不支持对话流。 |
| | | \
|版本 |指定工作流待评测的版本。 |\
| |仅支持评测发布版本，不支持评测草稿版本或提交版本。 |
| | | \
|字段映射 |配置评测对象和评测集的字段映射关系。 |\
| | |\
| |* **parameter**：工作流开始节点的输入参数。此处必须选择一个 Object 格式的字段，扣子罗盘会自动解析其中的子字段，并根据字段名一一映射为工作流的输入参数。 |\
| |* **bot_id**：工作流需要关联的智能体 ID。 部分工作流执行时需要指定关联的智能体，例如存在数据库节点、变量节点等节点的工作流。 |\
| |* **ext**：用于指定一些额外的字段，例如某些插件会隐式用到的经纬度等字段。目前仅支持latitude、longitude 和 user_id。 |\
| |* **app_id**：该工作流关联的应用的 ID。部分工作流执行时需要指定关联的应用，例如存在数据库节点、变量节点等节点的工作流。 |\
| | |\
| |:::tip 说明 |\
| |工作流的所有必选输入参数均应映射到对应的评测集字段，否则评测实验可能执行失败。 |\
| |::: |
5. 单击**添加评估器**，选择已创建的评估器和版本，然后将评测集的字段、评测对象的实际输出与评估器的参数关联，确保评估器准确获取数据并执行评估，最后单击**确认实验配置**。
6. 检查实验配置，确认无误后，单击**发起实验**。
发起实验后，你可以刷新实验页面，查看评估进度。
### 步骤四：分析实验结果 {#5ca9cf64}
在评估器执行完所有评估任务后，你可以在实验页面查看实验报告。通过实验报告来判断评估对象是否符合预期。
#### 查看评测结果 {#67563eb5}
在**数据明细**页面，你可以查看评估器对每个测试数据的执行结果的评分，以及评分的具体原因。
如果某个测试数据的评估器自动打分不准确，你可以将鼠标悬浮至评分上，然后点击出现的**人工校准**图标。在弹出的页面中输入修正的分数和原因。
#### 查看实验报告 {#f81ecab6}
在**实验详情**页面，单击**指标统计**页签查看实验数据报告。
## 常见问题 {#c0ee4053}
### 配置列如何导入样例数据？ {#d13d262a}
扣子推荐你在配置评测集字段时，对于 parameter 等 Object 类型的字段，可以直接导入 JSON 格式的工作流的输入参数，提升评测集的构建效率。输入 JSON 之后，系统会自动解析字段，并以此定义评测集字段。操作方式如下：
1. 获取 JSON 格式的工作流的输入参数。
在工作流编排页面单击试运行，开启 JSON 格式，并复制 “_input” 字段值。注意复制的 JSON 中只包含开始字段的参数。
2. 导入 JSON 样例，自动解析字段。
::::cols
@col 33
在新建评测集的页面，找到 Object 类型的字段（例如 parameter），单击**导入样例数据**。
@col 33
将复制好的 JSON 填入样例区域，单击提取数据结构。
@col 33
查看导入效果，并确认字段配置，例如字段名、数据类型、是否必选等。
::::