Методы установки llama-cpp-python с помощью Wheel (whl) файлов

Раздел: Инструменты -> Установка библиотек

Введение в установку llama-cpp-python через whl

Библиотека llama-cpp-python предоставляет Python обёртку для llama.cpp, позволяя запускать большие языковые модели (LLM) на CPU и GPU. Установка через предварительно собранные wheel файлы (whl) избавляет от необходимости компилировать код на месте, что особенно удобно на Windows. Основной репозиторий с готовыми сборками находится на GitHub в разделе Releases. Далее приведены различные подходы к установке.

Основное решение: установка из официальных whl сборок

Как установить llama-cpp-python без компиляции на своей платформе?

Самый надёжный способ - найти подходящий whl файл в Releases и выполнить прямую установку через pip. Файлы помечены метками cpu, cuda, vulkan и др. Для этого требуется Python версии 3.8–3.11 (на октябрь 2024 поддерживаются только эти версии). Пример команды для CPU сборки под Windows, Python 3.10 64-bit:

pip install https://github.com/abetlen/llama-cpp-python/releases/download/v0.2.78/llama_cpp_python-0.2.78-cp310-cp310-win_amd64.whl

как установить библиотеку в python (установка библиотеки в python)

Пояснение: в имени файла указана версия Python (cp310), платформа (win_amd64) и версия библиотеки. Если ваша конфигурация отличается, следует подобрать соответствующий whl.

Типичные проблемы и их решения

  • Ошибка “No matching distribution found”: значит, нет подходящего whl для вашей версии Python/платформы. Проверьте список доступных файлов. Для нестандартных конфигураций (например, Python 3.12) потребуется собрать из исходников или дождаться появления поддержки.
  • Ошибка “ImportError: DLL load failed”: на Windows может не хватать зависимостей (например, C++ Redistributable или CUDA Runtime). Установите Microsoft Visual C++ Redistributable или, если используется GPU, проверьте совместимость версий CUDA Toolkit (рекомендуется 11.x или 12.x).
  • Ошибка “pip is not recognized”: требуется добавить Python в PATH или использовать полный путь к pip.

Вариант 1: установка с поддержкой GPU (NVIDIA CUDA)

Как использовать llama-cpp-python с графическим ускорителем NVIDIA?

Для GPU ускорения нужен whl с пометкой cuda. Убедитесь, что на системе установлена совместимая версия CUDA Toolkit (обычно 11.x или 12.x). Пример для CUDA 12.1 и Python 3.10:

pip install https://github.com/abetlen/llama-cpp-python/releases/download/v0.2.78/llama_cpp_python-0.2.78-cp310-cp310-win_amd64.whl --force-reinstall --no-deps

Llama cpp python whl (установка llama-cpp-python через whl)

Дополнительно может потребоваться флаг --extra-index-url для указания источника, если в релизе несколько вариантов. После установки проверьте, что библиотека видит CUDA: import llama_cpp; print(llama_cpp.llama_supports_gpu()).

Типичные проблемы

  • “Could not find cudart”: укажите путь к CUDA Runtime через переменную окружения CUDA_PATH.
  • Ошибка при импорте: убедитесь, что версия CUDA соответствует той, под которую собран whl (обычно указано в имени файла, например, cuda11 или cuda12).

Вариант 2: установка с OpenBLAS (Linux)

Как ускорить работу на CPU с помощью OpenBLAS?

Для систем Linux доступны сборки с OpenBLAS. Они обычно помечены как cpu_blas или openblas. Пример для Ubuntu, Python 3.10:

pip install https://github.com/abetlen/llama-cpp-python/releases/download/v0.2.78/llama_cpp_python-0.2.78-cp310-cp310-linux_x86_64.whl

Opencv python windows (установка opencv для python на windows)

Перед установкой может потребоваться установить системные пакеты OpenBLAS. На Ubuntu/Debian: sudo apt-get install libopenblas-dev.

Вариант 3: локальная установка из скачанного whl файла

Как установить библиотеку из ранее загруженного wheel файла?

Если требуется установка в офлайн-среде или контроль над версией, можно скачать whl вручную, а затем выполнить:

pip install /путь/к/файлу/llama_cpp_python-0.2.78-cp310-cp310-linux_x86_64.whl

Requests python 3.13 (использование requests с python 3.13)

Или на Windows:

pip install C:\Downloads\llama_cpp_python-0.2.78-cp310-cp310-win_amd64.whl

Python requests windows (установка requests на windows)

Такой способ удобен при использовании менеджеров зависимостей типа poetry или pipenv - достаточно указать путь в файле конфигурации.

Вариант 4: сборка из исходников с собственными флагами

Как собрать библиотеку для нестандартной конфигурации (например, Python 3.12 или ARM)?

Если подходящего whl нет, допускается сборка из исходного кода. Для этого потребуется компилятор C++ (gcc, clang или MSVC) и, возможно, флаги для включения GPU/OpenBLAS. Базовая команда:

pip install llama-cpp-python --force-reinstall --no-cache-dir --verbose --config-settings=--force-reinstall

как установить requests в python (установка библиотеки requests)

Для включения CUDA нужно предварительно установить переменную CMAKE_ARGS:

export CMAKE_ARGS="-DLLAMA_CUBLAS=on"
pip install llama-cpp-python --force-reinstall --no-cache-dir

как установить matplotlib в python (установка библиотеки matplotlib)

На Windows потребуется установить Visual Studio Build Tools. Сборка может занять несколько минут и требует наличия интернета для скачивания зависимостей.

Типичные проблемы при сборке

  • “CMake was not found”: установите cmake (например, pip install cmake).
  • “fatal error: cuda.h: No such file or directory”: проверьте, что CUDA Toolkit установлен и его bin добавлен в PATH.
  • Ошибки линковки: обычно решаются установкой соответствующих библиотек разработки (libcublas-dev, libopenblas-dev и т.д.).

Вариант 5: установка через conda (альтернативный менеджер)

Как установить библиотеку через conda, если не удаётся через pip?

Хотя официального канала conda нет, существуют сторонние сборки, например, от conda-forge. Команда:

conda install -c conda-forge llama-cpp-python

Однако такие сборки могут отставать по версии и не всегда поддерживают GPU. Рекомендуется использовать pip.

Расширенные примеры установки и проверки llama-cpp-python

Пример 1: установка CPU версии на Windows с явным указанием версии

Предположим, система - Windows 10, Python 3.10 64-bit. Выполняем в командной строке (cmd):

Пример 
pip install https://github.com/abetlen/llama-cpp-python/releases/download/v0.2.78/llama_cpp_python-0.2.78-cp310-cp310-win_amd64.whl

Ожидаемый вывод (сокращён):

Collecting llama-cpp-python==0.2.78
  Downloading llama_cpp_python-0.2.78-cp310-cp310-win_amd64.whl (15.2 MB)
Installing collected packages: llama-cpp-python
Successfully installed llama-cpp-python-0.2.78

Пример 2: установка с GPU (CUDA 12) на Windows

В данном случае файл может называться llama_cpp_python-0.2.78-cp310-cp310-win_amd64_cuda12.whl. Команда:

Пример 
pip install https://github.com/abetlen/llama-cpp-python/releases/download/v0.2.78/llama_cpp_python-0.2.78-cp310-cp310-win_amd64_cuda12.whl --force-reinstall

После установки проверяем поддержку GPU в Python:

Пример 
import llama_cpp
print("GPU support:", llama_cpp.llama_supports_gpu())
GPU support: True

Пример 3: установка из локального whl на Linux с проверкой зависимостей

Скачиваем файл llama_cpp_python-0.2.78-cp310-cp310-linux_x86_64.whl в каталог /home/user/wheels/. Выполняем:

Пример 
pip install /home/user/wheels/llama_cpp_python-0.2.78-cp310-cp310-linux_x86_64.whl

Если возникают ошибки о нехватке библиотек, следует установить gcc и python3-dev:

Пример 
sudo apt update && sudo apt install build-essential python3-dev

Пример 4: сборка с поддержкой OpenBLAS на Linux

Установка OpenBLAS и компиляция:

Пример 
sudo apt-get install libopenblas-dev
CMAKE_ARGS="-DLLAMA_OPENBLAS=on" pip install llama-cpp-python --no-cache-dir --verbose

Результат может выглядеть так (сокращённый вывод):

-- The C compiler identification is GNU 11.4.0
-- Found OpenBLAS: /usr/lib/x86_64-linux-gnu/libopenblas.so
-- Configuring done
-- Generating done
-- Build files have been written to /tmp/pip-install-xxxx
...
Successfully built llama-cpp-python

Пример 5: проверка работоспособности после установки

Базовый тест с загрузкой небольшой модели (например, tinyllama-1.1b). Скачиваем модель (GGUF) и запускаем:

Пример 
from llama_cpp import Llama
llm = Llama(model_path="path/to/tinyllama-1.1b.Q4_K_M.gguf")
output = llm("Hello, how are you?", max_tokens=32)
print(output["choices"][0]["text"])
 I am fine, thank you! How can I assist you today?

Пример 6: типичная ошибка несовместимости версии Python и её исправление

Попытка установить whl для Python 3.10 на Python 3.12 даст ошибку:

Пример 
pip install llama_cpp_python-0.2.78-cp310-cp310-win_amd64.whl
ERROR: llama-cpp-python-0.2.78-cp310-cp310-win_amd64.whl is not a supported wheel on this platform.

Решение: использовать сборку для Python 3.12 или собрать из исходников. На момент написания статьи для Python 3.12 нет официальных whl; альтернатива - собрать через CMAKE_ARGS.

установка llama-cpp-python через whl - comments

En
Llama cpp python whl (python)