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

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

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

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

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

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

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

Также полезно понимать llama.cpp, даже если позже вы выберете серверный процесс с более высокой пропускной способностью. Например, если ваша цель — максимальная пропускная способность на GPU, вам стоит сравнить его с vLLM, используя материал: Быстрый старт vLLM: высокопроизводительный сервис LLM а также протестировать выбор инструментов в: Ollama против vLLM против 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 и OpenSSL перед сборкой. Вот проверенная последовательность действий:

1. Установка комплекта CUDA 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.

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

Вариант 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

Вариант 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Чтобы завершить генерацию, когда модель напечатает определенную последовательность, используйте обратный промпт (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

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

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

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

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

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

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

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

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.

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

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

Вопрос из FAQ «Какие параметры командной строки 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 теперь поддерживает встроенное спекулятивное декодирование с много-токеновым предсказанием (MTP), которое может значительно повысить пропускную способность генерации. См. Qwen 3.6 27B и 35B MTP против Стандартного на GPU 16GB для измеренных скоростей генерации, накладных расходов VRAM и рекомендуемых значений --spec-draft-n-max.

Мониторинг 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
• Официальная документация и детали API llama-server