Как поставить llama-cpp-python, включить сборку под видеокарту, загрузить GGUF-модель прямо с Hugging Face и поднять OpenAI-совместимый сервер одной командой.

Если локальная модель нужна внутри своего кода, а не в чужом приложении, llama-cpp-python обычно оказывается самым коротким путём. Это питоновские привязки к llama.cpp: тот же движок, те же GGUF-файлы, но вызывается всё из скрипта.

Один нюанс портит первое впечатление у половины пользователей, и лучше знать о нём заранее.

Установка

Базовая команда выглядит безобидно:

pip install llama-cpp-python

Вот тут и прячется нюанс: по умолчанию пакет собирает llama.cpp из исходников. На машине без компилятора установка падает, а на машине с компилятором занимает заметное время. Если сборка сломалась, добавь --verbose — иначе причина остаётся за кулисами.

Второй момент: собранная так версия работает на процессоре. Видеокарта сама себя не включит.

Как включить видеокарту

Два пути.

Задать флаги сборки через переменную окружения:

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/cu121

Вместо cu121 подставляется своя версия — доступны сборки под разные выпуски CUDA. Второй путь быстрее и ломается реже, поэтому начинать стоит с него.

◆

Версия CUDA в адресе должна соответствовать той, что стоит у тебя, а не самой новой в списке. Несовпадение проявляется не при установке, а при первом запуске модели — и сообщение об ошибке будет про библиотеки, а не про версию.

Модель прямо с Hugging Face

Файл можно не скачивать руками. Метод from_pretrained берёт GGUF из репозитория по маске имени (нужен установленный huggingface-hub):

from llama_cpp import Llama

llm = Llama.from_pretrained(
    repo_id="lmstudio-community/Qwen3.5-0.8B-GGUF",
    filename="*Q8_0.gguf"
)

Удобно для экспериментов: меняешь строку с моделью и сравниваешь. Про то, что означают метки вроде Q8_0 и какую выбрать, есть разбор формата GGUF.

Свой сервер одной командой

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

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

Документация API открывается на http://localhost:8000/docs.

По сути это альтернатива готовому llama-server из сборок llama.cpp. Разница в том, что здесь всё живёт внутри питоновского окружения, а значит проще встраивается в существующий проект и управляется теми же зависимостями. Если обвязка на Python не нужна, обычный llama-server проще: не требует ни pip, ни сборки.

Что выбрать

Задача	Инструмент
Модель вызывается из своего Python-кода	`llama-cpp-python`
Нужен только локальный API для других программ	`llama-server` из сборок
Нужен чат и переключение моделей мышкой	LM Studio или Jan
Нужен агент, который делает работу	см. ниже

Про обвязку, которую пишут все

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

Через месяц выясняется, что ты пишешь агента. Это нормальный путь и полезный опыт, но стоит хотя бы раз сравнить его с готовым решением, прежде чем вкладывать в него ещё три вечера.

Дока — этот агент в собранном виде: работа с файлами и терминалом, ведение задачи через несколько шагов, MCP-серверы, расписания и локальная модель, которая ставится из интерфейса. Питоновский код при этом никуда не девается: агент умеет его запускать, так что твои скрипты становятся инструментами, а не заменяются.

Разумная проверка — взять задачу, под которую ты собирался писать очередной скрипт, и прогнать её в агенте. Если справится, скрипт можно не писать. Если нет, llama-cpp-python никуда не денется.

llama-cpp-python: локальная модель из Python за десять минут