Llama Cpp

llama.cpp 本地 GGUF 推理 + Hugging Face Hub 模型發現。

技能元數據


來源	捆綁（默認安裝）
路徑	`skills/mlops/inference/llama-cpp`
版本	`2.1.2`
作者	Orchestra Research
許可證	MIT
依賴項	`llama-cpp-python>=0.2.0`
標籤	`llama.cpp`, `GGUF`, `Quantization`, `Hugging Face Hub`, `CPU Inference`, `Apple Silicon`, `Edge Deployment`, `AMD GPUs`, `Intel GPUs`, `NVIDIA`, `URL-first`

參考：完整 SKILL.md

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理看到的指令。

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 變體之間做出選擇

模型發現工作流

在請求 hf、Python 或自定義腳本之前，優先使用 URL 工作流。

在 Hub 上搜索候選倉庫：
- 基礎鏈接：https://huggingface.co/models?apps=llama.cpp&sort=trending
- 添加 search=<term> 以搜索特定模型系列
- 當用戶有大小限制時，添加 num_parameters=min:0,max:24B 或類似參數
使用 llama.cpp 本地應用視圖打開倉庫：
- https://huggingface.co/<repo>?local-app=llama.cpp
當本地應用片段可見時，將其視為事實來源：
- 複製確切的 llama-server 或 llama-cli 命令
- 準確報告 HF 顯示的推薦量化版本
將相同的 ?local-app=llama.cpp URL 作為頁面文本或 HTML 讀取，並提取 Hardware compatibility（硬件兼容性）下的部分：
- 優先使用其確切的量化標籤和大小，而非通用表格
- 保留倉庫特定的標籤，如 UD-Q4_K_M 或 IQ4_NL_XL
- 如果在該獲取的頁面源代碼中不可見該部分，請說明情況並回退到 tree API 加上通用量化指導
查詢 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 作為人工備用方案
如果本地應用片段在文本中不可見，則根據倉庫和所選量化重建命令：
- 簡寫量化選擇：llama-server -hf <repo>:<QUANT>
- 精確文件回退：llama-server --hf-repo <repo> --hf-file <filename.gguf>
僅當倉庫尚未暴露 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 blob 或校準 artifacts

在此步驟中使用 tree API：

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

對於像 unsloth/Qwen3.6-35B-A3B-GGUF 這樣的倉庫，local-app 頁面可以顯示量化芯片（quant chips），例如 UD-Q4_K_M、UD-Q5_K_M、UD-Q6_K 和 Q8_0，而 tree API 則暴露帶有字節大小的確切文件路徑，例如 Qwen3.6-35B-A3B-UD-Q4_K_M.gguf 和 Qwen3.6-35B-A3B-Q8_0.gguf。使用 tree 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
示例 local-app 頁面: https://huggingface.co/unsloth/Qwen3.6-35B-A3B-GGUF?local-app=llama.cpp
示例 tree 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

技能元數據​

參考：完整 SKILL.md​

llama.cpp + GGUF

何時使用​

模型發現工作流​

快速開始​

安裝 llama.cpp​

直接從 Hugging Face Hub 運行​

從 Hub 運行確切的 GGUF 文件​

OpenAI 兼容服務器檢查​

Python 綁定 (llama-cpp-python)​

基本生成​

聊天 + 流式傳輸​

嵌入​

選擇量化​

從倉庫中提取可用的 GGUF​

搜索模式​

輸出格式​

參考資料​

資源​