huggingface-local-models

Hugging Face 本地模型

在 Hugging Face Hub 上搜索兼容 llama.cpp 的 GGUF 仓库，选择合适的量化版本，并使用 llama-cli 或 llama-server 启动模型。

默认工作流

1. 使用 apps=llama.cpp 搜索 Hub。
2. 打开 https://huggingface.co/<repo>?local-app=llama.cpp。
3. 如果页面上有 HF 本地应用代码片段和量化建议，优先采用。
4. 使用 https://huggingface.co/api/models/<repo>/tree/main?recursive=true 确认确切的 .gguf 文件名。
5. 使用 llama-cli -hf <repo>:<QUANT> 或 llama-server -hf <repo>:<QUANT> 启动。
6. 如果仓库使用自定义文件命名，则改用 --hf-repo 和 --hf-file。
7. 仅当仓库未提供 GGUF 文件时，才从 Transformers 权重进行转换。

快速入门

安装 llama.cpp

brew install llama.cpp
winget install llama.cpp

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

验证受限仓库的身份

hf auth login

搜索 Hub

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 运行

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

运行指定的 GGUF 文件

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

仅在没有 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

对本地服务进行冒烟测试

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

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"}
    ]
  }'

量化版本选择

• 优先选择 HF 在 ?local-app=llama.cpp 页面上标记为兼容的确切量化版本。
• 保留仓库原有的标签，例如 UD-Q4_K_M，不要对其进行标准化处理。
• 除非仓库页面或硬件配置另有建议，否则默认使用 Q4_K_M。
• 内存允许时，代码或技术类工作负载优先使用 Q5_K_M 或 Q6_K。
• RAM 或 VRAM 预算较紧时，可考虑 Q3_K_M、Q4_K_S，或仓库专用的 IQ / UD-* 变体。
• 将 mmproj-*.gguf 文件视为投影器权重，而非主检查点。

参考资料

• 阅读 hub-discovery.md，了解以 URL 为先的工作流、模型搜索、树 API 提取和命令重建。
• 阅读 quantization.md，了解格式表、模型缩放、质量权衡和 imatrix。
• 阅读 hardware.md，了解 Metal、CUDA、ROCm 或 CPU 的构建和加速详情。

资源

• llama.cpp：https://github.com/ggml-org/llama.cpp
• Hugging Face GGUF + llama.cpp 文档：https://huggingface.co/docs/hub/gguf-llamacpp
• Hugging Face 本地应用文档：https://huggingface.co/docs/hub/main/local-apps
• Hugging Face 本地 Agent 文档：https://huggingface.co/docs/hub/agents-local
• GGUF 转换器 Space：https://huggingface.co/spaces/ggml-org/gguf-my-repo