VoltAgent 离线评估(Offline Evaluations)实战指南:从 createExperiment 到 CI 质量门禁

原创2026-09-24 23:28:421,922 阅读
文章标签:人工智能AI AgentAgent 框架多智能体工具调用MCP 服务Agent 记忆RAGAgent 工作流Agent 编排可观测性AI 评测语音后端

VoltAgent 离线评估(Offline Evaluations)实战指南:从 createExperiment 到 CI 质量门禁

离线评估(Offline Evaluations)是 VoltAgent 中面向固定数据集的确定性评估方案:每次运行针对同一批输入执行 Agent 与评分器,产出可复现的分数、阈值判定与通过标准,非常适合回归测试、CI 质量门禁以及在部署前对比提示词或模型改动。本文以官方文档为骨架,结合仓库源码(packages/evals、packages/scorers、packages/cli)与可运行示例(examples/with-offline-evals)逐步讲解:如何用 createExperiment 定义实验、如何添加评分器与阈值、如何用 passCriteria 定义整体通过标准,以及如何通过 API 或 VoltAgent CLI 运行实验并将结果上报到 VoltOps。读完本文,你将能独立搭建一套可进 CI 的离线评估流水线。

离线评估是什么,运行结果去哪里了

离线评估针对一个固定的数据集运行,产出确定性的结果。它的典型用途包括:

  • 回归测试:每当提示词、模型或工具链发生变化,重跑同一数据集,捕捉准确率或回答质量的回退;
  • CI 门禁:在部署前用 passCriteria 强制要求整体通过率与平均分达标;
  • 方案对比:在同一个数据集上比较不同模型或提示词版本,用分数说话。

运行结果的去向:当你带着 voltOpsClient 运行实验时,每一次执行都会被记录为 VoltOps 中的一个 Eval Run。你可以在 VoltOps Console 中查看每条数据条目(item)的输出、各项分数(scores)、通过标准(pass criteria)和汇总摘要(summaries);阈值不达标的条目还会参与 annotation 自动化流程,进入人工审查队列。如果你省略 voltOpsClient,实验会完全在本地执行,结果只保留在内存 / STDOUT 中,不上传任何远程服务。

从源码看,上报逻辑集中在 packages/evals/src/voltops/run.ts:运行时按序调用 create(创建 run)、appendResult(逐条追加 item 结果)、complete(携带 summary 终结 run),并依据 inferTerminalStatus 推导最终状态——只要存在 error 则标记 failed;配置了 pass criteria 时要求全部通过才标记 succeeded。这也是后面 Step 4 的 passCriteria 能直接决定 CI 成败的底层依据。

Step 1:用 createExperiment 创建最小实验

最简单的实验只需要三样东西:一个 id、一个带内联条目(inline items)的 dataset,以及一个 runner 函数。

import { createExperiment } from "@voltagent/evals";
import { Agent } from "@voltagent/core";
import { openai } from "@ai-sdk/openai";

export default createExperiment({
  id: "offline-smoke",
  dataset: {
    items: [
      {
        id: "1",
        input: "The color of the sky",
        expected: "blue",
      },
      {
        id: "2",
        input: "2+2",
        expected: "4",
      },
    ],
  },
  runner: async ({ item }) => {
    const supportAgent = new Agent({
      name: "offline-evals-support",
      instructions: "You are a helpful assistant. Answer questions very short.",
      model: openai("gpt-4o-mini"),
    });
    const result = await supportAgent.generateText(item.input);
    return {
      output: result.text,
    };
  },
});

runner 函数接收每条数据集条目并返回一个输出。你可以直接返回输出,也可以把它包在带有附加元数据的对象里返回(详见下文“runner 的返回格式”)。id 会用于日志、遥测和 VoltOps 运行元数据;dataset.items 的每个元素至少包含 id 与 input,expected 供评分器对照使用。

实现细节:createExperiment 在 packages/evals/src/experiment/create-experiment.ts 中会做运行时校验——id 必须是非空字符串、runner 必须是函数,否则直接抛出 TypeError;随后它会规范化 tags(去空白、去重、冻结)、克隆 dataset 描述符与 passCriteria,并把整个 config 冻结成不可变对象。换句话说,实验定义一旦创建就不可在运行中被篡改,保证每次运行语义一致。

注意:到了这一步,实验可以运行,但还没有任何评估动作——没有评分器,所有条目默认通过。让我们进入 Step 2。

Step 2:添加 Scorer 开始打分

添加一个评分器(scorer)来把 runner 的输出与期望值(expected)进行比较。先从最基础的启发式评分器 levenshtein(编辑距离 / 字符串相似度)开始:

import { createExperiment } from "@voltagent/evals";
import { Agent } from "@voltagent/core";
import { openai } from "@ai-sdk/openai";
import { scorers } from "@voltagent/scorers";

export default createExperiment({
  id: "offline-smoke",
  dataset: {
    items: [
      {
        id: "1",
        input: "The color of the sky",
        expected: "blue",
      },
      {
        id: "2",
        input: "2+2",
        expected: "4",
      },
    ],
  },
  runner: async ({ item }) => {
    const supportAgent = new Agent({
      name: "offline-evals-support",
      instructions: "You are a helpful assistant. Answer questions very short.",
      model: openai("gpt-4o-mini"),
    });
    const result = await supportAgent.generateText(item.input);
    return {
      output: result.text,
    };
  },
  scorers: [scorers.levenshtein],
});

重要行为:默认情况下,评分器有一个为 0 的阈值(threshold),也就是说无论分数高低,每条条目都会通过。评分器会产出一个 0.0 到 1.0 之间的数值分数,但没有阈值时它不会影响 pass/fail 状态,只是把分数计入汇总指标。

实现细节:scorers 命名空间中的启发式评分器来自 packages/scorers/src/index.ts,它基于 AutoEvals 的 ExactMatch、Levenshtein、NumericDiff、JSONDiff、ListContains 封装而成,且都不依赖 LLM / API Key。在 packages/evals/src/experiment/run-experiment.ts 的 toExperimentScore 中可以看到阈值的判定逻辑:只有当设置了阈值且 score >= threshold 时 thresholdPassed 才为 true;未设阈值时该字段保持 null,条目不会因分数低而失败。

Step 3:设置阈值让打分有意义

给评分器加上 threshold,让它真正决定条目的生死:分数低于阈值时条目标记为 failed。

import { createExperiment } from "@voltagent/evals";
import { Agent } from "@voltagent/core";
import { openai } from "@ai-sdk/openai";
import { scorers } from "@voltagent/scorers";

export default createExperiment({
  id: "offline-smoke",
  dataset: {
    items: [
      {
        id: "1",
        input: "The color of the sky",
        expected: "blue",
      },
      {
        id: "2",
        input: "2+2",
        expected: "4",
      },
    ],
  },
  runner: async ({ item }) => {
    const supportAgent = new Agent({
      name: "offline-evals-support",
      instructions: "You are a helpful assistant. Answer questions very short.",
      model: openai("gpt-4o-mini"),
    });
    const result = await supportAgent.generateText(item.input);
    return {
      output: result.text,
    };
  },
  scorers: [
    {
      scorer: scorers.levenshtein,
      threshold: 0.5,
    },
  ],
});

现在,如果 levenshtein 分数低于 0.5,该条目就会被标记为 failed。你还可以给评分器指定一个自定义 id,以便在 pass criteria 中引用它:

scorers: [
  {
    id: "my-custom-scorer-id",
    scorer: scorers.levenshtein,
    threshold: 0.5,
  },
],

实现细节:评分器配置条目的 id、name 覆盖逻辑位于 packages/evals/src/experiment/scorers.ts 的 resolveExperimentScorers:它会规范化阈值、合并元数据,并用 entry.id(若提供)替换评分器原本的 id,使后续汇总与 criteria 引用保持一致。这一点在测试 packages/evals/src/experiment/run-experiment.spec.ts 中也有覆盖:显式指定 id: "hede" 后,summary.scorers 中以 hede 为键聚合,而原始 id 不再出现。

Step 4:用 passCriteria 定义整体通过标准

单个评分器的阈值决定每条条目是否通过,而 pass criteria(通过标准) 决定整个实验是否成功。使用 passCriteria 设置整体成功条件。

有两种类型的 criterion:

  • meanScore:所有条目的平均分必须达到某个最小值;
  • passRate:通过条目所占百分比必须达到某个最小值。
import { createExperiment } from "@voltagent/evals";
import { Agent } from "@voltagent/core";
import { openai } from "@ai-sdk/openai";
import { scorers } from "@voltagent/scorers";

export default createExperiment({
  id: "offline-smoke",
  dataset: {
    items: [
      {
        id: "1",
        input: "The color of the sky",
        expected: "blue",
      },
      {
        id: "2",
        input: "2+2",
        expected: "4",
      },
    ],
  },
  runner: async ({ item }) => {
    const supportAgent = new Agent({
      name: "offline-evals-support",
      instructions: "You are a helpful assistant. Answer questions very short.",
      model: openai("gpt-4o-mini"),
    });
    const result = await supportAgent.generateText(item.input);
    return {
      output: result.text,
    };
  },
  scorers: [
    {
      id: "my-custom-scorer-id",
      scorer: scorers.levenshtein,
      threshold: 0.5,
    },
  ],
  passCriteria: [
    {
      type: "passRate",
      min: 1.0, // All items must pass
      scorerId: "my-custom-scorer-id", // Only consider this scorer
    },
    {
      type: "meanScore",
      min: 0.5, // Average score must be at least 0.5
    },
  ],
});

关键语义:pass criteria 在所有条目都执行完毕之后才被评估。任一 criterion 未满足,实验结果中会明确指出哪些标准没有达成。你还可以在不需要让运行失败、但需要被记录上报的 criterion 上设置 severity: "warn":

passCriteria: {
  type: "meanScore",
  min: 0.9,
  severity: "warn", // 不会导致运行失败,但会在摘要中上报
}

实现细节:criterion 的求值逻辑位于 packages/evals/src/experiment/aggregator.ts 的 evaluatePassCriteria:meanScore 默认取全局平均分,若指定 scorerId 则改用该评分器的平均分;passRate 同理。归一化逻辑 normalizePassCriteria 支持传入单个对象或数组。整个实验的最终 pass/fail 由 packages/evals/src/voltops/run.ts 的 inferTerminalStatus 汇总:有 error 即 failed;有 criteria 时全部通过才 succeeded,否则 failed。

Step 5:运行实验

有两种方式执行实验:通过 API 编程式调用,或通过 VoltAgent CLI。

方式一:通过 API 运行(runExperiment)

使用 runExperiment 编程式执行实验:

import { runExperiment } from "@voltagent/evals";
import experiment from "./experiments/offline.experiment";

const result = await runExperiment(experiment, {
  onProgress: ({ completed, total }) => {
    const label = total !== undefined ? `${completed}/${total}` : `${completed}`;
    console.log(`[with-offline-evals] processed ${label} items`);
  },
});

console.log("Summary:", {
  success: result.summary.successCount,
  failures: result.summary.failureCount,
  errors: result.summary.errorCount,
  meanScore: result.summary.meanScore,
  passRate: result.summary.passRate,
});

API 选项(runExperiment options):

选项 说明
concurrency 并行处理的条目数(默认 1)
signal 用于取消运行的 AbortSignal
voltOpsClient VoltOps 客户端实例,用于遥测与云端数据集(VoltOpsClient 或 VoltOpsRestClient)
onProgress 每个条目处理完成后回调,携带 { completed, total? }
onItem 每个条目处理完成后回调,携带 { index, item, result, summary }

带全量选项的示例:

import { VoltOpsClient } from "@voltagent/sdk";

const result = await runExperiment(experiment, {
  concurrency: 4,
  signal: abortController.signal,
  voltOpsClient: new VoltOpsClient({
    publicKey: process.env.VOLTAGENT_PUBLIC_KEY,
    secretKey: process.env.VOLTAGENT_SECRET_KEY,
  }),
  onProgress: ({ completed, total }) => {
    console.log(`Processed ${completed}/${total ?? "?"} items`);
  },
  onItem: ({ index, result }) => {
    console.log(`Item ${index}: ${result.status}`);
  },
});

实现细节:runExperiment 的并发执行模型位于 packages/evals/src/experiment/run-experiment.ts。它维护一个 active 任务集合,使用 Promise.race 在达到并发上限时等待最早完成的任务(if (active.size >= concurrency) await Promise.race(active)),从而在有序遍历数据集的同时实现有界并行;每个 item 依次执行 runner → 运行本地评分器 → 评估状态 → 写入聚合器 → 追加到 VoltOps。运行前它会校验 signal 是否已中止(ensureNotAborted),中止时抛出 abort reason。VoltOpsClient 在 packages/sdk/src/index.ts 中从 @voltagent/core 再导出。

方式二:通过 CLI 运行

VoltAgent CLI 提供了便捷的命令行运行方式:

pnpm volt eval run --experiment ./src/experiments/offline.experiment.ts

CLI 选项:

选项 说明
--experiment <path> 实验模块路径(必填)
--concurrency <count> 最大并发条目数(默认 1)
--dataset <name> 运行时覆盖的数据集名称
--experiment-name <name> VoltOps 实验名称覆盖
--tag <trigger> VoltOps 触发来源标签(默认 "cli-experiment")
--dry-run 跳过 VoltOps 提交(仅本地打分)

带并发参数的示例:

pnpm volt eval run \
  --experiment ./src/experiments/offline.experiment.ts \
  --concurrency 4

CLI 会自动解析 TypeScript 导入,把进度流式输出到 stdout,并在环境变量中存在 VOLTAGENT_PUBLIC_KEY 和 VOLTAGENT_SECRET_KEY 时把运行关联到 VoltOps。

实现细节:CLI 命令定义在 packages/cli/src/commands/eval.ts,真正的执行逻辑在 packages/cli/src/services/eval/run-experiment.ts。可以看到:TypeScript 模块通过 bundle-require 打包加载(支持 .ts/.tsx/.mts/.cts),加载后校验默认导出是否为 kind === "voltagent.experiment" 的定义;--dataset / --experiment-name / --tag 会被 applyOverrides 合并进实验配置;--dry-run 会设置 VOLTAGENT_DISABLE_REMOTE_SUBMIT=1 并跳过鉴权;此外 CLI 还会在 stdout 打印 banner 与最终摘要,并在关联成功时给出 VoltOps 运行查看入口。

Step 6:自定义数据集解析器(Dataset Resolver)

除了内联 items,你还可以提供自定义的 resolve 函数,从外部来源、数据库或 API 拉取数据:

import { createExperiment } from "@voltagent/evals";

export default createExperiment({
  id: "custom-dataset-example",
  dataset: {
    name: "custom-source",
    resolve: async ({ limit, signal }) => {
      // Fetch from your API, database, or any source
      const response = await fetch("https://api.example.com/test-data", { signal });
      const data = await response.json();

      // Apply limit if provided
      const items = limit ? data.slice(0, limit) : data;

      return {
        items, // Can be an array or async iterable
        total: data.length, // Optional: total count for progress tracking
        dataset: {
          name: "custom-source",
          metadata: { source: "api", fetchedAt: new Date().toISOString() },
        },
      };
    },
  },
  runner: async ({ item }) => {
    // Your runner logic
    return { output: processItem(item.input) };
  },
});

Resolver 函数契约:

  • 接收 { limit?, signal? } 作为参数;
  • 可以返回一个可迭代对象(iterable)、异步可迭代对象(async iterable),或一个 { items, total?, dataset? } 对象;
  • 支持用 async iterable 流式处理大数据集;
  • signal 用于支持取消。

用 async generator 流式产出的示例:

dataset: {
  resolve: async function* ({ signal }) {
    for await (const item of fetchItemsStream()) {
      if (signal?.aborted) break;
      yield item;
    }
  },
}

实现细节:数据集解析的完整实现位于 packages/evals/src/experiment/dataset.ts。resolveExperimentDataset 对描述符的处理优先级为:items 内联数据 → resolve 函数 → 按 name 查注册表;limit 会经过 normalizeLimit 规范化(非有限值或负数视为未设置),并通过 limitAsyncIterable 在流式迭代中提前截断。普通的同步 iterable 也会被包装成 async iterable(ensureAsyncIterable),从而统一走 for await 消费路径。

Step 7:使用 VoltOps 命名数据集(Named Datasets)

在生产工作流中,建议把数据集存放在 VoltOps 里,然后按名称引用。这样能获得版本控制、团队协作和可复用的测试套件。

import { createExperiment } from "@voltagent/evals";

export default createExperiment({
  id: "voltops-dataset-example",
  dataset: {
    name: "support-qa-v1",
    versionId: "abc123", // Optional - defaults to latest version
    limit: 100, // Optional - limit items processed
  },
  runner: async ({ item }) => {
    // Your runner logic
    return { output: processItem(item.input) };
  },
});

数据集配置项:

配置项 说明
name VoltOps 中的数据集名称(必填)
versionId 指定版本 ID(可选,默认取最新版本)
limit 最大处理条目数(可选)

当你携带 voltOpsClient 运行实验时,数据集会自动从 VoltOps 拉取。如果没有提供客户端,实验会抛出清晰的错误信息(提示该命名数据集未注册,可通过 registerExperimentDataset() 注册或接入 VoltOps 客户端)。

实现细节:运行时数据集的拉取走 packages/evals/src/voltops/dataset.ts 的 resolveVoltOpsDatasetStream:先解析数据集与版本标识(支持 id + versionId、id、name + versionId、name 等组合),再分页迭代条目(默认每页 200 条,见 DEFAULT_PAGE_SIZE),把异步迭代器作为流返回。在 run-experiment.ts 的 attachVoltOpsDatasetResolver 中,若 dataset 描述符既无 items 也无 resolve,且检测到 VoltOps 客户端(或能从中提取 publicKey / secretKey 构造 VoltOpsRestClient),会自动挂载一个从 VoltOps 拉取数据的 resolver。

用 CLI 管理数据集

使用 CLI 可以把本地数据集推送到 VoltOps,或把远程数据集拉取到本地:

推送数据集(push):

pnpm volt eval dataset push \
  --name support-qa-v1 \
  --file ./datasets/support-qa.json

拉取数据集(pull):

pnpm volt eval dataset pull \
  --name support-qa-v1 \
  --version abc123 \
  --output ./datasets/support-qa-v1.json

CLI 数据集命令选项:

  • push — 上传本地数据集 JSON 文件到 VoltOps
    • --name <datasetName>(必填)数据集名称
    • --file <datasetFile> 数据集 JSON 文件路径
  • pull — 从 VoltOps 下载某个数据集版本
    • --name <datasetName> 数据集名称(默认取 VOLTAGENT_DATASET_NAME)
    • --id <datasetId> 数据集 ID(优先于 --name)
    • --version <versionId> 版本 ID(默认最新)
    • --output <filePath> 自定义输出文件路径
    • --overwrite 文件已存在时直接覆盖
    • --page-size <size> 每次请求拉取的条目数

实现细节:这两个命令的选项定义与实现都在 packages/cli/src/commands/eval.ts。push 会把数据集文件解析后经 pushDatasetToVoltOps 上传,成功后输出 datasetId、versionId 与条目数;pull 支持按 --id 或 --name 定位数据集,未指定版本时默认选最新版本,若本地已有同名文件则会比较内容是否一致(一致则跳过),否则在 --overwrite、另存新文件、取消之间做出选择,最后把结果写入本地文件。两者都会通过 resolveAuthConfig 读取 VOLTAGENT_PUBLIC_KEY / VOLTAGENT_SECRET_KEY 等鉴权配置。

配置参考(Configuration Reference)

必填字段

id

实验的唯一标识,用于日志、遥测和 VoltOps 运行元数据。

id: "support-regression";

dataset

指定评估输入,共有三种方式。

内联 items:

dataset: {
  items: [
    { id: "1", input: "hello", expected: "hello" },
    { id: "2", input: "goodbye", expected: "goodbye" },
  ];
}

命名数据集(从 VoltOps 拉取):

dataset: {
  name: "support-qa-v1",
  versionId: "abc123",  // optional - defaults to latest
  limit: 100,           // optional - limit items processed
}

自定义 resolver:

dataset: {
  name: "custom-source",
  resolve: async ({ limit, signal }) => {
    const items = await fetchFromAPI(limit, signal);
    return {
      items,
      total: items.length,
      dataset: { name: "custom-source", metadata: { source: "api" } },
    };
  },
}

resolver 接收 { limit?, signal? },返回 iterable、async iterable 或 { items, total?, dataset? } 对象(详见 Step 6)。

runner

为每条数据集条目执行你的 Agent / 工作流的函数。它接收一个上下文对象并返回输出。

上下文属性:

  • item — 当前数据集条目({ id, input, expected?, label?, extra?, ... })
  • index — 在数据集中的零基位置
  • total — 条目总数(若已知)
  • signal — 用于取消处理的 AbortSignal
  • voltOpsClient — VoltOps 客户端实例(若提供)
  • runtime — 运行元数据,包括 runId、startedAt、tags

返回格式:

// 完整格式:
runner: async ({ item }) => {
  return {
    output: "agent response",
    metadata: { tokens: 150 },
    traceIds: ["trace-id-1"], // Optional: trace IDs for observability
  };
};

// 简写格式(只返回输出):
runner: async ({ item }) => {
  return "agent response";
};

runner 可以直接返回输出,也可以返回包装了 metadata 和 traceIds 的对象。实现细节:上下文与返回类型定义在 packages/evals/src/experiment/types.ts(ExperimentRunnerContext、ExperimentRunnerResult),返回值的归一化在 packages/evals/src/experiment/run-experiment.ts 的 normalizeRunnerResult:只有返回对象且含 output 属性时才按完整格式解析,否则把原值直接作为 output。

可选字段

scorers

用于评估输出的评分函数数组。每个 scorer 将 runner 输出与期望值比较,或应用自定义逻辑。

基础用法(启发式评分器,无需 LLM / API Key):

// These scorers don't require LLM/API keys
scorers: [scorers.exactMatch, scorers.levenshtein, scorers.numericDiff];

带阈值与自定义 ID:

scorers: [
  {
    id: "similarity-check",
    scorer: scorers.levenshtein,
    threshold: 0.8,
  },
];

带 LLM 型评分器:

import { createAnswerCorrectnessScorer } from "@voltagent/scorers";
import { openai } from "@ai-sdk/openai";

scorers: [
  {
    scorer: scorers.levenshtein, // Heuristic scorer
    threshold: 0.8,
  },
  {
    scorer: createAnswerCorrectnessScorer({
      model: openai("gpt-4o-mini"), // LLM scorer requires model
    }),
    threshold: 0.9,
  },
];

设置阈值后,条目在 score < threshold 时判定失败;未设置阈值的评分器只贡献指标、不影响 pass/fail。

passCriteria

定义整个实验的成功条件,可以是单个 criterion 或数组。

平均分(meanScore):

passCriteria: {
  type: "meanScore",
  min: 0.9,
  scorerId: "exactMatch",  // optional - defaults to all scorers
  severity: "error",       // optional - "error" or "warn"
  label: "Accuracy check", // optional - for reporting
}

通过率(passRate):

passCriteria: {
  type: "passRate",
  min: 0.95,
  scorerId: "exactMatch",
}

多个 criterion:

passCriteria: [
  { type: "meanScore", min: 0.8 },
  { type: "passRate", min: 0.9, scorerId: "exactMatch" },
];

所有 criterion 必须全部通过,运行才算成功。标记为 severity: "warn" 的 criterion 不会让运行失败,但会在摘要中被上报。

label 与 description

用于仪表盘和日志的人类可读字符串:

label: "Nightly Regression Suite",
description: "Validates prompt changes against production scenarios."

tags

附加到运行上、用于过滤和检索的字符串数组:

tags: ["nightly", "production", "v2-prompts"];

metadata

包含在运行结果中的任意键值数据:

metadata: {
  branch: "feature/new-prompts",
  commit: "abc123",
  environment: "staging",
}

experiment

把运行绑定到 VoltOps 中的命名实验:

experiment: {
  name: "support-regression",
  id: "exp-123",        // optional - explicit experiment ID
  autoCreate: true,     // optional - create experiment if missing (default: true)
}

当 autoCreate 为 true 且实验不存在时,VoltOps 会在首次运行时自动创建它。该默认值在 createExperiment 的源码(create-experiment.ts)中体现为 autoCreate: config.experiment.autoCreate ?? true。

voltOps

VoltOps 集成设置:

voltOps: {
  client: voltOpsClient,        // optional - SDK instance
  triggerSource: "ci",          // optional - "ci", "manual", "scheduled", etc.
  autoCreateRun: true,          // optional - defaults to true
  autoCreateScorers: true,      // optional - register scorers in VoltOps
  tags: ["regression", "v2"],   // optional - additional tags
}

数据集条目结构(Dataset Items)

数据集中的每个条目具有如下结构:

interface ExperimentDatasetItem {
  id: string; // unique identifier
  input: unknown; // passed to runner
  expected?: unknown; // passed to scorers
  label?: string | null; // human-readable description
  extra?: Record<string, unknown> | null; // additional metadata
  datasetId?: string; // VoltOps dataset ID (auto-populated)
  datasetVersionId?: string; // VoltOps version ID (auto-populated)
  datasetName?: string; // Dataset name (auto-populated)
  metadata?: Record<string, unknown> | null; // item-level metadata
}

input 和 expected 是泛型类型——你可以使用 runner 和评分器期望的任何结构。datasetId / datasetVersionId / datasetName 由框架在运行时自动填充(例如从 VoltOps 拉取数据时),无需手动设置。完整类型定义见 packages/evals/src/experiment/types.ts。

Scorers 详解

评分器把 runner 输出与期望值比较,或应用自定义校验。每个评分器返回一个结果,包含:

  • status — "success"、"error" 或 "skipped"
  • score — 数值分数(归一化评分器为 0.0 到 1.0)
  • metadata — 附加上下文(例如 token 数、相似度细节)
  • reason — 分数的解释(尤其对 LLM 裁判)
  • error — 当 status 为 "error" 时的错误信息

启发式评分器(无需 LLM)

import { scorers } from "@voltagent/scorers";

// String comparison
scorers.exactMatch; // output === expected
scorers.levenshtein; // edit distance (0-1 score)

// Numeric and data comparison
scorers.numericDiff; // normalized numeric difference
scorers.jsonDiff; // JSON object comparison
scorers.listContains; // list element matching

LLM 型评分器

LLM 型评估请使用 VoltAgent 原生评分器,它们显式要求传入模型:

import {
  createAnswerCorrectnessScorer,
  createAnswerRelevancyScorer,
  createContextPrecisionScorer,
  createContextRecallScorer,
  createContextRelevancyScorer,
  createModerationScorer,
  createFactualityScorer,
  createSummaryScorer,
} from "@voltagent/scorers";
import { openai } from "@ai-sdk/openai";

// Create LLM scorers with explicit model configuration
const answerCorrectness = createAnswerCorrectnessScorer({
  model: openai("gpt-4o-mini"),
  options: { factualityWeight: 0.8 },
});

const moderation = createModerationScorer({
  model: openai("gpt-4o-mini"),
  threshold: 0.5,
});

实现细节:这些 create*Scorer 工厂函数的完整清单在 packages/scorers/src/index.ts 中导出,除上述外还包括 createToolCallAccuracyScorer、createTranslationScorer、createHumorScorer、createPossibleScorer 等。以 createAnswerCorrectnessScorer(packages/scorers/src/llm/answer-correctness.ts)为例,它让 LLM 把回答中的陈述逐条归类为 TP / FP / FN(真阳性、假阳性、假阴性),据此计算 F1 分数作为最终得分,options.factualityWeight 默认值为 1.0,可用来调节事实性权重。

自定义评分器

自定义打分逻辑请使用 @voltagent/core 的 buildScorer:

import { buildScorer } from "@voltagent/core";

const customLengthScorer = buildScorer({
  id: "length-validator",
  label: "Length Validator",
})
  .score(({ payload }) => {
    const output = String(payload.output || "");
    const minLength = Number(payload.minLength || 10);
    const valid = output.length >= minLength;

    return {
      score: valid ? 1.0 : 0.0,
      metadata: {
        actualLength: output.length,
        minLength,
      },
    };
  })
  .reason(({ score, results }) => ({
    reason:
      score >= 1
        ? `Output meets minimum length of ${results.raw.minLength}`
        : `Output too short: ${results.raw.actualLength} < ${results.raw.minLength}`,
  }))
  .build();

buildScorer 采用链式 DSL:.score() 定义打分逻辑,.reason() 生成人类可读的判定解释,.build() 产出可被 createExperiment 直接消费的评分器定义。更完整的自定义评分器指南见 Building Custom Scorers。

结果结构(Result Structure)

runExperiment 返回:

interface ExperimentResult {
  runId?: string; // VoltOps run ID (if connected)
  summary: ExperimentSummary; // aggregate metrics
  items: ExperimentItemResult[]; // per-item results
  metadata?: Record<string, unknown> | null;
}

汇总(Summary)

interface ExperimentSummary {
  totalCount: number;
  completedCount: number;
  successCount: number; // items with status "passed"
  failureCount: number; // items with status "failed"
  errorCount: number; // items with status "error"
  skippedCount: number; // items with status "skipped"
  meanScore?: number | null;
  passRate?: number | null;
  startedAt: number; // Unix timestamp
  completedAt?: number; // Unix timestamp
  durationMs?: number;
  scorers: Record<string, ScorerAggregate>; // per-scorer stats
  criteria: PassCriteriaEvaluation[]; // pass/fail breakdown
}

单条条目结果(Item Results)

interface ExperimentItemResult {
  item: ExperimentDatasetItem;
  itemId: string;
  index: number;
  status: "passed" | "failed" | "error" | "skipped";
  runner: {
    output?: unknown;
    metadata?: Record<string, unknown> | null;
    traceIds?: string[];
    error?: unknown;
    startedAt: number;
    completedAt?: number;
    durationMs?: number;
  };
  scores: Record<string, ExperimentScore>;
  thresholdPassed?: boolean | null; // true if all thresholds passed
  error?: unknown;
  durationMs?: number;
}

实现细节:这些结构的真实定义见 packages/evals/src/experiment/types.ts。汇总指标由 packages/evals/src/experiment/aggregator.ts 实时累加:recordAggregatorResult 按状态累加 successCount / failureCount / errorCount / skippedCount,并逐评分器维护 sumScore、minScore、maxScore 与 passCount;buildAggregatorSummary 最终计算全局 meanScore(分数总和 / 分数计数)、passRate(成功数 / 完成数)以及每个评分器的独立聚合。逐评分器的聚合 ExperimentScorerAggregate 还包含 meanScore / minScore / maxScore / passRate / threshold,可作为调试不同评分器表现的第一手依据。

错误处理

Runner 抛错

如果 runner 抛出异常,该条目会被标记为 status: "error",错误被捕获到 itemResult.error 和 itemResult.runner.error 中:

runner: async ({ item }) => {
  try {
    return await agent.generateText(item.input);
  } catch (error) {
    // Error captured automatically - no need to handle here
    throw error;
  }
};

实现细节:在 packages/evals/src/experiment/run-experiment.ts 的 processExperimentItem 中,runner 的异常被 try/catch 捕获后写入 runnerSnapshot.error,而 evaluateItemStatus 优先检查 runnerError——只要 runner 抛错,条目直接为 error 状态,不会继续执行评分。

Scorer 抛错

如果某个评分器抛错,条目同样标记为 status: "error",且该评分器自身的结果包含 status: "error" 和错误信息。从 evaluateItemStatus 的判定顺序可以看到:runner 出错 → scoring 出错 → 任一评分器结果 status === "error" → 条目为 error;只有全部评分器都正常执行后,才根据是否存在 thresholdPassed === false 判定为 failed 或 passed。没有配置任何评分器时,条目默认 passed。

取消运行(Cancellation)

传入 AbortSignal 可以提前停止运行:

const controller = new AbortController();

setTimeout(() => controller.abort(), 30000); // 30 second timeout

const result = await runExperiment(experiment, {
  signal: controller.signal,
});

被中止时 runExperiment 会抛出中止原因(signal.reason)。取消前已处理完的条目会包含在部分结果中(若已连接 VoltOps,可从中获取)。实现上,运行循环在每次迭代开始前调用 ensureNotAborted 检查中止状态,并在条目内部把同一个 signal 透传给 runner 上下文,供 Agent 调用协同取消。

并发控制(Concurrency)

通过 concurrency 并行处理多个条目:

const result = await runExperiment(experiment, {
  concurrency: 10, // 10 items at once
});

并发同时作用于 runner 执行 和 评分 阶段。更高的值提升吞吐量,但会消耗更多资源(模型 API 配额、内存、令牌数)。建议从 4–8 开始,再根据限流与系统容量调整。实现上,run-experiment.ts 用 Math.max(1, Math.trunc(options.concurrency ?? 1) || 1) 保证并发至少为 1,并通过上文所述的 active 集合 + Promise.race 实现有界并行,同时仍按数据集顺序记录结果(results[currentIndex] 定位)。

最佳实践

按用途组织数据集

把相关场景归入同一个数据集:

  • user-onboarding — 注册流程与欢迎消息
  • support-faq — 有已知答案的常见问题
  • edge-cases — 错误处理与异常输入

使用版本标签

给数据集版本打标签,追踪变化:

dataset: {
  name: "support-faq",
  metadata: {
    version: "2024-01-15",
    description: "Added 20 new questions about billing",
  },
}

组合多个评分器

用互补的评分器捕获不同类型的失败模式:

scorers: [
  scorers.exactMatch, // strict match
  scorers.embeddingSimilarity, // semantic similarity
  scorers.moderation, // safety check
];

设置现实的阈值

从宽松的阈值开始,随时间收紧:

scorers: [
  { scorer: scorers.answerCorrectness, threshold: 0.7 }, // initial baseline
];

同时要监控误报,并根据生产数据调整。

用 tags 过滤运行

用标签按上下文组织运行,方便在 VoltOps 仪表盘和 API 中过滤:

tags: [`branch:${process.env.GIT_BRANCH}`, `commit:${process.env.GIT_SHA}`, "ci"];

处理长耗时条目

在 runner 中设置超时防止挂起:

runner: async ({ item, signal }) => {
  const timeout = setTimeout(() => controller.abort(), 30000);
  try {
    return await agent.generateText(item.input, { signal });
  } finally {
    clearTimeout(timeout);
  }
};

或者直接使用框架下发的 signal 做协同取消(见“取消运行”一节)。

验证实验配置

在跑完整套件之前,先用小数据集验证实验:

const result = await runExperiment(experiment, {
  voltOpsClient,
  onProgress: ({ completed, total }) => {
    if (completed === 1) {
      console.log("First item processed successfully");
    }
  },
});

检查第一个结果,确认 runner 输出格式与评分器兼容。

完整示例

基础回归测试

import { createExperiment } from "@voltagent/evals";
import { scorers } from "@voltagent/scorers";

export default createExperiment({
  id: "greeting-smoke",
  dataset: {
    items: [
      { id: "1", input: "hello", expected: "hello" },
      { id: "2", input: "goodbye", expected: "goodbye" },
    ],
  },
  runner: async ({ item }) => item.input.toLowerCase(),
  scorers: [scorers.exactMatch],
  passCriteria: { type: "passRate", min: 1.0 },
});

RAG 评估

import { createExperiment } from "@voltagent/evals";
import { scorers } from "@voltagent/scorers";

export default createExperiment({
  id: "rag-quality",
  dataset: { name: "knowledge-base-qa" },
  runner: async ({ item }) => {
    const docs = await retriever.retrieve(item.input);
    const answer = await agent.generateText(item.input, { context: docs });
    return {
      output: answer.text,
      metadata: {
        docs: docs.map((d) => d.id),
        tokens: answer.usage?.total_tokens,
      },
    };
  },
  scorers: [
    { scorer: scorers.answerCorrectness, threshold: 0.8 },
    { scorer: scorers.contextRelevancy, threshold: 0.7 },
  ],
  passCriteria: [
    { type: "meanScore", min: 0.75 },
    { type: "passRate", min: 0.9 },
  ],
});

仓库中的可运行示例

仓库自带的 examples/with-offline-evals 示例完整演示了上述全部能力,建议对照阅读:

  • src/experiments/dataset.ts — 定义 SupportDatasetItem 类型(input / expected / 丰富的 extra 字段)与内联数据集条目;
  • src/experiments/scorers.ts — 混用启发式评分器(exactMatch、levenshtein、numericDiff、jsonDiff、listContains)与 LLM 评分器(createAnswerCorrectnessScorer、createFactualityScorer、createModerationScorer 等),并用 buildScorer 手写了关键词匹配与“帮助度裁判”两个自定义评分器;
  • src/experiments/offline.experiment.ts — 组装实验定义:id: "offline-smoke"、标签与描述、runner 调用 Agent.generateText、评分器数组与 passCriteria;
  • src/index.ts — 用 runExperiment 编程式运行并打印 Summary。

示例的 package.json(examples/with-offline-evals/package.json)依赖 @voltagent/evals、@voltagent/scorers、@voltagent/cli、@voltagent/sdk、@voltagent/core 与 ai,并提供了 dev(tsx watch)与 volt 脚本,可直接本地体验。

下一步

登录后查看全文
voltagent