Содержание
  1. Что такое llama-cpp-python и чем отличается от llama.cpp и Ollama
  2. Требования: версия Python, компилятор, CUDA Toolkit, модель GGUF
  3. Установка через pip на CPU и проверка импорта
  4. Сборка с CUDA и готовые wheel для Windows: откуда брать и как проверить
  5. llama-cpp-python в pyproject.toml и виртуальном окружении
  6. Первый запуск: загрузить GGUF, получить ответ, поднять сервер
  7. Частые вопросы
Гайды

Как установить llama-cpp-python: pip, CUDA и Windows

14 октября 2026 · 11 минут чтения

Проверка фактов
Юлия Найпак
Методист по автоматизации. Сверяет паспорт инструмента с документацией вендора.
Автор
Редакция
Коллектив авторов, редакторов и иллюстраторов статей на сайте блога онлайн-университета «Зерокодер». Пишем…

Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.

Материал редакции Зерокодера. Счёт по выдаче снят собственным прогоном 14 октября 2026 года; цитаты источников приведены дословно. Обновлено: октябрь 2026.

Как установить llama-cpp-python: pip, CUDA и Windows — три сценария одной задачи. Базовый путь: pip install llama-cpp-python в виртуальном окружении даёт CPU-версию. Для GPU сборка идёт из исходников с переменной CMAKE_ARGS и флагами CUDA. На Windows headless-установка опирается на готовые wheel, собранные под конкретную версию Python и CUDA.

Собственный прогон 14 октября 2026 года по запросу «Как установить llama-cpp-python: pip, CUDA и Windows» показал: текст отдали 8 из 10 страниц выдачи, медиана объёма читаемого текста — 1543 слова, метку 2026 года несут 8 из 8 прочитанных страниц. Ниже — порядок действий, требования и проверки. Мы скачали топ-10 выдачи DuckDuckGo (ru-RU) по запросу «Как установить llama-cpp-python: pip, CUDA и Windows»: текст отдали 8 из 10.

Что такое llama-cpp-python и чем отличается от llama.cpp и Ollama

llama-cpp-python — это Python-привязка к llama.cpp. Она даёт доступ к движку инференса из кода на Python: загрузка GGUF-модели, генерация ответа, локальный сервер с OpenAI-совместимым API. Сам llama.cpp — это C/C++ движок, который собирается в бинарники и запускается из терминала. Пакет llama-cpp-python включает движок как зависимость и собирается вместе с ним.

Отличие от llama.cpp в точке входа. Бинарники llama.cpp удобны для запуска из командной строки, пакет llama-cpp-python — для вызова из Python-скриптов и веб-сервисов. Отличие от Ollama в уровне контроля. Автор инструкции по установке на Windows в репозитории на GitHub отмечает: Ollama прост в использовании, однако сервер ограничивает набор ролей в промпте; для моделей, дообученных под вызов функций, потребовалась ручная переработка пользовательских промптов, что увеличило расход токенов. Тот же автор добавляет, что при достаточности функциональности Ollama остаётся удобным сервером инференса.

Практический вывод: llama-cpp-python выбирают, когда нужен прямой доступ к параметрам движка и свои роли в шаблоне чата. Если задача — быстро поднять модель без сборки, смотрите Как подключить Qwen Code к Ollama. Если нужен локальный запуск другой модели из кода, пригодится Как установить DeepSeek Coder локально.

Требования: версия Python, компилятор, CUDA Toolkit, модель GGUF

Требования зависят от сценария. Для CPU-установки нужны Python, pip и компилятор C++: по умолчанию пакет собирает llama.cpp из исходников, и на машине без компилятора установка падает. Для сборки с CUDA нужен компилятор C++, CUDA Toolkit и переменные окружения сборки. В issue №1963 репозитория abetlen/llama-cpp-python на GitHub автор приводит рабочую конфигурацию: Python 3.12.9 с замечанием, что версия 3.11 и 3.13, вероятно, тоже подойдут; CUDA Toolkit 12.8.0, установленный без изменения драйверов PhysX, Display и HD Audio; видеокарты RTX 3080 и RTX A4000. В том же обсуждении перечислены компоненты Visual Studio: «Desktop development with C++» и «Linux and embedded development with C++».

Отдельная инструкция по установке llama.cpp с CUDA на Windows в репозитории swamikannan на GitHub фиксирует версию CUDA Toolkit 12.5 и замечание про совместимость с PyTorch: актуальная на момент написания поддержка PyTorch — CUDA 12.1. Там же разобрана причина ошибок сборки: доступная для скачивания Community-версия Visual Studio оказалась несовместима даже с последней версией CUDA, и автор связал с этим большую часть сбоев.

Модель нужна в формате GGUF — это квантизированный формат, который читает движок. Файл скачивается заранее и передаётся в код по пути. Требования к железу определяет размер модели и тип квантизации: чем меньше бит на вес, тем меньше памяти нужно.

Сценарий Что нужно Что даёт
CPU Python, pip, компилятор C++ Установка одной командой, работа на процессоре
CUDA из исходников Компилятор C++, CUDA Toolkit, переменные сборки Ускорение на GPU NVIDIA
Windows wheel Готовая сборка под версию Python и CUDA Отсутствие локальной компиляции

Установка через pip на CPU и проверка импорта

Базовая установка идёт в виртуальное окружение. Порядок действий:

  1. Создайте окружение: python -m venv .venv.
  2. Активируйте его под своей ОС.
  3. Обновите pip: python -m pip install --upgrade pip.
  4. Установите пакет: pip install llama-cpp-python.

Эта команда ставит сборку без CUDA. Движок отработает на процессоре. Проверка импорта — один вызов:

PYTHON3 строки
from llama_cpp import Llama

llm = Llama(model_path="model.gguf", n_ctx=2048)

Отсутствие ошибки на строке импорта означает, что библиотека загрузилась. Ошибка на строке с model.gguf означает, что библиотека установлена, а путь к модели задан неверно.

На Windows полезна отдельная деталь из issue №1963: автор требует выполнять шаги сборки в Command Prompt и отдельно оговаривает, что PowerShell для них не подходит; переменные сборки задаются командой set и действуют только до выхода из текущей сессии CMD.

Виртуальное окружение снимает конфликт версий между проектами. Если пакет нужен одной задаче, его ставят в отдельное окружение.

Сборка с CUDA и готовые wheel для Windows: откуда брать и как проверить

Сборка с CUDA задаётся флагами CMake в переменной CMAKE_ARGS в момент установки. В обзоре llama-cpp-python на doka-ai.ru флаг передаётся прямо в команде установки: CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python; такая запись работает в оболочках Linux и macOS, в CMD переменную задают отдельной командой set. Если сборка падает, флаг --verbose показывает причину. Порядок из issue №1963 на GitHub:

  1. Скачать CUDA Toolkit и Visual Studio с компонентом «Desktop development with C++».
  2. Открыть Command Prompt.
  3. Клонировать репозиторий с подмодулями:
КОД
git clone --recursive -j%NUMBER_OF_PROCESSORS% https://github.com/abetlen/llama-cpp-python.git
  1. Обновить подмодуль движка: git submodule update --remote vendor/llama.cpp.
  2. Задать переменные окружения сборки: set FORCE_CMAKE=1 и set CMAKE_ARGS=-DGGML_CUDA=ON. Автор отмечает, что они временные и сбрасываются при выходе из сессии CMD.
  3. Собрать и поставить пакет: python -m pip install . --no-cache-dir --force-reinstall --upgrade.

Автор issue пишет, что ошибки сборки, которые оставались даже с правильными инструментами, ушли после обновления подмодуля llama.cpp. Один из участников обсуждения получил ошибку о ненайденном Curl. Другой участник обошёл ту же ошибку значением set CMAKE_ARGS=-DGGML_CUDA=ON -DLLAMA_CURL=OFF; сборка у него заняла около пятнадцати минут, потому что он не включил сборку на нескольких ядрах, и ускорение на GPU он подтвердил на моделях Gemma2-9b и Gemma3-12b.

Инструкция swamikannan на GitHub относится к сборке самого llama.cpp и в процедуру установки пакета llama-cpp-python не входит, но в ней разобран общий для Windows сбой: Visual Studio не обнаруживает CUDA при сборке исполняемого файла. Автор связал большинство своих ошибок с несовместимостью Community-версии Visual Studio и CUDA; для связки он копирует файлы интеграции из каталога C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.5\extras\visual_studio_integration\MSBuildExtensions, где номер версии подставляется свой, в каталог BuildCustomizations Visual Studio.

Готовые wheel для Windows. Сборка из исходников занимает время и требует полного тулчейна, поэтому есть предсобранные wheel-файлы. В обзоре llama-cpp-python на doka-ai.ru их ставят из индекса автора пакета: pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121, где cu121 меняется на свою версию CUDA. Там же предупреждение: версия CUDA в адресе должна совпадать с установленной, и несовпадение проявляется при первом запуске модели ошибкой про библиотеки. Порядок работы с ними:

Шаг Действие Проверка
1 Определить версию Python python --version
2 Определить версию CUDA nvcc --version
3 Найти wheel под эту пару Совпадение тега cp3XX и бэкенда
4 Установить файл pip install ./файл.whl
5 Проверить импорт from llama_cpp import Llama

Проверка источника wheel обязательна: файл запускает нативный код. Смотрите на автора сборки, на совпадение версии Python и на заявленный бэкенд CUDA. Сборка под другую версию Python даст отказ на этапе установки.

llama-cpp-python в pyproject.toml и виртуальном окружении

В проекте пакет объявляют зависимостью в pyproject.toml. Для CPU-сценария достаточно обычной записи зависимости. Для CUDA нужны переменные сборки, поэтому на практике применяют один из двух подходов: держать зависимость в файле и передавать CMAKE_ARGS при установке, либо описывать установку отдельной командой в инструкции проекта.

Виртуальное окружение решает три задачи. Оно изолирует пакет от системного Python, фиксирует версию сборки под конкретный проект и позволяет пересобрать пакет, не затрагивая остальные задачи на машине. Если в одном окружении стоят две сборки llama-cpp-python с разными бэкендами, конфликт решается пересозданием окружения.

Зависимость в файле проекта удобна при переносе: коллега или сервер ставит пакет одной командой. Плата за это — неявная зависимость от тулчейна на машине установки: сборка с CUDA требует компилятора и CUDA Toolkit на каждой новой системе.

Отдельная тонкость — версия. Пакет развивается вместе с движком, и обновление подмодуля llama.cpp в issue №1963 названо условием успешной сборки. Если сборка падает с ошибками компиляции внутри vendor\llama.cpp, первым шагом обновите подмодуль: в issue №1963 этот шаг снял такие ошибки.

Первый запуск: загрузить GGUF, получить ответ, поднять сервер

Первый вызов из кода. Модель в GGUF передаётся по пути, контекст задаётся в конструкторе:

PYTHON10 строк
from llama_cpp import Llama

llm = Llama(
    model_path="model.gguf",
    n_ctx=2048,
    n_threads=8,
)

out = llm("Кратко объясни, что такое квантизация.", max_tokens=256)
print(out["choices"][0]["text"])

Порядок проверки: сначала импорт, затем загрузка модели, затем один запрос. Ошибка на каждом шаге указывает на свой слой — библиотека, файл модели, параметры генерации.

Сервер. llama-cpp-python умеет поднимать OpenAI-совместимый сервер, и код, написанный под OpenAI API, обращается к локальной модели. В обзоре llama-cpp-python на doka-ai.ru сервер ставится и запускается двумя командами: pip install 'llama-cpp-python[server]' и python3 -m llama_cpp.server --model models/7B/llama-model.gguf, где путь к модели подставляется свой. Документация API после запуска открывается на http://localhost:8000/docs. Инструкция swamikannan на GitHub описывает смежный сценарий для самого llama.cpp: сборку llama-server, запуск с моделью GGUF и первый запрос через библиотеку openai.

Готовый промпт для проверки связки. Задача — убедиться, что модель отвечает осмысленно и с учётом системной роли.

КОД3 строки
Ты — технический ассистент. Отвечай по существу, одним абзацем, без вступлений.
Тема вопроса: [ваша тема].
Сначала назови ключевое ограничение темы, затем дай один практический шаг.

Что менять под себя: [ваша тема] — ваш вопрос; при необходимости добавьте требование к длине ответа и язык. Варианты той же задачи:

  1. Промпт с ролью код-ревьюера: разобрать фрагмент и назвать слабое место.
  2. Промпт-суммаризатор: сжать текст в несколько тезисов.
  3. Промпт-переводчик: перевести абзац и сохранить термины.
  4. Промпт-извлекатель: вытащить из текста даты и сущности.
  5. Промпт-классификатор: отнести обращение к одной из заданных категорий.

Если задача — собрать агента поверх локальной модели, посмотрите Как подключить DeepSeek к Hermes Agent. Для работы с облачным API пригодится Как получить API ключ Z.ai.

Частые вопросы

llama cpp python не ставится, что проверить?
Проверьте версию Python и наличие компилятора. Для сборки с CUDA нужен CUDA Toolkit и переменные сборки. В issue №1963 репозитория на GitHub отдельно указано: шаги выполняются в Command Prompt. Обновите pip перед установкой.

llama cpp python whl — где взять готовую сборку?
Готовые wheel ставят из индекса автора пакета: флаг —extra-index-url с адресом https://abetlen.github.io/llama-cpp-python/whl/cu121, где cu121 меняется на свою версию CUDA. Версия CUDA в адресе должна совпадать с установленной. Проверяйте автора сборки: wheel устанавливает нативный код.

pip install llama cpp python поставил CPU-версию, как включить GPU?
Базовая установка через pip даёт сборку без CUDA. GPU включают двумя путями: пересборкой с флагом -DGGML_CUDA=on в CMAKE_ARGS или готовым wheel под свою версию CUDA через --extra-index-url. После установки проверьте, что загруженная сборка видит GPU.

python cuda llama cpp: какая версия CUDA нужна?
В issue №1963 на GitHub рабочая конфигурация собрана на CUDA Toolkit 12.8.0. В инструкции по llama.cpp с CUDA на Windows указан CUDA Toolkit 12.5. Версию выбирают под драйвер и под совместимость с другими библиотеками проекта.

llama cpp python windows: как поднять сервер?
Пакет умеет запускать OpenAI-совместимый сервер из Python. Сначала убедитесь, что модель GGUF отвечает при прямом вызове из кода, затем поднимайте сервер и обращайтесь к нему по протоколу OpenAI. Клиентский код остаётся тем же.

Читайте также

3 материала