getsentry/vitest-evals

什么是 vitest‑evals？

vitest‑evals 是一个 单体仓库，为 JavaScript 测试运行器 Vitest 添加了一流的评估层。它允许开发者为 AI 驱动的应用程序（LLM、代理、使用工具的机器人等）编写 显式运行 的评估套件，并获得结构化的 JSON 报告，这些报告可本地检查或重新发布到 GitHub Actions 中。

为什么它很重要

AI 友好的测试助手 – describeEval、run 和 expect(...).toSatisfyJudge 让你可以在保持普通 Vitest 断言的同时，使用 判断器（例如事实性、工具调用正确性）检查 LLM 输出。
可插拔的适配器 – 为 Sentry AI SDK、OpenAI 代理、Pi-AI 或任何自定义适配器提供适配器，使相同的评估 API 能在不同模型提供商之间通用。
CI 集成 – 内置的 GitHub Action 读取 JSON 报告，添加步骤摘要，标注失败，并可发布一个检查运行，根据通过率或分数阈值来阻止 PR 合并。
本地 UI – vitest‑evals serve 启动一个 React 单页应用，可视化运行结果、工具调用、令牌使用量、成本和追踪跨度，使调试 LLM 行为变得容易得多。
可重放的工具调用 – 工具调用的记录被保存在磁盘上，可自动重放，确保测试运行的确定性。

仓库的核心组件

包 / 应用	作用
`packages/vitest-evals`	核心 API：`describeEval`、判断器、适配器/会话类型，以及自定义 Vitest 报告器。
`packages/core`	共享基础结构、JSON 模式定义和用于聚合完整报告的辅助函数。
`packages/report-ui`	React 单页应用和 CLI（`serve`）用于浏览 JSON 评估资产。
`packages/harness‑ai-sdk`	适配器，使核心 API 能与 Sentry AI SDK 适配器通信。
`packages/harness‑openai‑agents`	适用于 @openai/agents 风格代理的适配器。
`packages/harness‑pi‑ai`	适用于 pi‑ai 的适配器，内置工具重放支持。
`packages/github-reporter`	GitHub Actions 动作，消费 Vitest JSON 报告并写入摘要/注释/检查运行。
`apps/demo‑pi`, `apps/demo‑ai-sdk`, `apps/demo‑openai‑agents`	小型端到端演示应用，展示如何使用每个适配器评估一个退款代理。

如何使用它

添加包 到单体仓库（或从 npm 安装所需包）。

使用熟悉的 Vitest 语法编写评估套件：

import { describeEval, FactualityJudge, toolCalls } from 'vitest-evals';
import { piAiHarness, piAiJudgeHarness } from '@vitest-evals/harness-pi-ai';

const judge = FactualityJudge({ judgeHarness: piAiJudgeHarness({ model: 'claude-sonnet', temperature: 0 }) });

describeEval('refund agent', { harness: piAiHarness({ agent: createRefundAgent }) }, (it) => {
  it.for([{ name: 'approves invoice', input: 'Refund invoice 123', expectedTools: ['lookupInvoice','createRefund'] }])
    ('$name', async ({ input, expectedTools }, { run }) => {
      const result = await run(input);
      expect(toolCalls(result).map(c => c.name)).toEqual(expectedTools);
      await expect(result).toSatisfyJudge(judge);
    });
});

使用提供的 CLI 运行套件：

pnpm evals          # 运行所有暴露 "evals" 脚本的包/应用
pnpm evals --info   # 更丰富的每工具元数据

本地检查结果：
```
pnpm exec vitest-evals serve vitest-results.json
```
这将打开一个 UI，显示每个测试、LLM 输出、工具调用、令牌使用量和成本。

添加 CI 报告（README 中的 GitHub Actions 示例）：

- run: pnpm exec vitest run ... --reporter=vitest-evals/reporter --outputFile.json=vitest-results.json
- uses: getsentry/vitest-evals@v0
  with:
    results: vitest-results.json
    publish-check: true
    min-pass-rate: 0.8

该动作会发布摘要、标注失败，并在通过率低于阈值时阻止合并。

核心概念详解

适配器 – 一种轻量级包装器，知道如何启动你的 AI 驱动的应用（或代理）并用测试输入调用它。不同 SDK/提供商有不同适配器。
判断器 – 一种逻辑（通常由 LLM 支持）对模型响应进行评分。内置判断器包括 FactualityJudge、StructuredOutputJudge 和 ToolCallJudge。通过实现 assess(ctx) 函数可编写自定义判断器。
显式运行 – 与让 Vitest 直接调用测试函数不同，套件调用适配器的 run(input)，从而完全控制请求/响应生命周期，并允许框架捕获跨度、令牌计数和工具使用情况。
重放模式 – 工具调用记录保存在 .vitest-evals/recordings 下。当 VITEST_EVALS_REPLAY_MODE=auto 时，会自动重放现有记录；record 强制进行实时调用。这使评估具有确定性，同时仍可轻松刷新测试用例。
JSON 报告 – 自定义报告器输出一个结构化文件，包含每项测试的元数据、分数、令牌使用量、成本（美元）、原始跨度。该文件驱动 UI、GitHub Action 和任何下游分析。

哪些人应该考虑使用它？

构建 LLM 驱动的服务、代理或使用工具的机器人 并需要自动化质量检查的团队。
已经使用 Vitest 进行单元/集成测试并希望以低摩擦方式添加 AI 特定断言的项目。
希望实现 CI 可门控评估（例如，要求最低事实性分数才能合并）的组织。
任何希望拥有 可视化调试 UI 以查看 LLM 输出、令牌使用量和工具交互的人。

如何了解更多

文档网站 – https://vitest-evals.sentry.dev/docs（设置指南、架构、CI 详情）。
包 README – 尤其是 packages/vitest-evals/README.md，了解核心 API。
演示应用 – apps/demo‑pi、apps/demo‑ai-sdk、apps/demo‑openai‑agents 展示了真实世界用法。

总结

vitest‑evals 通过为 AI 代理提供结构化评估框架，扩展了 Vitest，提供适配器、可重用判断器、JSON 报告、本地 UI 和 GitHub Actions 的原生集成。它让你可以保留常规测试断言，同时添加可重现、可观测且可被 CI 门控的 AI 特定质量检查。