前言¶

做应用或实验时，「这个任务该用哪个模型」往往是第一个具体问题。常见做法是翻博客、看社区讨论，或凭印象选一个参数量「差不多能跑」的 checkpoint，再对照零散评测片段。Hugging Face Hub 上已有带 benchmark:official 标记的官方排行榜数据集，但要把任务、榜单、参数量与本地显存或统一内存对齐，仍需要多次查 API 和模型卡。

下面介绍 Hugging Face 在 huggingface/skills 仓库中提供的 huggingface-best Skill：它把「解析需求 → 查官方榜单 → 补全元数据 → 按设备过滤 → 输出对比表」写成 Agent 可执行的固定流程，适合在 Cursor、Claude Code、Codex、Gemini CLI 等支持 Agent Skills 的环境里启用。

这是什么¶

huggingface-best 是面向「模型推荐与对比」的 Agent Skill，遵循 Agent Skills 标准，以目录内的 SKILL.md（YAML frontmatter + 操作说明）形式交付。

维护方是 Hugging Face，与 Hub CLI、MCP 等同一套 Skills 生态。Skill 的 description 写明：当用户询问某任务的最佳/推荐模型、该用什么 AI 模型、或希望按 benchmark 分数对比模型时触发；即使用户未提到 Hugging Face 或 benchmark，只要意图是选型或对比，也应启用本 Skill。

核心产出是：基于官方 HF benchmark 排行榜查询结果，结合模型参数量与许可证等信息，在用户给出设备约束时做可部署性判断，并以 Markdown 对比表返回推荐排序。

核心功能¶

解析任务与设备¶

从用户消息中提取：

• Task：coding、数学/推理、对话、OCR、RAG/检索、语音识别、图像分类、多模态、Agent 等。
• Device：例如 MacBook M 系列统一内存 8/16/32/64GB、带指定 VRAM 的 RTX、仅 CPU、云端/无约束等。

若未提及设备，不做体量过滤，按 benchmark 分数返回表现最好的模型。任务 genuinely 模糊时，Skill 要求只问一个澄清问题。

设备 → 参数量预算¶

指定设备时，从可用内存（Apple Silicon 为统一内存，独显为 VRAM）估算：

• fp16 最大参数量（B） ≈ 内存（GB） ÷ 2
• Q4 最大参数量（B） ≈ 内存（GB） × 2

示例：16GB → 约 8B fp16 / 32B Q4；24GB VRAM → 约 12B fp16 / 48B Q4；8GB → 约 4B fp16 / 16B Q4。

查询官方 Benchmark 与排行榜¶

1. 拉取全部官方 benchmark 数据集列表（filter=benchmark:official），按 id、tags、description 匹配与用户任务相关的数据集，力求覆盖完整而非只选两三个。
2. 对每个选中数据集的 leaderboard API 取前 15 名（含 rank、modelId、value、verified）。
3. 对约 10–15 个候选 model ID 调用 Models API 或 hf models info，提取参数量（优先 safetensors.total）、许可证标签等；无 safetensors 时从模型名解析如 7b、70b 等。

上述 HTTP 请求在 Skill 说明中使用 Hub API，并约定 Header：

Authorization: Bearer $(cat ~/.cache/huggingface/token)

过滤、排序与输出¶

• 有设备约束：剔除超过 fp16 预算的模型；仅 Q4 能装下的标为 Q4；略超预算的高排名模型保留并注明需 Q4，不静默丢弃。
• 无设备约束：仅按 benchmark 分数排序，保留约 5–8 个模型。
• 排行榜若出现专有/API 模型（如 GPT-4、Claude、Gemini），可列入但标为 API only；用户明确要求仅本地/开源时可排除。

最终输出 Markdown 对比表：模型链到 https://huggingface.co/<model_id>，多 benchmark 列用 — 表示未评测，榜首用 ⭐ 标记，「On device」取 Yes (fp16)、Q4 only、Too large、API only 等。

展示表格后，Skill 会追问是否运行推荐模型；若肯定，再区分本地部署或 HF Jobs 指引。

错误与回退¶

• 某 leaderboard 404/401 等：跳过并在输出中注明不可用。
• 找不到任务相关 benchmark：使用 Skill 内 curated fallback，或 hub_repo_search 按任务 filter、按 trendingScore 排序。
• 全部 leaderboard 失败：回退到按任务标签的热门模型，并说明结果是流行度而非 benchmark 分数。

安装与启用¶

本 Skill 属于 huggingface/skills 仓库的 skills/huggingface-best 目录。仓库说明：Marketplace 默认侧重 hf-cli；其它工作流 Skill 可用 hf skills add <skill-name> 按需安装，或由支持 Skill 的客户端通过 CLI/MCP 发现。

Claude Code¶

注册插件市场并安装 CLI Skill 后，用 hf 添加本 Skill：

/plugin marketplace add huggingface/skills

/plugin install hf-cli@huggingface/skills

hf skills add huggingface-best

Codex¶

将仓库 skills/ 下对应目录复制或 symlink 到 Codex 标准的 .agents/skills 路径（如 $REPO_ROOT/.agents/skills 或 $HOME/.agents/skills），由客户端按 Agent Skills 标准加载 SKILL.md。亦可使用仓库生成的 agentsmd/AGENTS.md 作为回退。

Gemini CLI¶

gemini extensions install https://github.com/huggingface/skills.git --consent

或在本机扩展目录执行 gemini extensions install . --consent（见仓库 gemini-extension.json）。

Cursor¶

通过仓库的 Cursor 插件清单（.cursor-plugin/plugin.json、.mcp.json）安装；Marketplace 入口以 hf-cli 为主，额外 Skill 同样建议：

hf skills add huggingface-best

执行 API 查询前，需已配置 ~/.cache/huggingface/token，并安装 hf CLI（hf models info 等）。与选型衔接时，仓库还提供 huggingface-local-models（llama.cpp / GGUF 本地运行）、hf-mem（估算加载权重内存）等 Skill，可按需要一并安装。

典型用法¶

Skill 由 Agent 在用户自然语言提问时自动触发，典型表述包括：best model for X、what model should I use for、top models for [task]、which model runs on my laptop、compare models for、what's state of the art for 等。

Agent 侧会按 Skill 步骤调用 Hub API。例如列出官方 benchmark：

curl -s -H "Authorization: Bearer $(cat ~/.cache/huggingface/token)" \
  "https://huggingface.co/api/datasets?filter=benchmark:official&limit=500" | jq '[.[] | {id, tags, description}]'

对选定数据集取排行榜：

curl -s -H "Authorization: Bearer $(cat ~/.cache/huggingface/token)" \
  "https://huggingface.co/api/datasets/<namespace>/<repo>/leaderboard" | jq '[.[:15] | .[] | {rank, modelId, value, verified}]'

用户只需在对话中说明任务与设备，例如：「16GB M2 MacBook 上做 Python coding，推荐能本地跑的开源模型并对比 benchmark。」Agent 应返回带许可证与「能否在本机 fp16/Q4」列的表格，并给出后续是否本地跑或走 HF Jobs 的选项。

适用场景与注意¶

适合：需要在短时间内基于 HF 官方 leaderboard 做任务导向选型；要在同一表格里对比多个 benchmark 分数；本地或边缘设备有明确内存上限，希望 Agent 自动做参数量与量化档位判断。

注意：

• fp16/Q4 预算为 Skill 内近似公式，实际推理还受上下文长度、框架与 KV cache 影响，表格中的「On device」是选型提示而非严格 profiling；精细内存估算可配合 hf-mem。
• 依赖 Hub API 与 token；部分 leaderboard 可能不可用，输出会标注并可能回退到 trending 搜索。
• Benchmark 覆盖随官方数据集更新变化，Agent 需根据返回列表判断与任务的匹配度，而非固定几张表。

结尾¶

huggingface-best 把「查官方 benchmark、对齐设备、生成对比表」收敛成可重复的 Agent 工作流，减少在 Hub 与评测信息之间手工拼接的时间。官方 Skill 说明与源码目录：

https://github.com/huggingface/skills/tree/main/skills/huggingface-best