hugging-face-community-evals

用途

本技能用于在本地硬件上对 Hugging Face Hub 上的模型运行评估。它聚焦于本地执行与后端选择，涵盖 inspect-ai 与 lighteval 两个评估框架的本地推理用法，以及 vLLM、Hugging Face Transformers、accelerate 三种推理后端之间的取舍。

主要能力

使用 inspect-ai 进行本地推理评估，支持通过 Hugging Face Inference Providers 或本地 GPU 运行。
使用 lighteval 进行本地推理评估，支持 vLLM 或 accelerate 后端。
在 vLLM、Hugging Face Transformers、accelerate 之间选择推理后端。
冒烟测试、任务选择与后端回退策略。

使用方式

前置条件：优先使用 uv run 进行本地执行；为受限或私有模型设置 HF_TOKEN；本地 GPU 运行前先验证 GPU 访问：

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

若 nvidia-smi 不可用，可使用 scripts/inspect_eval_uv.py 进行较轻量的 provider 支持评估，或转交 hugging-face-jobs 技能以使用远程算力。

核心工作流：

选择评估框架。需要显式任务控制与 inspect 原生流程时用 inspect-ai；基准天然以 lighteval 任务字符串表达（尤其是排行榜类任务）时用 lighteval。
选择推理后端。支持的架构上优先用 vLLM 提升吞吐；兼容性回退用 Hugging Face Transformers（--backend hf）或 accelerate。
先做冒烟测试。inspect-ai 加 --limit 10 或类似参数；lighteval 加 --max-samples 10。冒烟测试通过后再扩大规模。
若需远程执行，将同一脚本与参数转交 hugging-face-jobs。

快速开始：

选项 A：inspect-ai 配合本地推理 providers 路径（模型已被 Hugging Face Inference Providers 支持、希望本地配置开销最低时最佳）：

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

选项 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 \
  --trust-remote-code \
  --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 \
  --trust-remote-code \
  --max-samples 20

后端选择：支持的架构上优先 inspect_vllm_uv.py --backend vllm 以获得快速 GPU 推理；vLLM 不支持该模型时用 --backend hf。支持的模型上优先 lighteval_vllm_uv.py --backend vllm 提升吞吐；兼容性回退用 --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。

适用场景

需要在本地硬件上评估 Hugging Face Hub 模型。
需要在 vLLM、Transformers、accelerate 之间选择推理后端。
需要本地 GPU 评估。
需要以 inspect-ai 或 lighteval 任务字符串形式运行基准测试。

限制

本技能有意止步于本地执行与后端选择。不覆盖以下内容：Hugging Face Jobs 编排、模型卡或 model-index 编辑、README 表格提取、Artificial Analysis 导入、.eval_results 生成或发布、PR 创建或 community-evals 自动化。若用户希望在 Hugging Face Jobs 上远程运行同一评估，应转交 hugging-face-jobs 技能并传入本技能中的某个本地脚本；若用户希望将结果发布到 community evals 工作流，应在生成评估运行后停止，并将发布步骤转交 ~/code/community-evals。

故障排查：CUDA 或 vLLM 显存不足时，可减小 --batch-size、降低 --gpu-memory-utilization、为冒烟测试换用更小模型，必要时转交 hugging-face-jobs。vLLM 不支持该模型时，inspect-ai 切换到 --backend hf，lighteval 切换到 --backend accelerate。受限或私有仓库访问失败时，检查 HF_TOKEN。需要自定义模型代码时，添加 --trust-remote-code。

其他说明：仅在任务明确匹配其上游产品或 API 范围时使用本技能；在做出更改前，应依据当前官方文档核实命令、API 行为、定价、配额、凭据与部署影响；不要将生成的示例视为环境特定测试、安全审查或对破坏性/高成本操作的用户批准的替代。

技能介绍

用途

主要能力

使用方式

适用场景

限制