跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客我的书AI学习GitHub 精选镜像AI工具UI配色美学关于
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
PythonAI算法

llama-cpp-python 完整安装与配置指南

介绍 llama-cpp-python 的安装与配置方法。支持通过 pip 直接安装源码或预构建轮子。提供 CUDA、Metal 及 OpenBLAS 硬件加速配置方案。涵盖 Windows 与 MacOS 常见错误解决,以及开发环境搭建。包含高级 API 调用示例,如文本生成与聊天完成功能,帮助开发者快速在本地部署大语言模型。

开源信徒发布于 2026/4/6更新于 2026/10/24115 浏览

基础安装:一键搞定

llama-cpp-python 的安装过程极其简单,只需运行以下命令:

pip install llama-cpp-python 

这个命令会自动从源码构建 llama.cpp,并将其与 Python 包一起安装。如果遇到构建问题,可以添加 --verbose 参数查看详细构建日志。

硬件加速配置方案

为了获得最佳性能表现,您可以根据自己的硬件配置选择合适的加速后端。

CUDA 加速配置(NVIDIA 显卡用户)
CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python 
Metal 加速配置(苹果设备用户)
CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python 
OpenBLAS 加速配置(CPU 优化方案)
CMAKE_ARGS="-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS" pip install llama-cpp-python 

预构建轮子安装方法

如果您不想从源码编译,可以使用预构建的二进制轮子进行快速安装。

基础 CPU 版本
pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu 
CUDA 加速版本
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 系统安装问题

如果在 Windows 系统上遇到'找不到 nmake'或 CMAKE_C_COMPILER 相关错误,可以设置以下环境变量:

$env:CMAKE_GENERATOR = "MinGW Makefiles"
$env:CMAKE_ARGS = 
"-DGGML_OPENBLAS=on -DCMAKE_C_COMPILER=C:/w64devkit/bin/gcc.exe"
MacOS 系统注意事项

苹果 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]'

核心功能模块介绍

高级 API 使用示例

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": "今天天气怎么样?"}
    ]
)

目录

  1. 基础安装:一键搞定
  2. 硬件加速配置方案
  3. CUDA 加速配置(NVIDIA 显卡用户)
  4. Metal 加速配置(苹果设备用户)
  5. OpenBLAS 加速配置(CPU 优化方案)
  6. 预构建轮子安装方法
  7. 基础 CPU 版本
  8. CUDA 加速版本
  9. 快速验证安装结果
  10. 初始化模型(请替换为实际模型路径)
  11. 进行简单的文本生成测试
  12. 常见安装问题解决方案
  13. Windows 系统安装问题
  14. MacOS 系统注意事项
  15. 开发环境搭建指南
  16. 升级 pip 以确保兼容性
  17. 以可编辑模式安装
  18. 安装服务器功能(可选)
  19. 核心功能模块介绍
  20. 高级 API 使用示例
  21. 初始化模型并设置参数
  22. 创建文本补全
  23. 聊天完成功能
  24. 创建聊天完成

更多推荐文章

查看全部
  • go-zero 框架下随机图形验证码 API 接口实现
  • 智能梯控系统设计方案:跨品牌群控与 AI 调度架构解析
  • 大模型技术对汽车行业的影响与变革
  • 网络安全工程师职业定义、核心技能与认证体系详解
  • MySQL 数据库 Windows 免安装版配置与使用教程
  • Net-NTLMv2 哈希的捕获与破解
  • LLM 常见归一化方法解析:LayerNorm、RMSNorm 与 DeepNorm
  • JavaAI 插件在 IntelliJ IDEA 中的安装与使用指南
  • AI 大模型应用开发指南:传统开发者转型路径
  • Nginx 高可用方案:基于 Keepalived 的双机热备实战
  • Stable Diffusion 秋叶整合包本地安装与使用指南
  • 2024 年大模型行业应用十大典范案例解析
  • 昇腾 NPU 部署 Llama 2 模型:性能测试与实战优化
  • 双延迟深度确定性策略梯度算法 (TD3) 详解
  • Windows 程序启动失败:Visual C++ 运行库缺失修复方案
  • 双指针算法专题二:三角形个数与多数之和
  • DeepSeek-R1 大模型基于 MS-Swift 框架的部署、推理与微调实践
  • Neo4j 图数据库核心概念与在线控制台实战
  • 32 岁,八年程序员的互联网中年危机与转型思考
  • 二分查找实战:旋转数组最小值与缺失数字查找

相关免费在线工具

  • 加密/解密文本

    使用加密算法(如AES、TripleDES、Rabbit或RC4)加密和解密文本明文。 在线工具,加密/解密文本在线工具,online

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online

  • 随机西班牙地址生成器

    随机生成西班牙地址(支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选),支持数量快捷选择、显示全部与下载。 在线工具,随机西班牙地址生成器在线工具,online

  • Gemini 图片去水印

    基于开源反向 Alpha 混合算法去除 Gemini/Nano Banana 图片水印,支持批量处理与下载。 在线工具,Gemini 图片去水印在线工具,online

  • curl 转代码

    解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具,curl 转代码在线工具,online