Name: HuggingFace模型评估管理Skill
Rating: 5 (4 reviews)
Author: huggingface

名称: hugging-face-evaluation 描述: 在 Hugging Face 模型卡中添加和管理评估结果。支持从 README 内容提取评估表格，从 Artificial Analysis API 导入分数，以及使用 vLLM/lighteval 运行自定义模型评估。与 model-index 元数据格式兼容。

概述

这个技能提供工具，用于向 Hugging Face 模型卡添加结构化评估结果。它支持多种添加评估数据的方法：

从 README 内容提取现有评估表格
从 Artificial Analysis 导入基准分数
使用 vLLM 或加速后端（lighteval/inspect-ai）运行自定义模型评估

与 HF 生态系统的集成

模型卡: 更新 model-index 元数据以集成排行榜
Artificial Analysis: 直接 API 集成用于基准导入
Papers with Code: 与其 model-index 规范兼容
Jobs: 使用 uv 集成直接在 Hugging Face Jobs 上运行评估
vLLM: 高效 GPU 推理用于自定义模型评估
lighteval: HuggingFace 的评估库，支持 vLLM/加速后端
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 "用户名/模型名称"

如果存在开放 PR：

不要创建新 PR - 这会为维护者创建重复工作
警告用户 已经存在开放 PR
向用户展示 现有 PR 的 URL，以便他们查看
仅当用户明确确认他们想创建另一个 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 帮助）：

get-prs → 首先检查现有开放 PR
inspect-tables → 查找表格编号/列
extract-readme --table N → 默认打印 YAML
添加 --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. Model-Index 管理

YAML 生成: 创建正确格式化的 model-index 条目
合并支持: 向现有模型卡添加评估而不覆盖
验证: 确保符合 Papers with Code 规范
批量操作: 高效处理多个模型

4. 在 HF Jobs 上运行评估（推理提供者）

Inspect-AI 集成: 使用 inspect-ai 库运行标准评估
UV 集成: 在 HF 基础设施上无缝运行具有临时依赖项的 Python 脚本
零配置: 无需 Dockerfiles 或空间管理
硬件选择: 为评估作业配置 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 排行榜任务
inspect-ai 框架: 英国 AI 安全研究所的评估库
独立或作业: 本地运行或提交到 HF Jobs 基础设施

使用说明

该技能包含 scripts/ 中的 Python 脚本来执行操作。

前提条件

首选：使用 uv run（PEP 723 头自动安装依赖项）
或手动安装：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) 检查表格以获取表格编号和列提示
uv run scripts/evaluation_manager.py inspect-tables --repo-id "用户名/模型"

# 2) 提取特定表格（默认打印 YAML）
uv run scripts/evaluation_manager.py extract-readme \
  --repo-id "用户名/模型" \
  --table 1 \
  [--model-column-index <检查表格显示的列索引>] \
  [--model-name-override "<列标题/模型名称>"]  # 如果无法使用索引，则使用精确的标题文本

# 3) 应用更改（推送或 PR）
uv run scripts/evaluation_manager.py extract-readme \
  --repo-id "用户名/模型" \
  --table 1 \
  --apply       # 直接推送
# 或
uv run scripts/evaluation_manager.py extract-readme \
  --repo-id "用户名/模型" \
  --table 1 \
  --create-pr   # 打开一个 PR

验证清单：

默认打印 YAML；在应用前与 README 表格比较。
优先使用 --model-column-index；如果使用 --model-name-override，列标题文本必须精确。
对于转置表格（模型作为行），确保仅提取一行。

方法 2：从 Artificial Analysis 导入

从 Artificial Analysis API 获取基准分数并将其添加到模型卡。

基本用法：

AA_API_KEY="您的 API 密钥" uv run scripts/evaluation_manager.py import-aa \
  --creator-slug "anthropic" \
  --model-name "claude-sonnet-4" \
  --repo-id "用户名/模型名称"

使用环境文件：

# 创建 .env 文件
echo "AA_API_KEY=您的 API 密钥" >> .env
echo "HF_TOKEN=您的 HF 令牌" >> .env

# 运行导入
uv run scripts/evaluation_manager.py import-aa \
  --creator-slug "anthropic" \
  --model-name "claude-sonnet-4" \
  --repo-id "用户名/模型名称"

创建拉取请求：

uv run scripts/evaluation_manager.py import-aa \
  --creator-slug "anthropic" \
  --model-name "claude-sonnet-4" \
  --repo-id "用户名/模型名称" \
  --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 或加速后端直接在 GPU 上评估自定义 HuggingFace 模型。这些脚本 与推理提供者脚本分开，并在作业的硬件上本地运行模型。

何时使用 vLLM 评估（vs 推理提供者）

特性	vLLM 脚本	推理提供者脚本
模型访问	任何 HF 模型	具有 API 端点的模型
硬件	您的 GPU（或 HF Jobs GPU）	提供者的基础设施
成本	HF Jobs 计算成本	API 使用费
速度	vLLM 优化	取决于提供者
离线	是（下载后）	否

选项 A：使用 vLLM 后端的 lighteval

lighteval 是 HuggingFace 的评估库，支持 Open LLM 排行榜任务。

独立（本地 GPU）：

# 使用 vLLM 运行 MMLU 5-shot
uv run scripts/lighteval_vllm_uv.py \
  --model meta-llama/Llama-3.2-1B \
  --tasks "leaderboard|mmlu|5"

# 运行多个任务
uv run scripts/lighteval_vllm_uv.py \
  --model meta-llama/Llama-3.2-1B \
  --tasks "leaderboard|mmlu|5,leaderboard|gsm8k|5"

# 使用加速后端代替 vLLM
uv run scripts/lighteval_vllm_uv.py \
  --model meta-llama/Llama-3.2-1B \
  --tasks "leaderboard|mmlu|5" \
  --backend accelerate

# 聊天/指令调整模型
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 - 零-shot 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 排行榜任务（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 安全研究所的评估框架。

独立（本地 GPU）：

# 使用 vLLM 运行 MMLU
uv run scripts/inspect_vllm_uv.py \
  --model meta-llama/Llama-3.2-1B \
  --task mmlu

# 使用 HuggingFace Transformers 后端
uv run scripts/inspect_vllm_uv.py \
  --model meta-llama/Llama-3.2-1B \
  --task mmlu \
  --backend hf

# 多 GPU 张量并行
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 模式挑战
humaneval - 代码生成

选项 C：Python 助手脚本

助手脚本自动选择硬件并简化作业提交：

# 基于模型大小自动检测硬件
uv run scripts/run_vllm_eval_job.py \
  --model meta-llama/Llama-3.2-1B \
  --task "leaderboard|mmlu|5" \
  --framework lighteval

# 显式硬件选择
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

# 使用 HF Transformers 后端
uv run scripts/run_vllm_eval_job.py \
  --model microsoft/phi-2 \
  --task mmlu \
  --framework inspect \
  --backend hf

硬件推荐：

模型大小	推荐硬件
< 30 亿参数	`t4-small`
30 亿 - 130 亿	`a10g-small`
130 亿 - 340 亿	`a10g-large`
340 亿+	`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 "用户名/模型名称"

从 README 提取：

uv run scripts/evaluation_manager.py extract-readme \
  --repo-id "用户名/模型名称" \
  --table N \
  [--model-column-index N] \
  [--model-name-override "精确列标题或模型名称"] \
  [--task-type "text-generation"] \
  [--dataset-name "自定义基准"] \
  [--apply | --create-pr]

从 Artificial Analysis 导入：

AA_API_KEY=... uv run scripts/evaluation_manager.py import-aa \
  --creator-slug "创建者名称" \
  --model-name "模型别名" \
  --repo-id "用户名/模型名称" \
  [--create-pr]

查看 / 验证：

uv run scripts/evaluation_manager.py show --repo-id "用户名/模型名称"
uv run scripts/evaluation_manager.py validate --repo-id "用户名/模型名称"

检查开放 PR（在使用 --create-pr 前始终运行）：

uv run scripts/evaluation_manager.py get-prs --repo-id "用户名/模型名称"

列出模型仓库的所有开放拉取请求。显示 PR 编号、标题、作者、日期和 URL。

运行评估作业（推理提供者）：

hf jobs uv run scripts/inspect_eval_uv.py \
  --flavor "cpu-basic|t4-small|..." \
  --secret HF_TOKEN=$HF_TOKEN \
  -- --model "模型 ID" \
     --task "任务名称"

或使用 Python 助手：

uv run scripts/run_eval_job.py \
  --model "模型 ID" \
  --task "任务名称" \
  --hardware "cpu-basic|t4-small|..."

运行 vLLM 评估（自定义模型）：

# 使用 vLLM 的 lighteval
hf jobs uv run scripts/lighteval_vllm_uv.py \
  --flavor "a10g-small" \
  --secrets HF_TOKEN=$HF_TOKEN \
  -- --model "模型 ID" \
     --tasks "leaderboard|mmlu|5"

# 使用 vLLM 的 inspect-ai
hf jobs uv run scripts/inspect_vllm_uv.py \
  --flavor "a10g-small" \
  --secrets HF_TOKEN=$HF_TOKEN \
  -- --model "模型 ID" \
     --task "mmlu"

# 助手脚本（自动硬件选择）
uv run scripts/run_vllm_eval_job.py \
  --model "模型 ID" \
  --task "leaderboard|mmlu|5" \
  --framework lighteval

Model-Index 格式

生成的 model-index 遵循此结构：

model-index:
  - name: 模型名称
    results:
      - task:
          type: text-generation
        dataset:
          name: 基准数据集
          type: benchmark_type
        metrics:
          - name: MMLU
            type: mmlu
            value: 85.2
          - name: HumanEval
            type: humaneval
            value: 72.5
        source:
          name: 来源名称
          url: https://source-url.com

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

错误处理

表格未找到: 脚本将报告是否未检测到评估表格
无效格式: 针对格式错误的表格提供清晰的错误消息
API 错误: 针对临时 Artificial Analysis API 故障的重试逻辑
令牌问题: 在尝试更新前进行验证
合并冲突: 添加新条目时保留现有 model-index 条目
空间创建: 优雅处理命名冲突和硬件请求失败

最佳实践

首先检查现有 PR: 在创建任何新 PR 前运行 get-prs 以避免重复
始终从 inspect-tables 开始: 查看表格结构并获取正确的提取命令
使用 --help 获取指南: 运行 inspect-tables --help 查看完整工作流
先预览: 默认行为打印 YAML；在使用 --apply 或 --create-pr 前审查
验证提取值: 手动将 YAML 输出与 README 表格比较
对多表格 README 使用 --table N: 当存在多个评估表格时需要
对比较表格使用 --model-name-override: 从 inspect-tables 输出复制精确列标题
为他人创建 PR: 当更新您不拥有的模型时使用 --create-pr
每个仓库一个模型: 仅将主要模型的结果添加到 model-index
YAML 名称中无 markdown: YAML 中的模型名字段应为纯文本

模型名称匹配

当提取包含多个模型的评估表格（无论是作为列还是行）时，脚本使用 精确归一化令牌匹配：

移除 markdown 格式（粗体 **、链接 []() ）
归一化名称（小写，将 - 和 _ 替换为空格）
比较令牌集："OLMo-3-32B" → {"olmo", "3", "32b"} 匹配 "**Olmo 3 32B**" 或 "[Olmo-3-32B](...)
仅当令牌完全匹配时提取（处理不同的单词顺序和分隔符）
如果未找到精确匹配则失败（而不是从相似名称猜测）

对于基于列的表格（基准作为行，模型作为列）：

找到与模型名称匹配的列标题
仅从该列提取分数

对于转置表格（模型作为行，基准作为列）：

在第一列中找到与模型名称匹配的行
仅从该行提取所有基准分数

这确保仅提取正确模型的分数，从不提取无关模型或训练检查点。

常见模式

更新您自己的模型：

# 从 README 提取并直接推送
uv run scripts/evaluation_manager.py extract-readme \
  --repo-id "您的用户名/您的模型" \
  --task-type "text-generation"

更新他人的模型（完整工作流）：

# 步骤 1：始终首先检查现有 PR
uv run scripts/evaluation_manager.py get-prs \
  --repo-id "其他用户名/他们的模型"

# 步骤 2：如果不存在开放 PR，则继续创建一个
uv run scripts/evaluation_manager.py extract-readme \
  --repo-id "其他用户名/他们的模型" \
  --create-pr

# 如果存在开放 PR：
# - 警告用户关于现有 PR
# - 向他们展示 PR 的 URL
# - 除非用户明确确认，否则不要创建新 PR

导入新基准：

# 步骤 1：检查现有 PR
uv run scripts/evaluation_manager.py get-prs \
  --repo-id "anthropic/claude-sonnet-4"

# 步骤 2：如果没有 PR，则从 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

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

解决方案：为具有自定义代码的模型添加 --trust-remote-code 标志（例如，Phi-2、Qwen）

问题：“未找到聊天模板”

解决方案：仅对包含聊天模板的指令调整模型使用 --use-chat-template

集成示例

Python 脚本集成：

import subprocess
import os

def update_model_evaluations(repo_id, readme_content):
    """用 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"成功更新 {repo_id}")
    else:
        print(f"错误： {result.stderr}")