llama.cpp 的 Python 绑定

@ggerganov 的 llama.cpp 库的简单 Python 绑定。 本包提供：

• 通过 ctypes 接口访问 C API 的低层访问。
• 用于文本补全的高层 Python API
  • OpenAI 风格的 API
  • LangChain 兼容性
  • LlamaIndex 兼容性
• OpenAI 兼容的 Web 服务器
  • 本地 Copilot 替代品
  • Function Calling 支持
  • Vision API 支持
  • 多模型支持

文档可在 https://llama-cpp-python.readthedocs.io/en/latest 获取。

安装

要求：

• Python 3.8+
• C 编译器
  • Linux: gcc 或 clang
  • Windows: Visual Studio 或 MinGW
  • MacOS: Xcode

要安装该包，请运行：

pip install llama-cpp-python

这还将从源码构建 llama.cpp 并将其与此 Python 包一起安装。

如果此操作失败，请将 --verbose 添加到 pip install 以查看完整的 cmake 构建日志。

预构建 Wheel（新）

也可以安装带有基本 CPU 支持的预构建 wheel。

pip install llama-cpp-python \
  --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu

安装配置

llama.cpp 支持多种硬件加速后端以加速推理，以及后端特定的选项。完整的列表请参阅 llama.cpp README。

所有 llama.cpp cmake 构建选项均可通过 CMAKE_ARGS 环境变量或在安装时通过 --config-settings / -C cli 标志进行设置。

# Linux and Mac
CMAKE_ARGS="-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS" \
  pip install llama-cpp-python

# Windows
$env:CMAKE_ARGS = "-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS"
pip install llama-cpp-python

pip install --upgrade pip # ensure pip is up to date
pip install llama-cpp-python \
  -C cmake.args="-DGGML_BLAS=ON;-DGGML_BLAS_VENDOR=OpenBLAS"

# requirements.txt

llama-cpp-python -C cmake.args="-DGGML_BLAS=ON;-DGGML_BLAS_VENDOR=OpenBLAS"

支持的后端

以下是一些常见后端、它们的构建命令以及所需的额外环境变量。

CMAKE_ARGS="-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS" pip install llama-cpp-python

CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python

pip install llama-cpp-python \
  --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/<cuda-version>

pip install llama-cpp-python \
  --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121

CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python

pip install llama-cpp-python \
  --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/metal

CMAKE_ARGS="-DGGML_HIP=on" pip install llama-cpp-python

pip install llama-cpp-python \
  --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/rocm72

pip install llama-cpp-python `
  --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/hip-radeon

CMAKE_ARGS="-DGGML_VULKAN=on" pip install llama-cpp-python

pip install llama-cpp-python \
  --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/vulkan

source /opt/intel/oneapi/setvars.sh   
CMAKE_ARGS="-DGGML_SYCL=on -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx" pip install llama-cpp-python

source /opt/intel/oneapi/setvars.sh   
CMAKE_ARGS="-DGGML_RPC=on" pip install llama-cpp-python

Windows 注意事项

$env:CMAKE_GENERATOR = "MinGW Makefiles"
$env:CMAKE_ARGS = "-DGGML_OPENBLAS=on -DCMAKE_C_COMPILER=C:/w64devkit/bin/gcc.exe -DCMAKE_CXX_COMPILER=C:/w64devkit/bin/g++.exe"

MacOS 说明

详细的 MacOS Metal GPU 安装文档可在 docs/install/macos.md 处获取

wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh
bash Miniforge3-MacOSX-arm64.sh

CMAKE_ARGS="-DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_APPLE_SILICON_PROCESSOR=arm64 -DGGML_METAL=on" pip install --upgrade --verbose --force-reinstall --no-cache-dir llama-cpp-python

升级与重新安装

要升级并重新构建 llama-cpp-python，请在 pip install 命令中添加 --upgrade --force-reinstall --no-cache-dir 标志，以确保从源代码重新构建该包。

高级 API

API 参考

高级 API 通过 Llama 类提供了一个简单的托管接口。

下面是一个简短的示例，演示如何使用高级 API 进行基本的文本补全：

from llama_cpp import Llama

llm = Llama(
      model_path="./models/7B/llama-model.gguf",
      # n_gpu_layers=-1, # Uncomment to use GPU acceleration
      # seed=1337, # Uncomment to set a specific seed
      # n_ctx=2048, # Uncomment to increase the context window
)
output = llm(
      "Q: Name the planets in the solar system? A: ", # Prompt
      max_tokens=32, # Generate up to 32 tokens, set to None to generate up to the end of the context window
      stop=["Q:", "\n"], # Stop generating just before the model would generate a new question
      echo=True # Echo the prompt back in the output
) # Generate a completion, can also call create_completion
print(output)

默认情况下，llama-cpp-python 以 OpenAI 兼容格式生成补全：

{
  "id": "cmpl-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "object": "text_completion",
  "created": 1679561337,
  "model": "./models/7B/llama-model.gguf",
  "choices": [
    {
      "text": "Q: Name the planets in the solar system? A: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune and Pluto.",
      "index": 0,
      "logprobs": None,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 28,
    "total_tokens": 42
  }
}

文本补全功能可通过 Llama 类的 __call__ 和 create_completion 方法实现。

从 Hugging Face Hub 拉取模型

您可以使用 from_pretrained 方法直接从 Hugging Face 下载 gguf 格式的 Llama 模型。 要使用此功能，您需要安装 huggingface-hub 包（pip install huggingface-hub）。

llm = Llama.from_pretrained(
    repo_id="lmstudio-community/Qwen3.5-0.8B-GGUF",
    filename="*Q8_0.gguf",
    verbose=False
)

默认情况下 from_pretrained 会将模型下载到 huggingface 缓存目录，之后你可以使用 hf 工具来管理已安装的模型文件。

Chat Completion

高级 API 也提供了一个用于聊天补全的简单接口。

聊天补全要求模型知道如何将消息格式化为单个提示词。 Llama 类通过使用预注册的聊天格式（例如 chatml、llama-2、gemma 等）或提供自定义的聊天处理对象来实现这一点。

模型将按照以下优先级顺序将消息格式化为单个提示词：

• 如果提供了 chat_handler，则使用它
• 如果提供了 chat_format，则使用它
• 使用 gguf 模型元数据中的 tokenizer.chat_template（对于大多数新模型应该有效，旧模型可能没有此项）
• 否则，回退到 llama-2 聊天格式

设置 verbose=True 以查看所选的聊天格式。

from llama_cpp import Llama
llm = Llama(
      model_path="path/to/llama-2/llama-model.gguf",
      chat_format="llama-2"
)
llm.create_chat_completion(
      messages = [
          {"role": "system", "content": "You are an assistant who perfectly describes images."},
          {
              "role": "user",
              "content": "Describe this image in detail please."
          }
      ]
)

Chat completion 可通过 Llama 类的 create_chat_completion 方法使用。

为了兼容 OpenAI API v1，请使用 create_chat_completion_openai_v1 方法，该方法将返回 pydantic 模型而非字典。

JSON 和 JSON Schema 模式

要将聊天响应限制为仅有效的 JSON 或特定的 JSON Schema，请在 create_chat_completion 中使用 response_format 参数。

JSON 模式

以下示例将响应限制为仅有效的 JSON 字符串。

from llama_cpp import Llama
llm = Llama(model_path="path/to/model.gguf", chat_format="chatml")
llm.create_chat_completion(
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant that outputs in JSON.",
        },
        {"role": "user", "content": "Who won the world series in 2020"},
    ],
    response_format={
        "type": "json_object",
    },
    temperature=0.7,
)

JSON Schema 模式

若要进一步将响应约束到特定的 JSON Schema，请将该 schema 添加到 response_format 参数的 schema 属性中。

from llama_cpp import Llama
llm = Llama(model_path="path/to/model.gguf", chat_format="chatml")
llm.create_chat_completion(
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant that outputs in JSON.",
        },
        {"role": "user", "content": "Who won the world series in 2020"},
    ],
    response_format={
        "type": "json_object",
        "schema": {
            "type": "object",
            "properties": {"team_name": {"type": "string"}},
            "required": ["team_name"],
        },
    },
    temperature=0.7,
)

函数调用

高级 API 支持兼容 OpenAI 的函数和工具调用。这可以通过 functionary 预训练模型的聊天格式或通用的 chatml-function-calling 聊天格式实现。

from llama_cpp import Llama
llm = Llama(model_path="path/to/chatml/llama-model.gguf", chat_format="chatml-function-calling")
llm.create_chat_completion(
      messages = [
        {
          "role": "system",
          "content": "A chat between a curious user and an artificial intelligence assistant. The assistant gives helpful, detailed, and polite answers to the user's questions. The assistant calls functions with appropriate input when necessary"

        },
        {
          "role": "user",
          "content": "Extract Jason is 25 years old"
        }
      ],
      tools=[{
        "type": "function",
        "function": {
          "name": "UserDetail",
          "parameters": {
            "type": "object",
            "title": "UserDetail",
            "properties": {
              "name": {
                "title": "Name",
                "type": "string"
              },
              "age": {
                "title": "Age",
                "type": "integer"
              }
            },
            "required": [ "name", "age" ]
          }
        }
      }],
      tool_choice={
        "type": "function",
        "function": {
          "name": "UserDetail"
        }
      }
)

from llama_cpp import Llama
from llama_cpp.llama_tokenizer import LlamaHFTokenizer
llm = Llama.from_pretrained(
  repo_id="meetkai/functionary-small-v2.2-GGUF",
  filename="functionary-small-v2.2.q4_0.gguf",
  chat_format="functionary-v2",
  tokenizer=LlamaHFTokenizer.from_pretrained("meetkai/functionary-small-v2.2-GGUF")
)

多模态模型

llama-cpp-python 支持如 llava1.5 等模型，允许语言模型从文本和图像中读取信息。

以下是支持的多模态模型及其各自的聊天处理器（Python API）和聊天格式（Server API）。

在 Google Colab 中尝试 Gemma 4 12B ->

在 Google Colab 中尝试 Gemma 4 12B QAT ->

然后，您需要使用自定义聊天处理器来加载 clip 模型并处理聊天消息和图像。

from llama_cpp import Llama
from llama_cpp.llama_chat_format import Llava15ChatHandler
chat_handler = Llava15ChatHandler(clip_model_path="path/to/llava/mmproj.bin")
llm = Llama(
  model_path="./path/to/llava/llama-model.gguf",
  chat_handler=chat_handler,
  n_ctx=2048, # n_ctx should be increased to accommodate the image embedding
)
llm.create_chat_completion(
    messages = [
        {"role": "system", "content": "You are an assistant who perfectly describes images."},
        {
            "role": "user",
            "content": [
                {"type" : "text", "text": "What's in this image?"},
                {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" } }
            ]
        }
    ]
)

你也可以使用 from_pretrained 方法从 Hugging Face Hub 拉取模型。

from llama_cpp import Llama
from llama_cpp.llama_chat_format import MoondreamChatHandler

chat_handler = MoondreamChatHandler.from_pretrained(
  repo_id="vikhyatk/moondream2",
  filename="*mmproj*",
)

llm = Llama.from_pretrained(
  repo_id="vikhyatk/moondream2",
  filename="*text-model*",
  chat_handler=chat_handler,
  n_ctx=2048, # n_ctx should be increased to accommodate the image embedding
)

response = llm.create_chat_completion(
    messages = [
        {
            "role": "user",
            "content": [
                {"type" : "text", "text": "What's in this image?"},
                {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" } }

            ]
        }
    ]
)
print(response["choices"][0]["text"])

注意：多模态模型也支持工具调用和 JSON 模式。

import base64

def image_to_base64_data_uri(file_path):
    with open(file_path, "rb") as img_file:
        base64_data = base64.b64encode(img_file.read()).decode('utf-8')
        return f"data:image/png;base64,{base64_data}"

# Replace 'file_path.png' with the actual path to your PNG file
file_path = 'file_path.png'
data_uri = image_to_base64_data_uri(file_path)

messages = [
    {"role": "system", "content": "You are an assistant who perfectly describes images."},
    {
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": data_uri }},
            {"type" : "text", "text": "Describe this image in detail please."}
        ]
    }
]

推测解码

llama-cpp-python 支持推测解码，允许模型基于草稿模型生成补全内容。

使用推测解码的最快方式是通过 LlamaPromptLookupDecoding 类。

只需在初始化时将其作为草稿模型传递给 Llama 类。

from llama_cpp import Llama
from llama_cpp.llama_speculative import LlamaPromptLookupDecoding

llama = Llama(
    model_path="path/to/model.gguf",
    draft_model=LlamaPromptLookupDecoding(num_pred_tokens=10) # num_pred_tokens is the number of tokens to predict 10 is the default and generally good for gpu, 2 performs better for cpu-only machines.
)

嵌入

要生成文本嵌入，请使用 create_embedding 或 embed。请注意，在创建模型时，必须向构造函数传递 embedding=True，这些功能才能正常工作。

import llama_cpp

llm = llama_cpp.Llama(model_path="path/to/model.gguf", embedding=True)

embeddings = llm.create_embedding("Hello, world!")

# or create multiple embeddings at once

embeddings = llm.create_embedding(["Hello, world!", "Goodbye, world!"])

在 Transformer 风格的模型中，嵌入（embeddings）主要有两个概念：token 级别和序列级别。序列级别的嵌入是通过“池化”（pooling）token 级别的嵌入生成的，通常通过取平均值或使用第一个 token 来实现。

明确面向嵌入的模型通常默认返回序列级别的嵌入，每个输入字符串对应一个。非嵌入模型，例如为文本生成设计的模型，通常只返回 token 级别的嵌入，每个序列中的每个 token 对应一个。因此，token 级别嵌入的返回类型维度会比序列级别高一个维度。

在某些情况下，可以通过在创建模型时使用 pooling_type 标志来控制池化行为。你可以使用 LLAMA_POOLING_TYPE_NONE 确保从任何模型获取 token 级别的嵌入。反之，让面向生成的模型输出序列级别的嵌入目前是不可能的，但你始终可以手动进行池化。

调整上下文窗口

Llama 模型的上下文窗口决定了可以一次性处理的最大 token 数量。默认情况下，这被设置为 512 个 token，但可以根据你的需求进行调整。

例如，如果你想处理更大的上下文，可以在初始化 Llama 对象时设置 n_ctx 参数来扩展上下文窗口：

llm = Llama(model_path="./models/7B/llama-model.gguf", n_ctx=2048)

OpenAI 兼容 Web 服务器

llama-cpp-python 提供了一个 Web 服务器，旨在作为 OpenAI API 的直接替代品。 这允许你使用任何 OpenAI 兼容客户端（语言库、服务等）来运行 llama.cpp 兼容的模型。

要安装服务器包并开始使用：

pip install 'llama-cpp-python[server]'
python3 -m llama_cpp.server --model models/7B/llama-model.gguf

与上文中的硬件加速部分类似，您也可以像这样安装带有 GPU（cuBLAS）支持的版本：

CMAKE_ARGS="-DGGML_CUDA=on" FORCE_CMAKE=1 pip install 'llama-cpp-python[server]'
python3 -m llama_cpp.server --model models/7B/llama-model.gguf --n_gpu_layers 35

导航至 http://localhost:8000/docs 以查看 OpenAPI 文档。

若要绑定到 0.0.0.0 以启用远程连接，请使用 python3 -m llama_cpp.server --host 0.0.0.0。 类似地，若要更改端口（默认为 8000），请使用 --port。

您可能还需要设置提示格式。对于 chatml，请使用

python3 -m llama_cpp.server --model models/7B/llama-model.gguf --chat_format chatml

这将按照模型所期望的格式对提示词进行格式化。你可以在模型卡片中找到提示词格式。 有关可能的选项，请参阅 llama_cpp/llama_chat_format.py，并查找以 "@register_chat_format" 开头的行。

如果你已安装 huggingface-hub，也可以使用 --hf_model_repo_id 标志从 Hugging Face Hub 加载模型。

python3 -m llama_cpp.server --hf_model_repo_id lmstudio-community/Qwen3.5-0.8B-GGUF --model '*Q8_0.gguf'

Web Server 功能

• 本地 Copilot 替代方案
• Function Calling 支持
• Vision API 支持
• 多模型

Docker 镜像

Docker 镜像可在 GHCR 上获取。要运行服务器：

docker run --rm -it -p 8000:8000 -v /path/to/models:/models -e MODEL=/models/llama-model.gguf ghcr.io/abetlen/llama-cpp-python:latest

Docker on termux (requires root) 是目前已知的在手机上运行的唯一方式，参见 termux support issue

Low-level API

API Reference

低层 API 是对 llama.cpp 提供的 C API 的直接 ctypes 绑定。 完整的低层 API 可在 llama_cpp/llama_cpp.py 中找到，并直接镜像了 llama.h 中的 C API。

下面是一个简短的示例，演示如何使用低层 API 对提示词进行分词：

import llama_cpp
import ctypes
llama_cpp.llama_backend_init()  # Must be called once at the start of each program
model_params = llama_cpp.llama_model_default_params()
ctx_params = llama_cpp.llama_context_default_params()
prompt = b"Q: Name the planets in the solar system? A: "
# use bytes for char * params
model = llama_cpp.llama_model_load_from_file(b"./models/7b/llama-model.gguf", model_params)
ctx = llama_cpp.llama_init_from_model(model, ctx_params)
vocab = llama_cpp.llama_model_get_vocab(model)
max_tokens = ctx_params.n_ctx
# use ctypes arrays for array params
tokens = (llama_cpp.llama_token * int(max_tokens))()
n_tokens = llama_cpp.llama_tokenize(vocab, prompt, len(prompt), tokens, max_tokens, True, False)
llama_cpp.llama_free(ctx)
llama_cpp.llama_model_free(model)

查看 examples 文件夹 以获取更多使用低级 API 的示例。

文档

文档可通过 https://llama-cpp-python.readthedocs.io/ 获取。 如果你发现文档中存在任何问题，请提交 issue 或 PR。

开发

此包正在积极开发中，我欢迎任何贡献。 请参阅 CONTRIBUTING.md 了解贡献流程、PR 标题、变更日志、测试和样式指南。

要开始使用，请克隆仓库并以可编辑/开发模式安装该包：

git clone --recurse-submodules https://github.com/abetlen/llama-cpp-python.git
cd llama-cpp-python

# Upgrade pip (required for editable mode)
pip install --upgrade pip

# Install with pip
pip install -e .

# install development tooling (tests, docs, ruff)
pip install -e '.[dev]'

# if you want to use the fastapi / openapi server
pip install -e '.[server]'

# to install all optional dependencies
pip install -e '.[all]'

# to clear the local build cache
make clean

现在尝试运行测试

pytest

在提交 PR 之前，请检查格式 / 代码规范：

python -m ruff check llama_cpp tests
python -m ruff format --check llama_cpp tests

# or use the Makefile targets
make lint
make format

有一个 Makefile 可用，其中包含有用的目标。 典型的工作流程如下所示：

make build
make test

你还可以通过检出 vendor/llama.cpp 子模块中所需的提交来测试 llama.cpp 的特定提交，然后再次运行 make clean 和 pip install -e .。llama.h API 的任何更改都需要 对 llama_cpp/llama_cpp.py 文件进行相应的更改以匹配新 API（其他地方可能还需要进行额外的更改）。

常见问题解答

是否有预构建的二进制文件 / 二进制 wheel 可用？

推荐的安装方法是按照上述说明从源代码安装。 这样做的原因是 llama.cpp 是使用针对你的系统特定的编译器优化构建的。 使用预构建的二进制文件将需要禁用这些优化，或者为每个平台支持大量预构建的二进制文件。

话虽如此，通过 Releases 以及一些社区提供的 wheel，也可以获得一些预构建的二进制文件。

未来，我希望为常见平台提供预构建的二进制文件和 wheel，并且我很乐意接受在此领域的任何有用贡献。 目前这正在 #741 中跟踪

这与 llama.cpp 的其他 Python 绑定相比如何？

我最初编写这个包是为了自己使用，并怀有两个目标：

• 提供一个简单的流程来安装 llama.cpp 并从 Python 访问 llama.h 中的完整 C API
• 提供一个高级 Python API，可以作为 OpenAI API 的直接替代品使用，以便现有应用程序可以轻松移植以使用 llama.cpp

对该包的任何贡献和更改都将基于这些目标进行。

许可证

本项目依据 MIT 许可证的条款授权。