llama-server из llama.cpp 1.0: запуск, API и настройка

llama-server
llama.cpp сервер OpenAI API
запуск llama.cpp на сервере
llama-server из llama.cpp 1.0: запуск, API и настройка

llama-server — HTTP-сервер из проекта llama.cpp, который запускает модель в формате GGUF и отдаёт OpenAI-совместимый API: /v1/chat/completions, /v1/embeddings, /v1/responses и другие. Он работает на CPU, видеокартах NVIDIA, AMD и Apple, не требует Python и подходит для сервера на одну-две модели и небольшого числа пользователей. Ниже — установка, первый запуск, проверка API, параллельность, защита и мониторинг.

Инструкцию подготовила AI студия Владимира Ломтева 16 ноября 2026 года по README llama-server и заметкам к выпуску llama.cpp v1.0.0 от 13 ноября 2026 года. Команды проверены на синтаксис, но не запускались нами на конкретном железе. Флаги и значения по умолчанию меняются между сборками, поэтому сверяйтесь с llama-server --help своей версии.

Содержание

Чем llama-server отличается от Ollama и vLLM

llama-server Ollama vLLM
Основа llama.cpp напрямую llama.cpp и собственный слой управления Собственный движок на PyTorch
Формат модели GGUF GGUF через собственный реестр Веса Hugging Face, AWQ, GPTQ, FP8
Железо CPU, CUDA, ROCm, Metal, Vulkan и другие CPU, CUDA, ROCm, Metal В основном GPU NVIDIA и AMD
Управление Флаги командной строки Команды ollama pull/run, Modelfile Флаги и конфигурация
Типичный сценарий Один сервер, тонкая настройка Быстрый старт на рабочей станции Много пользователей на GPU

llama-server даёт прямой доступ ко всем параметрам llama.cpp без промежуточного слоя: типу KV-кэша, числу слоёв на GPU, слотам, шаблонам чата. Ollama удобнее для быстрого старта, vLLM — для высокой параллельности на GPU. Подробное сравнение есть в статье «vLLM, Ollama, llama.cpp или SGLang».

Что изменилось в llama.cpp 1.0.0

Выпуск 1.0.0 закрепил стабильный публичный API и семантическое версионирование, как объясняет пост ggml-org о версии 1.0. Для пользователей llama-server важны:

  • удалён флаг --defrag-thold и 35 устаревших функций C API;
  • добавлен KV-кэш в FP8 (-ctk/-ctv f8_e4m3);
  • исправлены обработка --cors-origins, защита от DNS rebinding и SSRF через CORS-прокси и запросы к медиа по URL;
  • вызовы MCP-инструментов отменяются при отключении клиента;
  • добавлен OpenAI-совместимый эндпоинт /v1/audio/speech;
  • переработан встроенный веб-интерфейс.

Если ваш скрипт запуска использует --defrag-thold, удалите флаг перед обновлением: аргумент больше не поддерживается.

Установка

Есть три пути: готовый архив сборки со страницы выпусков, Docker-образ или сборка из исходников. Для GPU NVIDIA сборка из исходников по руководству по сборке llama.cpp выглядит так:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j
./build/bin/llama-server --version

Docker-образы публикуются в ghcr.io/ggml-org/llama.cpp. Вариант с CUDA из README:

docker run -p 8080:8080 -v /srv/models:/models --gpus all \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m /models/model-Q4_K_M.gguf -c 8192 \
  --host 0.0.0.0 --port 8080 --n-gpu-layers 99

Внутри контейнера сервер слушает все интерфейсы, поэтому ограничивайте доступ на уровне Docker и сети, например публикуйте порт только на 127.0.0.1:8080:8080.

Первый запуск

Модель можно указать локальным файлом через -m или скачать с Hugging Face через -hf. По README при -hf квантование можно не указывать: по умолчанию берётся Q4_K_M, а если его нет — первый файл в репозитории.

llama-server \
  -hf ggml-org/gemma-3-4b-it-GGUF:Q4_K_M \
  --host 127.0.0.1 --port 8080 \
  -c 16384 -np 4 \
  -ngl auto -fa auto \
  --api-key-file /etc/llama/keys.txt \
  --metrics

Что делают параметры:

  • --host — по умолчанию 127.0.0.1, то есть сервер доступен только с этой машины;
  • --port — задавайте явно: в текущем README по умолчанию указан 9931, а во многих инструкциях встречается 8080;
  • -c — размер контекста в токенах; 0 означает взять значение из модели;
  • -np — число слотов, то есть одновременно обслуживаемых запросов;
  • -ngl — сколько слоёв держать в видеопамяти: число, auto или all;
  • -fa — Flash Attention: on, off или auto;
  • --api-key-file — файл с ключами доступа, по одному на строку;
  • --metrics — включает эндпоинт Prometheus.

Шаблон чата обрабатывается движком Jinja; по README он включён по умолчанию (--jinja).

Проверка API

GET /health не требует ключа и возвращает 503, пока модель загружается, и 200, когда сервер готов:

curl -s http://127.0.0.1:8080/health
curl -s http://127.0.0.1:8080/v1/models -H "Authorization: Bearer $LLAMA_KEY"
curl -s http://127.0.0.1:8080/v1/chat/completions \
  -H "Authorization: Bearer $LLAMA_KEY" -H "Content-Type: application/json" \
  -d '{"model":"default","messages":[{"role":"user","content":"Кратко: что такое KV-кэш?"}],"max_tokens":200}'

Из Python подходит стандартный клиент OpenAI:

import os
from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key=os.environ["LLAMA_KEY"])
reply = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "Составь план проверки сервера LLM из пяти пунктов"}],
    max_tokens=300,
)
print(reply.choices[0].message.content)

В режиме одной модели сервер не выбирает модель по полю model, а имя, которое он показывает в /v1/models, можно задать через --alias. В режиме нескольких моделей по этому полю выбирается модель, об этом ниже.

Параллельность, контекст и KV-кэш

Каждый одновременный запрос занимает слот. Флаг -np задаёт число слотов, по умолчанию -1 — автоматически. Флаг --kv-unified включает единый KV-буфер, общий для всех последовательностей; по README он включён по умолчанию, когда число слотов выбирается автоматически. Если задать слоты вручную без общего буфера, контекст -c фактически делится между ними, и каждому запросу достаётся меньше.

Память KV-кэша можно уменьшить типами -ctk и -ctv. Доступны f16 (по умолчанию), bf16, q8_0, q4_0, новый f8_e4m3 и другие. Как это влияет на ёмкость и качество, разобрано в статье «KV-кэш в FP8», а как считать видеопамять под веса и контекст — в статье «Сколько VRAM нужно для LLM».

Флаг --cache-reuse N позволяет переиспользовать фрагменты промпта из кэша через сдвиг KV, если они не короче N токенов. Это полезно для чатов, где история растёт, а начало остаётся тем же.

Несколько моделей в одном сервере

Если запустить llama-server без модели, он работает в режиме маршрутизатора: главный процесс запускает отдельный экземпляр под каждую модель и направляет запросы по полю model в JSON. По умолчанию модель загружается при первом обращении; --no-models-autoload это отключает. --models-max ограничивает число одновременно загруженных моделей, вытесняя давно не использованные, а --models-memory-margin N выгружает модели, пока новая не поместится, оставляя N МиБ свободными на каждом устройстве.

Для сервера, где днём нужна одна модель, а ночью другая, есть --sleep-idle-seconds: после указанного времени простоя модель и её KV-кэш выгружаются из памяти, а следующий запрос загружает их снова. Запросы к /health, /props, /models и /metrics сервер не будят.

Безопасность

  • Ключи. --api-key или --api-key-file. Эндпоинт /health публичный по замыслу.
  • Адрес. Оставляйте 127.0.0.1 и выводите сервер наружу через обратный прокси с TLS и журналом доступа. Для прямого TLS есть --ssl-key-file и --ssl-cert-file.
  • CORS. По README сервер по умолчанию отражает любой заголовок Origin с разрешёнными учётными данными. Для локальной сети задайте --cors-origins с адресом своего интерфейса, для той же машины — localhost.
  • Инструменты. Флаг --tools открывает через API чтение и запись файлов. README помечает его как экспериментальный и не рекомендует в недоверенной среде; если он нужен, используйте --tools-runtime с отдельным контейнером.
  • Обновления. В 1.0.0 исправлены проблемы с CORS, DNS rebinding и SSRF — сервер, доступный из сети, стоит обновить.

Мониторинг

С флагом --metrics сервер отдаёт метрики Prometheus на /metrics. Полезные для начала:

Метрика Что показывает
llamacpp:requests_processing Сколько запросов обрабатывается
llamacpp:requests_deferred Сколько запросов ждут свободного слота
llamacpp:prompt_tokens_seconds Средняя скорость обработки промпта, токенов в секунду
llamacpp:predicted_tokens_seconds Средняя скорость генерации, токенов в секунду
llamacpp:n_busy_slots_per_decode Среднее число занятых слотов на шаг

Рост requests_deferred означает, что слотов не хватает: увеличьте -np при наличии памяти или поставьте очередь с лимитами на шлюзе, как описано в статье об очереди запросов к LLM. Эндпоинт /slots показывает состояние каждого слота.

Запуск как службы systemd

[Unit]
Description=llama-server
After=network-online.target

[Service]
User=llama
ExecStart=/opt/llama.cpp/build/bin/llama-server -m /srv/models/model-Q4_K_M.gguf --host 127.0.0.1 --port 8080 -c 16384 -np 4 -ngl all --api-key-file /etc/llama/keys.txt --metrics
Restart=on-failure

[Install]
WantedBy=multi-user.target

Сохраните файл как /etc/systemd/system/llama-server.service, затем выполните systemctl daemon-reload и systemctl enable --now llama-server. Пути и параметры замените своими.

Частые ошибки

  • Сервер не запускается после обновления — проверьте, не остался ли в команде удалённый --defrag-thold.
  • Ответы медленные, GPU почти не загружен — модель частично на CPU; проверьте -ngl и строки о размещении слоёв в логе запуска.
  • Ответы обрываются на длинных документах — контекст на слот меньше, чем нужно; увеличьте -c или уменьшите -np.
  • Браузерное приложение из локальной сети получает отказ — не настроен --cors-origins.
  • Ответ не в том формате — шаблон чата модели не совпадает с ожидаемым; проверьте /props и при необходимости задайте шаблон явно.

Частые вопросы

Можно ли заменить Ollama на llama-server без изменения приложения? Если приложение использует OpenAI-совместимый API, достаточно поменять адрес и ключ. Если оно использует собственный API Ollama (/api/chat), понадобится доработка.

Сколько пользователей выдержит llama-server? Зависит от модели, железа и длины запросов. Ориентируйтесь на нагрузочный тест, а не на число слотов; методика — в статье о нагрузочном тесте локальной LLM.

Нужен ли GPU? Нет, llama-server работает и на CPU, но генерация будет заметно медленнее. Для небольших моделей и редких запросов этого может хватить.

Поддерживаются ли эмбеддинги и реранкинг? Да, в README описаны /v1/embeddings и /reranking, для них нужна подходящая модель.

Как AI студия Владимира Ломтева помогает запустить llama-server

AI студия Владимира Ломтева разворачивает LLM на серверах компании, в том числе в закрытом контуре. Для llama-server это означает:

  • подобрать модель, квантование и параметры контекста под задачу и имеющееся железо;
  • настроить сервер как службу с ключами доступа, обратным прокси и мониторингом;
  • интегрировать API с корпоративными системами и проверить ответы на реальных задачах;
  • провести нагрузочное тестирование и передать команде инструкцию по обновлению.

Первый шаг — выбрать одну задачу для локальной модели, записать, на каком сервере она будет работать, и какой результат считается достаточным. Обсудить задачу.

Итог: llama-server — прямой доступ к llama.cpp

llama-server подходит, когда нужен лёгкий OpenAI-совместимый сервер без Python, с полным контролем над параметрами llama.cpp и работой на любом железе. Запускайте его на локальном адресе с ключами, включайте метрики и обновляйтесь до 1.0.0 ради исправлений безопасности. Когда пользователей станет много, а задержка начнёт расти, оцените переход на vLLM или SGLang.

Оставить заявку

Заполните форму и мы свяжемся с вами

← Все статьи

Комментарии (0)

Пока нет комментариев. Будьте первым!

Оставить комментарий
Регистрация не требуется