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

Источник: https://modelium.tech/zhurnal/llama-cpp/

llama.cpp подходит, если нужен управляемый локальный запуск GGUF-моделей через командную строку или HTTP API без обязательного графического интерфейса. Для первого теста установите готовую сборку, возьмите небольшую совместимую GGUF-модель, проверьте ответ через `llama cli`, а затем поднимите `llama serve`. Размер файла весов не равен минимальной RAM или VRAM: отдельно учитываются контекст, KV-кэш и размещение слоёв между CPU и GPU.

**Граница проверки.** Инструкция сверена с официальной документацией стабильного тега llama.cpp `v0.4.1` на 22 сентября 2026 года. Modelium не запускал команды на собственном железе и не измерял скорость, качество ответов, RAM или VRAM. Перед рабочим внедрением зафиксируйте версию runtime, модель, 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](#src-s1) [s4](#src-s4) [s5](#src-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](#src-s2) [s3](#src-s3).

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

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

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

Официальная инструкция перечисляет готовые пакеты conda-forge для Windows, macOS и Linux, Winget для Windows, Homebrew и другие менеджеры [s2](#src-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](#src-s2). После установки убедитесь, что dispatcher и подкоманды находятся в `PATH`:

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

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

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

Базовая CPU-сборка через CMake описана двумя командами [s3](#src-s3):

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если исходная модель опубликована не в GGUF, документация направляет к Python-конвертерам репозитория, а отдельный quantize guide показывает явный `--outtype` и напоминает установить Python requirements [s7](#src-s7) [s8](#src-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](#src-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](#src-s8). Сравнивайте кванты одной модели на одинаковых входных данных и не переносите результат на другую архитектуру без проверки.

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

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

Минимальная команда сервера [s1](#src-s1) [s5](#src-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](#src-s5). Проверяйте нужный клиентом endpoint отдельно: совместимость интерфейса не означает одинаковые ответы с облачными моделями.

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

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

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

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

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

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

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

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

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

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

- `llama cli --help` и `llama serve --help` выполняются без ошибки.

- В логе загрузки указан ожидаемый GGUF-файл.

- Короткий CLI-запрос завершается полным ответом.

- Ответ соответствует заранее заданному критерию, а не просто содержит текст.

- Сервер после загрузки возвращает HTTP 200 на `/health` [s5](#src-s5).

- Web UI открывается локально, а API-клиент видит нужный endpoint.

- Система не уходит в постоянный swap и не завершает процесс из-за памяти.

- В журнале сохранены версия llama.cpp, ОС, CPU, GPU, драйвер, модель, квант, контекст и команда.

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

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

## Источники

1. [llama.cpp v0.4.1 — README](https://github.com/ggml-org/llama.cpp/blob/v0.4.1/README.md) — получено 2026-09-22
2. [llama.cpp v0.4.1 — Installation](https://github.com/ggml-org/llama.cpp/blob/v0.4.1/docs/install.md) — получено 2026-09-22
3. [llama.cpp v0.4.1 — Build](https://github.com/ggml-org/llama.cpp/blob/v0.4.1/docs/build.md) — получено 2026-09-22
4. [llama.cpp v0.4.1 — llama-cli](https://github.com/ggml-org/llama.cpp/blob/v0.4.1/tools/cli/README.md) — получено 2026-09-22
5. [llama.cpp v0.4.1 — llama-server](https://github.com/ggml-org/llama.cpp/blob/v0.4.1/tools/server/README.md) — получено 2026-09-22
6. [llama.cpp v0.4.1 — Docker](https://github.com/ggml-org/llama.cpp/blob/v0.4.1/docs/docker.md) — получено 2026-09-22
7. [llama.cpp v0.4.1 — Working with models](https://github.com/ggml-org/llama.cpp/blob/v0.4.1/docs/models.md) — получено 2026-09-22
8. [llama.cpp v0.4.1 — Quantize](https://github.com/ggml-org/llama.cpp/blob/v0.4.1/tools/quantize/README.md) — получено 2026-09-22