Быстрый старт с llama.cpp: CLI и сервер

llama.cpp — это движок инференса на C/C++ для моделей в формате GGUF: llama-cli для интерактивного чата, llama-completion для скриптованных промптов и llama-server для HTTP API, совместимого с OpenAI.

Если вы всё ещё выбираете между локальным, self-hosted и облачным подходом, начните с основного руководства: Хостинг LLM в 2026: Сравнение локальной, self-hosted и облачной инфраструктуры.

Зачем выбирать llama.cpp в 2026 году

llama.cpp — это лёгкий движок инференса, ориентированный на:

• переносимость между CPU и различными бэкендами GPU,
• предсказуемую задержку на одном устройстве,
• гибкость развёртывания — от ноутбуков до on-prem серверов.

Он особенно полезен, когда вам нужны конфиденциальность и работа в автономном режиме, когда требуется детерминированный контроль над флагами времени выполнения или когда вы хотите интегрировать инференс в более крупную систему без использования тяжёлого Python-стека.

Также полезно понимать llama.cpp даже в том случае, если вы впоследствии выберете серверный рантайм с высокой пропускной способностью. Например, если ваша цель — максимальная пропускная способность на GPU, вам может пригодиться сравнение с vLLM, используя: vLLM Quickstart: Высокопроизводительный сервинг LLM. а также вы можете сравнить инструменты по бенчмаркам в: Ollama vs vLLM vs LM Studio: Лучший способ запуска LLM локально в 2026?.

Если Ollama — это конкретная альтернатива, с которой вы сравниваете llama-server, то пара статей llama.cpp vs Ollama в 2026 — это специальное попарное сравнение с конкретными критериями, когда стоит остаться на Ollama, а когда переходить на прямой llama.cpp.

Установка llama.cpp на Windows, macOS и Linux

Команды ниже соответствуют версии llama.cpp v0.6.0 (5 октября 2026 г.). Каталог для того же рантайма — GGUF инференс на CPU и ускорительных бэкендах, версионируемый по коммиту сборки — находится в справочнике по рантайму llama.cpp на LLM Systems. Существует четыре практических способа установки в зависимости от того, что вам важнее: удобство, переносимость или максимальная производительность.

Установка через менеджеры пакетов

Это самый быстрый способ «просто запустить».

# macOS или Linux
brew install llama.cpp

# Windows
winget install llama.cpp

# macOS (MacPorts)
sudo port install llama.cpp

# macOS или Linux (Nix)
nix profile install nixpkgs#llama-cpp

# Ubuntu (universe). Этот пакет сильно отстаёт от актуальной версии:
# 8681+dfsg против текущей сборки b11433 / v0.6.0, поэтому новых флагов не будет.
sudo apt install llama.cpp-tools

Совет: после установки проверьте наличие инструментов:

llama-cli --version
llama-completion --version
llama-server --version

Установка через предкомпилированные бинарники

Если вам нужна чистая установка без компиляторов, используйте официальные предкомпилированные бинарники, опубликованные в релизах llama.cpp на GitHub. Обычно они покрывают несколько целевых ОС и несколько бэкендов (варианты только для CPU и с поддержкой GPU).

Типичный рабочий процесс:

# 1) Скачайте правильный архив для вашей ОС и бэкенда
# 2) Распакуйте его
# 3) Запустите из распакованной папки

./llama-cli --help
./llama-server --help

Запуск официального контейнера

Проект публикует серверные образы в GitHub Container Registry. Образ для CPU — ghcr.io/ggml-org/llama.cpp:server; образ для CUDA — :server-cuda. Контейнер должен слушать на всех интерфейсах, так как привязка по умолчанию всё ещё 127.0.0.1:

docker run --gpus all -p 8080:8080 \
  -v /path/to/models:/models \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m models/my-model.gguf -c 4096 --host 0.0.0.0 -ngl all

Сборка из исходников под ваше конкретное оборудование

Если вам важно выжать максимум производительности из вашего бэкенда CPU/GPU, соберите проект из исходников с помощью CMake.

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# Сборка для CPU
cmake -B build
cmake --build build --config Release

После сборки бинарники обычно находятся здесь:

ls -la ./build/bin/

Сборка для GPU одной командой

Включите бэкенд, соответствующий вашему оборудованию (примеры показаны для CUDA и Vulkan):

# NVIDIA CUDA
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Vulkan
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

Ubuntu 24.04 + NVIDIA GPU: полный разбор сборки

На Ubuntu 24.04 с GPU от NVIDIA перед сборкой необходимы CUDA toolkit и OpenSSL. Вот проверенная последовательность действий:

1. Установка CUDA toolkit 13.1. В этом руководстве закреплён локальный установщик версии 13.1.1. Более новый toolkit из репозитория NVIDIA для Ubuntu 24.04 следует той же схеме с файлом pin и локальными deb-пакетами, но с обновлёнными именами файлов.

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-ubuntu2404.pin
sudo mv cuda-ubuntu2404.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/13.1.1/local_installers/cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo dpkg -i cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2404-13-1-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-13-1

2. Добавьте CUDA в окружение (добавьте в ~/.bashrc):

# cuda toolkit
export PATH=/usr/local/cuda-13.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-13.1/lib64:$LD_LIBRARY_PATH

Затем выполните source ~/.bashrc или откройте новый терминал.

3. Установка заголовков разработки OpenSSL (необходимо для чистой сборки):

sudo apt update
sudo apt install libssl-dev

4. Сборка llama.cpp (из каталога, содержащего клон llama.cpp, с включённым CUDA):

cmake llama.cpp -B llama.cpp/build -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split llama-embedding
cp llama.cpp/build/bin/llama-* llama.cpp

В результате в каталоге llama.cpp появятся llama-cli, llama-mtmd-cli, llama-server, llama-embedding и llama-gguf-split.

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

Выбор модели GGUF и квантизации

Для запуска инференса вам нужен файл модели в формате GGUF (*.gguf). GGUF — это формат единого файла, который объединяет веса модели и стандартизированные метаданные, необходимые для движков вроде llama.cpp.

Два способа получить модель

Вариант A: Использование локального файла GGUF

Скачайте или скопируйте файл GGUF в ./models/:

mkdir -p models
# Поместите ваш GGUF в models/my-model.gguf

Затем запустите его, указав путь:

llama-cli -m models/my-model.gguf -p "Hello! Explain what llama.cpp is." -n 128 -st

Вариант B: Пусть llama.cpp скачает с Hugging Face

Современные сборки llama.cpp могут скачивать модели с Hugging Face и хранить файлы в локальном кэше. Это часто самый простой рабочий процесс для быстрых экспериментов.

# Скачиваем модель с HF и запускаем промпт
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "Once upon a time," \
  -n 200 \
  -st

Вы также можете указать квантизацию в селекторе репозитория и позволить инструменту выбрать соответствующий файл:

llama-cli \
  --hf-repo unsloth/phi-4-GGUF:q4_k_m \
  -p "Summarize the concept of quantization in one paragraph." \
  -n 160 \
  -st

Если вам впоследствии понадобится полностью автономный рабочий процесс, флаг --offline принудительно использует кэш и предотвращает доступ к сети.

Выбор квантизации для локального инференса

Квантизация — это практичный ответ на вопрос «Какая квантизация GGUF подходит для локального инференса», поскольку она напрямую влияет на качество, размер модели и скорость.

Практическая отправная точка:

• начинайте с вариантов Q4 или Q5 для машин, работающих преимущественно на CPU,
• переходите к более высокой точности (или менее агрессивной квантизации), когда можете позволить себе больше оперативной или видеопамяти,
• если модель «ведёт себя глупо» в вашей задаче, решение часто заключается в выборе лучшей модели или менее агрессивной квантизации, а не только в настройке сэмплинга.

Также помните, что размер контекстного окна важен: более крупные размеры контекста увеличивают потребление памяти (иногда драматически), даже если сам файл GGUF помещается в память.

Быстрый старт llama-cli и ключевые параметры

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

С момента переписи в декабре 2025 года llama-cli является интерактивным клиентом чата. Когда модель поставляется с шаблоном чата, режим разговора включён по умолчанию, а --no-conversation отклоняется с указателем на llama-completion. Эта вторая утилита — это старый llama-cli: один промпт на входе, один результат на выходе, подходит для скриптов и конвейеров. Из нового клиента флаг --single-turn (-st) генерирует один ответ и завершает работу.

Один ответ, затем выход

llama-cli \
  -m models/my-model.gguf \
  -p "Write a short TCP vs UDP comparison." \
  -n 200 \
  -st

Тот же промпт через небезопасный (неинтерактивный) бинарник:

llama-completion \
  -m models/my-model.gguf \
  -p "Write a short TCP vs UDP comparison." \
  -n 200 \
  --no-conversation

Интерактивная сессия чата

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "You are a concise systems engineering assistant." \
  --ctx-size 4096

Флаг --conversation больше не требуется. Чтобы остановить генерацию, когда модель напечатает определённую последовательность, используйте обратный промпт (reverse prompt).

Основные флаги llama-cli, на которые стоит обратить внимание

Вместо того чтобы запоминать 200 флагов, сосредоточьтесь на тех, которые определяют правильность, задержку и потребление памяти.

Модель и загрузка

Контекст и пропускная способность

Оффлоад на GPU и выбор оборудования

Сэмплинг и качество вывода

Примеры задач с llama-cli

Резюмирование файла, а не просто промпта

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "You summarize technical documents. Output five bullets max." \
  --file ./docs/incident-report.txt \
  -n 300 \
  -st

Повышение воспроизводимости результатов

При отладке промптов зафиксируйте сид и снизьте случайность:

llama-cli \
  -m models/my-model.gguf \
  -p "Extract key risks from this design note." \
  -n 200 \
  --seed 42 \
  --temp 0.2 \
  -st

Быстрый старт llama-server с API, совместимым с OpenAI

llama-server — это встроенный HTTP-сервер, который может предоставлять:

• endpoints, совместимые с OpenAI, для чата, дополнений (completions), эмбеддингов и ответов,
• веб-интерфейс для интерактивного тестирования,
• необязательные endpoints мониторинга для видимости в продакшене.

Запуск сервера с локальной моделью

llama-server \
  -m models/my-model.gguf \
  -c 4096

По умолчанию он слушает 127.0.0.1:8080.

Чтобы привязаться к внешнему адресу (например, внутри Docker или в локальной сети), укажите хост и порт:

llama-server \
  -m models/my-model.gguf \
  -c 4096 \
  --host 0.0.0.0 \
  --port 8080

Необязательные, но важные флаги сервера

Если вы работаете в контейнерах, многие настройки также можно контролировать через переменные окружения LLAMA_ARG_*.

Примеры API-вызовов

Чат-комплетион с curl

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Give me a quick llama.cpp checklist." }
    ],
    "temperature": 0.7
  }'

Совет для реального продакшена: если вы задали --api-key, вы можете передавать его через заголовок x-api-key (или продолжать использовать заголовки Authorization в зависимости от вашего шлюза).

Клиент OpenAI Python для llama-server

Совместимый с OpenAI сервер позволяет многим клиентам работать с изменением только base_url — именно так исследовательские агенты, такие как lukeswade/deep-research, общаются с llama-server напрямую, без отдельного слоя адаптера. Self-Hosted Deep Research Systems: 12 Tools Compared описывает этот проект и другие, направленные на локальные endpoints, совместимые с OpenAI.

import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-no-key-required",
)

resp = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain threads vs batch size in llama.cpp."},
    ],
)

print(resp.choices[0].message.content)

Эмбеддинги

Эмбеддинги, совместимые с OpenAI, доступны по адресу /v1/embeddings, но модель должна поддерживать режим пулинга эмбеддингов, отличный от none.

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "input": ["hello", "world"],
    "model": "GPT-4",
    "encoding_format": "float"
  }'

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

llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

или, если вы хотите запустить llama-cpp с моделью эмбеддингов на CPU:

CUDA_VISIBLE_DEVICES="" llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

попробуйте так:

CUDA_VISIBLE_DEVICES="" llama-embedding \
  -m /path/to/Qwen3-Embedding-0.6B-Q8_0.gguf \
  -p "your text here" \
  --pooling last \
  --verbose-prompt

Обслуживание нескольких моделей из одного процесса

В примерах выше llama-server привязывается к одной модели при запуске. Если вам нужно переключаться между моделями для каждого запроса — без перезапуска процесса — для этого предназначен режим маршрутизатора. См. llama-server router mode: динамическое переключение моделей без перезапуска. Для скриптового процесса разгрузки всех моделей, который освобождает VRAM без перезапуска маршрутизатора, см. Unload All llama.cpp Router Models Without Restarting.

Производительность, мониторинг и защита для продакшена

Частый вопрос «Какие флаги командной строки llama.cpp важнее всего для скорости и памяти» становится гораздо проще, когда вы рассматриваете инференс как систему:

• Потолок памяти обычно является первым ограничением (ОЗУ на CPU, VRAM на GPU).
• Размер контекста — основной множитель потребления памяти.
• Оффлоад слоёв на GPU часто является самым быстрым путём к повышению количества токенов в секунду.
• Размер батчей и потоки могут улучшить пропускную способность, но также могут увеличить нагрузку на память.

Для более глубокого, инженерного взгляда, см.: LLM Performance in 2026: Benchmarks, Bottlenecks & Optimization.

Если вы хотите получить измеренные результаты в стиле llama-cli на GPU класса 16 ГБ — токены в секунду, VRAM и загрузка GPU при изменении контекста (19K / 32K / 64K) для плотных и MoE моделей GGUF — см. 16 GB VRAM LLM benchmarks with llama.cpp (speed and context).

Для Qwen 3.6 llama.cpp поддерживает встроенное спекулятивное декодирование с предсказанием нескольких токенов (Multi-Token Prediction). Включите его с помощью --spec-type draft-mtp; --spec-draft-n-max задает, сколько токенов предлагает draft-head (по умолчанию 3). Версия v0.6.0 расширяет этот же путь MTP на Qwen4Exp. Для сравнения методов см. Speculative Decoding. Для измеренных чисел Qwen 3.6 на 16 ГБ см. Qwen 3.6 MTP vs Standard on 16GB GPU.

Мониторинг llama-server с Prometheus и Grafana

llama-server предоставляет метрики, совместимые с Prometheus, по пути /metrics, только если включён флаг --metrics. Направьте Prometheus на этот путь в качестве задачи скреппинга. Дашборды и пороги алертов для llama.cpp, vLLM и TGI находятся в Monitor LLM Inference in Production (2026): Prometheus & Grafana for vLLM, TGI, llama.cpp.

Базовый чек-лист усиления безопасности

Когда ваш llama-server доступен за пределами localhost:

• используйте --api-key (или --api-key-file), чтобы запросы аутентифицировались,
• избегайте привязки к 0.0.0.0, если это не требуется,
• рассмотрите возможность использования TLS через SSL-флаги сервера или терминации TLS на обратном прокси,
• ограничивайте параллелизм с помощью --parallel, чтобы защитить задержку под нагрузкой,
• оставьте --tools и --agent выключенными. Оба являются экспериментальными и предоставляют доступ к операциям с файлами и оболочкой через API; включение любого из них также ограничивает CORS только localhost.

Быстрые решения проблем

Модель загружается, но ответы в чате странные

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

• передать явный --system-prompt (режим разговора уже является вариантом по умолчанию в llama-cli),
• убедиться, что ваша модель — это инструктированная или чат-настроенная версия,
• протестировать, используя веб-интерфейс сервера, прежде чем подключать его к приложению. В v0.6.0 этот интерфейс был переосмыслен с браузером Hugging Face Hub, так что модель можно скачать со страницы, а не только из CLI.

Мыслящие модели оборачивают ответ в трассировки рассуждений. --reasoning off подавляет их, а --reasoning-format deepseek перемещает трассировку в reasoning_content вместо content.

У вас ошибка «недостаточно памяти»

Уменьшите контекст или выберите меньшую квантизацию:

• уменьшите --ctx-size,
• уменьшите --n-gpu-layers, если проблема в VRAM, или установите --cpu-moe, чтобы веса экспертов MoE оставались в ОЗУ,
• переключитесь на меньшую модель или более сжатую квантизацию,
• заквантизируйте KV-кэш с помощью --cache-type-k q8_0 --cache-type-v q8_0.

Контекст или распределение на GPU не те, что вы указали

--fit включен по умолчанию и переписывает настройки памяти, которые вы не задали, стремясь оставить 1024 МБ свободными на каждом устройстве (--fit-target). Он уменьшит контекст, но никогда ниже --fit-ctx (4096), и только если вы не передали -c. Он не будет трогать размещение слоёв, как только вы передадите любой -ngl. --fit off отключает механизм. Если в логах написано n_gpu_layers already set by user, то ваша явная настройка -ngl и загрузила значения, и fit не спасет от ошибки недостатка памяти.

Это медленно на CPU

Начните с:

• --threads, равного количеству физических ядер,
• умеренного размера батчей,
• проверки, что вы установили сборку, соответствующую вашей машине (фичи CPU и бэкенд).

Ссылки

• Официальный репозиторий и документация llama.cpp
• Официальная документация по флагам CLI
• Официальная документация llama-server и детали API