VoltAgent 离线评估(Offline Evaluations)实战指南:从 createExperiment 到 CI 质量门禁
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— 用于取消处理的AbortSignalvoltOpsClient— 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 脚本,可直接本地体验。
下一步
- Prebuilt Scorers — 预置评分器完整目录
- Building Custom Scorers — 编写你自己的评估评分器