llama cpp python
v0.3.2
llama.cpp 
Простые привязки Python для библиотеки llama.cpp @ggerganov . Этот пакет обеспечивает:
ctypes .Документация доступна по адресу https://llama-cpp-python.readthedocs.io/en/latest.
Требования:
Чтобы установить пакет, запустите:
pip install llama-cpp-python Это также создаст llama.cpp из исходного кода и установит его вместе с этим пакетом Python.
Если это не помогло, добавьте --verbose в pip install чтобы просмотреть полный журнал сборки cmake.
Готовое колесо (новое)
Также можно установить предварительно встроенное колесо с базовой поддержкой ЦП.
pip install llama-cpp-python
--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu llama.cpp поддерживает ряд механизмов аппаратного ускорения для ускорения вывода, а также специальные параметры серверной части. Полный список см. в README llama.cpp.
Все параметры сборки cmake llama.cpp можно установить с помощью переменной среды 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 -C / --config-settings и сохранить в файл requirements.txt :
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"Ниже приведены некоторые распространенные серверные части, их команды сборки и любые необходимые дополнительные переменные среды.
Для установки с помощью OpenBLAS перед установкой установите переменные среды GGML_BLAS и GGML_BLAS_VENDOR :
CMAKE_ARGS= " -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS " pip install llama-cpp-python Для установки с поддержкой CUDA перед установкой установите переменную среды GGML_CUDA=on :
CMAKE_ARGS= " -DGGML_CUDA=on " pip install llama-cpp-pythonГотовое колесо (новое)
Также возможна установка готового колеса с поддержкой CUDA. Если ваша система соответствует некоторым требованиям:
pip install llama-cpp-python
--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/ < cuda-version > Где <cuda-version> — одно из следующих:
cu121 : CUDA 12.1cu122 : CUDA 12.2cu123 : CUDA 12.3cu124 : CUDA 12.4cu125 : CUDA 12,5Например, чтобы установить колесо CUDA 12.1:
pip install llama-cpp-python
--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121 Для установки с помощью Metal (MPS) перед установкой установите переменную среды GGML_METAL=on :
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 Чтобы установить поддержку hipBLAS/ROCm для карт AMD, перед установкой установите переменную среды GGML_HIPBLAS=on :
CMAKE_ARGS= " -DGGML_HIPBLAS=on " pip install llama-cpp-python Для установки с поддержкой Vulkan перед установкой установите переменную среды GGML_VULKAN=on :
CMAKE_ARGS= " -DGGML_VULKAN=on " pip install llama-cpp-python Для установки с поддержкой 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 Для установки с поддержкой RPC перед установкой установите переменную среды GGML_RPC=on :
source /opt/intel/oneapi/setvars.sh
CMAKE_ARGS= " -DGGML_RPC=on " pip install llama-cpp-python Если вы столкнулись с проблемами, когда он жалуется, что не может найти 'nmake' '?' или CMAKE_C_COMPILER, вы можете извлечь w64devkit, как указано в репозитории llama.cpp, и добавить его вручную в CMAKE_ARGS перед запуском установки pip :
$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, которую вы хотите использовать.
Подробная документация по установке графического процессора MacOS Metal доступна по адресу docs/install/macos.md.
Примечание. Если вы используете Apple Silicon (M1) Mac, убедитесь, что у вас установлена версия Python, поддерживающая архитектуру Arm64. Например:
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh
bash Miniforge3-MacOSX-arm64.shВ противном случае при установке будет создана версия llama.cpp x86, которая будет в 10 раз медленнее на Apple Silicon (M1) Mac.
Попробуйте установить с помощью
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 добавьте флаги --upgrade --force-reinstall --no-cache-dir в команду pip install , чтобы гарантировать пересборку пакета из исходного кода.
Справочник по 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
}
} Завершение текста доступно через методы __call__ и create_completion класса Llama .
Вы можете загрузить модели Llama в формате gguf прямо из Hugging Face, используя метод from_pretrained . Чтобы использовать эту функцию, вам необходимо установить 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 , если он предусмотрен.tokenizer.chat_template из метаданных модели gguf (должен работать для большинства новых моделей, в старых моделях этого может не быть)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."
}
]
) Завершение чата доступно через метод create_chat_completion класса Llama .
Для совместимости OpenAI API v1 вы используете метод create_chat_completion_openai_v1 , который будет возвращать модели pydantic вместо dicts.
Чтобы ограничить ответы чата только допустимым JSON или определенной схемой JSON, используйте аргумент response_format в create_chat_completion .
В следующем примере ответ будет ограничен только допустимыми строками 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 аргумента response_format .
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"
}
}
) Различные файлы, конвертированные в gguf для этого набора моделей, можно найти здесь. Функционер может интеллектуально вызывать функции, а также анализировать любые выходные данные функций для генерации последовательных ответов. Все модели функционала v2 поддерживают параллельный вызов функций . Вы можете указать functionary-v1 или functionary-v2 для chat_format при инициализации класса Llama.
Из-за расхождений между llama.cpp и токенизаторами HuggingFace, необходимо предоставить HF Tokenizer для функционера. Класс LlamaHFTokenizer можно инициализировать и передать в класс Llama. Это переопределит токенизатор llama.cpp по умолчанию, используемый в классе Llama. Файлы токенизатора уже включены в соответствующие репозитории HF, в которых размещены файлы gguf.
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. Таким образом, сообщения должны содержать только сообщения чата и/или системные сообщения, которые обеспечивают дополнительный контекст для модели (например, дату и время и т. д.).
llama-cpp-python поддерживает, например, llava1.5, которые позволяют языковой модели считывать информацию как из текста, так и из изображений.
Ниже приведены поддерживаемые мультимодальные модели и соответствующие им обработчики чата (API Python) и форматы чата (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 |
| лунная мечта2 | MoondreamChatHandler | moondream2 |
| наноллава | NanollavaChatHandler | nanollava |
| лама-3-видение-альфа | Llama3VisionAlphaChatHandler | llama-3-vision-alpha |
| минипм-v-2.6 | MiniCPMv26ChatHandler | minicpm-v-2.6 |
Затем вам нужно будет использовать собственный обработчик чата для загрузки модели клипа и обработки сообщений и изображений чата.
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" } }
]
}
]
) Вы также можете вытащить модель из Hugging Face Hub, используя метод from_pretrained .
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.
Изображения можно передавать как URI данных в кодировке Base64. В следующем примере показано, как это сделать.
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: уровень токена и уровень последовательности . Вложения на уровне последовательности создаются путем «объединения» вложений на уровне токена, обычно путем их усреднения или использования первого токена.
Модели, которые явно ориентированы на внедрение, обычно по умолчанию возвращают внедрения на уровне последовательности, по одному для каждой входной строки. Модели без внедрения, например модели, предназначенные для генерации текста, обычно возвращают только внедрения на уровне токена, по одному для каждого токена в каждой последовательности. Таким образом, размерность возвращаемого типа будет на единицу выше для вложений на уровне токена.
В некоторых случаях можно управлять поведением пула, используя флаг pooling_type при создании модели. Вы можете обеспечить внедрение уровня токена из любой модели, используя LLAMA_POOLING_TYPE_NONE . Обратное: получить модель, ориентированную на генерацию, для получения вложений на уровне последовательности в настоящее время невозможно, но вы всегда можете выполнить объединение вручную.
Контекстное окно моделей Llama определяет максимальное количество токенов, которые могут быть обработаны одновременно. По умолчанию установлено 512 токенов, но его можно изменить в соответствии с вашими требованиями.
Например, если вы хотите работать с более крупными контекстами, вы можете расширить окно контекста, установив параметр n_ctx при инициализации объекта Llama:
llm = Llama ( model_path = "./models/7B/llama-model.gguf" , n_ctx = 2048 ) llama-cpp-python предлагает веб-сервер, который призван заменить OpenAI API. Это позволяет вам использовать модели, совместимые с llama.cpp, с любым клиентом, совместимым с OpenAI (языковыми библиотеками, службами и т. д.).
Чтобы установить серверный пакет и начать работу:
pip install ' llama-cpp-python[server] '
python3 -m llama_cpp.server --model models/7B/llama-model.ggufКак и в разделе «Аппаратное ускорение» выше, вы также можете установить поддержку графического процессора (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 .
Вероятно, вы также захотите установить формат приглашения. Для чата используйте
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 'Образ 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:latestDocker на termux (требуется root) в настоящее время является единственным известным способом запустить его на телефонах, см. проблему поддержки termux.
Справочник по API
Низкоуровневый API — это прямая привязка ctypes к C API, предоставляемая llama.cpp . Весь низкоуровневый API можно найти в llama_cpp/llama_cpp.py, и он напрямую отражает C API в llama.h.
Ниже приведен краткий пример, демонстрирующий, как использовать низкоуровневый API для токенизации приглашения:
import llama_cpp
import ctypes
llama_cpp . llama_backend_init ( 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 , llama_cpp . c_bool ( True ))
llama_cpp . llama_free ( ctx )Посетите папку примеров, чтобы увидеть больше примеров использования низкоуровневого API.
Документация доступна по адресу https://llama-cpp-python.readthedocs.io/. Если вы обнаружите какие-либо проблемы с документацией, пожалуйста, откройте проблему или отправьте запрос.
Этот пакет находится в активной разработке, и я приветствую любые вклады.
Для начала клонируйте репозиторий и установите пакет в режиме редактирования/разработки:
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 , проверив нужный коммит в подмодулеvendor vendor/llama.cpp , а затем запустив make clean и pip install -e . снова. Любые изменения в API llama.h потребуют внесения изменений в файл llama_cpp/llama_cpp.py чтобы он соответствовал новому API (дополнительные изменения могут потребоваться в другом месте).
