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

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

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

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

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

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

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

Также полезно понимать llama.cpp, даже если позже вы выберете серверный runtime с более высокой пропускной способностью. Например, если ваша цель — максимальная пропускная способность обслуживания на GPU, вы можете сравнить его с vLLM, используя: vLLM Quickstart: высокопроизводительное обслуживание 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
cp llama.cpp/build/bin/llama-* llama.cpp

Это создает llama-cli, llama-mtmd-cli, llama-server и 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 "Привет! Объясните, что такое 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,
• переходите на более высокую точность (или менее агрессивное квантование), когда можете позволить себе ОЗУ или видеопамять,
• когда модель «кажется глупой» для вашей задачи, решение часто заключается в лучшей модели или менее агрессивном кванте, а не только в настройках выборки.

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

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

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

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

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

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

Разгрузка GPU и выбор оборудования

Выборка и качество вывода

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

Суммирование файла, а не только запроса

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

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

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

llama-cli \
  -m models/my-model.gguf \
  -p "Извлеките ключевые риски из этого дизайн-нота." \
  -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/my-embedding-model.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --port 8080

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

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

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

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

Мониторинг 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