llama-cpp-python 的安装与配置流程。支持通过 pip 直接安装源码构建，或指定 CMAKE_ARGS 启用 CUDA、Metal 及 OpenBLAS 硬件加速。提供预构建轮子安装方案以简化流程。内容涵盖 Windows 和 MacOS 常见错误解决、开发环境搭建、高级 API 调用示例（文本生成与聊天完成）以及性能优化建议。旨在帮助用户快速在本地部署大型语言模型应用。
本文介绍 llama-cpp-python 的安装配置方法。作为 llama.cpp 的 Python 绑定库，它提供了简单易用的 AI 开发体验。
llama-cpp-python 的安装过程简单，只需运行以下命令：
pip install llama-cpp-python
该命令会自动从源码构建 llama.cpp。如果遇到构建问题，可以添加 参数查看详细日志。
--verbose为了获得最佳性能表现，您可以根据自己的硬件配置选择合适的加速后端。
CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python
CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python
CMAKE_ARGS="-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS" pip install llama-cpp-python
如果您不想从源码编译，可以使用预构建的二进制轮子进行快速安装。
pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121
安装完成后，您可以通过创建一个简单的测试脚本来验证安装是否成功：
from llama_cpp import Llama
# 初始化模型（请替换为实际模型路径）
llm = Llama(model_path="./models/your-model.gguf")
# 进行简单的文本生成测试
output = llm("你好，请介绍一下你自己", max_tokens=32)
print(output)
如果在 Windows 系统上遇到'找不到 nmake'或 CMAKE_C_COMPILER 相关错误，可以设置以下环境变量：
$env:CMAKE_GENERATOR = "MinGW Makefiles"
$env:CMAKE_ARGS = "-DGGML_OPENBLAS=on -DCMAKE_C_COMPILER=C:/w64devkit/bin/gcc.exe"
苹果 M 系列芯片用户务必安装 ARM64 版本的 Python，否则性能会大幅下降。
如果您想要参与项目开发或进行定制化修改，可以按照以下步骤搭建开发环境：
git clone --recurse-submodules https://github.com/abetlen/llama-cpp-python
cd llama-cpp-python
# 升级 pip 以确保兼容性
pip install --upgrade pip
# 以可编辑模式安装
pip install -e .
# 安装服务器功能（可选）
pip install -e '.[server]'
llama-cpp-python 提供了简单易用的高级 API 接口：
from llama_cpp import Llama
# 初始化模型并设置参数
llm = Llama(
model_path="./models/7B/llama-model.gguf",
n_ctx=2048, # 设置上下文窗口大小
n_gpu_layers=-1, # 启用 GPU 加速
seed=1337 # 设置随机种子
)
# 创建文本补全
response = llm.create_completion(
prompt="请解释什么是人工智能",
max_tokens=100,
temperature=0.7
)
# 创建聊天完成
chat_response = llm.create_chat_completion(
messages=[
{"role": "system", "content": "你是一个乐于助人的 AI 助手"},
{"role": "user", "content": "今天天气怎么样？"}
]
)
项目中提供了丰富的示例代码和实用工具：
完成基础安装后，您可以进一步探索：
现在您已经掌握了 llama-cpp-python 的完整安装配置方法，可以开始构建自己的 AI 应用了！
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online