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.cpp 1.0.0
- Установка
- Первый запуск
- Проверка API
- Параллельность, контекст и KV-кэш
- Несколько моделей в одном сервере
- Безопасность
- Мониторинг
- Запуск как службы systemd
- Частые ошибки
- Частые вопросы
Чем 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.






