huggingface-community-evals

概要

このスキルでは、ローカルのハードウェア上で Hugging Face Hub のモデルを評価します。

対象は次のとおりです。

• ローカル推論での inspect-ai
• ローカル推論での lighteval
• vllm、Hugging Face Transformers、accelerate の選択
• スモークテスト、タスクの選択、バックエンドのフォールバック戦略

次の内容は対象外です。

• Hugging Face Jobs のオーケストレーション
• モデルカードや model-index の編集
• README の表の抽出
• Artificial Analysis のインポート
• .eval_results の生成や公開
• PR の作成や community-evals の自動化

ユーザーが同じ評価を Hugging Face Jobs でリモート実行したい場合は、hugging-face-jobs スキルに引き継ぎ、このスキルのローカルスクリプトを渡してください。

ユーザーが結果を community evals のワークフローに公開したい場合は、評価の実行結果を生成した時点で作業を止め、その公開手順を ~/code/community-evals に引き継いでください。

以下のすべてのパスは、この SKILL.md を含むディレクトリからの相対パスです。

スクリプトの選び方

用途	スクリプト
推論プロバイダー経由で Hub モデルを使う、ローカルでの inspect-ai 評価	scripts/inspect_eval_uv.py
vllm または Transformers を使う、ローカル GPU での inspect-ai 評価	scripts/inspect_vllm_uv.py
vllm または accelerate を使う、ローカル GPU での lighteval 評価	scripts/lighteval_vllm_uv.py
その他のコマンドパターン	examples/USAGE_EXAMPLES.md

前提条件

• ローカル実行には uv run を優先して使用してください。
• 制限付きモデルやプライベートモデルには HF_TOKEN を設定してください。
• ローカル GPU で実行する場合は、開始前に GPU にアクセスできることを確認してください。

uv --version
printenv HF_TOKEN >/dev/null
nvidia-smi

nvidia-smi が利用できない場合は、次のいずれかを選択してください。

• 軽量なプロバイダーベースの評価には scripts/inspect_eval_uv.py を使用する
• ユーザーがリモートのコンピューティングリソースを希望する場合は、hugging-face-jobs スキルに引き継ぐ

基本的なワークフロー

1. 評価フレームワークを選択します。
   • タスクを明示的に制御し、inspect ネイティブのフローを利用したい場合は、inspect-ai を使用します。
   • ベンチマークを lighteval のタスク文字列で自然に表現できる場合、特にリーダーボード形式のタスクでは、lighteval を使用します。
2. 推論バックエンドを選択します。
   • 対応アーキテクチャでスループットを重視する場合は、vllm を優先してください。
   • 互換性のフォールバックとして、Hugging Face Transformers（--backend hf）または accelerate を使用してください。
3. まずスモークテストを実行します。
   • inspect-ai：--limit 10 などを追加します。
   • lighteval：--max-samples 10 を追加します。
4. スモークテストに合格してから、実行規模を拡大します。
5. ユーザーがリモート実行を希望する場合は、同じスクリプトと引数を添えて hugging-face-jobs に引き継ぎます。

クイックスタート

オプション A：ローカル推論プロバイダー経由の inspect-ai

モデルがすでに Hugging Face Inference Providers でサポートされており、ローカル環境のセットアップを最小限に抑えたい場合に最適です。

uv run scripts/inspect_eval_uv.py \
  --model meta-llama/Llama-3.2-1B \
  --task mmlu \
  --limit 20

次の場合にこの方法を使用してください。

• 手軽なローカルのスモークテストを実施したい
• GPU を直接制御する必要がない
• タスクがすでに inspect-evals に存在する

オプション B：ローカル GPU での inspect-ai

Hub のモデルを直接読み込む必要がある場合、vllm を使用する場合、または未対応のアーキテクチャに対して Transformers にフォールバックする場合に最適です。

ローカル GPU：

uv run scripts/inspect_vllm_uv.py \
  --model meta-llama/Llama-3.2-1B \
  --task gsm8k \
  --limit 20

Transformers へのフォールバック：

uv run scripts/inspect_vllm_uv.py \
  --model microsoft/phi-2 \
  --task mmlu \
  --backend hf \
  --trust-remote-code \
  --limit 20

オプション C：ローカル GPU での lighteval

特に Open LLM Leaderboard 形式のベンチマークなど、タスクを lighteval のタスク文字列で自然に表現できる場合に最適です。

ローカル GPU：

uv run scripts/lighteval_vllm_uv.py \
  --model meta-llama/Llama-3.2-3B-Instruct \
  --tasks "leaderboard|mmlu|5,leaderboard|gsm8k|5" \
  --max-samples 20 \
  --use-chat-template

accelerate へのフォールバック：

uv run scripts/lighteval_vllm_uv.py \
  --model microsoft/phi-2 \
  --tasks "leaderboard|mmlu|5" \
  --backend accelerate \
  --trust-remote-code \
  --max-samples 20

リモート実行との境界

このスキルの対象は、意図的にローカル実行とバックエンドの選択までに限定しています。

ユーザーが次の作業を希望する場合：

• これらのスクリプトを Hugging Face Jobs で実行する
• リモートのハードウェアを選択する
• リモートジョブにシークレットを渡す
• 定期実行をスケジュールする
• ジョブの確認、キャンセル、監視を行う

hugging-face-jobs スキルに切り替え、これらのスクリプトのいずれかと、選択した引数を渡してください。

タスクの選択

inspect-ai の例：

• mmlu
• gsm8k
• hellaswag
• arc_challenge
• truthfulqa
• winogrande
• humaneval

lighteval のタスク文字列は suite|task|num_fewshot の形式です：

• leaderboard|mmlu|5
• leaderboard|gsm8k|5
• leaderboard|arc_challenge|25
• lighteval|hellaswag|0

複数の lighteval タスクは、--tasks でカンマ区切りで指定できます。

バックエンドの選択

• 対応アーキテクチャで高速な GPU 推論を行う場合は、inspect_vllm_uv.py --backend vllm を優先してください。
• vllm がモデルに対応していない場合は、inspect_vllm_uv.py --backend hf を使用してください。
• 対応モデルでスループットを高める場合は、lighteval_vllm_uv.py --backend vllm を優先してください。
• 互換性のための代替手段として、lighteval_vllm_uv.py --backend accelerate を使用してください。
• Inference Providers がすでにモデルをカバーしており、GPU を直接制御する必要がない場合は、inspect_eval_uv.py を使用してください。

ハードウェアの指針

モデルサイズ	推奨するローカルハードウェア
< 3B	コンシューマー向け GPU ／ Apple Silicon ／小型の開発用 GPU
3B - 13B	より高性能なローカル GPU
13B+	大容量メモリのローカル GPU、または hugging-face-jobs に委任

スモークテストでは、低コストのローカル実行と --limit または --max-samples の使用を優先してください。

トラブルシューティング

• CUDA または vLLM の OOM：
  • --batch-size を小さくする
  • --gpu-memory-utilization を小さくする
  • スモークテストでは、より小さなモデルに切り替える
  • 必要に応じて、hugging-face-jobs に委任する
• vllm がモデルに対応していない：
  • inspect-ai では --backend hf に切り替える
  • lighteval では --backend accelerate に切り替える
• ゲート付き／プライベートリポジトリへのアクセスに失敗する：
  • HF_TOKEN を確認する
• カスタムモデルコードが必要：
  • --trust-remote-code を追加する

例

以下を参照してください：

• ローカルコマンドのパターンは examples/USAGE_EXAMPLES.md
• scripts/inspect_eval_uv.py
• scripts/inspect_vllm_uv.py
• scripts/lighteval_vllm_uv.py