VoltAgent 评估体系实战指南:用离线回归、CI 门禁与在线监测度量 Agent 表现

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

VoltAgent 评估体系实战指南:用离线回归、CI 门禁与在线监测度量 Agent 表现

VoltAgent 提供了一套统一的 Agent 评估体系(Evaluations),让开发者可以用同一份实验定义,在本地、自动化流水线或 VoltOps 控制台之间无缝运行,衡量 Agent 在离线测试集、夜间回归和 CI 门禁中的表现。本文以 @voltagent/evals、@voltagent/scorers 为核心,完整讲解评估的六大构建块、离线评估的端到端流程(实验定义 → 数据集解析 → Runner 执行 → 打分 → 聚合 → 通过标准判定)、CLI 与 Node 两种运行方式,以及实时流量上的在线评分(Live Evaluations)如何通过 OTLP 追踪汇入 VoltOps。

读完本文,你将能够:定义一个可版本化、可复跑的 TypeScript 实验文件;在 CLI 与程序化 API 之间自由切换执行方式;组合启发式评分器与 LLM Judge;用 passCriteria 把评估变成发布门禁;并为生产 Agent 挂载采样评分以做内容安全监测。

为什么要为 Agent 建立评估体系

Agent 的输出是概率性的,改动一条提示词、更换一个模型或调整工具定义,都可能让行为在用户不可见处悄悄退化。VoltAgent Evaluations 的设计目标正是解决这类问题:

  • 上线前拦截回归(Catch regressions before they ship):同一份数据集在提示词或模型变更后重跑,即可量化准确率与质量的波动;
  • 标准化度量(Standardise measurement):单个实验可混用多种评分器(精确匹配、语义相似度、内容审核、LLM Judge 等),并自动计算通过阈值;
  • 与 VoltOps 形成闭环(Close the loop with VoltOps):每次离线运行都会与线上流量并列展示,复用同一套标签、过滤器和检索能力来调试 Agent;
  • 可脚本化、可复现(Scriptable & repeatable):实验本身就是普通的 TypeScript 模块,可以纳入版本控制、共享,并在任意 Node.js 环境执行。

这套设计在仓库中体现为独立的评估与评分包:packages/evals 负责实验编排,packages/scorers 提供评分器,二者共同支撑 packages/core 中的 Agent 运行时与在线评分能力。

六大核心构建块

概念 职责
实验定义(createExperiment) 描述一次运行:数据集来源、如何调用 Agent/Runner、应用哪些评分器、以及通过标准
Runner 接收一条数据集条目并返回 Agent 输出(可附带元数据 / 追踪)的函数
数据集(Dataset) 评估输入,可为内联 JSON、动态生成,或从 VoltOps 拉取
评分器(Scorers) 可复用的评分函数(精确匹配、嵌入、LLM 判分、内容审核等),产出分数、阈值与元数据
聚合器(Aggregator) 计算汇总统计(平均分、通过率、阈值合规)并给出整体通过/失败结论
VoltOps 集成 可选客户端,自动创建 run、流式上报逐条结果并最终化汇总,方便在 Console 中检视

从源码看,实验定义是一个带 kind: "voltagent.experiment" 标记、配置被 Object.freeze 冻结的不可变对象(见 create-experiment.ts)。createExperiment 在创建时即做运行时校验:id 必须是非空字符串、runner 必须是函数,否则直接抛出 TypeError——这保证了实验定义在写错的第一时间就被发现,而不是等到跑批时才崩溃。

实验定义的类型全景

createExperiment 接受的 ExperimentConfig 完整字段如下(定义见 types.ts):

字段 类型 说明
id string(必填) 实验唯一标识,非空字符串
label / description string? 便于在 UI 与日志中识别实验
dataset ExperimentDatasetDescriptor 数据集描述符:items、resolve 或 name 三选一
runner ExperimentRunner 接收 { item, index, total, signal, voltOpsClient, runtime } 并返回输出
scorers ExperimentScorerConfig[] 评分器定义或其带 threshold/params 的包装条目
passCriteria ExperimentPassCriteria | [] 支持 meanScore 与 passRate 两种标准
tags string[] 打标签,随 run 一起上报 VoltOps
experiment ExperimentBindingDescriptor 绑定到 VoltOps 侧实验(id / name / autoCreate)
metadata Record<string, unknown>? 自由元数据,随结果透传
voltOps ExperimentVoltOpsOptions client、triggerSource、autoCreateRun、autoCreateScorers、tags

createExperiment 在创建时会对 tags 做 trim 与去重、对 metadata 做浅拷贝,并把 experiment.autoCreate 默认置为 true——也就是说,当你在 experiment 中只给了一个 name 且客户端支持时,VoltOps 会自动为你创建对应的实验记录(见 create-experiment.ts)。

离线评估:端到端流程

离线评估(Offline Evaluations)面向固定数据集运行,产出确定性分数,最适合回归测试、CI 门禁与分支对比。官方文档给出了完整的五步流程,下面逐步展开并结合源码说明底层机制。

第 1 步:定义实验

// experiments/support-nightly.experiment.ts
import { createExperiment } from "@voltagent/evals";

export default createExperiment({
  id: "support-nightly",
  dataset: { name: "support-nightly" },
  runner: async ({ item }) => ({ output: item.input }),
});

一个实验文件就是一个默认导出的模块。id 用于标识实验本身,dataset.name 指向数据集,runner 是核心执行函数——它只负责"把一条输入变成 Agent 输出"。

第 2 步:解析数据集

数据集有三种声明方式(解析逻辑见 dataset.ts):

dataset: {
  items: [
    { id: "greeting", input: "hello", expected: "hello" },
    { id: "farewell", input: "goodbye", expected: "goodbye" },
  ],
};

// 或:按名称引用(需先用 registerExperimentDataset 注册,或由 VoltOps 提供)
dataset: { name: "support-nightly" };

// 或:自定义 resolver,动态生成 / 流式拉取
dataset: {
  name: "generated",
  resolve: async ({ limit, signal }) => ({ items: generateItems(limit) }),
};

解析优先级从源码看很清晰:items(内联数组/可迭代对象)→ resolve(自定义解析函数)→ name(查注册表或 VoltOps)。三种来源最终都会被规范化为异步可迭代流(AsyncIterable),并统一支持 limit 截断与 AbortSignal 取消。每个数据条目 ExperimentDatasetItem 的核心字段为 id、input、expected?、extra? 与 metadata(见 types.ts)。

需要强调的是:当数据集只有 name 且传入了 VoltOps 客户端时,运行时会自动把该名称解析到 VoltOps 托管的数据集(见 run-experiment.ts 的 attachVoltOpsDatasetResolver),这也是"同一数据集在 CLI、CI、UI 三处复用"的实现基础。

第 3 步:执行 Runner

runner: async ({ item }) => {
  const reply = await supportAgent.generateText(item.input);
  return { output: reply.text, metadata: { tokens: reply.usage?.total_tokens } };
};

Runner 的返回结构由 ExperimentRunnerReturn 定义:既可以返回 { output, metadata?, traceIds? } 结构化对象,也可以直接返回裸值(如字符串),运行时会把裸值规范化为 { output: value }(见 run-experiment.ts)。traceIds 字段用于把本次调用的链路追踪 ID 带上,便于在 VoltOps 中从评估结果直接跳转到对应的真实 Trace。

Runner 执行失败不会中断整个实验:异常会被捕获并写入该条目的 runner.error,该条目状态标记为 error,继续处理后续条目(见 run-experiment.ts)。

第 4 步:评分

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

scorers: [scorers.exactMatch, scorers.embeddingSimilarity({ expectedMin: 0.8 })];

评分阶段发生在 Runner 成功之后。运行时把 { input, expected, output, item, datasetId, ... } 组装成评分 Payload,调用 runLocalScorers 并行执行所有评分器(见 run-experiment.ts)。评分器配置有两种写法:

  • 直接引用:scorers.exactMatch——使用评分器默认参数;
  • 包装条目:{ scorer, threshold?, params?, id?, name? }——可覆盖阈值、注入参数。包装条目中的 threshold 会被归一化为有限数字,并写进评分器元数据的 voltAgent.threshold 字段(见 scorers.ts)。

@voltagent/scorers 的评分器分两大类(见 index.ts):

  • 启发式评分器(无需 API Key):exactMatch、levenshtein、numericDiff、listContains、jsonDiff,源自 AutoEvals 且不依赖 LLM;
  • LLM 评分器(需传入模型):createModerationScorer、createFactualityScorer、createAnswerCorrectnessScorer、createAnswerRelevancyScorer、createContextPrecisionScorer、createContextRecallScorer、createContextRelevancyScorer、createToolCallAccuracyScorerCode 等(源码见 scorers/src/llm 目录)。

文档示例中的 scorers.embeddingSimilarity({ expectedMin: 0.8 }) 是带阈值的评分器配置形态:评分器内部产出分数后,运行时会依据 threshold(或其元数据中的阈值)计算 thresholdPassed——只要 score >= threshold 即视为通过(见 run-experiment.ts)。

第 5 步:聚合与通过标准

passCriteria: { type: "passRate", min: 0.95 };

passCriteria 支持两种标准(见 types.ts):

类型 字段 语义
meanScore min: number,可选 scorerId 全局(或指定评分器)平均分 ≥ min 即通过
passRate min: number,可选 scorerId 通过条目占比 ≥ min 即通过

两条标准均可传入数组,全部满足才算整体通过;未指定 scorerId 时按全局指标计算(见 aggregator.ts)。聚合器逐条累积 successCount / failureCount / errorCount / skippedCount、全局分数总和与各评分器的 min/max/mean/passRate,最终输出 ExperimentSummary(见 aggregator.ts)。

条目级的状态判定规则同样值得关注(见 run-experiment.ts):Runner 或评分器抛错 → error;无任何评分器 → 直接 passed;任一评分器 thresholdPassed === false → failed;否则 passed。

运行离线评估:CLI 与 Node 双通道

方式一:CLI

npm run volt eval run \
  -- --experiment ./src/experiments/support-nightly.experiment.ts \
  --concurrency 4

CLI 会替你完成 TypeScript 打包与 VoltOps 关联:自动解析 .experiment.ts 模块、流式打印进度,并在检测到 VoltOps 凭据时把 run 链接到命名实验(见 packages/cli)。

方式二:Node 脚本(程序化 API)

import { VoltOpsClient } from "@voltagent/core";
import { runExperiment } from "@voltagent/evals";
import experiment from "./experiments/support-nightly.experiment";

const voltOpsClient = new VoltOpsClient({
  publicKey: process.env.VOLTAGENT_PUBLIC_KEY,
  secretKey: process.env.VOLTAGENT_SECRET_KEY,
});

const result = await runExperiment(experiment, {
  voltOpsClient,
  concurrency: 4,
  onProgress: ({ completed, total }) => console.log(`Processed ${completed}/${total ?? "?"}`),
});

runExperiment 的完整选项(见 run-experiment.ts):

选项 说明
concurrency 并发条数,默认 1,运行时经 Math.max(1, trunc(concurrency)) 规范化
signal AbortSignal,用于中途取消(每个条目执行前都会检查是否已 abort)
voltOpsClient 客户端实例,优先级高于配置内的 voltOps.client
onItem 逐条回调:({ index, item, result, summary })
onProgress 进度回调:({ completed, total })

源码层面的并发实现是"信号量式"的:运行时维护一个进行中的任务集合 active,当 active.size >= concurrency 时 await Promise.race(active) 等待最早完成的任务腾出名额(见 run-experiment.ts)。runExperiment 的返回值 ExperimentResult 包含 runId、summary(含逐评分器聚合与 criteria 判定)、items(逐条结果含分数明细)与 metadata,可直接用于 CI 断言。

一个完整的离线冒烟实验

// experiments/offline-smoke.experiment.ts
import { createExperiment } from "@voltagent/evals";
import { scorers } from "@voltagent/scorers";
import { supportAgent } from "../agents/support";

export default createExperiment({
  id: "offline-smoke",
  dataset: { name: "support-nightly" },
  experiment: { name: "support-nightly-regression" },
  runner: async ({ item }) => {
    const reply = await supportAgent.generateText(item.input);
    return { output: reply.text };
  },
  scorers: [scorers.exactMatch],
  passCriteria: { type: "meanScore", min: 0.9 },
});

这个实验的亮点在于 experiment: { name: "support-nightly-regression" }:它把本次离线 run 绑定到一个命名实验。从 voltops/run.ts 可以看到,运行时先尝试按 name 解析实验 ID,解析不到且 autoCreate 为真时自动创建,并把解析结果写回结果的 metadata.voltOps.experiment 中。若客户端不支持实验自动创建,autoCreateReason 会记录具体原因——这一设计让"实验结果归属到哪个实验"始终可审计、可追溯。

VoltOps run 生命周期

只要检测到 VoltOps 客户端,运行时会自动执行一次完整的 run 生命周期(实现见 voltops/run.ts):

  1. create:创建 Eval Run,携带 datasetVersionId、experimentId 与 triggerSource(默认值 "run-experiment",见 voltops/run.ts,可通过 voltOps.triggerSource 覆盖);
  2. appendResults:每完成一个条目即流式上报(分数、阈值、thresholdPassed、Trace ID、输入输出等,见 voltops/run.ts);
  3. complete:根据汇总推断终态——有错误或存在未通过标准则 failed,否则 succeeded(见 voltops/run.ts);
  4. fail:异常路径下将错误序列化上报,run 标记为失败。

voltOps.autoCreateRun 设为 false 可以关闭自动建 run,适合只想本地跑分、不打扰云端数据的情况。测试侧,run-experiment.spec.ts 与 voltops/run.spec.ts 覆盖了这些生命周期路径,可作为理解行为细节的补充参考。

在线评估:把评分器挂到实时流量上

在线评估(Live Evaluations)把评分器直接附着到真实的 Agent 交互上,适合生产监控、内容审核,以及在实际流量下采样对话质量。与离线评估"先跑批再打分"不同,它随调用即时发生:

// Attach live scorers when defining an agent
import VoltAgent, { Agent, VoltAgentObservability } from "@voltagent/core";
import { createModerationScorer } from "@voltagent/scorers";
import { openai } from "@ai-sdk/openai";
import honoServer from "@voltagent/server-hono";

const observability = new VoltAgentObservability();
const moderationModel = openai("gpt-4o-mini");

const supportAgent = new Agent({
  name: "live-scorer-demo",
  instructions: "Answer questions about VoltAgent.",
  model: openai("gpt-4o-mini"),
  eval: {
    triggerSource: "production",
    environment: "demo",
    sampling: { type: "ratio", rate: 1 },
    scorers: {
      moderation: {
        scorer: createModerationScorer({ model: moderationModel, threshold: 0.5 }),
      },
    },
  },
});

new VoltAgent({
  agents: { support: supportAgent },
  observability,
  server: honoServer(),
});

配置要点拆解:

  • sampling:采样策略,{ type: "ratio", rate: 1 } 表示 100% 采样。在线评分会在每次 Agent 调用后按此策略决定是否执行评分器,避免高分频流量下的成本失控;
  • triggerSource / environment:标记评分来源与运行环境,随 OTLP 属性上报;
  • scorers:以命名键挂载多个评分器,本例用 createModerationScorer 做内容审核,threshold: 0.5 表示审核分数达到 0.5 即触发告警判定。

典型使用场景:

  • 采样线上流量、执行内容审核或喂给 LLM Judge,无需等待批跑;
  • 与离线评估组合:上线前用离线回归做确定性检查,上线后用在线评分做持续监测。

在线与离线的关键区别(文档原话,务必留意):在线评分结果通过 eval.scorer.* 属性写入 OTLP Trace Span,并展示在 VoltOps 的 Live Scores / 遥测视图中;它们不会被持久化到 Eval Runs,与数据集/实验 run 保持隔离。

这条链路在 packages/core/src/agent/eval.ts 中有完整实现:运行时在每个 span 上写入 eval.scorer.id、eval.scorer.name、eval.scorer.kind: "live"、eval.scorer.status、eval.scorer.score、eval.scorer.threshold、eval.scorer.threshold_passed、eval.scorer.duration_ms 以及采样相关的 eval.scorer.sampling.applied / rate / strategy 等属性(见 eval.ts),并通过 addEvent("eval.scorer.result", ...) 记录结果事件。这正呼应了文档中"Live scorer results are added to OTLP trace spans via eval.scorer.*"的描述——排查线上问题时,你可以直接在 Trace 上看到每次调用被哪个评分器打了多少分、是否通过阈值。

下一步

  • Quick-start 快速上手演练:docs/evals/quick-start(规划中)
  • 实验定义参考:docs/evals/concepts/experiment-definition(规划中)
  • 评分器目录与编写指南:docs/evals/concepts/scorers(规划中)
  • CLI 使用说明:docs/evals/reference/cli(规划中)

在上述文档正式发布前,仓库内已有大量可直接参考的实现与测试:packages/evals/src/experiment 下的 types.ts(完整类型)、run-experiment.ts(执行引擎)、aggregator.ts(聚合器)、dataset.ts(数据集解析),packages/scorers/src 下的启发式与 LLM 评分器,以及配套的 *.spec.ts 测试文件,都是理解这套评估体系最权威的一手资料。

登录后查看全文
voltagent