Быстрый старт с llama.cpp: командная строка и сервер

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

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

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

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

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

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

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

Установка 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

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

Если вы хотите чистую установку без компиляторов, используйте официальные готовые бинарники, опубликованные в релизах llama.cpp на GitHub. Обычно они поддерживают несколько ОС и бэкендов (варианты только для 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 + NVIDIA GPU: полное руководство по сборке

На 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-cli, llama-mtmd-cli, llama-server, llama-embedding и llama-gguf-split в директории llama.cpp.

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

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

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

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

Вариант А: Используйте локальный файл 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 с API, совместимым с OpenAI

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

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

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

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

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

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

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

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

Python-клиент OpenAI для 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": "Объясните разницу между потоками и размером батча в 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": ["привет", "мир"],
    "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 к одной модели при запуске. Если вам нужно переключаться между моделями на уровне запроса — без перезапуска процесса — для этого предназначен режим роутера. См. Режим роутера llama-server: динамическое переключение моделей без перезапусков.

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

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

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

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

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

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

llama-server может экспортировать метрики, совместимые с Prometheus, на /metrics, когда включен флаг --metrics. Это естественно сочетается с конфигурациями скрапинга 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 на обратном прокси,
• ограничьте параллелизм с помощью --parallel, чтобы защитить задержку под нагрузкой.

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

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

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

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

Вы получили ошибку нехватки памяти

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

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

Медленно на CPU

Начните с:

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

Ссылки

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