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

ランカード仕様

概要。 ランカードはベンチマークの最小単位であり、1回の評価実行の完全な設定・エントリーごとの結果・集計スコアを記録したJSONドキュメントです。このページではスキーマ、フィールド、フィンガープリントの仕組み、およびスコア構造について説明します。正規の定義についてはベンチマーク仕様を参照してください。

ランカードは1回の評価実行の完全な記録です。実験を理解・再現・検証するために必要なすべての情報（設定、スコア、個別結果、トークン使用量、環境メタデータ）が含まれています。

スキーマバージョン: 2.0

:::info 権威あるスキーマ ベンチマーク仕様がランカードスキーマの唯一の情報源です。メトリクスの定義、複合ウェイト、品質ティアについてはスコアリング仕様を参照してください。このページは現在の実装について説明しています。 :::

トップレベルフィールド​

フィールド型説明
run_idstring実行開始時に生成されるUUID v4
harness_versionstringこのカードを生成したハーネスのセマンティックバージョン（例：2.0）
model_slugstring実行に使用したモデルスラッグ（例：google/gemini-3.1-pro）
model_idstringAPIが返す解決済みモデル識別子（例：gemini-3.1-pro-001）
conditionstring実験ラベル（例：baseline、coached-v3、few-shot）
timestampstring実行開始時のISO 8601 UTCタイムスタンプ
elapsed_secondsnumber実行全体の実経過時間
{
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "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​

評価データセットを識別し、SHA-256によって特定のコンテンツバージョンに固定します。

フィールド型説明
idstringデータセット識別子（例：edtekla-dev-v1）
versionstringデータセットのバージョン文字列
language_pairstring表示ラベル（例：EN→CRK）
sha256stringデータセットファイルの内容のSHA-256ハッシュ。使用した正確なデータを保証します
entry_countnumberデータセット内のエントリー数
// Example using master_corpus.json (62 gold + 342 textbook = 404)
{
  "dataset": {
    "id": "edtekla-dev-v1",
    "version": "1.0",
    "language_pair": "EN→CRK",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "entry_count": 404
  }
}

config​

この実行に使用したAPIおよびバッチ処理の設定です。

フィールド型説明
api_providerstringAPIプロバイダー名（例：openrouter）
temperaturenumberサンプリング温度
max_tokensnumber補完ごとの最大トークン数
batch_sizenumber同時バッチあたりのエントリー数
concurrencynumber最大並列APIリクエスト数
coaching_filestringコーチングプロンプトファイルへのパス（使用する場合）
method_pathstringメソッドプラグインディレクトリへのパス（使用する場合）
fst_retriesnumberFSTリトライ試行回数
{
  "config": {
    "api_provider": "openrouter",
    "temperature": 0.0,
    "max_tokens": 32768,
    "batch_size": 25,
    "concurrency": 8
  }
}

:::info 公開ランカードにはmethod_configが含まれます mt-eval publishでランカードが公開される際、publish.pyは正規の8フィールドMethodConfigを含むmethod_configブロックを挿入します。これにより、リーダーボードへのインストールが摩擦なく行えます。公開カードから直接メソッドを再現することが可能です。

{
  "method_config": {
    "model": "gemini-pro",
    "temperature": 0.0,
    "batchSize": 25,
    "register": "Formal Plains Cree. Use SRO orthography.",
    "coachingFile": "prompts/crk-coaching-v8.txt",
    "coachingPrompt": null,
    "promptContext": "champollion",
    "qualityTier": "verified"
  }
}

すべてのフィールドはcamelCaseを使用し、正規のMethodConfigスキーマに従います（メソッドの構築を参照）。 :::

system_prompt_sha256 / system_prompt_used​

フィールド型説明
system_prompt_sha256stringシステムプロンプトのSHA-256ハッシュ。フィンガープリントに含まれます
system_prompt_usedstringモデルに送信したシステムプロンプトの全文

プロンプトハッシュはフィンガープリントの一部です。他のすべての設定が同じであっても、プロンプトが異なる2つの実行は異なるフィンガープリントを持ちます。

fingerprint​

再現性の識別子です。フィンガープリントが同一の2つの実行は、同じ実験設定を使用しています。

フィールド型説明
hashstringソートされたコンポーネントのSHA-256ハッシュ
componentsobjectハッシュ化された入力値

フィンガープリントのコンポーネント​

コンポーネント説明
dataset_sha256データセットファイルのハッシュ
model_slug使用したモデル
condition実験条件ラベル
system_prompt_sha256システムプロンプトのハッシュ
temperatureサンプリング温度
harness_versionハーネスバージョン
{
  "fingerprint": {
    "hash": "7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069",
    "components": {
      "dataset_sha256": "e3b0c44298fc1c14...",
      "model_slug": "google/gemini-3.1-pro",
      "condition": "baseline",
      "system_prompt_sha256": "abc123...",
      "temperature": 0.0,
      "harness_version": "2.0"
    }
  }
}

:::info フィンガープリント ≠ ランカードハッシュ フィンガープリントは実験設定を識別します。run_card_hashは結果ファイルの整合性を検証します。詳細はフィンガープリントとランカードハッシュの違いを参照してください。 :::

scores​

実行全体の集計メトリクスです。

トップレベルスコア​

フィールド型説明
totalnumber評価したエントリーの総数
exact_matchesnumber出力がゴールドスタンダードと完全一致したエントリー数
exact_match_ratenumberexact_matches / total（0.0〜1.0）
fst_acceptednumberFSTアナライザーが出力を受理したエントリー数
fst_acceptance_ratenumberfst_accepted / total（0.0〜1.0）。FSTアナライザーが使用されていない場合はnull
chrf_plus_plusnumberコーパスレベルのchrF++スコア（0〜100）
errorsnumber失敗したエントリー数（APIエラー、タイムアウトなど）
avg_latency_secondsnumber全エントリーの平均応答時間
median_latency_secondsnumber応答時間の中央値
p95_latency_secondsnumber応答時間の第95パーセンタイル

by_difficulty​

難易度ティア別のスコアです。各キー（整数1〜5）はトップレベルスコアと同じメトリクスフィールドを含みます。

{
  "by_difficulty": {
    "1": {
      "total": 20,
      "exact_matches": 8,
      "exact_match_rate": 0.40,
      "chrf_plus_plus": 68.2,
      "fst_accepted": 18,
      "fst_acceptance_rate": 0.90
    },
    "2": { ... },
    "3": { ... },
    "4": { ... },
    "5": { ... }
  }
}

by_provenance​

エントリーの出典別のスコアです。各キー（例：gold_standard、textbook）は同じメトリクスフィールドを含みます。

{
  "by_provenance": {
    "gold_standard": {
      "total": 80,
      "exact_matches": 10,
      "exact_match_rate": 0.125,
      "chrf_plus_plus": 44.8
    },
    "textbook": { ... }
  }
}

totals​

実行全体のトークン使用量とコストの追跡情報です。

フィールド型説明
prompt_tokensnumber全APIコールの入力トークン合計
completion_tokensnumber出力トークンの合計
reasoning_tokensnumber思考連鎖推論に使用したトークン数（モデル依存、ほとんどのモデルでは0）
cached_tokensnumberプロバイダーのプロンプトキャッシュから提供されたトークン数
total_cost_usdnumber総コスト（USD、APIが報告する値）
cost_per_entry_usdnumbertotal_cost_usd / entry_count
reasoning_rationumberreasoning_tokens / completion_tokens（0.0〜1.0）
{
  "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
  }
}

environment​

再現性のためのランタイム環境メタデータです。

フィールド型説明
harness_versionstringハーネスバージョン（トップレベルのharness_versionと同じ値）
harness_git_commitstring実行時のハーネスのGitコミットSHA
python_versionstringPythonインタープリターのバージョン
sacrebleu_versionstringsacrebleuライブラリのバージョン（chrF++スコアリングに使用）
osstringオペレーティングシステムの識別子
{
  "environment": {
    "harness_version": "2.0",
    "harness_git_commit": "a1b2c3d",
    "python_version": "3.11.9",
    "sacrebleu_version": "2.4.0",
    "os": "macOS-14.5-arm64"
  }
}

results[]​

エントリーごとの結果配列です。データセットのエントリーごとに1つのオブジェクトがインデックス順に格納されます。

フィールド型説明
entry_idintegerコーパス内のこのエントリーのID（entries[].idと一致）
sourcestring翻訳されたソーステキスト
referencestringコーパスのゴールドスタンダード参照訳
predictedstringメソッドの実際の出力
exact_matchboolean正規化後にpredictedがreferenceと完全一致するかどうか
entry_chrfnumberこのエントリーの文レベルchrF++スコア（0〜100）
fst_acceptedboolean | nullFSTアナライザーが出力を受理したかどうか。アナライザーが設定されていない場合はnull
fst_analysisstring[]出力のFST解析文字列（未解析または拒否された場合は空配列）
difficultyintegerコーパスの難易度ティア（1〜5）
provenancestringコーパスの出典タグ
latency_secondsnumberこのエントリーの応答時間
usageobjectエントリーごとのトークン使用量：{ prompt_tokens, completion_tokens, reasoning_tokens }
errorstring | nullこのエントリーが失敗した場合のエラーメッセージ。成功時はnull
{
  "results": [
    {
      "entry_id": 1,
      "source": "Hello",
      "reference": "tânisi",
      "predicted": "tânisi",
      "exact_match": true,
      "entry_chrf": 100.0,
      "fst_accepted": true,
      "fst_analysis": ["tânisi+V+AI+Ind+2Sg"],
      "difficulty": 1,
      "provenance": "gold_standard",
      "latency_seconds": 0.82,
      "usage": {
        "prompt_tokens": 385,
        "completion_tokens": 12,
        "reasoning_tokens": 0
      },
      "error": null
    }
  ]
}

run_card_hash​

フィールド型説明
run_card_hashstringランカードJSON全体のSHA-256ハッシュ。ハッシュ計算中はrun_card_hashフィールド自体を""に設定します

これは改ざん検知のシールです。リーダーボードは提出時にこのハッシュを再計算し、一致しないカードは拒否します。

ハッシュの計算方法：

  1. run_card_hashを""に設定した状態でランカードをJSONにシリアライズする
  2. シリアライズされた文字列のSHA-256を計算する
  3. run_card_hashに得られた16進ダイジェストを設定する
import hashlib, json

card["run_card_hash"] = ""
card_json = json.dumps(card, sort_keys=True, ensure_ascii=False)
card["run_card_hash"] = hashlib.sha256(card_json.encode()).hexdigest()

:::info エントリーごとのドリルダウン 公開ランカードはrun_card_entries Supabaseテーブルにも格納されます。このテーブルにはエントリーごとの結果が保存され、リーダーボード上でのドリルダウン分析が可能です。このテーブルはmt-eval publishの実行中に自動的に入力されます。 :::

関連情報​