llama.cpp库的Python绑定

导航

验证详情

这些详情已由PyPI验证
维护者
Avatar for Grant.Jenks from gravatar.com Grant.Jenks

未验证详情

这些详情尚未由PyPI验证
项目链接
元数据
分类器

项目描述

🦙 Python Bindings for llama.cpp

Documentation Status Tests PyPI PyPI - Python Version PyPI - License PyPI - Downloads

简单的Python绑定，用于llama.cpp库。本包提供

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

安装

llama-cpp-python可以直接从PyPI以源代码包的形式安装，运行以下命令：

pip install llama-cpp-python

这将使用cmake和您的系统编译器（必需）从源代码构建llama.cpp，并将其与Python包一起安装。

如果在安装过程中遇到问题，请将--verbose标志添加到pip install命令中，以查看完整的cmake构建日志。

使用特定硬件加速（BLAS、CUDA、Metal等）安装

默认pip安装行为是在Linux和Windows上为CPU仅构建llama.cpp，并在MacOS上使用Metal。

llama.cpp支持多个硬件加速后端，包括OpenBLAS、cuBLAS、CLBlast、HIPBLAS和Metal。有关支持的完整后端列表，请参阅llama.cpp README。

所有这些后端都由llama-cpp-python支持，并且可以在安装前通过设置CMAKE_ARGS环境变量来启用。

在Linux和Mac上，您可以这样设置CMAKE_ARGS：

CMAKE_ARGS="-DLLAMA_BLAS=ON -DLLAMA_BLAS_VENDOR=OpenBLAS" pip install llama-cpp-python

在Windows上，您可以这样设置CMAKE_ARGS：

$env:CMAKE_ARGS = "-DLLAMA_BLAS=ON -DLLAMA_BLAS_VENDOR=OpenBLAS"
pip install llama-cpp-python

OpenBLAS

要使用OpenBLAS进行安装，请在安装前设置环境变量LLAMA_BLAS和LLAMA_BLAS_VENDOR。

CMAKE_ARGS="-DLLAMA_BLAS=ON -DLLAMA_BLAS_VENDOR=OpenBLAS" pip install llama-cpp-python

cuBLAS

要使用cuBLAS进行安装，请在安装前设置环境变量LLAMA_CUBLAS=1。

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

Metal

要使用Metal（MPS）进行安装，请在安装前设置环境变量LLAMA_METAL=on。

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

CLBlast

要使用CLBlast进行安装，请在安装前设置环境变量LLAMA_CLBLAST=1。

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

hipBLAS

要使用hipBLAS / ROCm支持AMD卡，请在安装前设置环境变量LLAMA_HIPBLAS=on。

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

Windows注意事项

如果您遇到问题，系统提示找不到'nmake'、'?'或CMAKE_C_COMPILER，您可以根据llama.cpp仓库中提到的内容提取w64devkit，并将其手动添加到CMAKE_ARGS中，然后再运行pip install。

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

请参阅上述说明，并将CMAKE_ARGS设置为您希望使用的BLAS后端。

MacOS注意事项

注意：如果您使用的是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倍。

详细的MacOS Metal GPU安装文档可在文档/install/macos.md中找到。

升级和重新安装

要升级或重新构建llama-cpp-python，请添加以下标志以确保正确重新构建包：

pip install llama-cpp-python  --upgrade --force-reinstall --no-cache-dir

这将确保所有源文件都使用最新设置的CMAKE_ARGS标志重新构建。

高级API

API参考

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

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

>>> from llama_cpp import Llama
>>> llm = Llama(model_path="./models/7B/llama-model.gguf")
>>> output = llm(
      "Q: Name the planets in the solar system? A: ", # Prompt
      max_tokens=32, # Generate up to 32 tokens
      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)
{
  "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
  }
}

文本补全可以通过__call__和create_completion方法来使用Llama类。

聊天补全

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

请注意，必须为使用的特定模型设置chat_format选项。

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

聊天补全可以通过create_chat_completion方法来使用Llama类。

函数调用

高级API还提供了一个简单的函数调用接口。

请注意，目前只有“functionary”模型支持完全的函数调用。此模型的gguf-转换文件可在此处找到：functionary-7b-v1

>>> from llama_cpp import Llama
>>> llm = Llama(model_path="path/to/functionary/llama-model.gguf", chat_format="functionary")
>>> 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_choices=[{
        "type": "function",
        "function": {
          "name": "UserDetail"
        }
      }]
)

多模态模型

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

您首先需要下载GGUF格式的可用的多模态模型之一。

然后，您需要使用自定义聊天处理程序来加载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 accomodate the image embedding
  logits_all=True,# needed to make llava work
)
>>> llm.create_chat_completion(
    messages = [
        {"role": "system", "content": "You are an assistant who perfectly describes images."},
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": "https://.../image.png"}},
                {"type" : "text", "text": "Describe this image in detail please."}
            ]
        }
    ]
)

调整上下文窗口

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 的即插即用替代品。这使得您可以使用与 llama.cpp 兼容的模型与任何 OpenAI 兼容的客户端（语言库、服务等）一起使用。

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

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

类似于上面的硬件加速部分，您也可以这样使用支持 GPU（cuBLAS）的安装

CMAKE_ARGS="-DLLAMA_CUBLAS=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

导航到 https://: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” 开头的行。

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(numa=False) # Must be called once at the start of each program
>>> params = llama_cpp.llama_context_default_params()
# use bytes for 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
# use ctypes arrays for array params
>>> 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, add_bos=llama_cpp.c_bool(True))
>>> llama_cpp.llama_free(ctx)

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

文档

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

# 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

常见问题解答

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

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

尽管如此，Release 中有一些预构建的二进制文件以及一些社区提供的轮文件。

将来，我希望为常见平台提供预构建的二进制文件和轮文件，并且我很高兴接受任何在这个领域的有用贡献。目前，这个问题正在 #741 中跟踪。

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

我最初编写此包是为了自己的使用，有两个目标

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

对此包的任何贡献和更改都将以这些目标为依据。

许可证

本项目遵循MIT许可证条款。

项目详情

验证详情

这些详情已由PyPI验证
维护者
Avatar for Grant.Jenks from gravatar.com Grant.Jenks

未验证详情

这些详情尚未由PyPI验证
项目链接
元数据
分类器

发布历史 发布通知 | RSS订阅

本版本

0.2.26

下载文件

下载适合您平台的文件。如果您不确定选择哪个，请了解有关安装包的更多信息。

源分布

llama_cpp_python_binary-0.2.26.tar.gz (864.1 kB 查看哈希值)

上传时间 源代码

由以下组织支持