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 特定品質檢查。