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 或自动化社区评测

如果用户想要在 Hugging Face Jobs 上远程运行相同的评测，请转交给 hugging-face-jobs 技能，并传入此技能中的一个本地脚本。

如果用户想要将结果发布到社区评测工作流，请在生成评测运行结果后停止，并将发布步骤转交给 ~/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

适用于任务适合用 lighteval 任务字符串表示的情况，尤其是 Open LLM Leaderboard 风格的基准测试。

本地 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。

后端选择

• 对于受支持的架构，优先使用 inspect_vllm_uv.py --backend vllm 进行快速 GPU 推理。
• 如果 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 显存溢出：
  • 调低 --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