AI Benchmark Index

benchmark-core

AI Benchmark Index · npm · API · MCP

benchmark-core は、再現性のある AI モデルベンチマークのためのオープンソース TypeScript エンジンです。1 つの定義から SDK、コマンドラインインターフェイス（CLI）、Model Context Protocol（MCP）サーバー、HTTP API を生成します。

タスクと決定論的な採点器で定義した内容を測定します。同梱のサンプルでは、20 件の算術問題の回答と、一時的な注文サービス障害が発生するツール使用のエピソード 1 件を測定します。

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 の 1 つだけです。

ベンチマークを定義する

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 は実行またはランタイムの失敗を表します。

Model Context Protocol

createMcpServer(benchmark) は、list_tasks、get_task、score_answer、run_benchmark、get_provenance を公開します。startMcp(benchmark) は、サーバーを標準入力と標準出力に接続します。

run_benchmark は OpenRouter を使用し、OPENROUTER_API_KEY が必要です。その他の 4 つのツールは、ネットワーク接続もキーも必要ありません。

HTTP API

createHandler(benchmark) は (request: Request) => Promise<Response> を返します。グローバル状態を持たず、Node.js または Cloudflare Workers で動作します。

メソッド	ルート	結果
GET	/health	パッケージの識別情報と状態
GET	/v1/tasks	すべてのタスク
GET	/v1/tasks/:id	1 つのタスク
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形式のツール定義と、決定論的な4つのメソッドを公開します。

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

制限事項

ランナーは失敗したタスクを隠しません。再試行を使い切った場合、エラーメッセージを含むスコア0の行になります。

タイムアウトすると待機を停止し、プロバイダーのシグナルを中断します。アダプターがそのシグナルを無視すると、プロバイダーの処理がバックグラウンドで継続する場合があります。

組み込みのスキーマ採点器が実装しているのは、ドキュメントに記載されたサブセットであり、JSON Schema仕様全体ではありません。プロバイダーがコストを返さない場合、コストは記録されません。

公開されている算術タスクと注文タスクは、対象機能をテストするものであり、最先端モデルの能力を測るものではありません。本格的な比較には、非公開の分割データまたは保留データを使用してください。

開発

npm ci
npm run ci:local

このゲートでは、リンティング、型チェック、ビルドを実行し、エンドツーエンドスクリプトを1つ実行します。このスクリプトはすべてのタスク、API ルート、MCP ツールをテストし、その後 artifacts/e2e-report.json に書き込みます。

バージョン 0.1.0 はアルファ版です。不具合はGitHub のイシューから報告してください。

ライセンス

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}
}