AgentbaseDocs
文档目录

评测数据集管理与基准测试

功能概述

评测数据集(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>expectedOutputSchemastring(必填,项目内唯一,如 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>statusinput:必填(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 .../:datasetIdobservability.datasets.read / write
管理数据集条目与 CSV 导入数据集详情 → Items 页签 / 导入 CSVGET/POST /v1/observability/datasets/:datasetId/items、PATCH/DELETE .../:itemIdobservability.datasets.read / write
从低分 Score 批量转入数据集评分列表/详情 → 添加到数据集POST /v1/observability/datasets/:datasetId/items/from-score/preview、/from-scoreobservability.datasets.write + scores.read
触发数据集运行(含 Agent Workbench 目标)数据集详情 → Runs → 新建运行GET/POST /v1/observability/datasets/:datasetId/runs、GET .../runs/:runId/itemsobservability.datasets.write
配置与触发远程自定义端点运行数据集详情 → 远程运行配置(Remote Trigger)GET/PUT/DELETE /v1/observability/datasets/:datasetId/remote-trigger、POST .../remote-runsobservability.datasets.write

与其他模块的协同关系


功能详解与操作指南

1. 创建黄金数据集 enterprise-support-golden-v1 并录入条目

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 视图横向对比多版本表现与下钻单题退化


入口与创建

在项目侧栏打开 Observability / AgentOps,进入 Assets / Data → Datasets。如果看不到该分区,请先确认当前实例已启用可观测能力,详见可观测总览。

添加测试用例

每条用例都需要输入和预期输出。可以手工创建,也可以导入 CSV;编辑用例时还可关联已有 Trace,并按需选择其中的 Observation,便于从实际请求整理回归样本。

从 CSV 导入

选择 Import CSV 上传带表头的 UTF-8 .csv 文件后,先检查列映射和预览,再开始导入。至少需要把一列映射为 Input,一列映射为 Expected output;其余列可映射为 Metadata 或忽略。常见表头会自动匹配,仍应在预览中确认:

CSV 表头示例默认映射
input、question、query、promptInput
expected_output、ground_truth、reference_answerExpected output
metadata、metaMetadata
其他列忽略

例如,下面的两列 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)”模板时,部分条目没有产出评分?

2. 修改了某道题目的 expectedOutput 标准答案后,之前已经跑完的历史 Dataset Run 的评分和根因分析会自动改变吗?

3. 如何暂时屏蔽数据集中某些不再适用的旧题目,但保留它们在历史 Run 中的对比记录?


相关文档