前言¶

要在本機跑大模型，常見路徑是：在 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。