llama.cpp 的 Python 绑定

为 @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（新功能）

也可以安装一个具有基础 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 命令行标志来设置。

# 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: Name the planets in the solar system? 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: 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 工具管理已安装的模型文件。

聊天补全

高级 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."
          }
      ]
)

聊天补全功能可通过 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 字符串。

```python
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