前言¶

要在本机跑大模型，常见路径是：在 Hub 上找权重、确认格式与量化档、再配 llama.cpp 的启动参数。模型页上的 quant 命名、自定义文件名、以及 CPU / CUDA / Metal / ROCm 的差异，容易让 Agent 或人工反复查文档。huggingface-local-models 把「搜 GGUF 仓库 → 选 quant → 用 llama-cli 或 llama-server 拉起服务」收成一套可执行的默认流程，并附带 Hub 发现、量化选择与硬件相关的参考说明。

这是什么¶

huggingface-local-models 是 Hugging Face 在 huggingface/skills 仓库中发布的一项 Agent Skill，遵循 Agent Skills 标准：目录内 SKILL.md 带 YAML 元数据（name、description），激活后指导编码 Agent 完成特定任务。

官方描述概括为：在本地用 llama.cpp 与 GGUF，在 CPU、Mac Metal、CUDA 或 ROCm 上选型并运行模型；覆盖在 Hub 上找 GGUF、量化选择、启动服务、精确 GGUF 文件查找、必要时从 Transformers 权重转换，以及 OpenAI 兼容的本地 serving。

核心功能¶

下面介绍 Skill 文档中写明的能力边界，均可在官方 SKILL.md 核对。

默认工作流¶

1. 在 Hub 搜索时使用 apps=llama.cpp 过滤。
2. 打开 https://huggingface.co/<repo>?local-app=llama.cpp，优先采用页面上 Hugging Face 给出的 local-app 片段与 quant 建议。
3. 用 https://huggingface.co/api/models/<repo>/tree/main?recursive=true 确认确切的 .gguf 文件名。
4. 用 llama-cli -hf <repo>:<QUANT> 或 llama-server -hf <repo>:<QUANT> 启动。
5. 若仓库使用自定义命名，回退到 --hf-repo 加 --hf-file。
6. 仅当仓库尚未提供 GGUF 时，再从 Transformers 权重转换。

量化选择要点¶

• 优先使用 ?local-app=llama.cpp 页面上标注为兼容的 quant。
• 保留仓库原生标签（例如 UD-Q4_K_M），不要自行「规范化」改名。
• 无特别说明时默认 Q4_K_M；代码或技术类任务在显存/内存允许时可考虑 Q5_K_M 或 Q6_K。
• 显存或内存更紧时，可考虑 Q3_K_M、Q4_K_S 或仓库提供的 IQ / UD-* 变体。
• mmproj-*.gguf 视为投影权重，不是主 checkpoint。

扩展参考¶

Skill 内引用三份说明文档（路径相对于 skill 目录）：references/hub-discovery.md（URL 优先的搜模与 tree API）、references/quantization.md（格式与 imatrix 等）、references/hardware.md（Metal、CUDA、ROCm、CPU 构建与加速）。

安装与启用¶

Hugging Face Skills 可通过 Claude Code、Codex、Gemini CLI、Cursor 等支持 Agent Skills 的客户端使用。仓库建议 Hub 相关操作可先安装 hf-cli；其他工作流 Skill 可用 hf skills add <skill-name> 按需安装。

Claude Code¶

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

/plugin marketplace add huggingface/skills

/plugin install hf-cli@huggingface/skills

hf skills add huggingface-local-models

Codex¶

将 skills/huggingface-local-models 复制或符号链接到 Codex 约定的 .agents/skills 位置（例如 $REPO_ROOT/.agents/skills 或 $HOME/.agents/skills），由客户端按 Agent Skills 标准发现并加载 SKILL.md。

Gemini CLI¶

在仓库根目录或 GitHub URL 安装扩展后，扩展会纳入该仓库中的 skills（见仓库 gemini-extension.json 与 Gemini CLI 扩展文档）。

Cursor¶

可通过 Cursor 插件流程从仓库 URL 或本地检出安装；市场入口以 hf-cli 为主，额外 Skill 同样可用 hf skills add huggingface-local-models 安装。

运行本 Skill 所描述的工作流前，需在机器上安装 llama.cpp 与（按需）Hugging Face CLI。

安装 llama.cpp 示例：

brew install llama.cpp
winget install llama.cpp

或从源码构建：

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
make

访问 gated 仓库时需先登录 Hub：

hf auth login

典型用法¶

在 Hub 上筛选 llama.cpp 模型¶

在浏览器打开带过滤的模型列表，例如按 trending 排序、或按参数量区间筛选：

https://huggingface.co/models?apps=llama.cpp&sort=trending
https://huggingface.co/models?search=Qwen3.6&apps=llama.cpp&sort=trending
https://huggingface.co/models?search=<term>&apps=llama.cpp&num_parameters=min:0,max:24B&sort=trending

直接从 Hub 拉取并运行¶

下面命令中的仓库与 quant 标签来自官方 Quick Start，用于演示 -hf repo:QUANT 写法：

llama-cli -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M
llama-server -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M

需要指定确切文件名时：

llama-server \
    --hf-repo unsloth/Qwen3.6-35B-A3B-GGUF \
    --hf-file Qwen3.6-35B-A3B-UD-Q4_K_M.gguf \
    -c 4096

无现成 GGUF 时再转换¶

仅当目标仓库没有 GGUF 文件时：

hf download <repo-without-gguf> --local-dir ./model-src
python convert_hf_to_gguf.py ./model-src \
    --outfile model-f16.gguf \
    --outtype f16
llama-quantize model-f16.gguf model-q4_k_m.gguf Q4_K_M

（convert_hf_to_gguf.py 位于 llama.cpp 仓库。）

本地 OpenAI 兼容接口冒烟测试¶

先启动 server：

llama-server -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M

默认在本机 8080 端口提供 /v1/chat/completions，可用 curl 验证：

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "messages": [
      {"role": "user", "content": "Write a limerick about exception handling"}
    ]
  }'

适用场景与注意¶

适合需要在本地完成推理、并希望 Agent 按统一步骤处理 Hub 上的 GGUF 与 llama.cpp 启动参数的场景；数据留在本机、避免按 token 计费的云端 API，是本地推理常见动机，具体成本与隐私边界仍取决于你的部署方式与模型许可。

注意以下几点：

• Skill 指导的是流程与命令约定，不替代你在本机安装、编译带 CUDA/Metal/ROCm 的 llama.cpp，硬件细节见 Skill 内 hardware.md 与 Hugging Face GGUF + llama.cpp 文档。
• 大模型量化与显存/内存占用需结合机器配置；可配合同仓库的 hf-mem Skill 估算加载 GGUF 或 Safetensors 所需内存。
• 转换路径仅在没有现成 GGUF 时使用，Hub 上已有 GGUF 的仓库应优先直接下载或 -hf 引用。

更多链接见 Skill 文档 Resources：llama.cpp 仓库、Local Apps、Local Agents、GGUF converter Space。

结尾¶

huggingface-local-models 把 Hugging Face Hub 上与 llama.cpp 配套的搜模、quant 选择与启动方式写进 Agent 可 Follow 的 Skill，减少在文档与文件名之间来回对照。官方 Skill 目录：https://github.com/huggingface/skills/tree/main/skills/huggingface-local-models。