实验是指通过组合评测数据集、评测对象、若干评估器三元组，执行评测动作得到实验结果的过程。通过分析实验结果，可以获得有助于业务决策的信息。本文档指导你如何创建和启动评测实验。 # 实验流程概述 AgentKit 支持的评估对象是你在 AgentKit 中创建的应用。你需要先准备评测集和评估器，然后才能发起评测实验。实验流程如下： 1. **指定评测集**：构建包含输入样本的数据集，可选择性地添加预期输出作为评估参考。 2. **添加评估器**：配置至少一个评估器执行评测任务。AgentKit 支持 LLM 和 Code 评估器，可自动对评测对象的输出进行多维度评估。 3. **分析实验结果**：实验完成后，通过详细的数据分析报告对评估对象进行效果验证和优化迭代。 # 创建实验在创建实验前，确保已构建评测集。参考以下步骤，创建实验。 1. 登录 [AgentKit控制台](https://console.volcengine.com/agentkit)。 2. 在左侧导航栏，选择**评测 \> 实验**，然后单击 **+ 新建实验**。如下图所示，你也可以在评测集详情页面，单击 ** + 新建实验**来创建时间。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b23122672a83bafdf5168e302eb4c182.png) 3. 填写基础信息。输入实验名称和描述，然后单击**下一步: 评测集**。 4. 选择评测集。选择已创建的评测集，并选择要使用的评测集版本，然后单击**下一步：评测对象**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_4ee8aa6323edb696f575d6cbb3d561b2.png =601x) 5. （可选）设置评测对象。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_cab16f01b0afd286e2588d9bb98f6ac8.png =597x) 7. （可选）设置评估器。为评测实验设置评估器。 * 如果你没有准备评估器，AgentKit 提供一系列预置评估器供你选择。如果没有合适的预置评估器，你也可以根据页面提示，基于评估器模板创建一个符合当前评测场景的自建评估器。准备好评估器之后，参考以下步骤为评测实验设置评估器。 1. 在**4.评估器**页签中选择已创建的评估器和版本。 2. 将评测集的字段、评测对象的实际输出actual_output与评估器的参数关联，确保评估器准确获取数据并执行评估。 3. 单击**确认实验配置**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_5fc8b478fce0a4925fb799a12acd1f89.png =663x) 7. 在页面底部，设置**最大并发执行条数**。评测实验支持并发执行评测集中的条目，默认为 5 条，最大可设置为 50 条。这里你需要设置理想的最大执行条数，但实际生效的并发数受限于评测对象的并发度限制和调用评估器的模型 TPM 限制。 8. 检查实验配置，确认无误后，单击**发起实验**。发起实验后，你可以刷新实验页面，查看评估进度。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c46997aca9a2bd6254e2ce3500b21618.png) # 实验洞察：单实验分析通过单次实验报告，开发者可以通过「宏观」维度的指标统计，与「微观」视角的数据明细，分析洞察本次实验评测对象的效果，进而支撑业务决策。 ## 指标统计在**指标统计**页面，可查看聚合得分、得分分布。 ### 查看聚合得分 * 查看本次实验中，评测对象在各个评估指标上的聚合得分。 * 聚合方式：平均、最大、最小、求和。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_fcce9c119a7444c0e691e75da5c8e5f6.png =505x) ### 查看得分分布查看本次实验中，评测对象的所有评测数据，在各个评估指标上的得分分布占比。例如，10 条评测数据，正确性指标得分情况：一条 0.8 分，一条 0.6 分，一条 0.3 分，一条 0.5 分，其余为 1 分。单击**指标统计**，查看正确性的得分分布。只统计 Top5 分数与占比情况，长尾得分归入其他。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_86238a8c1f295a640bb734eb3595bf0c.png =464x) ## 数据明细在**数据明细**页面，可调整页面展示、配置过滤器，并详细分析评测数据。 ### 可视化调整在列管理中，隐藏不关注的指标、视图调整（紧凑宽松视图切换）调整到方便分析的方式。 ### 搜索和过滤数据实验完成后，你可以在实验结果页面对实验结果进行模糊搜索和筛选。 * 通过筛选器，你可以基于统计指标中较差的指标、或者不符合预期的指标，通过过滤器筛选出来在目标指标上得分较低的 badcase。筛选范围是实验结果的所有列。 * 通过模糊搜索，你可以快速定位到匹配关键词的数据项，提高分析效率。目前模糊搜索的范围包括评测集的列数据、评测对象的输出、数据项的 ID。其中数据项的 ID 必须是完全匹配。 * 搜索框和过滤器均支持通过 Shift+Enter 进行换行。 * 隐藏的列不在筛选或检索的范围内。对于 Object 和 Array 类型的数据，开发者上传的数据结构中可能会存在大量的空格、换行符和符号 { } [ ] : , 。扣子罗盘存储数据时，会保留 key、value 中的空格和换行符，移除评测集、实际输出列中的其他空格、换行符后再进行存储。所以在检索这些复杂结构时，你需要确保关键字和空格、回车等都完全匹配。例如： |**数据类型** |**原始结构示例** |**检索引擎存储内容** | |---|---|---| |Object |```Plain Text|```Plain Text|\ | |{|{"key1":"hello world","key2":"look"}|\ | ||```|\ | || |\ | | "key1" ： "hello world",| |\ | | | |\ | | "key2": "look"| |\ | |}| |\ | |```| |\ | | | | |Array |```Plain Text|```Plain Text|\ | |[|["hello world", "look"]|\ | ||```|\ | || |\ | |"hello world", "look"| |\ | |]| |\ | |```| |\ | | | | ## 分析评测数据查看并分析详细评测数据项，以优化评估过程： * 分支1：查找评测对象的异常案例。 * 检查得分及其原因，人工核对评测集输入与实际输出，识别评估不准确的异常案例。 * 点击 **actual_output** 列下的输出内容旁边的 Trace 图标查看评测对象的 Trace 链路，结合 Trace 排查问题原因。 * 进入下一轮迭代优化 * 分支2：评估器评估不准确的异常案例。 * 检查得分及其原因，人工核对评测集输入与实际输出，识别评估器评估不准确的异常案例。 * 点击**评估指标**对应的 Trace 图标查看评估器的 Trace 链路，结合 Trace 排查问题原因。 * 人工校准得分刷新数据明细页面，指标统计页面也会联动刷新。然后，再进行对比分析。通过单实验报告的分析，评估评测对象的整体表现，识别异常案例并进行问题排查定位，指导业务决策。 # 实验洞察：多实验对比分析在真实的开发环境中，单实验分析可能无法满足需求。因为随着评测对象的迭代，常常会出现多个版本（例如多种 Prompt 优化策略）。开发者需要评估这些版本在目标指标上的优化情况，以及现有功能指标是否出现退化。为此，多实验对比分析功能为开发者提供： * 控制变量的实验思路：保持评测集和评估器不变，针对评测对象的不同版本进行实验。 * 设置对照组（基准）和多个实验组（开发过程中可能通过调优产生了多个版本）。 * 提供指标统计和数据明细，帮助开发者从「宏观」角度对比多个实验的整体优劣，从「微观」视角比较每条评测数据在不同实验中的表现。 ## 发起对比你可以通过以下方式发起多实验对比。仅关联了同个评测集（不区分版本）且已经达到稳态的实验（实验状态为成功、失败或中止）可以被发起多实验对比。 ### 方式一：在实验列表页面发起 1. 在**实验**列表页面，单击**批量选择**。 2. 选择要对比的实验，然后单击**实验对比**。 ### 方法二：在实验详情页发起 1. 在**实验**列表页面，选择一个目标实验。 2. 在实验详情页，单击**实验对比**。 3. 选择要关联对比的实验，然后单击**发起实验对比**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d6327e9363375adb07817b8f21023724.png) ### 方法三：在评测集详情页发起 1. 在**评测集**列表页面，选择一个目标评测集。 2. 在**评测集**详情页，单击**关联实验**，然后单击**批量选择。** 3. 选择要对比的实验，然后单击**实验对比**。 ### 方法四：在多实验对比看板继续添加实验 1. 在实验对比页面，单击 **+ 添加对比实验**。 2. 选择要对比的实验，然后单击**发起对比实验**。 ## 查看指标统计 **指标统计**提供了参与对比的实验的所有评估指标的综合看板，使开发者能够快速掌握多个实验的整体效果。 * 设置对照组（基准） ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_5ad796d71517d5a827f9dbd320fd6789.png) * （可选）可视化配置：隐藏暂不关心的评估指标。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9fab4cb44d181e9879942294872de185.png) * 对比基准，查看实验组的效果，识别不符合预期的指标。 * 进入数据明细，洞察劣化指标。 ## 查看数据明细（行级对比）通过数据明细对比，开发者可以深入分析指标统计中存疑或感兴趣的指标项，对单条评测数据在不同实验中的表现进行详细对比。通过检查实际输出、评估器打分及其原因，验证宏观指标统计的准确性，从而得出多实验对比的结论，指导下一步的业务决策。 * 可视化配置：隐藏暂不关注评测集列、实际输出列、评估指标；调整视图紧凑型。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ab03ba894bfac8e2b28d68981f6bff4e.png) * 筛选：通过过滤器筛选出低于某个指标分数线的评测数据项。 * 行级对比： * 对比多个版本的评测对象在相同评测数据输入下的输出和表现。例如，指标得分、Token 消耗和时延。数据明细除评测集数据外，还包括以下信息： * **基准实验**的评测集的数据项 ID 列 * **基准实验**的评测集的列 * **基准实验结果列** * 评测对象的实际输出 * 各评估器指标得分 * **实验组结果列**\*N * 评测对象的实际输出 * 各评估器指标得分 * 多实验对比行级数据，会有两个分支。 * 分支1：评测对象的异常案例。 * 检查得分及其原因，人工核对评测集输入与实际输出，识别评估不准确的异常案例。 * 分支2：评估器评估不准的异常案例。 * 检查得分及其原因，人工核对评测集输入与实际输出，识别评估器评估不准确的异常案例。 * 点击**评估指标**对应的 Trace 图标查看评估器的 Trace 链路，结合 Trace 排查问题原因。 * 人工校准得分刷新数据明细页面，指标统计页面也会联动刷新。然后，再进行对比分析。![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1fb557a3ff4ce9fb12cd55a18852554f.png) 根据多实验对比结果，选择表现更佳的实验版本进行下一步业务决策。可以选择发布该版本上线，或者针对该版本中存在的badcase进行进一步优化。 # 导出实验报告实验结束后，你可以将已完成的评测实验运行记录报告导出为 .csv 文件，并下载到本地。 ## 操作步骤导出并下载实验报告的操作步骤如下： 1. 找到指定的评测实验。 1. 登录 [AgentKit控制台](https://console.volcengine.com/agentkit)。 2. 在左侧导航栏选择**评测** \> **实验**。 3. 在实验列表中找到指定的评测实验，确保实验状态为**成功**。 2. 导出实验报告。 1. 在实验列表中单击评测实验名称，进入评测实验详情页。 2. 在页面右上角单击**导出** \> **CSV 格式**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f7c1f7ccd8eeb73a529f682d5625e6e7.png) 3. 导出完成后，页面右上角会有状态提示。你可以根据页面提示直接下载报告，也可以查看导出记录，下载当前实验的已导出的任意文件报告。 3. 下载实验报告。 1. 在评测实验详情页右上角单击**导出** \> **查看并下载文件**。 2. 找到指定的导出记录，在操作列单击**下载**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_01add9bfd94a0e97a103c5bdf6b9b83e.png) ## 实验报告格式实验报告文件中包含评测记录的 ID 列、评测集的每一列、执行结果列和评测得分列。各列的详细说明如下： |**评测集列名** |**说明** | |---|---| |ID |评测数据的 ID。 | |Tags |评测集数据行对应的标签。 | |status |评测记录的运行状态。Status 表示执行成功。 | |评测集的列 |评测集中定义的每一列。各个评测集结构不同，此处不再展开说明。 | |actual_output |评测对象在本次实验中的实际输出。 | |评估器 |列名为评估器名称及版本号。其值为每条评测记录的评分。 | |reason |对应评分的理由。 |