llama-cpp

llama.cpp + GGUF

将此技能用于本地 GGUF 推理、量化选择，或为 llama.cpp 查找 Hugging Face 仓库。

适用场景

• 在 CPU、Apple Silicon、CUDA、ROCm 或 Intel GPU 上运行本地模型
• 为特定 Hugging Face 仓库找到合适的 GGUF
• 根据 Hub 内容构建 llama-server 或 llama-cli 命令
• 搜索 Hub，查找已支持 llama.cpp 的模型
• 列出仓库中可用的 .gguf 文件及其大小
• 根据用户的 RAM 或 VRAM，在 Q4/Q5/Q6/IQ 变体之间做出选择

模型发现工作流

优先采用 URL 工作流，再询问用户是否能使用 hf、Python 或自定义脚本。

1. 在 Hub 上搜索候选仓库：
   • 基础 URL：https://huggingface.co/models?apps=llama.cpp&sort=trending
   • 添加 search=<term>，搜索某个模型系列
   • 如果用户对模型大小有要求，添加 num_parameters=min:0,max:24B 或类似筛选条件
2. 使用 llama.cpp 本地应用视图打开仓库：
   • https://huggingface.co/<repo>?local-app=llama.cpp
3. 如果能看到本地应用代码片段，将其作为权威信息来源：
   • 原样复制 llama-server 或 llama-cli 命令
   • 按 HF 显示的内容准确报告推荐量化
4. 读取相同的 ?local-app=llama.cpp URL 页面文本或 HTML，提取 Hardware compatibility 下的部分：
   • 优先采用其中的确切量化标签和大小，而不是通用表格
   • 保留仓库专用标签，例如 UD-Q4_K_M 或 IQ4_NL_XL
   • 如果获取到的页面源代码中没有该部分，请说明这一点，并退回使用 tree API 和通用量化建议
5. 查询 tree API，确认实际存在的文件：
   • https://huggingface.co/api/models/<repo>/tree/main?recursive=true
   • 保留 type 为 file 且 path 以 .gguf 结尾的条目
   • 使用 path 和 size 作为文件名及字节大小的权威来源
   • 将量化检查点与 mmproj-*.gguf 投影器文件以及 BF16/ 分片文件区分开
   • 仅将 https://huggingface.co/<repo>/tree/main 用作人工查看的备用方式
6. 如果本地应用代码片段无法以文本形式查看，请根据仓库和所选量化重建命令：
   • 简写量化选择：llama-server -hf <repo>:<QUANT>
   • 精确文件备用方式：llama-server --hf-repo <repo> --hf-file <filename.gguf>
7. 仅当仓库尚未提供 GGUF 文件时，才建议从 Transformers 权重转换。

快速开始

安装 llama.cpp

# macOS / Linux (simplest)
brew install llama.cpp

winget install llama.cpp

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build
cmake --build build --config Release

直接从 Hugging Face Hub 运行

llama-cli -hf bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0

llama-server -hf bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0

从 Hub 运行指定的 GGUF 文件

当 tree API 显示自定义文件命名，或缺少准确的 HF 代码片段时，使用此方式。

llama-server \
    --hf-repo microsoft/Phi-3-mini-4k-instruct-gguf \
    --hf-file Phi-3-mini-4k-instruct-q4.gguf \
    -c 4096

OpenAI 兼容服务检查

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

Python 绑定（llama-cpp-python）

pip install llama-cpp-python（CUDA：CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python --force-reinstall --no-cache-dir；Metal：CMAKE_ARGS="-DGGML_METAL=on" ...）。

基本生成

from llama_cpp import Llama

llm = Llama(
    model_path="./model-q4_k_m.gguf",
    n_ctx=4096,
    n_gpu_layers=35,     # 0 for CPU, 99 to offload everything
    n_threads=8,
)

out = llm("What is machine learning?", max_tokens=256, temperature=0.7)
print(out["choices"][0]["text"])

聊天 + 流式传输

llm = Llama(
    model_path="./model-q4_k_m.gguf",
    n_ctx=4096,
    n_gpu_layers=35,
    chat_format="llama-3",   # or "chatml", "mistral", etc.
)

resp = llm.create_chat_completion(
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Python?"},
    ],
    max_tokens=256,
)
print(resp["choices"][0]["message"]["content"])

# Streaming
for chunk in llm("Explain quantum computing:", max_tokens=256, stream=True):
    print(chunk["choices"][0]["text"], end="", flush=True)

嵌入

llm = Llama(model_path="./model-q4_k_m.gguf", embedding=True, n_gpu_layers=35)
vec = llm.embed("This is a test sentence.")
print(f"Embedding dimension: {len(vec)}")

你也可以直接从 Hub 加载 GGUF：

llm = Llama.from_pretrained(
    repo_id="bartowski/Llama-3.2-3B-Instruct-GGUF",
    filename="*Q4_K_M.gguf",
    n_gpu_layers=35,
)

选择量化

先查看 Hub 页面，再参考通用经验法则。

• 优先选择 HF 标记为兼容用户硬件配置的确切量化。
• 对于一般聊天，优先从 Q4_K_M 开始。
• 对于代码或技术工作，如果内存允许，优先选择 Q5_K_M 或 Q6_K。
• 对于 RAM 非常有限的情况，可以考虑 Q3_K_M、IQ 变体或 Q2 变体，但仅限用户明确优先考虑适配性而非质量的情况。
• 对于多模态仓库，需单独说明 mmproj-*.gguf。投影器不是主模型文件。
• 不要规范化仓库原生标签。如果页面显示 UD-Q4_K_M，就报告 UD-Q4_K_M。

从仓库中提取可用的 GGUF

当用户询问有哪些 GGUF 时，返回：

• 文件名
• 文件大小
• 量化标签
• 是主模型还是辅助投影器

除非用户提出要求，否则忽略：

• README
• BF16 分片文件
• imatrix 数据块或校准产物

此步骤使用树 API：

• https://huggingface.co/api/models/<repo>/tree/main?recursive=true

对于 unsloth/Qwen3.6-35B-A3B-GGUF 这样的仓库，本地应用页面可能显示 UD-Q4_K_M、UD-Q5_K_M、UD-Q6_K 和 Q8_0 等量化标签，而树 API 会公开 Qwen3.6-35B-A3B-UD-Q4_K_M.gguf 和 Qwen3.6-35B-A3B-Q8_0.gguf 等精确文件路径及字节大小。使用树 API 将量化标签转换为精确文件名。

搜索模式

直接使用以下 URL 格式：

https://huggingface.co/models?apps=llama.cpp&sort=trending
https://huggingface.co/models?search=<term>&apps=llama.cpp&sort=trending
https://huggingface.co/models?search=<term>&apps=llama.cpp&num_parameters=min:0,max:24B&sort=trending
https://huggingface.co/<repo>?local-app=llama.cpp
https://huggingface.co/api/models/<repo>/tree/main?recursive=true
https://huggingface.co/<repo>/tree/main

输出格式

回答发现类请求时，优先使用如下简洁的结构化结果：

Repo: <repo>
Recommended quant from HF: <label> (<size>)
llama-server: <command>
Other GGUFs:
- <filename> - <size>
- <filename> - <size>
Source URLs:
- <local-app URL>
- <tree API URL>

参考资料

• hub-discovery.md - 仅使用 URL 的 Hugging Face 工作流、搜索模式、GGUF 提取和命令重构
• advanced-usage.md — 推测解码、批量推理、语法约束生成、LoRA、多 GPU、自定义构建、基准测试脚本
• quantization.md — 量化质量权衡、Q4/Q5/Q6/IQ 的适用场景、模型大小扩展、imatrix
• server.md — 直接从 Hub 启动服务、OpenAI API 端点、Docker 部署、NGINX 负载均衡、监控
• optimization.md — CPU 线程、BLAS、GPU 卸载启发式方法、批次调优、基准测试
• troubleshooting.md — 安装／转换／量化／推理／服务问题、Apple Silicon、调试

资源

• GitHub：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
• 本地应用页面示例：https://huggingface.co/unsloth/Qwen3.6-35B-A3B-GGUF?local-app=llama.cpp
• 树 API 示例：https://huggingface.co/api/models/unsloth/Qwen3.6-35B-A3B-GGUF/tree/main?recursive=true
• llama.cpp 搜索示例：https://huggingface.co/models?num_parameters=min:0,max:24B&apps=llama.cpp&sort=trending
• 许可证：MIT