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

Я снова и снова возвращаюсь к llama.cpp для локального инференса — он предоставляет уровень контроля, который Ollama и другие инструменты скрывают за фасадом, и он просто работает. Легко запускать модели GGUF в интерактивном режиме через llama-cli или открывать HTTP API, совместимое с OpenAI, с помощью llama-server.

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

Почему llama.cpp в 2026 году

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

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

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

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

Если именно Ollama — это альтернатива, которую вы рассматриваете в противовес llama-server, то статья llama.cpp против Ollama в 2026 — это специальное попарное сравнение, содержащее конкретные триггеры для выбора между Ollama и прямым использованием llama.cpp.

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

Существует три практических пути установки в зависимости от того, что вам важнее: удобство, портативность или максимальная производительность.

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

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

# 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

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

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

Установка через готовые бинарные файлы

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

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

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

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

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

Если вам важно выжать максимальную производительность из вашего бэкенда 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 + GPU NVIDIA: полное руководство по сборке

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

1. Установка CUDA toolkit 13.1

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 "Привет! Объясни, что такое llama.cpp." -n 128

Вариант 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 "Давным-давно," \
  -n 200

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

llama-cli \
  --hf-repo unsloth/phi-4-GGUF:q4_k_m \
  -p "Сожмите концепцию квантизации в один абзац." \
  -n 160

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

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

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

Прагматичная отправная точка:

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

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

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

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

Минимальный запуск

llama-cli \
  -m models/my-model.gguf \
  -p "Напишите краткое сравнение TCP и UDP." \
  -n 200

Интерактивный чат

Режим разговора предназначен для шаблонов чата. Он обычно включает интерактивное поведение и форматирует промпты в соответствии с шаблоном модели.

llama-cli \
  -m models/my-model.gguf \
  --conversation \
  --system-prompt "Вы — лаконичный ассистент по системной инженерии." \
  --ctx-size 4096

Чтобы прекратить генерацию при появлении определенной последовательности, используйте reverse prompt (обратный промпт). Это особенно полезно в интерактивном режиме.

Основные флаги llama-cli, на которых стоит сосредоточиться

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

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

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

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

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

Примеры рабочих нагрузок с llama-cli

Резюме файла, а не только промпта

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "Вы суммируете технические документы. Выводите максимум пять пунктов." \
  --file ./docs/incident-report.txt \
  -n 300

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

Когда вы отлаживаете промпты, зафиксируйте seed и сниьте случайность:

llama-cli \
  -m models/my-model.gguf \
  -p "Извлеките ключевые риски из этой проектной заметки." \
  -n 200 \
  --seed 42 \
  --temp 0.2

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

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

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

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

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

Chat completions с 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": "Вы полезный ассистент." },
      { "role": "user", "content": "Дайте мне быстрый чек-лист по llama.cpp." }
    ],
    "temperature": 0.7
  }'

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

OpenAI Python-клиент, указанный на llama-server

С OpenAI-совместимым сервером многие клиенты могут работать, просто изменив base_url.

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": "Вы лаконичный ассистент."},
        {"role": "user", "content": "Объясните threads и batch size в 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 "ваш текст здесь" \
  --pooling last \
  --verbose-prompt

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

Приведенные выше примеры привязывают llama-server к одной модели при старте. Если вам нужно переключаться между моделями для каждого запроса — без перезапуска процесса — для этого существует режим роутера (router mode). См. Режим роутера llama-server: динамическое переключение моделей без перезагрузки. Для скриптового процесса разгрузки всех моделей, освобождения VRAM без перезагрузки роутера, см. Разгрузка всех моделей роутера llama.cpp без перезапуска.

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

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

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

Для более глубокого, инженерного взгляда см.: Производительность LLM в 2026 году: Бенчмарки, узкие места и оптимизация.

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

Специально для Qwen 3.6 llama.cpp теперь поддерживает встроенное спекулятивное декодирование Multi-Token Prediction (MTP), которое может значительно повысить пропускную способность генерации. Для комплексного руководства по всем методам спекулятивного декодирования в llama.cpp см. Спекулятивное декодирование. Для бенчмарков, специфичных для MTP Qwen 3.6, см. Qwen 3.6 MTP против Standard на GPU 16GB.

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

llama-server может открывать метрики, совместимые с Prometheus, по адресу /metrics, если включен флаг --metrics. Это естественно сочетается с конфигурациями скрейпинга [Prometheus](https://www.glukhov.org/ru/observability/monitoring-with-prometheus/ “Руководство по системе мониторинга Prometheus”}) и дашбордами Grafana.

Для дашбордов и алертов, специфичных для llama.cpp (и vLLM, TGI): Мониторинг LLM-инференса в продакшене (2026): Prometheus & Grafana для vLLM, TGI, llama.cpp. Более общие руководства: Наблюдаемость: Руководство по мониторингу, метрикам, Prometheus & Grafana и Наблюдаемость для LLM-систем.

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

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

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

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

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

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

• использование llama-cli --conversation плюс явный --system-prompt,
• убедитесь, что ваша модель — вариант, настроенный на инструкции или чат,
• протестируйте с помощью веб-интерфейса сервера, прежде чем подключать его к приложению.

Ошибка недостатка памяти

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

• уменьшите --ctx-size,
• сократите --n-gpu-layers, если проблема в VRAM,
• переключитесь на меньшую модель или более сжатую квантизацию.

Медленная работа на CPU

Начните с:

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

Ссылки

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