AI Benchmark Index

benchmark-core

AI 基准测试索引 · npm · API · MCP

benchmark-core 是一个开源的 TypeScript 引擎，用于可复现的 AI 模型基准测试。一个定义即可生成 SDK、命令行界面（CLI）、模型上下文协议（MCP）服务和 HTTP API。

它会测量由你的任务和确定性评分器定义的内容。附带的示例会测量 20 个算术答案，以及一个遇到订单服务短暂故障的工具使用过程。

npx benchmark-core run --model offline --provider mock --json

{"model":"mock:1","mean":0.5238,"confidenceInterval95":{"low":0.3333,"high":0.7143},"totals":{"tasks":21,"passed":11,"failed":0}}

示例数据来自一个已提交的、带种子的生成器。种子 20261015 可复现所有公开任务。

安装

benchmark-core 需要 Node.js 20 或更高版本。

npm install benchmark-core

该软件包只有一个运行时依赖：官方 MCP TypeScript SDK。

定义基准测试

import { defineBenchmark, exactMatch, run, mockAdapter } from "benchmark-core";

const benchmark = defineBenchmark({
  id: "benchmark-colors",
  name: "Color recall",
  tagline: "Checks exact color recall.",
  tags: ["science"],
  category: "memory",
  whatItMeasures: "Exact recall of a named color.",
  version: "0.1.0",
  status: "alpha",
  tasks: [{ id: "sky", kind: "single", prompt: "Name the sky color.", expected: "blue" }],
  grade: (task, submission) => exactMatch(task.expected, submission.answer ?? ""),
  provenance: [{
    name: "Maintainer-written task",
    kind: "human-written",
    url: "https://github.com/example/benchmark-colors",
    licence: "MIT",
    howToGet: "Read data/tasks.jsonl.",
    retrievedAt: "2026-10-15T00:00:00.000Z",
    contaminationNotes: "Public task; use a hidden split for final comparisons.",
    refresh: "Review and add tasks through pull requests."
  }],
  gradingMethod: "Exact string match."
});

const report = await run(benchmark, mockAdapter(), { concurrency: 2, seed: 7 });
console.log(report.mean);

tasks 可以替换为异步 loadTasks() 函数。任务 ID 必须唯一，并且每个任务都要声明 kind: "single" | "episode"。

工作原理

defineBenchmark({ tasks, grade, environment, provenance })
                  │
        ┌─────────┼──────────┐
        │         │          │
       SDK       CLI      MCP server
        │         │          │
        └─────────┴──── HTTP handler
                  │
             RunReport JSON

运行器在使用有限并发的同时保留任务顺序。每行都会记录尝试次数、延迟、得分、原因、用量和错误。过程类任务的行还会包含对话记录、工具日志、最终状态和中止原因。

95% 置信区间使用 2,000 次带种子的自助重采样计算。得分和种子相同，生成的区间也相同。

运行时接口

CLI

基准测试软件包会调用 createCli(benchmark, { bin })。返回的 main(argv) 支持：

• list
• show <task>
• run --model <id> --provider <openrouter|openai|mock>，可选设置过程类任务的限制
• score <results.json>
• card <report.json> [output.svg]
• provenance
• index-entry
• serve [port]
• mcp

每条命令都接受 --json。退出代码 0 表示成功，1 表示用法无效，2 表示运行或运行时失败。

模型上下文协议

createMcpServer(benchmark) 会公开 list_tasks、get_task、score_answer、run_benchmark 和 get_provenance。startMcp(benchmark) 会通过标准输入和输出连接到该服务。

run_benchmark 使用 OpenRouter，并需要 OPENROUTER_API_KEY。其他四个工具无需网络或密钥。

HTTP API

createHandler(benchmark) 返回 (request: Request) => Promise<Response>。它没有全局状态，可用于 Node.js 或 Cloudflare Workers。

方法	路由	结果
GET	/health	软件包标识和健康状态
GET	/v1/tasks	所有任务
GET	/v1/tasks/:id	单个任务
POST	/v1/score	对 { taskId, submission } 进行确定性评分
GET	/v1/provenance	数据来源
GET	/v1/index-entry	目录条目

GET 响应包含宽松的跨域资源共享（CORS）设置。超过 1 MiB 的请求正文会返回稳定的 REQUEST_TOO_LARGE 错误。

serve(handler, { port }) 使用 node:http 托管同一个处理程序。

服务默认监听 127.0.0.1。只有在容器或代理需要外部绑定时，才使用 serve --host 0.0.0.0。

POST /v1/score 没有内置身份验证。公开部署时，请在前面配置授权和速率限制。启用 LLM 评分器后，每次评分请求都会调用付费模型。

工具使用回合

回合任务针对预置的进程内 Environment 运行。环境会公开 JSON Schema 工具定义和四种确定性方法：

interface Environment {
  reset(task, seed): { system: string; tools: ToolSpec[] };
  callTool(name, args): { result: unknown; error?: { code: string; message: string } };
  state(): unknown;
  done(): boolean;
}

runEpisode(task, adapter, environment, options) 会强制执行轮次、工具调用次数和美元金额限制。超出预算时会返回 aborted: "budget" 的回合；主运行器仍会将其轨迹发送给评分器。

通用提交内容为 Trace：

{
  answer?: string;
  toolLog?: ToolLogEntry[];
  finalState?: unknown;
}

replay(environment, task, toolLog, seed) 会重置模拟器，并仅重复已记录的调用。回合评分器无需模型或网络调用即可计算结果。

参考实现 OrderLookupEnvironment 会在首次预置的查询中注入 HTTP 500 错误。其良好的模拟策略会重试、加载一笔 $35 的订单，并遵循 $50 的退款限额。

模型适配器

• mockAdapter({ seed, policies }) 可离线运行。它会返回确定性的预期答案与错误答案组合，然后遵循基准测试提供的 good(task) 或 bad(task) 回合脚本。
• openrouterAdapter({ model }) 会读取 OPENROUTER_API_KEY。
• openaiCompatAdapter({ baseUrl, model }) 会在选项未提供相应值时读取 OPENAI_BASE_URL 和 OPENAI_API_KEY。

适配器会为单项任务实现 complete(prompt, context)，并为回合实现 chat({ messages, tools }, context)。API 报告的用量和费用会计入各行及报告总计。

评分器

• exactMatch(expected, answer) 会精确比较 JSON 值。
• regexMatch(pattern, answer) 会测试字符串答案。
• numericWithin(expected, tolerance, answer) 会接受处于包含边界的容差范围内的数字。
• jsonSchemaMatch(schema, answer) 会检查无需依赖项的 JSON Schema 子集。
• judgeWithLLM(adapter, prompt?) 会创建一个可选启用的模型评分器。

jsonSchemaMatch 支持 type、enum、required、properties、items、additionalProperties、pattern、minimum 和 maximum。

默认评分提示词以 DEFAULT_JUDGE_PROMPT 导出：

对候选答案进行 0 到 1 的评分。仅返回包含数字 score 和字符串 reason 的 JSON。

评分器必须返回 {"score": number, "reason": string}。除非基准测试代码调用 judgeWithLLM，否则不会启用模型评分。

报告和元数据

• renderCard(report) 会返回一张 1200×630 的 SVG 分享卡片。
• renderMarkdown(report) 会返回 Markdown 摘要和任务表格。
• indexEntry(benchmark) 会返回 AI Benchmark Index 记录。
• provenanceMarkdown(benchmark) 会根据代码生成来源说明文档。

将渲染后的来源说明文件与 tasks.jsonl 放在一起提交。端到端测试会逐字节比较示例文件。

实用工具和类型

mulberry32(seed) 会提供一个小型的预置随机数生成器。bootstrapCI(values, seed?, resamples?) 会返回百分位数界限。

此软件包导出以下类型：

• Task、Trace、TaskScore 和 GradeContext
• ToolSpec、ToolCall、ToolLogEntry、ToolResult 和 ToolError
• Environment、EnvironmentStart、Episode 和 EpisodeOptions
• BenchmarkDefinition、Benchmark、BenchmarkTag 和 BenchmarkStatus
• ModelAdapter、ModelAdapterContext、CompletionResult、ChatRequest、ChatResult、ChatMessage 和 ModelUsage
• MockPolicies 和 ScriptedTurn
• RunOptions、RunRow 和 RunReport
• Provenance、ProvenanceKind 和 IndexEntry
• JsonSchema、JsonSchemaObject、JsonValue、JsonPrimitive 和 Answer

限制

运行器不会隐藏失败的任务。重试耗尽后，会生成得分为零且带有错误消息的行。

超时会停止等待并中止提供方信号。如果适配器忽略该信号，提供方的工作可能会在后台继续。

内置 Schema 评分器实现的是文档所述的子集，而非完整的 JSON Schema 规范。如果提供方未提供费用，费用字段将保持缺失。

公开的算术和订单任务测试的是各项功能，而非前沿模型能力。严肃比较时，请使用私有或留出集。

开发

npm ci
npm run ci:local

质量门禁会运行 lint、类型检查和构建，并执行一个端到端脚本。该脚本会测试每个任务、API 路由和 MCP 工具，然后写入 artifacts/e2e-report.json。

0.1.0 版为 alpha 版。请通过 GitHub issues 报告缺陷。

许可证

MIT © Pooria Arab

引用

请使用此软件包的 Zenodo DOI 引用。下方的 DOI 指向所有版本。GitHub 也会根据 CITATION.cff 显示“引用此仓库”框。

@software{arab2026benchmarkcore,
  author  = {Arab, Pooria},
  title   = {benchmark-core},
  year    = {2026},
  version = {0.1.0},
  doi     = {10.5281/zenodo.23422358},
  url     = {https://aibenchmarkindex.com/benchmarks/benchmark-core}
}