🦙 `llama.cpp`的Python绑定

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

通过 ctypes 接口对C API的低级访问。
用于文本补全的高级Python API
- 类OpenAI的API
- LangChain兼容性
- LlamaIndex兼容性
兼容OpenAI的Web服务器

文档可在 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构建日志。

预构建轮子（新）

现在也可以安装带有基本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

</details> <details> <summary>命令行 / requirements.txt</summary>

它们也可以通过 pip install -C / --config-settings 命令设置并保存到 requirements.txt 文件中：

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"

</details>

支持的后端

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

<details open> <summary>OpenBLAS (CPU)</summary>

要安装带有OpenBLAS的版本，在安装前设置 GGML_BLAS 和 GGML_BLAS_VENDOR 环境变量：

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

</details> <details> <summary>CUDA</summary>

要安装带有CUDA支持的版本，在安装前设置 GGML_CUDA=on 环境变量：

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

预构建轮子（新）

现在也可以安装带有CUDA支持的预构建轮子。只要你的系统满足以下要求：

CUDA版本为12.1、12.2、12.3或12.4
Python版本为3.10、3.11或3.12

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

其中 <cuda-version> 是以下之一：

cu121: CUDA 12.1
cu122: CUDA 12.2
cu123: CUDA 12.3
cu124: CUDA 12.4

例如，要安装CUDA 12.1的轮子：

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

</details> <details> <summary>Metal</summary>

要安装带有Metal (MPS)支持的版本，在安装前设置 GGML_METAL=on 环境变量：

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

预构建轮子（新）

现在也可以安装带有Metal支持的预构建轮子。只要你的系统满足以下要求：

MacOS版本为11.0或更高
Python版本为3.10、3.11或3.12

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

</details> <details> <summary>hipBLAS (ROCm)</summary>

要为AMD卡安装带有hipBLAS / ROCm支持的版本，在安装前设置 GGML_HIPBLAS=on 环境变量：

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

</details> <details> <summary>Vulkan</summary>

要安装带有Vulkan支持的版本，在安装前设置 GGML_VULKAN=on 环境变量：

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

</details> <details> <summary>SYCL</summary>

要安装带有SYCL支持的版本，在安装前设置 GGML_SYCL=on 环境变量：

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

</details> <details> <summary>RPC</summary>

要安装带有RPC支持的版本，在安装前设置 GGML_RPC=on 环境变量：

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

</details>

Windows注意事项

<details> <summary>错误：找不到 'nmake' 或 'CMAKE_C_COMPILER'</summary>

如果遇到无法找到 'nmake'、'?' 或 CMAKE_C_COMPILER 的问题，你可以解压 w64devkit，如 llama.cpp 仓库中所提到的，并在运行 pip 安装前将它们手动添加到 CMAKE_ARGS 中：

$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"

参考上述说明，将 CMAKE_ARGS 设置为你想使用的 BLAS 后端。

</details>

MacOS注意事项

详细的 MacOS Metal GPU 安装文档可在 docs/install/macos.md 查阅。

<details> <summary>M1 Mac性能问题</summary>

注意：如果你使用的是 Apple Silicon (M1) Mac，确保安装了支持 arm64 架构的 Python 版本。例如：

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

否则，在安装时它会构建 llama.cpp 的 x86 版本，这在 Apple Silicon (M1) Mac 上会慢 10 倍。

</details> <details> <summary>M 系列 Mac 错误：`(mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64'))`</summary>

尝试使用以下命令安装：

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

</details>

升级和重新安装

要升级和重建 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(
      "问：请列出太阳系中的行星？答：", # 提示
      max_tokens=32, # 生成最多 32 个令牌，设置为 None 以生成到上下文窗口的末尾
      stop=["问：", "\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": "问：请列出太阳系中的行星？答：水星、金星、地球、火星、木星、土星、天王星、海王星和冥王星。",
      "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="Qwen/Qwen2-0.5B-Instruct-GGUF",
    filename="*q8_0.gguf",
    verbose=False
)

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

聊天补全

高级 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，请将 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": "你是一个以 JSON 格式输出的有用助手。",
        },
        {"role": "user", "content": "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": "这是一个好奇的用户和人工智能助手之间的对话。助手对用户的问题给出有帮助、详细和礼貌的回答。助手在必要时会使用适当的输入调用函数"

        },
        {
          "role": "user",
          "content": "提取：Jason 今年 25 岁"
        }
      ],
      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"
        }
      }
)

<details> <summary>Functionary v2</summary>

这组模型的各种 gguf 转换文件可以在这里找到。Functionary 能够智能地调用函数，并分析任何提供的函数输出以生成连贯的响应。Functionary 的所有 v2 模型都支持并行函数调用。在初始化 Llama 类时，你可以为 chat_format 提供 functionary-v1 或 functionary-v2。

由于 llama.cpp 和 HuggingFace 的分词器之间存在差异，需要为 functionary 提供 HF 分词器。可以初始化 LlamaHFTokenizer 类并传递给 Llama 类。这将覆盖 Llama 类中使用的默认 llama.cpp 分词器。分词器文件已包含在托管 gguf 文件的相应 HF 仓库中。

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")
)

注意：不需要提供 Functionary 中使用的默认系统消息，因为它们会在 Functionary 聊天处理程序中自动添加。因此，消息应该只包含聊天消息和/或为模型提供附加上下文的系统消息（例如：日期时间等）。

</details>

多模态模型

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

以下是支持的多模态模型及其相应的聊天处理程序（Python API）和聊天格式（Server API）。

模型	`LlamaChatHandler`	`chat_format`
llava-v1.5-7b	`Llava15ChatHandler`	`llava-1-5`
llava-v1.5-13b	`Llava15ChatHandler`	`llava-1-5`
llava-v1.6-34b	`Llava16ChatHandler`	`llava-1-6`
moondream2	`MoondreamChatHandler`	`moondream2`
nanollava	`NanollavaChatHandler`	`nanollava`
llama-3-vision-alpha	`Llama3VisionAlphaChatHandler`	`llama-3-vision-alpha`

然后你需要使用自定义的聊天处理器来加载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以容纳图像嵌入
)
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模式。

<details> <summary>加载本地图像</summary>

图像可以作为base64编码的数据URI传递。以下示例演示了如何实现这一点。

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": "请详细描述这张图片。"}
        ]
    }
]

</details>

推测解码

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是要预测的标记数，10是默认值，通常适用于GPU，对于仅CPU的机器，2表现更好。
)

嵌入

要生成文本嵌入，请使用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风格的模型中，主要有两种嵌入概念：标记级和序列级。序列级嵌入是通过将标记级嵌入"池化"在一起产生的，通常是通过平均它们或使用第一个标记。

明确针对嵌入的模型通常会默认返回序列级嵌入，每个输入字符串一个。非嵌入模型，如那些设计用于文本生成的模型，通常只返回标记级嵌入，每个序列中的每个标记一个。因此，对于标记级嵌入，返回类型的维度会高一维。

在某些情况下，可以使用模型创建时的pooling_type标志来控制池化行为。你可以使用LLAMA_POOLING_TYPE_NONE从任何模型确保获得标记级嵌入。相反，目前无法让生成导向的模型产生序列级嵌入，但你始终可以手动进行池化。

调整上下文窗口

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

例如，如果你想处理更大的上下文，你可以在初始化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 Qwen/Qwen2-0.5B-Instruct-GGUF --model '*q8_0.gguf'

Web服务器功能

Docker镜像

GHCR上提供了一个Docker镜像。要运行服务器：

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（需要root权限）目前是在手机上运行此程序的唯一已知方法，请参见termux支持问题

低级API

API参考低级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(False) # 必须在每个程序开始时调用一次
params = llama_cpp.llama_context_default_params()
# 对char *参数使用bytes
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: Name the planets in the solar system? A: ", tokens, max_tokens, llama_cpp.c_bool(True))
llama_cpp.llama_free(ctx)

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

文档

文档可通过https://llama-cpp-python.readthedocs.io/获取。如果你发现文档中有任何问题，请提出issue或提交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 .

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

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

# 清除本地构建缓存
make clean

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