评测数据集管理与基准测试
功能概述
评测数据集(Evaluation Datasets,控制台入口为 智能体运维 → 数据集)是 Agentbase(v2.10.0)支撑智能体离线回归测试、Prompt 版本对比、模型选型评估以及线上 Bad Case 持续沉淀的核心数据资产中心。在企业级 AI 应用迭代过程中,每当团队升级底层大模型(例如从 qwen-turbo 切换至 qwen-plus)、调整系统提示词或修改知识库 kb_enterprise_support 的检索阈值时,都需要一套包含标准输入(input)与参考标准答案(expectedOutput)的黄金基准集(Golden Dataset),以科学验证改动是否真正带来准确率提升且未引发历史用例退化。
在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的标杆项目 **企业智能客服与知识中台**(enterprise-ai-hub-210)中,团队维护了核心黄金评测集 **enterprise-support-golden-v1**(涵盖工单 TK-20261022-001 至 004 代表的 OceanBase 分布式事务排障、HNSW 向量索引调优、AI 网关限流计费与标准客服 SOP 四大领域),实现了从“生产链路收集 → 数据集条目管理 → 自动化基准测试运行(Agent Runtime Workbench 或远程自定义端点)→ 多轮评估打分与根因对比”的完整闭环。
核心概念与架构
数据集引擎通过将静态测试条目(Dataset Items)与动态执行轨迹(Traces / Observations)绑定为不可变的运行记录(Dataset Runs),并与自动化评估器(Evaluations)无缝联动,构建可重复对比的基准评测流水线。
flowchart TB
subgraph SourceCollection["1. 数据集条目来源与构建"]
ManualCSV["手动新建与 CSV 批量导入\n定义 input / expectedOutput / metadata"]
TraceConvert["从线上 Trace / Observation 添加\n保留 sourceTraceId & sourceObservationId"]
ScoreImport["从低分 Score 一键转入数据集\nPOST /datasets/{id}/items/from-score"]
end
subgraph DatasetCore["2. 黄金评测集资产 (enterprise-support-golden-v1)"]
DatasetMeta["Dataset 容器 (/v1/observability/datasets)\n名称、描述、Schema 约束与版本演进"]
DatasetItems["Dataset Items (/datasets/{datasetId}/items)\n状态: ACTIVE / ARCHIVED\n字段: input / expectedOutput / metadata"]
DatasetMeta --> DatasetItems
end
subgraph BenchmarkExecution["3. 自动化基准测试触发与执行 (Dataset Runs)"]
WorkbenchTarget["方式 A: 智能体工作台目标 (Agent Runtime Target)\nPOST /datasets/{id}/runs\n冻结 Agent / Version / 运行配置,由服务端直接驱动"]
RemoteWebhook["方式 B: 远程自定义端点触发 (Remote Webhook)\nPUT/GET /datasets/{id}/remote-trigger\nPOST /datasets/{id}/remote-runs"]
SDKLocalRun["方式 C: 服务端 SDK 离线跑批上报\n(agentbase-node-sdk@2.10.0 逐条执行并关联 Trace)"]
end
subgraph EvalComparison["4. 自动评估与多版本横向对比"]
RunItems["Dataset Run Items\n绑定每次执行的 Trace / Observation 与耗时/Token"]
AutoJudge["自动触发数据集评估任务 (LLM-as-a-Judge)\n冻结当次 expectedOutput 计算 Correctness & Faithfulness"]
CompareUI["多 Run 并排对比视图\n对比准确率均值、P95 延迟、Token 成本与单题退化明细"]
end
ManualCSV --> DatasetItems
TraceConvert --> DatasetItems
ScoreImport --> DatasetItems
DatasetItems --> WorkbenchTarget
DatasetItems --> RemoteWebhook
DatasetItems --> SDKLocalRun
WorkbenchTarget --> RunItems
RemoteWebhook --> RunItems
SDKLocalRun --> RunItems
RunItems --> AutoJudge --> CompareUI数据集核心实体与字段定义表
| 核心实体 | 关键字段 | 类型与约束 | 业务含义与评测作用 |
|---|---|---|---|
| Dataset(数据集) | name<br>description<br>metadata<br>inputSchema<br>expectedOutputSchema | string(必填,项目内唯一,如 enterprise-support-golden-v1)<br>string / object<br>可选 JSON Schema | 组织同类评测用例的逻辑容器。支持可选配置 inputSchema 与 expectedOutputSchema 对新增条目执行结构化 JSON Schema 校验。 |
| Dataset Item(数据集条目) | id<br>input<br>expectedOutput<br>metadata<br>sourceTraceId<br>sourceObservationId<br>status | input:必填(JSON 或文本)<br>expectedOutput:可选标准答案<br>status:ACTIVE(默认)或 ARCHIVED | 单道基准测试题。当 status 设为 ARCHIVED 时,该条目保留历史关联记录但不再参与后续新建的基准运行(Dataset Run)。 |
| Dataset Run(数据集运行) | runId / name<br>description<br>metadata | 绑定特定测试配置快照(如 qwen-plus-v1 vs qwen-turbo-v1) | 针对同一数据集发起的一次完整回归测试批次。当以 Agent Runtime 为目标时,自动冻结当时的 Agent 版本、模型参数与知识库配置。 |
| Dataset Run Item(运行明细项) | datasetItemId<br>traceId<br>observationId | 关联单道题目与当次实际生成的 Trace / Observation | 将静态题目(含 expectedOutput)与当次动态推理结果(output、延迟、Token、成本)及自动评估产出的 Score 精确铆接。 |
角色、入口与关联关系
控制台入口与 REST API 权限矩阵
控制台入口位于:**项目 enterprise-ai-hub-210 → 智能体运维(Observability / AgentOps) → 数据集(Datasets)**(路由:/console/project-{region}-enterprise-ai-hub-210/datasets)。
| 操作功能 | 控制台入口 | REST API 端点 | 所需权限 Scope |
|---|---|---|---|
| 查询与创建数据集 | 数据集列表页 → 创建数据集 | GET/POST /v1/observability/datasets、GET .../:datasetId | observability.datasets.read / write |
| 管理数据集条目与 CSV 导入 | 数据集详情 → Items 页签 / 导入 CSV | GET/POST /v1/observability/datasets/:datasetId/items、PATCH/DELETE .../:itemId | observability.datasets.read / write |
| 从低分 Score 批量转入数据集 | 评分列表/详情 → 添加到数据集 | POST /v1/observability/datasets/:datasetId/items/from-score/preview、/from-score | observability.datasets.write + scores.read |
| 触发数据集运行(含 Agent Workbench 目标) | 数据集详情 → Runs → 新建运行 | GET/POST /v1/observability/datasets/:datasetId/runs、GET .../runs/:runId/items | observability.datasets.write |
| 配置与触发远程自定义端点运行 | 数据集详情 → 远程运行配置(Remote Trigger) | GET/PUT/DELETE /v1/observability/datasets/:datasetId/remote-trigger、POST .../remote-runs | observability.datasets.write |
与其他模块的协同关系
- 与链路追踪(Traces)和评分(Scores)的双向回流: 在线上运维发现典型 Bad Case(如某次工单问答出现幻觉或检索遗漏)时,运维人员可直接在该 Trace、Observation 或低分 Score 页面单击 添加到数据集,一键将线上真实输入(
input)、模型输出及sourceTraceId/sourceObservationId沉淀进enterprise-support-golden-v1,防止同类问题在后续迭代中复发。 - 与评估(Evaluations)及根因分析(RCA)的签名冻结联动: 只有绑定了数据集标准答案(
expectedOutput)的运行,才能启用 RAG 四阶段评测中的 答案准确性(Accuracy / Correctness) 评估。评估执行时,系统会使用独立域 HMAC 签名将当次问题、参考答案(expectedOutput)、Trace 与 RAG 检索指纹冻结在datasetEvidence中——后续即使有人修改了数据集条目的当前标准答案,历史评分的根因分析(RCA)依然严格核验当次冻结快照,不会产生错误归因。
功能详解与操作指南
1. 创建黄金数据集 enterprise-support-golden-v1 并录入条目
- 登录 Agentbase 控制台,进入项目
企业智能客服与知识中台(enterprise-ai-hub-210),打开 智能体运维 → 数据集(Datasets)。 - 单击右上角 创建数据集,填写名称
enterprise-support-golden-v1与描述"企业智能客服与技术支持黄金基准集(覆盖 OceanBase 排障、AI 网关限流与 SOP 问答)",单击保存。 - 录入数据集条目的三种方式:
- 方式一:手动创建或 CSV 批量导入:在数据集详情页单击 新建条目 或 导入 CSV,将包含
input(用户工单问题)、expectedOutput(标准排障步骤与答案)和metadata(如{"ticketCategory": "oceanbase-vector", "difficulty": "hard"})的表格批量导入; - 方式二:从线上 Trace / Observation 转化:在 智能体运维 → 链路(Traces) 详情页选中某条典型链路或
GENERATION节点,单击 添加到数据集,选择enterprise-support-golden-v1,经人工润色修正expectedOutput后保存,系统自动记录sourceTraceId与sourceObservationId; - **方式三:从低分 Score 批量转化(
from-score)**:在评分页筛选出低分记录,先调用/items/from-score/preview预览去重情况,再调用/items/from-score批量转入数据集。
- 方式一:手动创建或 CSV 批量导入:在数据集详情页单击 新建条目 或 导入 CSV,将包含
export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
export APPBASE_API_KEY="<APPBASE_API_KEY>"
# 1. 创建黄金评测数据集 enterprise-support-golden-v1
DS_RESP="$(curl -fsS -X POST "${APPBASE_ENDPOINT}/observability/datasets" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
-H "Content-Type: application/json" \
--data '{
"dataset": {
"name": "enterprise-support-golden-v1",
"description": "企业智能客服与知识中台黄金评测基准集 (v2.10.0)",
"metadata": {
"owner": "enterprise-ai-hub-team",
"knowledgeBaseId": "kb_enterprise_support"
}
}
}')"
DATASET_ID="$(echo "${DS_RESP}" | jq -er '.dataset.id')"
# 2. 向数据集中添加关联线上工单 Trace 的黄金评测条目
curl -fsS -X POST "${APPBASE_ENDPOINT}/observability/datasets/${DATASET_ID}/items" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
-H "Content-Type: application/json" \
--data '{
"item": {
"input": {
"question": "OceanBase Shared V2 项目在构建 1024 维 HNSW 向量索引时报错 -4013 (OB_ALLOCATE_MEMORY_FAILED),应该如何排查和修复?",
"userId": "user_zhangwei_001"
},
"expectedOutput": {
"answer": "1. 查询 GV$OB_VECTOR_MEMORY_INFO 核实租户向量内存使用率;2. 调大租户参数 ob_vector_memory_limit_percentage(建议从默认 10% 提升至 30%);3. 重新触发增量向量索引构建并确认 schema.status=ready。",
"mustIncludeSql": "GV$OB_VECTOR_MEMORY_INFO"
},
"metadata": {
"ticketId": "TK-20261022-001",
"domain": "oceanbase-vector-index",
"sla": "P0"
},
"sourceTraceId": "tr_support_ticket_20261022_001",
"sourceObservationId": "obs_gen_qwen_plus_001"
}
}' | jq .2. 触发自动化基准测试(Agent Runtime Workbench vs 自定义远程端点 vs SDK)
当数据集 enterprise-support-golden-v1 准备就绪后,可通过以下三种模式发起自动化基准运行(Dataset Run):
| 运行模式 | 触发入口 / 接口 | 执行原理与核心优势 | 适用场景 |
|---|---|---|---|
| 模式 A:智能体工作台目标(Agent Runtime Workbench) | 控制台 数据集 → 新建运行 → 选择 Agent Runtime(POST /v1/observability/datasets/:datasetId/runs) | 浏览器不直连底层 Runtime 服务,由平台服务端自动遍历数据集中的所有 ACTIVE 条目,向当前项目的 智能体工作台 发起真实 ReAct 运行,自动冻结当时的 Agent 版本、模型(qwen-plus)、知识库(kb_enterprise_support)与词典配置,并将生成的 Trace 自动挂载为 Dataset Run Item。 | 评测托管在 Agentbase 智能体工作台上的客服 Agent 不同配置版本的效果对比。 |
| 模式 B:自定义远程端点(Remote Webhook) | 控制台 配置远程触发器(PUT .../remote-trigger)并单击 触发远程运行(POST .../remote-runs) | 登记业务自建 Agent 服务的 HTTPS Webhook 地址与认证头后,平台将数据集条目批量推送给自定义端点执行,并将返回的响应与 Trace 关联回当前 Run。 | 业务智能体部署在自建微服务或 Functions 函数中,希望由控制台一键触发回归测试。 |
| 模式 C:服务端 SDK 编程式跑批 | 使用 agentbase-node-sdk@2.10.0 在 CI/CD 流水线中拉取条目、调用模型并上报关联 | 在本地或 CI 脚本中完全自主控制并发度、前置数据准备与多步编排,通过 POST /v1/observability/datasets/:datasetId/runs 记录对比批次。 | 集成到 Git 提交或每日定时构建(Nightly Build)的自动化质量门禁。 |
触发 Agent Runtime Workbench 自动化基准运行示例
# 针对 enterprise-support-golden-v1 触发一次面向 Agent Runtime 工作台的基准测试运行
curl -fsS -X POST "${APPBASE_ENDPOINT}/observability/datasets/${DATASET_ID}/runs" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
-H "Content-Type: application/json" \
--data '{
"run": {
"name": "benchmark-qwen-plus-graphrag-v210",
"description": "启用 kb_enterprise_support GraphRAG + Wiki 及 lex_enterprise_synonyms 词典后的基准回归",
"target": {
"type": "agent_runtime",
"agentId": "enterprise-support-agent"
},
"metadata": {
"model": "qwen-plus",
"knowledgeBase": "kb_enterprise_support",
"releaseBaseline": "2.10.0"
}
}
}' | jq .3. 在 Runs 视图横向对比多版本表现与下钻单题退化
- 进入数据集
enterprise-support-golden-v1的 Runs(运行记录) 页签。 - 勾选两次或多次不同的运行批次(例如
benchmark-qwen-turbo-baseline与benchmark-qwen-plus-graphrag-v210),进入并排对比视图: - 全局聚合指标对比:直观对比各批次在正确性(Correctness)、忠实度(Faithfulness)、上下文相关性(Context Relevance)等评估器上的平均得分、P50/P95 响应延迟、平均 Token 消耗与单次运行总成本估算;
- 逐题(Item-by-Item)下钻对比:表格逐行展示同一道
datasetItem在不同 Run 中的实际输出(Output)、得分差异与状态。对于得分下降的退化用例,单击关联的 Trace 链接即可直接进入 Trace 详情与根因分析 定位原因。
入口与创建
在项目侧栏打开 Observability / AgentOps,进入 Assets / Data → Datasets。如果看不到该分区,请先确认当前实例已启用可观测能力,详见可观测总览。
- 单击 Create dataset,填写名称;描述和元数据可选。
- 选择用例类型:Default、Good 或 Bad。需要填写元数据时使用 JSON 对象格式。
- 保存后会进入数据集详情页,可在 Items 中维护测试用例,在 Runs 中查看运行记录,在 Reports 中比较运行结果。
添加测试用例
每条用例都需要输入和预期输出。可以手工创建,也可以导入 CSV;编辑用例时还可关联已有 Trace,并按需选择其中的 Observation,便于从实际请求整理回归样本。
从 CSV 导入
选择 Import CSV 上传带表头的 UTF-8 .csv 文件后,先检查列映射和预览,再开始导入。至少需要把一列映射为 Input,一列映射为 Expected output;其余列可映射为 Metadata 或忽略。常见表头会自动匹配,仍应在预览中确认:
| CSV 表头示例 | 默认映射 |
|---|---|
input、question、query、prompt | Input |
expected_output、ground_truth、reference_answer | Expected output |
metadata、meta | Metadata |
| 其他列 | 忽略 |
例如,下面的两列 CSV 可以直接满足必需映射:
input,expected_output
"如何重置密码?","在登录页选择忘记密码,并按页面提示完成操作。"单个文件最大 10 MiB,最多 1,000 条数据行、100 列。空文件、空表头、重复表头、格式错误或超出限制时,先修正 CSV 再重新上传。若个别数据行写入失败,导入结果会保留成功/失败数量和失败行号及原因;重试前先筛出失败行,整份文件重新导入可能造成已成功记录重复。不要仅凭“导入完成”判断所有记录均已成功。
从 Trace 整理用例
在新增或编辑条目的来源选择器中搜索并选择 Trace;如果需要定位具体步骤,再选择该 Trace 中的 Observation。保存后,条目保留来源关联,可从用例继续回到相应轨迹检查上下文。若更换 Trace,需重新确认 Observation 选择。
运行与查看结果
在数据集详情页创建 Run,填写运行名称并选择执行方式:
| 执行方式 | 运行前检查 |
|---|---|
| Prompt | 先选择评估模板、Prompt/版本和 LLM 连接,再填写模型及模型参数 JSON;页面会提示缺少的必需配置。 |
| Agent | 选择项目 Draft Agent 或 AI Gateway 上的外部 Agent 目标;如果列表为空,先确认项目中已有可用目标。 |
运行后在 Runs 查看状态和记录。打开单条运行详情,可逐项对照输入、预期输出、实际输出和评分;页面也会展示可用的 Trace、延迟、成本及失败信息。Reports 可按不同 Run 对比平均延迟、平均成本和评分。运行或评分仍在处理中、评分为空、或某条用例失败时,先查看对应状态、错误和 Trace;空评分不代表评分为零,也不代表用例通过。
数据集运行依赖当前项目可用的 Prompt、模型连接或 Agent 执行目标,以及配置的评估器。评估配置和结果解释见评估与评分;指标来源和轨迹派生信号见指标分析。
检验知识库问答时,保持问题和参考答案固定,选择能产生真实检索证据的 Agent,再组合查询质量、上下文相关性、回答忠实性和答案准确性模板。完整步骤与提交异常处理见用数据集评估 RAG 回答。实际回答不能代替参考答案,缺失评分不能作为通过依据。
常见问题与排障
1. 为什么在数据集评估中选择“答案准确性(Accuracy / Correctness)”模板时,部分条目没有产出评分?
- 原因分析:答案准确性(Correctness)评估强依赖数据集条目中存在非空的有效参考标准答案(
expectedOutput)。如果某条 Dataset Item 在创建或从 Trace 导入时只填写了input,而expectedOutput为空或缺失,评估引擎会拒绝向 Judge 模型提交空标准答案,从而跳过该条目的准确性打分。 - 解决措施:在数据集 Items 页签中检查未产出分数的条目,补充完善的
expectedOutput标准答案后,重新触发一次 Dataset Run。
2. 修改了某道题目的 expectedOutput 标准答案后,之前已经跑完的历史 Dataset Run 的评分和根因分析会自动改变吗?
- 原因分析:不会。为了保证历史实验结论的可重现性与审计严谨性,Agentbase 在每次数据集评估执行时,都会将当时的
input与expectedOutput进行签名快照冻结(保存在 Score 的datasetEvidence元数据中)。后续修改数据集条目仅对新发起的 Dataset Run 生效。 - 解决措施:修正标准答案后,请新建一次 Dataset Run 以基于最新标准答案获取评估分数与根因分析。
3. 如何暂时屏蔽数据集中某些不再适用的旧题目,但保留它们在历史 Run 中的对比记录?
- 原因分析:如果直接物理删除(
DELETE)某条 Dataset Item,会导致历史 Run 中缺少该题目的题干对照。 - 解决措施:不要直接删除该条目,而是编辑该条目(
PATCH /v1/observability/datasets/:datasetId/items/:itemId)将其状态从ACTIVE切换为 **ARCHIVED(已归档)**。归档后的条目不会进入后续新触发的基准测试运行,但在历史 Run 详情页中依然完整保留可查。