kscz0000 Hugging Face 本地模型
何时使用
在需要在 CPU、Mac Metal、CUDA 或 ROCm 上选择通过 llama.cpp 与 GGUF 在本地运行的模型时使用本技能。涵盖 GGUF 查找、量化选择、启动服务器、精确 GGUF 文件定位、模型转换以及 OpenAI 兼容本地服务。
在 Hugging Face Hub 上搜索与 llama.cpp 兼容的 GGUF 仓库，选择合适的量化方案，并使用 llama-cli 或 llama-server 启动模型。
默认工作流
- 使用
apps=llama.cpp在 Hub 上搜索。 - 打开
https://huggingface.co/<repo>?local-app=llama.cpp。 - 优先采用 HF local-app 片段中可见的精确量化推荐。
- 通过
https://huggingface.co/api/models/<repo>/tree/main?recursive=true确认精确的.gguf文件名。 - 使用
llama-cli -hf <repo>:<QUANT>或llama-server -hf <repo>:<QUANT>启动。 - 当仓库使用自定义文件命名时，回退到
--hf-repo加上--hf-file。 - 仅当仓库尚未提供 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 优先工作流、模型搜索、tree 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 Local Apps 文档:
https://huggingface.co/docs/hub/main/local-apps - Hugging Face Local Agents 文档:
https://huggingface.co/docs/hub/agents-local - GGUF 转换 Space:
https://huggingface.co/spaces/ggml-org/gguf-my-repo
限制
- 仅当任务明确匹配其上游产品或 API 范围时使用本技能。
- 在进行修改前，请依据最新的官方文档核实命令、API 行为、价格、配额、凭据以及部署影响。
- 切勿将生成的示例视为环境特定测试、安全审查或用户对破坏性/高成本操作的批准的替代。