llama.cpp: установка, GGUF и локальный сервер

Когда стоит выбрать llama.cpp

llama.cpp — низкоуровневый runtime для локального инференса, ориентированный на GGUF-модели и работу на разном железе. В README стабильной версии основные команды показаны как llama cli и llama serve; документация инструментов и контейнеров также использует названия executable llama-cli и llama-server. Проект поддерживает CPU, Metal, CUDA, HIP, Vulkan, SYCL и гибридный режим CPU+GPU s1 s4 s5.

Выбирайте llama.cpp, если вам нужен хотя бы один из сценариев:

• явный контроль над файлом модели и параметрами запуска;
• локальная командная строка без обязательного desktop-приложения;
• OpenAI-совместимый HTTP endpoint для своей программы;
• сборка под конкретный GPU-backend;
• конвертация или квантизация модели в GGUF;
• запуск на машине, где готовое приложение вроде LM Studio избыточно.

Этот уровень контроля требует больше ручной работы. llama.cpp не выбирает модель за пользователя и не гарантирует, что любой GGUF-файл подходит имеющемуся компьютеру. Условия использования весов проверяйте в карточке и лицензии конкретной модели: наличие совместимого файла означает техническую совместимость формата, а не разрешение для любого сценария.

Если нужен более короткий путь «установить → скачать модель по имени → запустить API», сравните llama.cpp с Ollama. Если важен графический поиск и настройка моделей, удобнее начать с LM Studio. llama.cpp полезен, когда требуется управлять backend, сборкой, файлом GGUF и сервером напрямую.

Что проверить до установки

Сначала определите четыре вещи: операционную систему, процессор, доступный GPU-backend и контрольную задачу. Пакеты conda-forge отдельно перечисляют CUDA, Vulkan и Apple Metal, а сборка из исходников включает backend явными параметрами CMake; наличие видеокарты само по себе не означает, что установленный вариант использует её s2 s3.

Для первого теста не начинайте с самой крупной модели. Возьмите небольшой GGUF-файл с понятной карточкой, лицензией и назначением. Размер файла показывает объём скачивания и хранения, но не точный минимум памяти: runtime отдельно настраивает размер контекста, тип KV-кэша и число слоёв, размещаемых в VRAM. Гибридный CPU+GPU режим позволяет частично ускорять модели, которые больше доступной VRAM, но не превращает размер файла в формулу RAM или VRAM s1 s4.

Заранее задайте проверяемый результат. Например: модель должна ответить на короткий вопрос на русском, вернуть три поля в заданном формате или завершить простой фрагмент кода. Так можно отделить успешную установку от качества конкретной модели.

Как установить готовую сборку

Официальная инструкция перечисляет готовые пакеты conda-forge для Windows, macOS и Linux, Winget для Windows, Homebrew и другие менеджеры s2. Для первого запуска пакет обычно проще сборки из исходников, потому что не требует настройки CMake и компилятора.

На macOS документирован Homebrew:

brew install llama.cpp

Для Windows документирован Winget:

winget install llama.cpp

Для Windows, macOS и Linux также доступны сборки conda-forge; в документе отдельно перечислены варианты CUDA и Vulkan для Windows/Linux и Metal для macOS s2. После установки убедитесь, что dispatcher и подкоманды находятся в PATH:

llama --help
llama cli --help
llama serve --help

Если shell не находит executable, сначала исправьте путь установки. Не переходите к диагностике модели, пока сами программы не запускаются.

Как собрать llama.cpp из исходников

Базовая CPU-сборка через CMake описана двумя командами s3:

cmake -B build
cmake --build build --config Release

После сборки executable обычно находятся в каталоге build/bin. Точный путь зависит от платформы и генератора сборки.

На Apple Silicon Metal включён по умолчанию. Документация позволяет отключить Metal при сборке через -DGGML_METAL=OFF. Параметр --n-gpu-layers 0 оставляет слои модели вне VRAM, но отдельные операции всё ещё могут использовать GPU; для полного отключения устройств документирован --device none s3. Сначала проверьте стандартную сборку, а специальные параметры добавляйте только при понятной причине.

Для NVIDIA используется CUDA-сборка:

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

Она требует установленного CUDA toolkit. Для совместимости документация предлагает учитывать compute capability GPU и при необходимости явно задавать CMAKE_CUDA_ARCHITECTURES s3.

Для Vulkan документирован такой вариант:

cmake -B build -DGGML_VULKAN=1
cmake --build build --config Release

Не включайте несколько незнакомых backend одновременно при первом тесте. Сначала добейтесь работающей CPU-сборки или одного ожидаемого GPU-backend, затем сравнивайте конфигурации на одной модели и одном промпте.

Как выбрать и проверить GGUF-модель

llama.cpp требует GGUF. Если репозиторий уже содержит подходящий файл, конвертация не нужна. Проверьте автора, назначение модели, chat template, лицензию, размер конкретного файла и источник квантизации s7 s4. Community-конверсия не становится официальным выпуском автора модели только потому, что доступна на Hugging Face.

Проект позволяет запустить совместимую модель с Hugging Face через параметр -hf. В документации моделей приведён такой пример s7:

llama cli -hf ggml-org/gemma-3-1b-it-GGUF

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

Если у вас уже есть локальный файл, для одноразового контрольного запроса используйте -m и -p; оба параметра документированы в help llama-cli s4:

llama cli -m ./model.gguf -p "Ответь одним словом: столица Франции?" --single-turn

--single-turn завершает процесс после одного ответа; без него CLI может остаться в диалоговом режиме s4. Сохраните команду, полный лог загрузки и ответ. Успешный тест означает, что загрузился именно ожидаемый GGUF-файл, runtime не завершился с ошибкой и модель выполнила заранее заданное условие. Для диалогового режима учитывайте chat template: по умолчанию CLI берёт его из metadata модели, а при необходимости позволяет указать шаблон явно s4.

Когда нужны конвертация и квантизация

Если исходная модель опубликована не в GGUF, документация направляет к Python-конвертерам репозитория, а отдельный quantize guide показывает явный --outtype и напоминает установить Python requirements s7 s8. Пример из документации:

python convert_hf_to_gguf.py --outfile gemma-4-E2B-it-bf16.gguf --outtype bf16 --remote google/gemma-4-E2B-it

После получения высокоточного GGUF можно создать квантованный вариант инструментом llama-quantize s8:

./build/bin/llama-quantize gemma-4-E2B-it-bf16.gguf gemma-4-E2B-it-Q4_K_M.gguf Q4_K_M

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

Если скрипт не распознаёт архитектуру, не переименовывайте файлы и не подменяйте metadata вручную без понимания формата: найдите ревизию llama.cpp с поддержкой этой архитектуры или готовую конверсию с прозрачным происхождением. Подробный выбор квантов лучше выносить в отдельный материал о GGUF, чтобы tool-page не дублировала самостоятельный интент квантизации.

Как запустить локальный API-сервер

Минимальная команда сервера s1 s5:

llama serve -m ./model.gguf --port 8080

После загрузки web UI доступен по адресу http://localhost:8080. Разработчики заявляют OpenAI-compatible routes и документируют, среди прочего, /v1/chat/completions, /v1/completions, /v1/embeddings и /v1/models s5. Проверяйте нужный клиентом endpoint отдельно: совместимость интерфейса не означает одинаковые ответы с облачными моделями.

Перед подключением приложения проверьте готовность:

curl -f http://localhost:8080/health

По документации /health отвечает HTTP 200, когда сервер готов принимать запросы; во время загрузки модели возможен 503 s5. Затем откройте web UI и выполните короткий запрос. Только после этого меняйте base URL в клиенте.

Не публикуйте порт 8080 в интернет без отдельной защиты. Для доступа из локальной сети определите адрес привязки, firewall, аутентификацию, допустимые данные и журналирование. Локальный запуск модели не делает любой сетевой endpoint безопасным автоматически.

Для embeddings сервер нужно запускать с --embedding, причём документация рекомендует использовать модель, специально обученную для embeddings s5. Не используйте обычную чат-модель как embedding-модель только потому, что endpoint технически отвечает.

Когда использовать Docker

Три базовых официальных образа разделены по назначению: full, light и server; дополнительно опубликованы CUDA, ROCm, Vulkan, SYCL и другие варианты s6. Docker удобен для фиксированной среды и серверного запуска, но не устраняет аппаратные зависимости. CUDA-контейнер требует NVIDIA Container Toolkit, а каталог с моделью нужно передать в контейнер и указать через -m s6.

Начинайте с Docker, если окружение уже контейнеризировано или нужно повторяемо развернуть сервер. Для первого локального теста на ноутбуке готовый binary или пакетный менеджер обычно дают меньше дополнительных переменных.

Как понять, что запуск действительно успешен

Проверьте результат по шагам:

1. llama cli --help и llama serve --help выполняются без ошибки.
2. В логе загрузки указан ожидаемый GGUF-файл.
3. Короткий CLI-запрос завершается полным ответом.
4. Ответ соответствует заранее заданному критерию, а не просто содержит текст.
5. Сервер после загрузки возвращает HTTP 200 на /health s5.
6. Web UI открывается локально, а API-клиент видит нужный endpoint.
7. Система не уходит в постоянный swap и не завершает процесс из-за памяти.
8. В журнале сохранены версия llama.cpp, ОС, CPU, GPU, драйвер, модель, квант, контекст и команда.

Если CPU-запуск работает, а GPU-вариант падает, отдельно проверьте выбранный backend, драйвер, доступную VRAM и параметры offload: это диагностические направления, а не доказательство одной причины. Если модель загружается, но диалог размечен неправильно, проверьте chat template s4. Если сервер отвечает 503 сразу после старта, дождитесь окончания загрузки и повторите /health s5. При нехватке VRAM уменьшение --n-gpu-layers переносит больше слоёв на CPU и может увеличить нагрузку на RAM; при нехватке общей памяти сначала уменьшайте модель, квант или контекст s4.

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