HuggingFace模型评估管理Skill：把评估分数一键写进模型卡，让模型实力被看见
- 一句话定位：这是一款专为 Hugging Face 模型卡打造评估数据管理工具，能把 README 里的评估表格、Artificial Analysis 的基准分数，或你自己跑出来的评测结果，转换成标准
model-index元数据并写入模型卡。 - 四条数据通路：README 表格提取、Artificial Analysis API 导入、HF Jobs 上的 inspect-ai 评估作业、本地 GPU 上的 vLLM/lighteval 自定义评估，覆盖"已有分数"和"没有分数"两类情况。
- 生态兼容性：生成的
model-index遵循 Papers with Code 规范，可直接被 Hugging Face 排行榜识别，避免手工拼 YAML 出错。 - 安全护栏：内置
get-prs检查机制，创建 PR 前先查重，避免向他人模型仓库提交重复评估请求，把维护者的负担降到最低。 - 低门槛：基于
uv run的 PEP 723 脚本头自动装依赖，一条命令即可预览、应用或提 PR，当前版本 1.3.0。
该技能叫什么？如何下载安装 AI 技能提升开发效率？
技能基本信息
| 项目 | 内容 |
|---|---|
| 中文名 | HuggingFace模型评估管理Skill |
| 英文名 | hugging-face-evaluation |
| 技能ID | 13634 |
| 当前版本 | 1.3.0 |
它解决什么问题
在 Hugging Face 上发布模型，光有权重和 README 还不够。社区用户、排行榜、下游开发者判断一个模型"行不行"，主要看模型卡里的 model-index 结构化评估数据。但现实中，评估分数往往散落在 README 的 Markdown 表格里、第三方评测网站的页面上，或者是自己跑完还没整理的评测日志里。手工把这些内容改写成符合规范的 YAML，既枯燥又容易写错字段、写错缩进、写错模型名。
这个技能就是把这套"评估数据搬运与规范化"的流程自动化：解析表格、拉取 API 分数、运行评测、生成 YAML、合并进模型卡、必要时自动开 PR，全链路一气呵成。
一键安装与验证步骤
- 安装前提：准备一个可用的 Hugging Face 账号与具备写入权限的访问令牌（
HF_TOKEN）；如果要导入 Artificial Analysis 分数，还需要对应的AA_API_KEY；如果要跑自定义模型评估，需要本地有 GPU 且安装了uv。 - 进入技能目录：所有脚本路径都是相对于包含
SKILL.md的目录，运行前先cd到该目录，或使用完整路径。 - 安装依赖（推荐方式）：首选
uv run，脚本头遵循 PEP 723 规范，会自动安装所需依赖，无需手动配置环境。若你的环境不便使用uv，也可手动安装核心依赖：pip install huggingface-hub markdown-it-py python-dotenv pyyaml requests。启用 vLLM 自定义评估时，还需lighteval[accelerate,vllm]>=0.6.0、vllm>=0.4.0、torch>=2.0.0、transformers>=4.40.0、accelerate>=0.30.0。具体版本约束与更新以官方说明为准。 - 配置环境变量：设置
HF_TOKEN（写入令牌）与AA_API_KEY（按需）。技能支持python-dotenv，会自动加载.env文件，因此也可以把令牌写进.env里。 - 验证是否生效：运行
uv run scripts/evaluation_manager.py --version查看版本，运行uv run scripts/evaluation_manager.py --help获取最新工作流指南。再执行一次uv run scripts/evaluation_manager.py inspect-tables --repo-id "用户名/模型名称"，若能正常列出 README 中的表格结构，说明环境已就绪。
这里的"一键"并不是魔法，而是把"依赖安装 + 鉴权 + 解析 + 生成 + 推送"打包成一条命令。真正省下来的，是你反复手改 YAML 和反复调试格式的时间。
该技能的主要功能和特点
- README 评估表格提取：用
inspect-tables查看 README 中所有表格的结构、列名与示例行，再用extract-readme --table N指定表格。基于markdown-it-py做精准解析，会忽略代码块和示例中的"假表格"，避免误抓。 - 格式智能识别：能识别"基准作为行、模型作为列"的常规表格，也能识别"模型作为行、基准作为列"的转置表格，以及包含多个模型的对比表格。
- 模型名精确匹配：采用精确归一化令牌匹配，自动去除粗体、链接等 Markdown 格式，统一大小写与分隔符，
"OLMo-3-32B"能匹配到"**Olmo 3 32B**"，但匹配不到就报错，绝不猜，从源头杜绝把别的模型分数抄进来。 - Artificial Analysis 直连导入：通过
import-aa从 Artificial Analysis API 拉取基准分数，自动转成model-index格式，同时保留来源名称与 URL 归属信息，并附带针对临时 API 故障的重试逻辑。 - model-index 管理与合并：生成符合 Papers with Code 规范的 YAML，向已有模型卡追加条目而非覆盖，支持批量处理多个模型，并提供
show、validate子命令做查看与校验。 - HF Jobs 上跑评估作业：用
hf jobs uv run把 inspect-ai 评估脚本直接提交到 Hugging Face 基础设施运行，无需编写 Dockerfile、无需管理 Space，可选 CPU 或 GPU 硬件规格，API 令牌通过--secret安全传递。 - vLLM 自定义模型评估：基于 lighteval 或 inspect-ai，用 vLLM 后端在本地 GPU 或 HF Jobs GPU 上跑 Open LLM 排行榜任务，官方描述其推理速度相比标准 HF 方法有显著提升，且模型下载后可离线运行。
- PR 防重复机制：
get-prs列出仓库所有开放 PR 的编号、标题、作者、日期和 URL，创建新 PR 前必须先行检查，这是写进技能说明的硬性要求。 - 输出即预览：
extract-readme默认只打印 YAML 不写入，让你先人工比对 README 表格再决定--apply还是--create-pr，把不可逆操作放到最后一步。
与普通"手改 README"的方式相比，它的差异化不在于"能填表"，而在于解析准确、格式合规、合并安全、来源可溯、流程可复用。
如何使用该技能？
方法一：从 README 提取评估表格（最常用）
- 先查重：
uv run scripts/evaluation_manager.py get-prs --repo-id "用户名/模型名称"。如果已有开放 PR，不要新建，把 PR 链接告知相关方即可。 - 看表结构：
uv run scripts/evaluation_manager.py inspect-tables --repo-id "用户名/模型"，输出会告诉你共有几张表、每张表的编号、列标题和若干示例行。 - 试提取并预览：
uv run scripts/evaluation_manager.py extract-readme --repo-id "用户名/模型" --table 1。此时终端只打印 YAML，不会改动仓库。 - 处理多模型表格：优先用
--model-column-index <检查输出中的列索引>指定模型所在列；无法用索引时再用--model-name-override "精确列标题"，注意标题文本必须与检查结果完全一致。 - 补充任务类型：用
--task-type "text-generation"设置task.type字段，用--dataset-name "自定义基准"覆盖数据集名称。 - 确认写入：自己的模型用
--apply直接推送；更新他人的模型用--create-pr开拉取请求。
示例输出形态如下（YAML，节选）：
model-index:
- name: 模型名称
results:
- task:
type: text-generation
dataset:
name: 基准数据集
type: benchmark_type
metrics:
- name: MMLU
type: mmlu
value: 85.2
source:
name: 来源名称
url: https://source-url.com
方法二：从 Artificial Analysis 导入分数
- 准备好
AA_API_KEY，可写入.env。 - 执行：
uv run scripts/evaluation_manager.py import-aa --creator-slug "anthropic" --model-name "claude-sonnet-4" --repo-id "用户名/模型名称"。 - 确认结果无误后，追加
--create-pr发起 PR。注意creator-slug与model-name必须与 API 中的取值一致。
方法三：在 HF Jobs 上运行评估
- 用
hf jobs uv run scripts/inspect_eval_uv.py --flavor cpu-basic --secret HF_TOKEN=$HF_TOKEN -- --model "meta-llama/Llama-2-7b-hf" --task "mmlu"提交 CPU 作业；换成--flavor a10g-small并指定--task "gsm8k"即为 GPU 作业。 - 也可以用 Python 助手：
uv run scripts/run_eval_job.py --model "meta-llama/Llama-2-7b-hf" --task "mmlu" --hardware "t4-small"。
方法四：用 vLLM 跑自定义模型评估
- 运行前检查脚本路径、
uv是否安装、nvidia-smi是否能看到 GPU。 - lighteval 方式：
uv run scripts/lighteval_vllm_uv.py --model meta-llama/Llama-3.2-1B --tasks "leaderboard|mmlu|5"；多任务用逗号分隔；不想用 vLLM 可加--backend accelerate；指令微调模型加--use-chat-template。 - inspect-ai 方式：
uv run scripts/inspect_vllm_uv.py --model meta-llama/Llama-3.2-1B --task mmlu；大模型可加--tensor-parallel-size 4。 - 任务命名遵循
suite|task|num_fewshot，如leaderboard|mmlu|5、leaderboard|gsm8k|5、lighteval|hellaswag|0。 - 想让脚本自动挑硬件：
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。
硬件参考：30 亿参数以下可用 t4-small；30 亿至 130 亿用 a10g-small；130 亿至 340 亿用 a10g-large；340 亿以上建议 a100-large。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| hugging-face-evaluation（本技能） | 模型卡评估数据的全流程管家 | README 表格提取、AA 导入、model-index 合并校验、HF Jobs 评估、vLLM 自定义评测、PR 防重 | 中低：uv run 自动装依赖，需 HF_TOKEN，vLLM 评测需 GPU |
模型作者补评估、第三方补 PR、团队本地跑基准 | 优势是端到端打通且格式合规、防重复 PR；不足是 vLLM 路线对硬件有要求，需注意显存 |
| 在 Hugging Face 网页手工编辑模型卡 | 最原始的替代方案 | 人工复制粘贴 YAML | 极低：打开网页即可 | 只有一两行分数、临时修补 | 优势是零学习成本；不足是易写错缩进与字段、无法批量、多模型表格易抄错行 |
| 直接使用 lighteval 原生命令行 | 通用评估框架 | 运行 Open LLM 排行榜等任务并输出结果 | 中高：需自行配置环境与后端 | 纯做评测、不关心模型卡格式 | 优势是任务覆盖广；不足是不负责解析 README、不生成 model-index、不会自动开 PR |
| EleutherAI lm-evaluation-harness | 老牌评测工具链 | 大量基准任务的评测执行 | 中高：需自行搭环境、显存与并行需调 | 学术评测、内网离线评测 | 优势是基准丰富、社区成熟；不足是与 HF 模型卡元数据链路不直连，仍需手工转格式 |
| Artificial Analysis 网页/API 单独使用 | 第三方基准聚合平台 | 提供跨模型基准分数与对比 | 低：网页可直接查 | 快速横向看分、做选型参考 | 优势是数据集中直观；不足是只解决"取分"一环，写入模型卡、格式化、提 PR 仍需另做 |
从对比可以看出，本技能的不可替代性在于"把分数送到该去的地方"——评测框架只管跑分，聚合平台只管展示，而它负责把分数变成模型卡里能被排行榜识别的结构化数据。
该技能的典型应用场景与实际体验情况
场景一：开源模型作者给自己的新模型补上评估数据
角色是独立开发者或小团队算法工程师。痛点是模型刚上传，README 里有一张从论文搬来的成绩表，但从没转换成 model-index，导致排行榜抓不到、曝光低。使用方式是 inspect-tables 看清表格结构 → extract-readme --table 1 --task-type "text-generation" 预览 YAML → 核对无误后 --apply 推送。实际体验上，这条路径最顺，因为仓库自己有写权限，不需要 PR，几分钟内就能完成。注意事项是要先人工比对 YAML 里的数值与 README 表格是否一致，别把"平均值行"当成模型行提取了。
场景二：研究者为他人的模型补充第三方评测
角色是评测方向的研究者或社区贡献者。痛点是手头跑出了别人的模型分数，想贡献回去，但直接开 PR 容易被维护者视为噪音，甚至和已有 PR 撞车。使用方式严格按技能规定：先 get-prs 查开放 PR，没有重复才 --create-pr。实际体验上，get-prs 输出会列出 PR 编号、标题、作者、日期和 URL，信息足够判断是否重复；如果已有 PR，技能的说明明确要求警告用户并展示链接，而不是硬提。注意点是每个仓库只加主模型的结果，不要把训练检查点的分数也塞进去。
场景三：算法团队在自有 GPU 上跑 MMLU / GSM8K 验证微调效果
角色是模型微调工程师。痛点是微调后想知道相对基线的涨跌，但不想把模型上传到任何平台、也不想付 API 费用。使用方式是先 nvidia-smi 确认显卡可用，再用 uv run scripts/lighteval_vllm_uv.py --model meta-llama/Llama-3.2-1B --tasks "leaderboard|mmlu|5" 本地跑，vLLM 后端加载快、吞吐高；不想用 vLLM 就切 --backend accelerate。实际体验上，任务串 suite|task|num_fewshot 一眼能懂，--use-chat-template 对指令模型很关键，忘了加会导致分数明显偏低。注意事项是显存紧张时容易 OOM，可以换更大的硬件规格、调低 --gpu-memory-utilization，或用 --tensor-parallel-size 做多卡并行；遇到 vLLM 不支持的架构，切 --backend hf；像 Phi-2、Qwen 这类需要自定义代码的模型要加 --trust-remote-code。
场景四：社区维护者批量对齐多个模型的公开分数
角色是模型榜单或合集仓库的维护者。痛点是几十个模型的分数来源五花八门，格式各异，逐个手改几乎不可行。使用方式是 --creator-slug + --model-name 组合批量调用 import-aa，把 Artificial Analysis 的分数直接落到各自的模型卡，来源 URL 一并保留。实际体验上，自动格式化与元数据保留省了大量核对工作；但 creator-slug 和 model-name 必须精确匹配 API 取值，写错会提示"Artificial Analysis 中未找到模型"，需要先确认拼写。
该技能能为用户带来的价值
效率层面：把一个"看表格 → 抄数字 → 拼 YAML → 校对缩进 → 提交 PR"的机械流程压缩成两三条命令。过去处理一张多模型对比表可能要在 README 和编辑器之间来回切换十几分钟，现在预览加确认基本是分钟级。批量导入时差距更明显，因为命令可以脚本化调用（技能本身也给出了 Python 集成示例，用 subprocess 调 extract-readme 即可批量处理）。
质量层面：model-index 规范里最容易踩的坑是字段名写错、task.type 缺失、模型名里带了 Markdown 加粗符号、把别人的分数混进来。技能通过格式校验、精确令牌匹配、合并而非覆盖、来源 URL 保留这几道关卡，把这些错误挡在提交之前。验证命令 validate 和 show 让"改完对不对"有了确定答案。
门槛层面：不需要事先精通 Papers with Code 的 model-index 规范，也不需要理解 lighteval 的任务命名体系。--help 给出最新工作流，inspect-tables 先带你看清数据结构，默认输出即预览，错误信息也会针对"未找到表格"“转置表找不到模型”“令牌无写入权限”“硬件需付费”"CUDA OOM"等具体情形给出明确提示。
长期价值：模型卡里的结构化评估数据会持续被排行榜、选型工具、下游集成方读取。每次评估更新都按同一套标准写入，就等于为模型积累一份可追溯、可对比、可机器读取的"成绩档案"，而不是散落在各处的截图和临时表格。加上 PR 查重机制保护了社区协作礼仪，让贡献行为更容易被接受，长期看是模型曝光度和社区口碑的双重收益。
常见问题 FAQ
Q1：这个技能怎么安装？必须用 uv 吗？
不强制。推荐方式是在技能目录下直接 uv run scripts/evaluation_manager.py ...，脚本的 PEP 723 头会自动安装依赖。如果你的环境不便使用 uv，也可以手动执行 pip install huggingface-hub markdown-it-py python-dotenv pyyaml requests 后改用 python scripts/evaluation_manager.py ...。但走 vLLM 自定义评估路线时，技能说明明确要求设备已安装 uv，并具备足够的 GPU 显存。具体依赖版本以官方说明为准。
Q2：用这个技能要花钱吗？
技能本身是脚本工具，不收取费用。可能产生的成本来自两处：一是 HF Jobs 上使用非 CPU 硬件（如 a10g-small、a100-large）会消耗计算资源，需要账户绑卡，遇到"硬件需要付款"提示通常就是没绑支付方式；二是调用 Artificial Analysis API 可能需要相应密钥与额度。在本地 GPU 上跑评估则只耗自己的电和显卡。
Q3：为什么我创建 PR 时被要求先查 PR？
因为模型仓库的维护者最怕被重复评估 PR 淹没。技能把"创建 PR 前先运行 get-prs"写成了硬性流程：如果已存在开放 PR，正确做法是不新建，告知用户已存在、把已有 PR 的 URL 展示出来，只有在用户明确确认要再开一个时才继续。这既是技术流程，也是社区协作礼仪。
Q4：适合谁用？我只想看看别人的模型分数，需要装它吗？
如果只是查分做选型，直接用模型卡或 Artificial Analysis 网页更省事，不需要安装。这个技能的目标用户是三类人：需要为自己的模型补评估数据的作者、想向他人模型提交评估 PR 的贡献者、以及需要在本地或 HF Jobs 上跑基准并落盘格式化的工程团队。
Q5：提取失败或分数对不上该怎么办？
先看错误类型。提示"README 中未找到评估表格"，说明 README 里没有带数字分数的 Markdown 表格，需要先补表格或改用 API 导入；提示"在转置表格中找不到模型 X"，脚本会列出可用模型名，用 --model-name-override 指定列表中的精确名称（例如 "**Olmo 3-32B**"）即可；提示"令牌没有写入访问权限"，检查 HF_TOKEN 是否有该仓库写权限；提示"AA_API_KEY 未设置"，把密钥写入环境变量或 .env。另外别忘了 extract-readme 默认只打印 YAML，先拿它和 README 表格逐项核对，确认无误再 --apply 或 --create-pr。