llama-cpp-python使用教程
以下是 llama-cpp-python 的完整使用教程，涵盖安装、基础用法、高级功能（如GPU加速、多模态等）和常见问题解决。
1. 安装
1.1 基础安装（CPU版）
pip install llama-cpp-python -i https://pypi.tuna.tsinghua.edu.cn/simple1.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++-115.3 性能优化
CPU绑定：设置
n_threads
为物理核心数（非超线程）。
批处理：通过
n_batch
参数调整（默认512）：
llm = Llama(..., n_batch=1024)