hugging-face-evaluation

概要

このスキルは、Hugging Face のモデルカードに構造化された評価結果を追加するためのツールを提供します。評価データの追加方法として、次の複数の方法に対応しています。

• README の内容から既存の評価テーブルを抽出する
• Artificial Analysis からベンチマークスコアをインポートする
• vLLM または accelerate バックエンド（lighteval／inspect-ai）でカスタムモデル評価を実行する

HF エコシステムとの統合

• モデルカード：リーダーボードとの統合に向けて model-index メタデータを更新します
• Artificial Analysis：ベンチマークのインポートに直接 API 連携します
• Papers with Code：model-index 仕様との互換性があります
• Jobs：uv 連携により Hugging Face Jobs で評価を直接実行します
• vLLM：カスタムモデル評価のための効率的な GPU 推論
• lighteval：vLLM／accelerate バックエンドに対応した HuggingFace の評価ライブラリ
• inspect-ai：英国 AI 安全性研究所の評価フレームワーク

バージョン

1.3.0

依存関係

コア依存関係

• huggingface_hub>=0.26.0
• markdown-it-py>=3.0.0
• python-dotenv>=1.2.1
• pyyaml>=6.0.3
• requests>=2.32.5
• re（組み込み）

推論プロバイダーの評価

• inspect-ai>=0.3.0
• inspect-evals
• openai

vLLM カスタムモデル評価（GPU が必要）

• lighteval[accelerate,vllm]>=0.6.0
• vllm>=0.4.0
• torch>=2.0.0
• transformers>=4.40.0
• accelerate>=0.30.0

注：uv run の使用時、PEP 723 のスクリプトヘッダーにより vLLM の依存関係は自動的にインストールされます。

重要：このスキルの使用方法

⚠️ 重大：新しい PR を作成する前に既存の PR を確認してください

--create-pr を指定してプルリクエストを作成する前に、必ず既存のオープン PR を確認してください。

uv run scripts/evaluation_manager.py get-prs --repo-id "username/model-name"

オープン PR がある場合：

1. 新しい PR を作成しないでください。メンテナーに重複作業が発生します
2. オープン PR がすでにあることをユーザーに警告してください
3. 既存の PR の URL をユーザーに示し、確認できるようにしてください
4. ユーザーが別の PR の作成を明示的に確認した場合に限り、続行してください

これにより、重複した評価 PR でモデルリポジトリに迷惑をかけることを防げます。

---

すべてのパスは、この SKILL.md ファイルがあるディレクトリを基準とします。 スクリプトを実行する前に、まずそのディレクトリに cd するか、完全なパスを使用してください。

最新のワークフローの案内には --help を使用してください。 通常の Python または uv run で動作します。

uv run scripts/evaluation_manager.py --help
uv run scripts/evaluation_manager.py inspect-tables --help
uv run scripts/evaluation_manager.py extract-readme --help

主なワークフロー（CLI のヘルプと一致）：

1. get-prs → 最初に既存のオープン PR を確認する
2. inspect-tables → テーブル番号／列を確認する
3. extract-readme --table N → デフォルトで YAML を出力する
4. --apply（プッシュ）または --create-pr を追加して変更を書き込む

主な機能

1. README の評価テーブルを調査・抽出する

• テーブルの調査：inspect-tables を使用して、README 内のすべてのテーブルの構造、列、サンプル行を確認します
• Markdown テーブルの解析：markdown-it-py を使用して正確に解析します（コードブロックや例は無視されます）
• テーブルの選択：特定のテーブルから抽出するには --table N を使用します（複数のテーブルがある場合は必須です）
• 形式の検出：一般的な形式を認識します（行にベンチマークがある形式、列にベンチマークがある形式、複数モデルの比較テーブル）
• 列の照合：モデルの列／行を自動的に特定します。--model-column-index（inspect の出力にあるインデックス）を優先してください。--model-name-override は列ヘッダーのテキストと完全に一致する場合のみ使用してください。
• YAML の生成：選択したテーブルを model-index YAML 形式に変換します
• タスクの種別指定：--task-type は model-index 出力の task.type フィールドを設定します（例：text-generation、summarization）

2. Artificial Analysis からインポートする

• API 連携：Artificial Analysis からベンチマークスコアを直接取得します
• 自動フォーマット：API レスポンスを model-index 形式に変換します
• メタデータの保持：出典の帰属情報と URL を保持します
• PR の作成：評価の更新を含むプルリクエストを自動的に作成します

3. モデルインデックスの管理

• YAML の生成：適切な形式のモデルインデックスエントリーを作成します
• マージのサポート：既存のモデルカードを上書きせずに評価を追加します
• 検証：Papers with Code の仕様への準拠を確認します
• バッチ処理：複数のモデルを効率よく処理します

4. HF Jobs（Inference Providers）で評価を実行

• Inspect-AI との統合：inspect-ai ライブラリを使用して標準的な評価を実行します
• UV との統合：一時的な依存関係を使用して、HF インフラストラクチャ上で Python スクリプトをシームレスに実行します
• 設定不要：Dockerfile や Space の管理は不要です
• ハードウェアの選択：評価ジョブに CPU または GPU ハードウェアを設定します
• 安全な実行：CLI 経由で渡されるシークレットを使用して、API トークンを安全に処理します

5. vLLM でカスタムモデルの評価を実行（新機能）

⚠️ 重要： この方法は、uv がインストールされ、十分な GPU メモリがあるデバイスでのみ利用できます。 メリット： hf_jobs() MCP ツールを使う必要はなく、ターミナルからスクリプトを直接実行できます 使用する場面： GPU が利用可能で、ユーザーがローカルデバイス上で直接作業している場合

スクリプトを実行する前に

• スクリプトのパスを確認します
• uv がインストールされていることを確認します
• nvidia-smi で GPU が利用可能であることを確認します

スクリプトの実行

uv run scripts/train_sft_example.py

機能

• vLLM バックエンド：高性能な GPU 推論（標準的な HF の方法より 5～10 倍高速）
• lighteval フレームワーク：Open LLM Leaderboard タスクに対応する HuggingFace の評価ライブラリ
• inspect-ai フレームワーク：英国 AI 安全研究所の評価ライブラリ
• 単独実行またはジョブ：ローカルで実行するか、HF Jobs インフラストラクチャに送信します

使用方法

このスキルには、処理を実行するための Python スクリプトが scripts/ に含まれています。

前提条件

• 推奨：uv run を使用します（PEP 723 ヘッダーにより依存関係が自動インストールされます）
• 任意の手動での代替方法：uv pip install huggingface-hub markdown-it-py python-dotenv pyyaml requests
• 書き込み権限のあるトークンを設定した HF_TOKEN 環境変数を設定します
• Artificial Analysis を使用する場合：AA_API_KEY 環境変数を設定します
• python-dotenv がインストールされている場合、.env は自動的に読み込まれます

方法 1：README から抽出（CLI ワークフロー）

推奨手順（--help に準拠）：

# 1) Inspect tables to get table numbers and column hints
uv run scripts/evaluation_manager.py inspect-tables --repo-id "username/model"

# 2) Extract a specific table (prints YAML by default)
uv run scripts/evaluation_manager.py extract-readme \
  --repo-id "username/model" \
  --table 1 \
  [--model-column-index <column index shown by inspect-tables>] \
  [--model-name-override "<column header/model name>"]  # use exact header text if you can't use the index

# 3) Apply changes (push or PR)
uv run scripts/evaluation_manager.py extract-readme \
  --repo-id "username/model" \
  --table 1 \
  --apply       # push directly
# or
uv run scripts/evaluation_manager.py extract-readme \
  --repo-id "username/model" \
  --table 1 \
  --create-pr   # open a PR

検証チェックリスト：

• YAML はデフォルトで出力されます。適用する前に README の表と照合してください。
• --model-column-index を優先してください。--model-name-override を使用する場合は、列見出しのテキストを正確に指定してください。
• 転置された表（モデルが行に並ぶ表）では、抽出される行が 1 行だけであることを確認してください。

方法 2：Artificial Analysis からインポート

Artificial Analysis API からベンチマークスコアを取得し、モデルカードに追加します。

基本的な使用方法：

AA_API_KEY="your-api-key" uv run scripts/evaluation_manager.py import-aa \
  --creator-slug "anthropic" \
  --model-name "claude-sonnet-4" \
  --repo-id "username/model-name"

環境ファイルを使用する場合：

# Create .env file
echo "AA_API_KEY=your-api-key" >> .env
echo "HF_TOKEN=your-hf-token" >> .env

# Run import
uv run scripts/evaluation_manager.py import-aa \
  --creator-slug "anthropic" \
  --model-name "claude-sonnet-4" \
  --repo-id "username/model-name"

プルリクエストを作成する場合：

uv run scripts/evaluation_manager.py import-aa \
  --creator-slug "anthropic" \
  --model-name "claude-sonnet-4" \
  --repo-id "username/model-name" \
  --create-pr

方法 3：評価ジョブを実行

hf jobs uv run CLI を使用して、Hugging Face インフラストラクチャ上で評価ジョブを送信します。

CLI を直接使用する場合：

HF_TOKEN=$HF_TOKEN \
hf jobs uv run hf-evaluation/scripts/inspect_eval_uv.py \
  --flavor cpu-basic \
  --secret HF_TOKEN=$HF_TOKEN \
  -- --model "meta-llama/Llama-2-7b-hf" \
     --task "mmlu"

GPU の例（A10G）：

HF_TOKEN=$HF_TOKEN \
hf jobs uv run hf-evaluation/scripts/inspect_eval_uv.py \
  --flavor a10g-small \
  --secret HF_TOKEN=$HF_TOKEN \
  -- --model "meta-llama/Llama-2-7b-hf" \
     --task "gsm8k"

Python ヘルパー（任意）：

uv run scripts/run_eval_job.py \
  --model "meta-llama/Llama-2-7b-hf" \
  --task "mmlu" \
  --hardware "t4-small"

方法 4：vLLM でカスタムモデルの評価を実行

vLLM または accelerate バックエンドを使用して、GPU 上でカスタム HuggingFace モデルを直接評価します。これらのスクリプトはInference Provider スクリプトとは別のもので、ジョブのハードウェア上でモデルをローカルに実行します。

vLLM による評価を使用する場面（Inference Providers との比較）

機能	vLLM スクリプト	Inference Provider スクリプト
モデルへのアクセス	任意の HF モデル	API エンドポイントを持つモデル
ハードウェア	使用する GPU（または HF Jobs の GPU）	プロバイダーのインフラストラクチャ
コスト	HF Jobs のコンピューティングコスト	API 利用料金
速度	vLLM による最適化	プロバイダーによって異なります
オフライン	はい（ダウンロード後）	いいえ

オプション A: vLLM バックエンドでの lighteval

lighteval は HuggingFace の評価ライブラリで、Open LLM Leaderboard のタスクをサポートしています。

スタンドアロン (ローカル GPU):

# Run MMLU 5-shot with vLLM
uv run scripts/lighteval_vllm_uv.py \
  --model meta-llama/Llama-3.2-1B \
  --tasks "leaderboard|mmlu|5"

# Run multiple tasks
uv run scripts/lighteval_vllm_uv.py \
  --model meta-llama/Llama-3.2-1B \
  --tasks "leaderboard|mmlu|5,leaderboard|gsm8k|5"

# Use accelerate backend instead of vLLM
uv run scripts/lighteval_vllm_uv.py \
  --model meta-llama/Llama-3.2-1B \
  --tasks "leaderboard|mmlu|5" \
  --backend accelerate

# Chat/instruction-tuned models
uv run scripts/lighteval_vllm_uv.py \
  --model meta-llama/Llama-3.2-1B-Instruct \
  --tasks "leaderboard|mmlu|5" \
  --use-chat-template

HF Jobs 経由:

hf jobs uv run scripts/lighteval_vllm_uv.py \
  --flavor a10g-small \
  --secrets HF_TOKEN=$HF_TOKEN \
  -- --model meta-llama/Llama-3.2-1B \
     --tasks "leaderboard|mmlu|5"

lighteval タスク形式: タスクは suite|task|num_fewshot の形式を使用します:

• leaderboard|mmlu|5 - 5-shot の MMLU
• leaderboard|gsm8k|5 - 5-shot の GSM8K
• lighteval|hellaswag|0 - zero-shot の HellaSwag
• leaderboard|arc_challenge|25 - 25-shot の ARC-Challenge

利用可能なタスクの検索: 利用可能な lighteval タスクの完全なリストは以下で確認できます: https://github.com/huggingface/lighteval/blob/main/examples/tasks/all_tasks.txt

このファイルには、suite|task|num_fewshot|0 の形式でサポートされているすべてのタスクが含まれています (末尾の 0 はバージョンフラグであり、無視できます)。一般的なスイートには以下が含まれます:

• leaderboard - Open LLM Leaderboard のタスク (MMLU、GSM8K、ARC、HellaSwag など)
• lighteval - 追加の lighteval タスク
• bigbench - BigBench タスク
• original - 元のベンチマークタスク

リストからタスクを使用するには、suite|task|num_fewshot の部分 (末尾の 0 を除く) を抽出し、--tasks パラメータに渡します。例えば:

• ファイルから: leaderboard|mmlu|0 → 使用: leaderboard|mmlu|0 (または 5-shot にするには 5 に変更)
• ファイルから: bigbench|abstract_narrative_understanding|0 → 使用: bigbench|abstract_narrative_understanding|0
• ファイルから: lighteval|wmt14:hi-en|0 → 使用: lighteval|wmt14:hi-en|0

複数のタスクはカンマ区切りの値として指定できます: --tasks "leaderboard|mmlu|5,leaderboard|gsm8k|5"

オプション B: vLLM バックエンドでの inspect-ai

inspect-ai は UK AI Safety Institute の評価フレームワークです。

スタンドアロン (ローカル GPU):

# Run MMLU with vLLM
uv run scripts/inspect_vllm_uv.py \
  --model meta-llama/Llama-3.2-1B \
  --task mmlu

# Use HuggingFace Transformers backend
uv run scripts/inspect_vllm_uv.py \
  --model meta-llama/Llama-3.2-1B \
  --task mmlu \
  --backend hf

# Multi-GPU with tensor parallelism
uv run scripts/inspect_vllm_uv.py \
  --model meta-llama/Llama-3.2-70B \
  --task mmlu \
  --tensor-parallel-size 4

HF Jobs 経由:

hf jobs uv run scripts/inspect_vllm_uv.py \
  --flavor a10g-small \
  --secrets HF_TOKEN=$HF_TOKEN \
  -- --model meta-llama/Llama-3.2-1B \
     --task mmlu

利用可能な inspect-ai タスク:

• mmlu - Massive Multitask Language Understanding
• gsm8k - Grade School Math
• hellaswag - 常識推論
• arc_challenge - AI2 Reasoning Challenge
• truthfulqa - TruthfulQA ベンチマーク
• winogrande - Winograd Schema Challenge
• humaneval - コード生成

オプション C: Python ヘルパースクリプト

ヘルパースクリプトはハードウェアを自動選択し、ジョブの送信を簡素化します:

# Auto-detect hardware based on model size
uv run scripts/run_vllm_eval_job.py \
  --model meta-llama/Llama-3.2-1B \
  --task "leaderboard|mmlu|5" \
  --framework lighteval

# Explicit hardware selection
uv run scripts/run_vllm_eval_job.py \
  --model meta-llama/Llama-3.2-70B \
  --task mmlu \
  --framework inspect \
  --hardware a100-large \
  --tensor-parallel-size 4

# Use HF Transformers backend
uv run scripts/run_vllm_eval_job.py \
  --model microsoft/phi-2 \
  --task mmlu \
  --framework inspect \
  --backend hf

ハードウェアの推奨事項:

モデルサイズ	推奨ハードウェア
< 3B パラメータ	t4-small
3B - 13B	a10g-small
13B - 34B	a10g-large
34B+	a100-large

コマンドリファレンス

トップレベルのヘルプとバージョン:

uv run scripts/evaluation_manager.py --help
uv run scripts/evaluation_manager.py --version

テーブルの検査 (ここから開始):

uv run scripts/evaluation_manager.py inspect-tables --repo-id "username/model-name"

README からの抽出:

uv run scripts/evaluation_manager.py extract-readme \
  --repo-id "username/model-name" \
  --table N \
  [--model-column-index N] \
  [--model-name-override "Exact Column Header or Model Name"] \
  [--task-type "text-generation"] \
  [--dataset-name "Custom Benchmarks"] \
  [--apply | --create-pr]

Artificial Analysis からのインポート:

AA_API_KEY=... uv run scripts/evaluation_manager.py import-aa \
  --creator-slug "creator-name" \
  --model-name "model-slug" \
  --repo-id "username/model-name" \
  [--create-pr]

表示 / 検証:

uv run scripts/evaluation_manager.py show --repo-id "username/model-name"
uv run scripts/evaluation_manager.py validate --repo-id "username/model-name"

オープン PR の確認 (--create-pr の前に必ず実行):

uv run scripts/evaluation_manager.py get-prs --repo-id "username/model-name"

モデルリポジトリのすべてのオープンプルリクエストを一覧表示します。PR 番号、タイトル、作成者、日付、URL を表示します。

評価ジョブの実行 (Inference Providers):

hf jobs uv run scripts/inspect_eval_uv.py \
  --flavor "cpu-basic|t4-small|..." \
  --secret HF_TOKEN=$HF_TOKEN \
  -- --model "model-id" \
     --task "task-name"

または Python ヘルパーを使用します:

uv run scripts/run_eval_job.py \
  --model "model-id" \
  --task "task-name" \
  --hardware "cpu-basic|t4-small|..."

vLLM 評価の実行 (カスタムモデル):

# lighteval with vLLM
hf jobs uv run scripts/lighteval_vllm_uv.py \
  --flavor "a10g-small" \
  --secrets HF_TOKEN=$HF_TOKEN \
  -- --model "model-id" \
     --tasks "leaderboard|mmlu|5"

# inspect-ai with vLLM
hf jobs uv run scripts/inspect_vllm_uv.py \
  --flavor "a10g-small" \
  --secrets HF_TOKEN=$HF_TOKEN \
  -- --model "model-id" \
     --task "mmlu"

# Helper script (auto hardware selection)
uv run scripts/run_vllm_eval_job.py \
  --model "model-id" \
  --task "leaderboard|mmlu|5" \
  --framework lighteval

モデルインデックス形式

生成されるモデルインデックスは次の構造に従います:

model-index:
  - name: Model Name
    results:
      - task:
          type: text-generation
        dataset:
          name: Benchmark Dataset
          type: benchmark_type
        metrics:
          - name: MMLU
            type: mmlu
            value: 85.2
          - name: HumanEval
            type: humaneval
            value: 72.5
        source:
          name: Source Name
          url: https://source-url.com

WARNING: モデル名には markdown フォーマットを使用しないでください。テーブルから正確な名前を使用してください。URL は source.url フィールドでのみ使用してください。

エラー処理

• テーブルが見つからない: 評価テーブルが検出されない場合、スクリプトが報告します
• 無効な形式: 不正な形式のテーブルに対する明確なエラーメッセージ
• API エラー: 一時的な Artificial Analysis API 障害に対する再試行ロジック
• トークンの問題: 更新を試みる前の検証
• マージ競合: 新しいエントリを追加する際に既存のモデルインデックスエントリを保持します
• スペースの作成: 命名の競合とハードウェアリクエストの失敗を適切に処理します

ベストプラクティス

1. まず既存の PR を確認する：重複を避けるため、新しい PR を作成する前に get-prs を実行します
2. 必ず inspect-tables から始める：テーブル構造を確認し、正しい抽出コマンドを取得します
3. ガイダンスには --help を使う：inspect-tables --help を実行して、ワークフロー全体を確認します
4. まずプレビューする：デフォルトでは YAML が出力されます。--apply または --create-pr を使う前に内容を確認します
5. 抽出した値を検証する：YAML の出力を README のテーブルと手動で比較します
6. 複数のテーブルがある README では --table N を使う：評価テーブルが複数ある場合に必要です
7. 比較テーブルでは --model-name-override を使う：inspect-tables の出力にある列見出しをそのままコピーします
8. 他の人のモデルでは PR を作成する：自分が所有していないモデルを更新する場合は --create-pr を使います
9. リポジトリごとにモデルは 1 つ：model-index にはメインモデルの結果だけを追加します
10. YAML の名前に Markdown を使わない：YAML のモデル名フィールドにはプレーンテキストを指定します

モデル名の照合

複数のモデルが列または行として含まれる評価テーブルを抽出する場合、スクリプトは正規化後のトークンの完全一致を使用します。

• Markdown の書式（太字 **、リンク []() ）を削除します
• 名前を正規化します（小文字に変換し、- と _ をスペースに置き換えます）
• トークンの集合を比較します："OLMo-3-32B" → {"olmo", "3", "32b"} は "**Olmo 3 32B**" または "[Olmo-3-32B](...)" と一致します
• トークンが完全一致した場合のみ抽出します（単語の順序や区切り文字の違いに対応します）
• 完全一致が見つからない場合は失敗します（類似した名前から推測することはありません）

列ベースのテーブル（ベンチマークが行、モデルが列の場合）：

• モデル名に一致する列見出しを見つけます
• その列からのみスコアを抽出します

転置されたテーブル（モデルが行、ベンチマークが列の場合）：

• 最初の列でモデル名に一致する行を見つけます
• その行からのみすべてのベンチマークスコアを抽出します

これにより、関係のないモデルやトレーニングチェックポイントではなく、正しいモデルのスコアだけが抽出されます。

よくあるパターン

自分のモデルを更新する：

# Extract from README and push directly
uv run scripts/evaluation_manager.py extract-readme \
  --repo-id "your-username/your-model" \
  --task-type "text-generation"

他の人のモデルを更新する（ワークフロー全体）：

# Step 1: ALWAYS check for existing PRs first
uv run scripts/evaluation_manager.py get-prs \
  --repo-id "other-username/their-model"

# Step 2: If NO open PRs exist, proceed with creating one
uv run scripts/evaluation_manager.py extract-readme \
  --repo-id "other-username/their-model" \
  --create-pr

# If open PRs DO exist:
# - Warn the user about existing PRs
# - Show them the PR URLs
# - Do NOT create a new PR unless user explicitly confirms

新しいベンチマークをインポートする：

# Step 1: Check for existing PRs
uv run scripts/evaluation_manager.py get-prs \
  --repo-id "anthropic/claude-sonnet-4"

# Step 2: If no PRs, import from Artificial Analysis
AA_API_KEY=... uv run scripts/evaluation_manager.py import-aa \
  --creator-slug "anthropic" \
  --model-name "claude-sonnet-4" \
  --repo-id "anthropic/claude-sonnet-4" \
  --create-pr

トラブルシューティング

問題：「README に評価テーブルが見つかりません」

• 解決策：README に数値スコアを含む Markdown テーブルがあるか確認します

問題：「転置されたテーブルにモデル 'X' が見つかりませんでした」

• 解決策：スクリプトに利用可能なモデルが表示されます。一覧にある名前を正確に指定して --model-name-override を使います
• 例：--model-name-override "**Olmo 3-32B**"

問題：「AA_API_KEY が設定されていません」

• 解決策：環境変数を設定するか、.env ファイルに追加します

問題：「トークンに書き込みアクセス権がありません」

• 解決策：HF_TOKEN にリポジトリへの書き込み権限があることを確認します

問題：「Artificial Analysis にモデルが見つかりません」

• 解決策：creator-slug と model-name が API の値と一致していることを確認します

問題：「ハードウェアの利用には支払いが必要です」

• 解決策：CPU 以外のハードウェアを使用するには、Hugging Face アカウントに支払い方法を追加します

問題：「vLLM のメモリが不足しています」または CUDA OOM

• 解決策：より大きなハードウェア構成を使用するか、--gpu-memory-utilization の値を下げるか、マルチ GPU 用に --tensor-parallel-size を使用します

問題：「vLLM がモデルアーキテクチャをサポートしていません」

• 解決策：HuggingFace Transformers には --backend hf（inspect-ai）または --backend accelerate（lighteval）を使用します

問題：「リモートコードへの信頼が必要です」

• 解決策：カスタムコードを含むモデル（例：Phi-2、Qwen）には --trust-remote-code フラグを追加します

問題：「チャットテンプレートが見つかりません」

• 解決策：チャットテンプレートを含む指示チューニング済みモデルにのみ --use-chat-template を使用します

統合例

Python スクリプトとの統合：

import subprocess
import os

def update_model_evaluations(repo_id, readme_content):
    """Update model card with evaluations from README."""
    result = subprocess.run([
        "python", "scripts/evaluation_manager.py",
        "extract-readme",
        "--repo-id", repo_id,
        "--create-pr"
    ], capture_output=True, text=True)

    if result.returncode == 0:
        print(f"Successfully updated {repo_id}")
    else:
        print(f"Error: {result.stderr}")