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：HuggingFace 的评估库，支持 vLLM/accelerate 后端
• 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 时，vLLM 依赖项会通过 PEP 723 脚本头自动安装。

重要：使用此技能

⚠️ 关键：创建新 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（索引取自检查输出）。仅当列标题文本完全匹配时，才使用 --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 框架：HuggingFace 的评估库，包含 Open LLM Leaderboard 任务
• 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，列标题文本必须完全一致。
• 对于转置表格（模型为行），请确保只提取一行。

方法 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 模型。这些脚本与推理提供商脚本相互独立，会在任务的硬件上本地运行模型。

何时使用 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 - 零样本的 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，表示 5-shot）
• 文件中的值：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 是英国 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 - 大规模多任务语言理解
• gsm8k - 小学数学
• hellaswag - 常识推理
• arc_challenge - AI2 推理挑战
• truthfulqa - TruthfulQA 基准测试
• winogrande - Winograd Schema 挑战
• 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 格式

生成的 model-index 遵循以下结构：

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

警告：不要在模型名称中使用 Markdown 格式。请使用表格中的准确名称。仅在 source.url 字段中使用 URL。

错误处理

• 未找到表格：如果未检测到评估表格，脚本会报告
• 格式无效：针对格式错误的表格提供清晰的错误消息
• API 错误：针对 Artificial Analysis API 的暂时性故障进行重试
• 令牌问题：在尝试更新前进行验证
• 合并冲突：添加新条目时保留现有的 model-index 条目
• Space 创建：妥善处理命名冲突和硬件请求失败

最佳实践

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. 每个仓库仅添加一个模型：只将主模型的结果添加到 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 值匹配

问题：“使用硬件需要付费”

• 解决方案：向 Hugging Face 账户添加付款方式，以使用非 CPU 硬件

问题：“vLLM 内存不足”或 CUDA OOM

• 解决方案：使用更高配置的硬件、降低 --gpu-memory-utilization，或使用 --tensor-parallel-size 启用多 GPU

问题：“vLLM 不支持此模型架构”

• 解决方案：使用 --backend hf（inspect-ai）或 --backend accelerate（lighteval）以运行 HuggingFace Transformers

问题：“需要信任远程代码”

• 解决方案：对于包含自定义代码的模型（例如 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}")