llama-cpp-python 本地部署入门

sleven fung2026-06-01 11:06

LLM应用系列文章目录

第一章 GeminiCLI与Repomix

第二章 MinerU与BabelDOC与KTransformers与OpenAI API库

第三章 应用工具之 MRKL 与零次学习

第四章 模型量化技术

第五章 llama-cpp-python 本地部署入门

文章目录

前言

本文主要整理 llama-cpp-python 相关内容，包括 LLaMA、GGML、GGUF、量化、本地运行模型、SafeTensors 转 GGUF、CPU/GPU 版本安装、远程模型与本地模型加载，以及 LangChain 中调用本地 GGML/GGUF 模型的方法。

llama-cpp-python

一、定义

1.LLaMA

  • LLaMA（Large Language Model Meta AI）是由Facebook的母公司Meta AI设计的一个新的大型语言模型。LLaMA拥有70亿到650亿个参数的模型集合，是目前最全面的语言模型之一。2023年2月24日，Meta向公众发布了LLaMA模型（我们现在用的都是泄露版）。

2.GGML

  • GGML（Grok Global Machine Learning）是一个用于机器学习的张量库，它只是一个C++库，允许在CPU或CPU + GPU上运行llm。
  • GGML定义了用于分发大型语言模型(llm)的二进制格式。
  • GGML使用了量化技术，允许大型语言模型在消费级别的硬件上运行。

3.量化（quant）

  • 模型的权重是浮点数。就像大整数(例如1000)比小整数(例如1)需要更多的空间一样，高精度浮点数(例如0.0001)比低精度浮点数(例如0.1)需要更多的空间。
  • 量化大型语言模型的过程涉及降低权重的精度，以减少使用模型所需的资源。GGML支持许多不同的量化策略(例如4位、5位和8位量化)，每种策略在效率和性能之间提供不同的权衡。
  • LLaMA量化后模型大小的对比：
Model Original size Quantized size(4-bit)
7B 13GB 3.9GB
13B 24GB 7.8GB
30B 60GB 19.5GB
65B 120GB 38.5GB

二、本地运行LlaMA模型

1.使用模型前，必须考虑有足够的内存和磁盘空间。

  • 运行存储在磁盘的模型，需要先完全加载到内存中。如果使用GPU，还需要将内存的模型加载到GPU显存中。
  • 所以不仅需要有足够的磁盘空间存储模型，还需要足够的RAM在执行期间加载。
  • 比如65B模型，即使在量化之后，也需要40GB的RAM。

2.为了在本地CPU上执行LLM，使用GGML格式的本地模型。可以直接从Hugging Face Models存储库下载bin文件。

  • GGML格式模型与Hugging Face使用Transformers读取的模型是不一样的。
  • 整一个GGML模型就是一个bin文件，不会分开多个文件存储。
  • GGML模型文件名称，如：llama-7b.ggmlv3.q4_0.bin
    • llama-7b为模型名称，权重参数数量。
    • ggmlv3为GGML模型，使用v3版本。
    • q4_0为量化策略。
  • 整一个GGUF模型就是一个gguf文件，不会分开多个文件存储。

3.GGML/GGUF格式的本地模型包含内容。

  • 模型权重（包括embedding层）
    • Token embedding层（用于将token映射为向量）
    • Transformer block（Self-Attention、MLP层等）
    • 输出头（通常是线性层映射到vocab）
    • 所有这些都是模型推理必需的部分
  • 模型结构信息
    • 模型层数（num_layers）
    • 隐藏维度（hidden_size）
    • 位置编码方式（RoPE or ALiBi）
    • vocab size、context size（ctx_len）等
  • 支持推理所需的全部内容
    • 推理必须要用的全部组件都包含在模型文件中，无需额外文件
    • 对于GGUF文件，还增加tokenizer配置、metadata，具备更好的自描述能力

三、GGML与llama-cpp-python

1.GGML是C++的一个张量库，需要使用Python调用C++接口（llama-cpp-python库）运行。

2.llama-cpp-python库是LLaMA.cpp的Python绑定，它在纯C/C++中充当LLaMA模型的推理。

3.cpp（C plus plus，即C++）的目标是使用4位整数量化来运行LLaMA模型，充分利用C/C++的速度优势和4位整数量化的优势。

4.llama.cpp支持的模型：LLaMA，Vicuna(Vicuna本质是基于LLaMA的增量改进)，Alpaca，GPT4All，Chinese LLaMA/Alpaca，Vigogne(French)，Koala，OpenBuddy(Multilingual)，Pygmalion7B/Metharme7B，WizardLM

5.理解：LLaMA模型一般是GGML/GGUF格式模型，需要使用C++/C语言来模型推理。如果需要使用python来模型推理，需要使用llama-cpp-python库，它提供一个python接口来运行C++来模型推理。

四、LLaMA与llama-cpp-python

1.LLaMA是模型，llama-cpp-python是用于运行LLaMA模型的工具库。

2.llama-cpp-python提供了一个Python接口，使得开发者可方便地加载、运行LLaMA模型，特别是在不依赖机器学习框架（如PyTorch）的情况下

3.LLaMA是由Meta提供的开源大模型，而llama-cpp-python是一个第三方项目，主要为LLaMA提供了更简便、优化的运行环境，专注于推理加速和资源优化，特别是在有限硬件上高效运行LLaMA模型。

五、GGUF与Transformers

1.GGUF模型是专为llama.cpp系列工具设计的，与Hugging Face的transformers框架没有直接关系。

2.Hugging Face的model hub允许上传任何格式的模型文件，包括.gguf。这并不等于Transformers库可以直接加载它。

六、GGUF与GGML

1.GGML库是一个为机器学习设计的张量库，目标是使大型模型能够在高性能的消费级硬件上运行。通过整数量化支持和内置优化算法实现。

2.GGUF（Grok Global Unifying Format）是由llama.cpp团队于2023年8月21日推出的一种新格式。GGUF是GGML的替代品，因为GGML已不再得到llama.cpp的支持。

3.一般情况下，只有GGUF模型才能在llama-cpp-python中使用GPU（如CUDA、Metal、OpenCL）。旧的GGML模型只能使用CPU。

4.GGUF优点：

  • GGUF是一种可扩展的、未来可维护的格式，可存储更多关于模型的元数据信息。
  • GGUF还包括显著改进的标记化代码，首次完全支持特殊标记。这将提高性能，特别是对于使用新特殊标记并实现自定义提示模板的模型而言。

七、GGUF/GGML模型与Meta AI（Facebook）

1.GGML格式是由llama.cpp团队之前开发的模型格式，用于支持LLaMA等模型的加载和推理。

2.GGUF格式是llama.cpp团队于2023年推出的新格式，目的替代GGML。

3.Meta AI仅开发了LLaMA模型。LLaMA是一个大规模的预训练语言模型。LLaMA是一个非常强大的生成型语言模型，以开放源代码的方式发布。

4.GGUF/GGML格式与Meta AI并没有直接的关联。而是，GGUF/GGML格式为LLaMA模型的高效使用提供的一种解决方案。

八、GGUF与GGML与GPTQ与AutoGPTQ

1.GPTQ属于训练后量化技术。

2.AutoGPTQ是GPTQ量化技术的一种实现，代码层面上的一个库。AutoGPTQ使用GPTQ量化技术，能够对模型进行量化压缩或者运行已量化的模型。

3.GGML是一个张量库，用于支持机器学习模型的高效执行。

4.GGML更多关注模型的执行效率，尤其是在硬件加速方面（如CPU和GPU的高效利用），并不专注于量化。

5.GGUF代替了GGML。

九、GGUF模型名称意义

1.GGUF模型名称量化标记

标记 含义
Q4_K_M 4-bit量化 + K-block 优化 + Medium 精度
Q6_K 6-bit量化 + K-block 优化
IQ2_XS Integer Quantized 2-bit量化 + Extra Small（极端压缩）
FP16 / BF16 未量化，保持半精度浮点
GGUF 新格式（替代GGML），兼容llama.cpp、text-generation-webui等框架

2.GGUF模型名称微调标记

  • Instruct：Instruct模型（或Instruction-tuned Model）是指经过指令微调的模型。这类模型通过专门的训练方式，使其能够更好地理解和遵循人类指令（instructions），从而生成更符合用户需求的响应。
  • Base：Base模型（基座模型）指未经额外任务微调（如指令微调、RLHF等）的预训练大语言模型（Pretrained Language Model, PLM）。它是大模型技术栈的底层基础，后续需要通过微调后才能适配不同任务（如对话、编程、翻译等）。

3.示例

  • 模型名：Kimi-K2-Instruct-UD-IQ1_M-00001-of-00007.gguf
    • Kimi-K2：模型的基础名称/系列名，由开发者或机构定义的模型，比如属于Moonshot/Kimi系列。
    • Instruct：表示指令微调模型（Instruct-tuned），适合对话或指令跟随任务
    • UD：多为定制用途缩写，可能表示UltraDense或User Defined或其他开发者定义的缩写，需要具体项目说明。
    • IQ1_M：量化方式说明。IQ = Integer Quantization。IQ1_M可能表示中等精度的INT1量化+中等保留矩阵精度（M = medium）。
    • 00001-of-00007：表示分片模型文件的第1个部分，共7个分片。完整模型需要加载7个.gguf文件。
    • .gguf：表示GGUF（GPT Graph Unified Format）格式模型。
  • 模型名：LLaMA2-13B-Base-Q4_K_M-00003-of-00007.gguf
    • 一个LLaMA2模型，13B参数量，基座模型，使用Q4_K_M量化方式，被分成了7个片段，这是第3个。

十、SafeTensors模型转换为GGUF格式模型

1.下载llama.cpp转换包：

bash 复制代码 
git clone https://github.com/ggerganov/llama.cpp.git

2.创建python虚拟环境，并进入：conda create -n myenv python=3.10

3.安装依赖包：pip install -r requirements.txt

4.下载SafeTensors模型文件

  • 模型包括三种文件：model.safetensors，config.json，tokenizer.json

5.执行转换脚本

  • 使用python执行convert_hf_to_gguf.py来执行转换。
  • 第一个参数为源safetensors模型目录，--outfile为生成的模型存放目录
  • 示例：
bash 复制代码 
python convert_hf_to_gguf.py "F:\model\safetensors\qwen2.5" --outtype f16 --verbose --outfile "F:\model\gguf\hg_models"

十一、安装CPU版本的llama-cpp-python

1.安装方式：pip install llama-cpp-python

2.提示错误

  • 报错内容：
bash 复制代码 
  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for llama-cpp-python
Failed to build llama-cpp-python
ERROR: ERROR: Failed to build installable wheels for some pyproject.toml based projects (llama-cpp-python)
  • 原因：Centos7需要使用gcc的12版本（或者11版本??），低版本不可以。Ubuntu需要安装9.4版本（建议使用Ubuntu。Centos安装gcc很复杂，并且有可能不起作用）。安装方式可以参考Linux文章的《linux结构与命令》章节。
  • 或者指定版本安装：pip install --no-cache-dir llama-cpp-python==0.2.77

十二、GPU运行llama-cpp-python加载GGUF模型

1.主要针对Ubuntu系统。

2.环境

  • Ubuntu工具
    • 安装gcc：安装方式可参考Linux文章的《linux结构与命令》章节
    • 安装其他依赖
bash 复制代码 
sudo apt update
sudo apt install -y build-essential cmake python3-dev
sudo apt install -y libopenblas-dev
sudo apt install -y libgomp1 libpthread-stubs0-dev libc6-dev
  • conda环境
    • 安装环境：conda create -n llamacpp python=3.12
    • 安装依赖：pip install wheel setuptools cmake ninja
    • 安装huggingface hub用于当需要下载时，自动从hf中下载：
bash 复制代码 
pip install huggingface-hub

3.安装GPU版本的llama-cpp-python

  • 设置环境变量，如果.bashrc有可以不设置
bash 复制代码 
export CUDA_HOME=/usr/local/cuda-12.8
  • 安装llama-cpp-python
bash 复制代码 
CMAKE_ARGS="-DGGML_CUDA=on" FORCE_CMAKE=1 pip install llama-cpp-python --force-reinstall --no-cache-dir
  • 报错：
    • 报错内容：

代码

bash 复制代码 
      FAILED: vendor/llama.cpp/tools/mtmd/llama-mtmd-cli
      : && /usr/bin/g++  -pthread -B /root/miniconda3/envs/llamacpp3/compiler_compat -O3 -DNDEBUG  vendor/llama.cpp/tools/mtmd/CMakeFiles/llama-mtmd-cli.dir/mtmd-cli.cpp.o -o vendor/llama.cpp/tools/mtmd/llama-mtmd-cli  -Wl,-rpath,/tmp/tmp2wvqjvnq/build/vendor/llama.cpp/tools/mtmd:/tmp/tmp2wvqjvnq/build/bin:  vendor/llama.cpp/common/libcommon.a  vendor/llama.cpp/tools/mtmd/libmtmd.so  bin/libllama.so  bin/libggml.so  bin/libggml-cpu.so  bin/libggml-cuda.so  bin/libggml-base.so  /usr/local/cuda-12.8/targets/x86_64-linux/lib/stubs/libcuda.so && :
      /root/miniconda3/envs/llamacpp3/compiler_compat/ld: warning: libgomp.so.1, needed by bin/libggml-cpu.so, not found (try using -rpath or -rpath-link)
      /root/miniconda3/envs/llamacpp3/compiler_compat/ld: warning: libdl.so.2, needed by /usr/local/cuda-12.8/lib64/libcudart.so.12, not found (try using -rpath or -rpath-link)
      /root/miniconda3/envs/llamacpp3/compiler_compat/ld: warning: libpthread.so.0, needed by /usr/local/cuda-12.8/lib64/libcudart.so.12, not found (try using -rpath or -rpath-link)
      /root/miniconda3/envs/llamacpp3/compiler_compat/ld: warning: librt.so.1, needed by /usr/local/cuda-12.8/lib64/libcudart.so.12, not found (try using -rpath or -rpath-link)
      /root/miniconda3/envs/llamacpp3/compiler_compat/ld: bin/libggml-cpu.so: undefined reference to GOMP_barrier@GOMP_1.0'
      /root/miniconda3/envs/llamacpp3/compiler_compat/ld: bin/libggml-cpu.so: undefined reference to GOMP_parallel@GOMP_4.0'
      /root/miniconda3/envs/llamacpp3/compiler_compat/ld: bin/libggml-cpu.so: undefined reference to omp_get_thread_num@OMP_1.0'
      /root/miniconda3/envs/llamacpp3/compiler_compat/ld: bin/libggml-cpu.so: undefined reference to GOMP_single_start@GOMP_1.0'
      /root/miniconda3/envs/llamacpp3/compiler_compat/ld: bin/libggml-cpu.so: undefined reference to omp_get_num_threads@OMP_1.0'
      collect2: error: ld returned 1 exit status
      ninja: build stopped: subcommand failed.
      
      
      *** CMake build failed
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for llama-cpp-python
Failed to build llama-cpp-python
ERROR: Failed to build installable wheels for some pyproject.toml based projects (llama-cpp-python)
  • 原因：链接失败（Linker Error），缺少一些系统库（如libgomp.so.1）导致llama-cpp-python编译失败。提示中，链接失败到这个路径了：/root/miniconda3/envs/llamacpp3/compiler_compat/ld
  • 解决：需要指定正确的链接器地址（可用g++或conda自带）安装
    • 可以设置环境变量强制使用系统工具链g++
bash 复制代码 
export CC=/usr/bin/gcc
export CXX=/usr/bin/g++
复制代码 
- 或者用conda-forge提供的工具链（推荐）
bash 复制代码 
conda install -c conda-forge compilers
  • 重装llama-cpp-python
bash 复制代码 
CMAKE_ARGS="-DGGML_CUDA=on" FORCE_CMAKE=1 pip install llama-cpp-python --force-reinstall --no-cache-dir

4.使用远程模型

  • 使用Llama.from_pretrained()方法，从Hugging Face下载GGUF格式的量化模型，并加载。返回模型对象。参数
    • repo_id：Hugging Face上模型仓库的ID，格式通常是作者名/模型名，如："MaziyarPanahi/Qwen3-4B-GGUF"。（必填）
    • filename：要加载的GGUF文件名。在仓库中使用的具体模型文件，如："Qwen3-4B.Q3_K_L.gguf"。（必填）
    • local_dir：模型将被下载（或从缓存中解压）到的本地目录。首次会从Hugging Face下载到此目录；若已存在，就从本地加载而不是再下载。
    • cache_dir：定义从Hugging Face下载的模型存储的目录。默认是 ~/.cache/huggingface/hub。
  • 返回模型对象后，使用create_chat_completion()方法，做聊天模式的推理。参数：
    • messages：聊天对话历史列表。列表每个元素为一个字典，包含role（角色）和content（内容）。
    • temperature：控制输出的多样性。取值范围为0.0～2.0，越低越确定，越高越发散。
    • max_tokens ：最大生成的token数。默认值依模型设置而定。
    • top_p：float，nucleus sampling中的保留概率阈值（默认1.0），越小越保守。
    • stop：设置生成的停止词（stop words），格式Liststr，遇到这些词时提前停止生成。
    • stream：是否启用流式输出（类似OpenAI流式响应）。默认False。

代码

bash 复制代码 
from llama_cpp import Llama

llm = Llama.from_pretrained(
    repo_id="MaziyarPanahi/Qwen3-4B-GGUF",
    filename="Qwen3-4B.Q3_K_L.gguf",
    local_dir="/opt/llamacpp",
)

res = llm.create_chat_completion(
    messages=[{"role": "user", "content": "法国首都是哪里？"}]
)
print(res)

5.使用本地模型

  • 使用Llama()方法，加载本地GGUF模型。返回模型对象。参数
    • model_path：GGUF模型的本地路径（.gguf 文件）。（必填）
    • n_gpu_layers：启用GPU加速的层数：
      • -1 表示所有层都在GPU上执行（推荐有显卡的系统）；
      • 0 表示完全CPU推理（默认）；
      • N 表示前N层在GPU上，后面在CPU。
    • n_ctx：最大上下文窗口长度（token 数），默认512，可改为2048、4096甚至更大（取决于模型训练时的上下文上限）。
    • n_threads：使用的CPU线程数，默认等于核心数），也可以手动设定，如n_threads=8。
    • chat_format：聊天模板格式（用于create_chat_completion）。常见值："llama-2", "qwen", "chatml" 等。自动识别自GGUF meta。
    • verbose：是否打印调试信息（默认False）。
    • seed：设置随机种子，保证可重复性。默认0
    • f16_kv：是否使用float16 KV-cache，减少显存/内存占用（大部分模型默认支持）。默认True
    • low_vram：是否使用low_vram，减少GPU 占用，适合低显存显卡。
    • use_mmap：是否内存映射加载模型（默认True更节省内存，启动稍慢）。
    • use_mlock：是否防止模型被swap出内存。默认False
  • 返回模型对象后，使用create_chat_completion()方法，做聊天模式的推理。

代码

bash 复制代码 
from llama_cpp import Llama

llm = Llama(
   model_path="/opt/models/Qwen3-4B.Q3_K_L.gguf",
   n_gpu_layers=-1,
)

res = llm.create_chat_completion(
    messages=[{"role": "user", "content": "法国首都是哪里？"}]
)
print(res["choices"][0]["message"]["content"])

结果

text 复制代码 
<think>
嗯，用户问的是法国的首都是哪里。首先，我需要确认这个问题的答案是否正确。法国的首都是巴黎，对吧？不过，可能用户会有疑问，因为有时候可能会有混淆，比如法国的某些地区可能有不同的行政中心，但通常来说，巴黎确实是法国的首都。
...
总结一下，法国的首都是巴黎，位于法兰西岛大区，是法国的政治、经济和文化中心，拥有独特的法律地位和历史意义。需要确认这个答案的正确性，并且解释清楚，避免混淆其他城市。
</think>

法国的首都是**巴黎**（Paris）。  
巴黎位于法国北部的法兰西岛大区，是法国的政治、经济、文化中心，也是全球最著名的城市之一。它不仅是法国的首都，还拥有独特的法律地位，例如：  
- **行政首都**：巴黎是法国的行政首都，法国政府、议会（如国民议会和参议院）以及许多国家机构均设于此。  
- **历史与文化中心**：巴黎拥有丰富的历史遗产

6.LangChain运行本地GGML/GGUF格式模型。

  • 使用LlamaCpp()运行本地模型文件返回模型对象。如：
bash 复制代码 
llm = LlamaCpp(model_path="./models/llama-7b.ggmlv3.q4_0.bin")
  • 因为模型文件包含了embedding层，所以可以使用LlamaCppEmbeddings()运行本地模型文件，返回embedding模型对象。
bash 复制代码 
embeddings = LlamaCppEmbeddings(model_path="models/llama-7b.ggmlv3.q4_0.bin")
  • 简易使用可参考《LangChain》的llm模型调用部分。

总结

本文整理了 llama-cpp-python 的基础概念与使用方式，重点说明了 LLaMA、GGML、GGUF、量化模型文件、本地模型运行条件、CPU/GPU 安装方式，以及通过 Llama.from_pretrained()、Llama() 和 LangChain 的 LlamaCpp/LlamaCppEmbeddings 调用本地模型的方法。实际使用时，需要重点关注模型格式、量化精度、内存/显存大小、CUDA 与编译工具链版本，避免安装或推理时出现依赖、编译和资源不足问题。

相关推荐
我叫袁小陌1 小时前
数据结构详解与算法关联指南
算法
头歌实践平台1 小时前
C++面向对象 - 运算符重载的应用
开发语言·c++·算法
福大大架构师每日一题1 小时前
rust 1.96.0 更新：语言、编译器、Cargo、Rustdoc、兼容性全面升级，必看完整解读
android·开发语言·rust
思麟呀1 小时前
C++11并发编程：互斥锁
linux·开发语言·c++·windows
li星野1 小时前
RAG优化系列：基于用户反馈的检索权重调整（Feedback Loop）——让系统越用越聪明
python·学习
特立独行的猫a1 小时前
鸿蒙 PC 平台 Python 第三方库移植全景指南
python·华为·harmonyos·三方库移植·鸿蒙pc
晚风予卿云月1 小时前
《二分答案》算法练习
数据结构·c++·算法·二分·竞赛·算法随笔
郭涤生1 小时前
C++ 各类数据的内存分区与读写性能详解
开发语言·c++
Pluchon1 小时前
萌萌技术分享笔记——Java综合项目
java·开发语言·笔记·git·github·mybatis·postman
热门推荐
01GitHub 镜像站点02【AI】2026 年具身智能模型和世界模型总结03【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法042026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf05Codex 接入 DeepSeek API 完整配置文档06DeepSeek V4 + Claude Code thinking mode 400 错误修复方案07裂开！ChatGPT 居然开始要手机号验证，附详细解决方法08CC-Switch & Claude 基于 Linux 服务器安装使用指南09几个好用的ip纯净度检测网站10API Key 登录 Codex 也能用插件了，还支持会话删除和导出