llama-cpp-python使用教程

以下是 llama-cpp-python 的完整使用教程，涵盖安装、基础用法、高级功能（如GPU加速、多模态等）和常见问题解决。

1. 安装

1.1 基础安装（CPU版）

pip install llama-cpp-python -i https://pypi.tuna.tsinghua.edu.cn/simple

1.2 启用GPU加速（CUDA）

CMAKE_ARGS="-DGGML_CUDA=ON" pip install llama-cpp-python --force-reinstall --no-cache-dir

注意：需提前安装 CUDA Toolkit 和匹配的 NVIDIA 驱动。

1.3 其他后端支持

| 参数                | 用途                     | 示例命令                                                                 |
|---------------------|--------------------------|--------------------------------------------------------------------------|
| -DGGML_OPENBLAS=ON | OpenBLAS加速（CPU）      | CMAKE_ARGS="-DGGML_OPENBLAS=ON" pip install...| -DGGML_METAL=ON    | Apple Metal（M1/M2 GPU） | CMAKE_ARGS="-DGGML_METAL=ON" pip install...

2. 基础用法

2.1 加载模型

from llama_cpp import Llama# 加载GGUF格式模型（需提前下载）
llm = Llama(model_path="mistral-7b-instruct-v0.1.Q4_K_M.gguf",  # 模型路径n_ctx=2048,  # 上下文长度n_threads=8  # CPU线程数
)

2.2 文本生成

output = llm.create_completion(prompt="Python如何读取文件？",max_tokens=100,  # 生成的最大token数temperature=0.8,  # 随机性（0-1，越高越随机）stop=["\n", "。"]  # 停止符号
)
print(output["choices"][0]["text"])

2.3 对话模式

response = llm.create_chat_completion(messages=[{"role": "system", "content": "你是一个编程助手"},{"role": "user", "content": "如何用Python写一个HTTP服务器？"}]
)
print(response["choices"][0]["message"]["content"])

3. 高级功能

3.1 GPU加速

llm = Llama(model_path="llama-2-7b.Q5_K_M.gguf",n_gpu_layers=20,  # 使用GPU计算的层数（越大显存占用越高）n_threads=4      # CPU线程数（与GPU配合）
)

3.2 多模态（图片+文本）

需安装 llava 分支的模型（如 llava-v1.5-7b-Q4_K.gguf）：from llama_cpp import Llama, LlamaVAModel# 加载多模态模型
llava = LlamaVAModel(clip_model_path="llava-v1.5-7b-mmproj-Q4_K.gguf",llm_model_path="llava-v1.5-7b-Q4_K.gguf"
)
# 图片描述生成
response = llava.create_image_completion(image_path="cat.jpg",prompt="描述这张图片的内容"
)

3.3 流式输出

stream = llm.create_completion(prompt="写一篇关于AI的文章",stream=True  # 启用流式
)for chunk in stream:print(chunk["choices"][0]["text"], end="", flush=True)

4. 实用技巧

4.1 模型量化

使用 llama.cpp 量化原始模型（节省显存/内存）：./quantize ./models/llama-2-7b.gguf ./models/llama-2-7b-Q4_K_M.gguf Q4_K_M常用量化等级：
| 等级     | 显存占用 | 质量 |
|----------|---------|------|
| Q2_K   | 极小     | 低   |
| Q4_K_M | 中等     | 推荐 |
| Q5_K_M | 较大     | 高   |

4.2 显存优化

控制GPU层数：
n_gpu_layers根据显存调整（7B模型约需20层+8GB显存）。启用内存映射：减少内存占用：
llm = Llama(model_path="...", use_mmap=True)

5. 常见问题

5.1 报错 

CUDA not found确认 
nvcc --version能正常运行。重新安装时指定CUDA路径：
CMAKE_ARGS="-DGGML_CUDA=ON -DCMAKE_CUDA_COMPILER=/usr/local/cuda/bin/nvcc" pip install...

5.2 报错 

GLIBCXX not found升级GCC：
sudo apt install gcc-11 g++-11
export CC=/usr/bin/gcc-11 CXX=/usr/bin/g++-11

5.3 性能优化

CPU绑定：设置 
n_threads为物理核心数（非超线程）。批处理：通过 
n_batch参数调整（默认512）：
llm = Llama(..., n_batch=1024)