llama.cpp 本地推理

llama.cpp 本地 GGUF 推理 + HF Hub 模型发现

llama.cpp + GGUF

使用场景

模型发现工作流

优先使用 URL 工作流，再考虑 hf、Python 或自定义脚本。

快速入门

安装 llama.cpp

# macOS / Linux（最简）
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 加载全部到 GPU
    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",   # 或 "chatml"、"mistral" 等
)

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"])

# 流式输出
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 页面指定的量化，其次参考通用启发式。

从仓库提取可用 GGUF

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

忽略（除非用户要求）：

使用 tree API：

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

Repo: 
Recommended quant from HF:  ()
llama-server: 
Other GGUFs:
-  - 
-  - 
Source URLs:
- 
- 

资源