メインコンテンツへスキップ

Eval Harness v2.0

エグゼクティブサマリー。 このページでは、MT評価ハーネスのインストール、設定、および使用方法について説明します。MT評価ハーネスは、翻訳手法を標準化されたコーパスに対してベンチマークし、スコア付きのランカードを生成するツールです。メトリクス、スキーマ、および評価プロトコルの正式な定義については、ベンチマーク仕様を参照してください。

ハーネスは翻訳実験を実行し、ランカードを生成します。プロンプトの構築、APIコール、スコアリング、および結果のシリアライズを処理します。データセットとモデルはユーザーが用意します。

インストール​

要件： Python 3.10以上

pip install sacrebleu aiohttp

ハーネスリポジトリをクローンします：

git clone https://github.com/gamedaysuits/arena.git
cd arena

使用方法​

mt-eval run --corpus path/to/dataset.json

これにより、コーパス内のすべてのエントリが設定済みのモデル（またはメソッドプラグイン）を通じて処理され、出力がスコアリングされ、ランカードのJSONファイルが出力ディレクトリに書き込まれます。

CLIフラグ​

mt-eval run​

フラグ必須デフォルト説明
--corpus✅—コーパスファイルへのパス（.json、.jsonl、.tsv）
--source-file / --reference-file——対訳テキストファイル（FLORES+、WMT形式）
-m, --model—gemini-proモデルスラッグ（短縮名またはOpenRouterのフルID）。shared/model-aliases.jsonを通じて解決されます。マルチモデル実行の場合はカンマ区切り
-d, --dataset—allデータセットフィルター：all、セグメント名、またはIDの範囲
--ids——評価するエントリIDのカンマ区切りリスト
--source-lang—Englishソース言語名
--target-lang——ターゲット言語名
-p, --prompt—naiveプロンプトバージョン（naive、custom、champollion）
--coaching-file——コーチングプロンプトテキストファイルへのパス
--coaching——インラインコーチングテキスト（引用文字列）
--method——メソッドプラグインディレクトリへのパス（method.jsonとPythonモジュールを含む）
--method-card——リーダーボードメタデータ用のメソッドカードJSONへのパス
--fst-retries—0FSTリトライ試行回数（デフォルトLLMメソッドのみ）
--skip-fst—falseFSTクオリティゲートを完全にスキップする
--tools—falseツール呼び出しモードを有効にする
--tools-list——ツール名のカンマ区切りリスト
--max-tool-rounds—8エントリごとのツール呼び出しの最大ラウンド数
--hooks——翻訳後フック名
--style-profile——スタイルプロファイルJSONへのパス。文章スタイルの一貫性メトリクスを有効にします（情報提供のみ — コンポジットスコアには含まれません。§ 文章スタイルとレジスターメトリクスを参照）
-b, --batch-size—25APIコールあたりのエントリ数
-c, --concurrency—8並列APIコール数
--max-tokens—32768APIコールあたりの最大トークン数
--temperature—0.0サンプリング温度（0.0 = 決定論的）
--no-cache—falseレスポンスキャッシュを無効にする
--cache-dir—eval/cache/harnessキャッシュディレクトリのパス
-o, --output-dir—eval/logs/harnessランカードとログの出力ディレクトリ
-n, --name——人間が読めるラン名
--dry-run—falseAPIコールを行わずに設定を検証する
--champollion-config——champollion.config.jsonへのパス
--champollion-cards-dir——言語カードのディレクトリ
--target-lang-code——BCP-47言語コード

その他のサブコマンド​

サブコマンド説明
mt-eval test <log_path>完了したランログを分析する
mt-eval publish <report_path>ランカードをリーダーボードに提出する
mt-eval compare <logs...>複数のランを並べて比較する
mt-eval dashboard <logs...>ランログからHTMLダッシュボードを生成する
mt-eval list models|prompts|datasets利用可能なリソースを一覧表示する
mt-eval export現在のセットアップをchampollionメソッドプラグインとしてパッケージ化する
mt-eval export-config解決済みのMethodConfig（全8つの正規フィールド）をJSONとしてエクスポートする

使用例​

# Run with defaults (gemini-pro alias → google/gemini-3.1-pro-preview, naive prompt)
mt-eval run --corpus data/edtekla-dev-v1.json

# Coached experiment with coaching file
mt-eval run \
  --corpus data/edtekla-dev-v1.json \
  --model google/gemini-3.1-pro \
  --coaching-file prompts/crk-coaching-v8.txt \
  --temperature 0.0

# Run a custom method plugin with FST retries
mt-eval run \
  --corpus data/edtekla-dev-v1.json \
  --method ./methods/fst-gated-pipeline \
  --fst-retries 3

ランカードスキーマ​

すべての実験はランカード（自己完結型のJSONドキュメント）を生成します。トップレベルの構造：

{
  "run_id": "uuid-v4",
  "harness_version": "2.0",
  "model_slug": "google/gemini-3.1-pro",
  "model_id": "gemini-3.1-pro-001",
  "condition": "baseline",
  "timestamp": "2026-06-01T03:22:41Z",
  "elapsed_seconds": 142.7,
  "dataset": { ... },
  "config": { ... },
  "method_card": { ... },
  "system_prompt_sha256": "abc123...",
  "system_prompt_used": "You are a translator...",
  "fingerprint": { ... },
  "scores": { ... },
  "totals": { ... },
  "environment": { ... },
  "results": [ ... ],
  "run_card_hash": "sha256-of-entire-card"
}

すべてのフィールドが文書化された完全なスキーマについては、ランカード仕様を参照してください。

:::info 正式なスキーマ ベンチマーク仕様はランカードスキーマの唯一の信頼できる情報源です。メトリクスの定義、コンポジットの重み、および品質ティアについては、スコアリング仕様を参照してください。このページではハーネスの使用方法を説明しており、出力の意味については仕様書で定義されています。 :::

主要ブロック​

dataset — 使用されたデータセットを識別します。コンテンツハッシュが含まれており、結果が特定のバージョンに紐付けられます：

// Example using master_corpus.json (62 gold + 342 textbook = 404)
{
  "id": "edtekla-dev-v1",
  "version": "1.0",
  "language_pair": "EN→CRK",
  "sha256": "...",
  "entry_count": 404
}

scores — ランの集計メトリクス：

// Counts reflect the dataset used (here: master_corpus.json, 404 entries)
{
  "total": 404,
  "exact_matches": 12,
  "exact_match_rate": 0.0968,
  "fst_accepted": 87,
  "fst_acceptance_rate": 0.7016,
  "chrf_plus_plus": 42.31,
  "errors": 0,
  "avg_latency_seconds": 1.15,
  "median_latency_seconds": 1.02,
  "p95_latency_seconds": 2.34,
  "by_difficulty": { ... },
  "by_provenance": { ... }
}

totals — トークン使用量とコストの追跡：

{
  "prompt_tokens": 48200,
  "completion_tokens": 3100,
  "reasoning_tokens": 0,
  "cached_tokens": 12000,
  "total_cost_usd": 0.42,
  "cost_per_entry_usd": 0.0034,
  "reasoning_ratio": 0.0
}

文章スタイルとレジスターメトリクス（情報提供のみ）​

ハーネスは、WritingStyleConsistencyメトリクスプラグイン（mt_eval_harness/plugins/writing_style.py）を通じて、翻訳がターゲットのレジスターおよび文章スタイルに一致しているかどうかを評価できます。翻訳は言語的に正確であっても、レジスターが誤っている場合があります。たとえば、法律文書でのくだけた表現や、マーケティングコピーでの堅苦しい定型文などです。文字列メトリクスではこれらを検出できませんが、これらのメトリクスは検出できます。

測定内容（エントリごと）：

メトリクススケール意味
style_register_matchboolean出力が期待されるレジスターと一致しているか？ターゲットはコーパスエントリのregisterフィールド（ベンチマーク仕様 §2.6を参照）またはスタイルプロファイルから取得されます
style_sentence_length_ratiofloat予測値と参照値の平均文長の比較（1.0 = 一致；乖離 = スタイルドリフト）
style_formality_score0.0–1.0フォーマル／インフォーマルマーカーの存在（T–V代名詞、短縮形など）。言語ごとのマーカーリソースを使用

集計： style_consistency_rate — レジスターの不一致が検出されなかったエントリの割合。

--style-profile path/to/profile.jsonでカスタムターゲットを有効にします（例：ブランドボイスプロファイル）。指定がない場合、プラグインは各コーパスエントリのregisterメタデータ（存在する場合）にフォールバックします。

:::caution 適用範囲について これらのメトリクスは情報提供のみです。コンポジットスコアには含まれず、フォーマリティ検出はマーカーベース（ヒューリスティック）であり、学習済みの判断ではありません。スタイル品質の判定としてではなく、レジスター遵守のドリフト検出器として扱ってください。 :::

フィンガープリントとランカードハッシュ​

ハーネスは2つの異なるハッシュを生成します。それぞれ異なる目的を持っています。

フィンガープリント​

フィンガープリントが答える問い：「このランは再現可能か？」

出力ではなく、実験設定を定義する入力の組み合わせをハッシュ化します：

  • データセットのSHA-256
  • モデルスラッグ
  • 条件ラベル
  • システムプロンプトのSHA-256
  • 温度
  • ハーネスバージョン

フィンガープリントが同一の2つのランは、同じセットアップを使用しています。それらの結果は比較可能です（APIの非決定性を除く）。

ランカードハッシュ​

ランカードハッシュが答える問い：「この特定の結果ファイルは改ざんされていないか？」

ランカードJSON全体のSHA-256です（run_card_hashフィールド自体は除く）。スコア、タイムスタンプ、単一の出力など、いずれかのフィールドが変更されるとハッシュが壊れます。

:::info どちらを使うべきか 比較可能なランをグループ化する場合（同じ実験、異なる実行）はフィンガープリントを使用してください。特定の結果ファイルの整合性を検証する場合はランカードハッシュを使用してください。 :::

リーダーボードへの公開​

ランが完了したら、mt-eval publishを使用してランカードを提出します：

mt-eval publish eval/logs/harness/your-run-card.json

ランの実行中に--method-cardが指定されていない場合、mt-eval publishはインタラクティブウィザード（method_card_wizard.py）を起動し、メソッドの説明（名前、クラス、使用ツールなど）を案内します。ウィザードの出力は提出前にランカードに埋め込まれます。

手動提出​

ランカードはJSONファイルとして出力ディレクトリに保存されます。/leaderboardのリーダーボードUIから任意のランカードファイルを提出することも、APIを通じて提出することもできます：

curl -X POST https://champollion.dev/api/leaderboard/submit \
  -H "Content-Type: application/json" \
  -d @eval/logs/harness/your-run-card.json

:::warning リーダーボードの検証 リーダーボードは提出されたランカードをデータセットレジストリに対して検証します。未知のデータセットを参照している提出や、run_card_hashが壊れている提出は拒否されます。 :::

:::danger 評価データでのトレーニング禁止 開発中に評価データセットを参照したことがある場合（トレーニングデータ、few-shotの例、辞書エントリ、またはプロンプトエンジニアリング素材として）、提出は失格となります。良いメソッドと悪いメソッドの基準については、MT Evaluationを参照してください。 :::

関連情報​