Python 绑定：针对 llama.cpp 的封装

为 @ggerganov 的 llama.cpp 库提供了一套简单的 Python 绑定。 该包提供了以下功能：

• 通过 ctypes 接口对 C API 进行低级访问。
• 高级 Python API，用于文本补全
  • 类似 OpenAI 的 API
  • LangChain 兼容性
  • LlamaIndex 兼容性
• OpenAI 兼容的 Web 服务器
  • 本地 Copilot 替代方案
  • 函数调用支持
  • 视觉 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 包一同安装。

若安装失败，请在 pip install 命令中添加 --verbose 参数，以查看完整的 CMake 构建日志。

预编译 Wheel（新版本）

您也可以安装一个预编译的 Wheel，以支持基本的 CPU 加速。

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 进行设置。

# Linux 和 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 # 确保 pip 已更新
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_HIPBLAS=on" pip install llama-cpp-python

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

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, # 如需启用 GPU 加速，请取消注释
      # seed=1337, # 如需设置特定种子，请取消注释
      # n_ctx=2048, # 如需扩大上下文窗口大小，请取消注释
)
output = llm(
      "Q: 请说出太阳系中的行星名称？A: ", # 提示语
      max_tokens=32, # 生成最多 32 个 token，若设为 None，则可生成至上下文窗口的末尾
      stop=["Q:", "\n"], # 在模型生成新问题之前停止生成
      echo=True # 将提示语回传至输出中
) # 生成补全结果，也可调用 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: 请说出太阳系中的行星名称？A: 水星、金星、地球、火星、木星、土星、天王星、海王星和冥王星。",
      "index": 0,
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 28,
    "total_tokens": 42
  }
}

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

从 Hugging Face Hub 下载模型

您可以通过 from_pretrained 方法，直接从 Hugging Face 下载 Llama 的 gguf 格式模型。

要使用此功能，您需要先安装 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 方法会将模型下载至 Hugging Face 缓存目录中；您随后可以使用 hf 工具来管理已安装的模型文件。

聊天补全

高级 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": "您是一位能够完美描述图像的助手。"},
          {
              "role": "user",
              "content": "请详细描述这张图片。"
          }
      ]
)

聊天补全功能可通过 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": "您是一位乐于助人的助手，能够以 JSON 格式输出结果。"
        },
        {"role": "user", "content": "2020 年世界大赛的冠军是谁？"}
    ],
    response_format={
        "type": "json_object"
    },
    temperature=0.7
)

JSON Schema 模式

若要进一步将回复严格限制为特定的 JSON Schema，只需在 response_format 参数的 schema 属性中添加该 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": "您是一位乐于助人的助手，能够以 JSON 格式输出结果。"
        },
        {"role": "user", "content": "2020 年世界大赛的冠军是谁？"}
    ],
    response_format={
        "type": "json_object",
        "schema": {
            "type": "object",
            "properties": {"team_name": {"type": "string"}}
        }
    },
    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": "一场好奇的用户与人工智能助手之间的对话。助手会为用户提供有帮助、详尽且礼貌的回答。必要时，助手会调用相关函数并提供恰当的输入。"
        },
        {
          "role": "user",
          "content": "请提取 Jason 的年龄"
        }
      ],
      tools=[{
        "type": "function",
        "function": {
          "name": "UserDetail",
          "parameters": {
            "type": "object",
            "title": "UserDetail",
            "properties": {
              "name": {
                "title": "姓名",
                "type": "string"
              },
              "age": {
                "title": "年龄",
                "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）：

接下来，您需要使用自定义的聊天处理程序来加载剪辑模型，并对聊天消息和图像进行处理。

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 应该增加以适应图像嵌入
)
llm.create_chat_completion(
    messages = [
        {"role": "system", "content": "您是一位能完美描述图像的助手。"},
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "这张图片里有什么？"},
                {"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 应该增加以适应图像嵌入
)

response = llm.create_chat_completion(
    messages = [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "这张图片里有什么？"},
                {"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}"

# 将 'file_path.png' 替换为您的 PNG 文件的实际路径
file_path = 'file_path.png'
data_uri = image_to_base64_data_uri(file_path)

messages = [
    {"role": "system", "content": "您是一位能完美描述图像的助手。"}, 
    {
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": data_uri }},
            {"type": "text", "text": "请详细描述这张图片。"}
        ]
    }
]

思考性解码

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 是要预测的 token 数量；10 是默认值，通常对 GPU 来说效果不错，而 2 则更适合仅使用 CPU 的机器。
)

嵌入式表示

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

import llama_cpp

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

embeddings = llm.create_embedding("你好，世界！")

# 或者一次性创建多个嵌入式表示

embeddings = llm.create_embedding(["你好，世界！", "再见，世界！"])

Transformer 风格的模型中，嵌入式表示主要有两种概念：token 级别 和 序列级别。序列级别嵌入式表示是通过将 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 的即插即用替代品。 通过使用该服务器，您可以将兼容 llama.cpp 的模型与任何兼容 OpenAI 的客户端（如语言库、服务等）配合使用。

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

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 服务器功能

• 本地 Copilot 替代方案
• 函数调用支持
• 视觉 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

目前，只有通过 Termux 运行此服务的方法是已知的（需 root 权限）。有关更多信息，请参阅 Termux 支持问题。

低级 API

API 参考

低级 API 是对 llama.cpp 提供的 C API 的直接 ctypes 绑定。整个低级 API 可在 llama_cpp/llama_cpp.py 中找到，并且直接映射了 C API 的结构于 llama.h 中。

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

import llama_cpp
import ctypes
llama_cpp.llama_backend_init(False) # 必须在每个程序启动时调用一次
params = llama_cpp.llama_context_default_params()
# 使用字节类型表示 char * params
model = llama_cpp.llama_load_model_from_file(b"./models/7b/llama-model.gguf", params)
ctx = llama_cpp.llama_new_context_with_model(model, params)
max_tokens = params.n_ctx
# 使用 ctypes 数组来存储数组参数
tokens = (llama_cpp.llama_token * int(max_tokens))()
n_tokens = llama_cpp.llama_tokenize(ctx, b"Q: 请说出太阳系中的行星名称？A: ", tokens, max_tokens, llama_cpp.c_bool(True))
llama_cpp.llama_free(ctx)

请查看 [examples/low_level_api] 文件夹，了解更多关于低级 API 的使用示例。

文档

文档可通过 https://llama-cpp-python.readthedocs.io/ 获取。 如果您发现文档有任何问题，请随时提交问题或创建 PR。

开发

本软件包正处于积极开发阶段，我们欢迎任何贡献。

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

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

# 升级 pip（适用于可编辑模式）
pip install --upgrade pip

# 通过 pip 安装
pip install -e .

# 安装开发工具（测试、文档、ruff）
pip install -e '.[dev]'

# 如果您想使用 fastapi / openapi 服务器
pip install -e '.[server]'

# 若需安装所有可选依赖项
pip install -e '.[all]'

# 清理本地构建缓存
make clean

现在尝试运行测试：

pytest

在提交 PR 前，请检查格式化和代码检查：

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

# 或者使用 Makefile 目标
make lint
make format

Makefile 中包含了一些实用的目标。典型的流程如下：

make build
make test

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

常见问题

是否有预编译的二进制文件或二进制轮子可供使用？

推荐的安装方式是按照上述说明从源码编译安装。原因在于，llama.cpp 是基于特定于您系统的编译器优化而构建的。若使用预编译的二进制文件，您需要禁用这些优化，或者为每个平台支持大量预编译的二进制文件。

不过，您仍然可以通过发布版以及社区提供的轮子获取一些预编译的二进制文件。

未来，我希望能为常见平台提供预编译的二进制文件和轮子，并乐于接受任何在这方面的有用贡献。目前，这一工作正在 #741 中进行跟踪。

与 llama.cpp 的其他 Python 绑定相比，它有何不同？

我最初编写这个软件包是为了满足自己的需求，主要有两个目标：

• 提供一种简单便捷的方式，用于安装 llama.cpp 并从 Python 调用 llama.h 中的完整 C API。
• 提供一个高级别的 Python API，可作为 OpenAI API 的即插即用替代品，从而轻松将现有应用迁移到使用 llama.cpp 的环境中。

任何对该软件包的贡献和修改，都将围绕以上目标展开。

许可证

本项目采用 MIT 许可证授权。

llama-cpp-python 快速上手指南

llama-cpp-python 是 llama.cpp 的 Python 绑定库，允许你在本地高效运行量化后的 LLM 模型（GGUF 格式）。它提供了从底层 C API 访问到高层 OpenAI 兼容接口的完整支持。

环境准备

在开始之前，请确保你的系统满足以下要求：

• Python 版本：3.8 或更高版本。
• 编译器依赖：安装过程中需要从源码编译 llama.cpp，因此需要安装 C 编译器。
  • Linux: gcc 或 clang
  • Windows: Visual Studio Build Tools 或 MinGW
  • macOS: Xcode Command Line Tools
• 硬件加速（可选）：如需 GPU 加速，需提前安装对应的驱动和工具包（如 NVIDIA CUDA Toolkit, macOS Metal 等）。

注意：如果你使用的是 Apple Silicon (M1/M2/M3) Mac，请务必安装支持 arm64 架构的 Python 版本（推荐使用 Miniforge 或官方 arm64 安装包），否则性能会大幅下降。

安装步骤

1. 基础安装（CPU 版本）

最简单的安装方式是使用 pip。这将自动下载并编译 llama.cpp。

pip install llama-cpp-python

如果网络较慢导致下载失败，可以使用国内镜像源加速：

pip install llama-cpp-python -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 启用硬件加速（推荐）

为了获得更好的推理速度，建议根据硬件配置设置环境变量进行安装。

NVIDIA GPU (CUDA)

确保已安装 CUDA Toolkit (版本 12.1-12.5)。

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

或者安装预编译的 CUDA Wheel（需 Python 3.10+ 且 CUDA 版本匹配）：

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

macOS (Metal/MPS)

适用于 M 系列芯片 Mac，启用 Metal 加速。

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

或者安装预编译的 Metal Wheel：

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

AMD GPU (ROCm)

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

提示：如果安装失败，请添加 --verbose 参数查看详细的编译日志。若需重新编译，请加上 --upgrade --force-reinstall --no-cache-dir 参数。

基本使用

1. 加载模型并生成文本

首先，你需要一个 .gguf 格式的模型文件。以下是最简单的高层 API 使用示例：

from llama_cpp import Llama

# 初始化模型
llm = Llama(
      model_path="./models/7B/llama-model.gguf",
      # n_gpu_layers=-1, # 取消注释以启用 GPU 加速（将所有层卸载到 GPU）
      # n_ctx=2048,      # 取消注释以设置上下文窗口大小
)

# 生成文本
output = llm(
      "Q: Name the planets in the solar system? A: ", # 提示词
      max_tokens=32,     # 最大生成 token 数
      stop=["Q:", "\n"], # 停止生成的条件
      echo=True          # 是否在输出中包含提示词
)

print(output)

输出结果为 OpenAI 兼容的字典格式，包含生成的文本、token 用量等信息。

2. 直接从 Hugging Face 加载模型

你可以无需手动下载模型，直接使用 from_pretrained 方法从 Hugging Face Hub 加载 GGUF 模型（需先安装 huggingface-hub）：

pip install huggingface-hub

from llama_cpp import Llama

llm = Llama.from_pretrained(
    repo_id="lmstudio-community/Qwen3.5-0.8B-GGUF",
    filename="*Q8_0.gguf", # 支持通配符匹配文件名
    verbose=False
)

response = llm("你好，请介绍一下你自己。", max_tokens=100)
print(response["choices"][0]["text"])

3. 开启聊天模式

对于对话类模型，可以使用 create_chat_completion 方法，它会自动处理消息格式化：

messages = [
    {"role": "system", "content": "你是一个乐于助人的助手。"},
    {"role": "user", "content": "太阳系有哪些行星？"}
]

output = llm.create_chat_completion(
      messages=messages,
      max_tokens=100
)

print(output["choices"][0]["message"]["content"])