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 处理。

按用途选择脚本

• 通过推理提供方对 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. 如需远程执行，将同一脚本与参数转交 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：inspect-ai 本地 GPU

适合需要直接加载 Hub 模型、使用 vllm，或对不受支持架构回退到 Transformers 的场景。

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 \
  --limit 20

选项 C：lighteval 本地 GPU

适合任务可自然表达为 lighteval 任务字符串、尤其是 Open LLM Leaderboard 类基准的场景。

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 \
  --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，仅适用于标准模型架构。自定义代码工作流需另行走流程：固定不可变模型版本、检查每个代码文件、获得明确批准，并在文件系统/网络隔离中不带凭据运行。

限制

导入的上游技能；执行前需核实凭据、权限与安全边界。不替代针对具体环境的验证、测试或维护者审查。