llama.cpp в Docker: CPU, CUDA и проверка локального API

Какой Docker-образ выбрать под своё железо

Для проверки самой цепочки контейнер → GGUF → HTTP достаточно ghcr.io/ggml-org/llama.cpp:server: это серверный образ без отдельного GPU backend. Для NVIDIA выберите :server-cuda или, при совместимом драйвере, :server-cuda13; на хосте нужен настроенный NVIDIA Container Toolkit. Поддержка конкретной видеокарты, драйвера и архитектуры хоста должна проверяться отдельно, а не выводиться из имени тега. Есть также варианты server-rocm, server-vulkan и server-intel; они требуют своего устройства и конфигурации, поэтому CUDA-команду ниже на них просто заменой тега переносить нельзя. s1 s2 s8

server содержит именно llama-server, а light и full рассчитаны на другие исполняемые программы. Теги образов могут обновляться: для повторяемого рабочего окружения сохраните полученный digest и версию движка Docker после собственного совместимого теста. Не считайте зафиксированный Git-коммит документации пином бинарного Docker-образа. s1 s2

Контрольная текстовая модель — Qwen/Qwen3-0.6B-GGUF, файл Qwen3-0.6B-Q8_0.gguf на ревизии Hugging Face 23749fefcc72300e3a2ad315e1317431b06b590a. Наличие файла и метка apache-2.0 видны в репозитории; условия применения читайте в приложенном LICENSE. Небольшой демонстрационный вариант не обещает размещение в определённом объёме RAM/VRAM или качество ответа на бизнес-данных. Перед тестом скачайте файл именно с указанной ревизии в заранее созданный каталог models на своём хосте и проверьте имя и целостность по данным репозитория; Modelium файл не скачивал. s6 s7

Как запустить сервер с закрытым хостовым портом

Сначала убедитесь, что Docker Engine работает и ваш каталог models действительно содержит выбранный GGUF: опция --mount не создаёт отсутствующую исходную папку автоматически. При запуске из каталога проекта для CPU-проверки используйте одну команду: docker run --rm --name llama-cpp-local -p 127.0.0.1:8080:8080 --mount type=bind,src="$PWD"/models,dst=/models,readonly ghcr.io/ggml-org/llama.cpp:server -m /models/Qwen3-0.6B-Q8_0.gguf --host 0.0.0.0 --port 8080 --n-gpu-layers 0 --no-webui. Путь внутри контейнера /models/... соответствует bind mount; readonly защищает исходный каталог от записи из контейнера. 0.0.0.0 здесь — интерфейс внутри контейнера, тогда как 127.0.0.1:8080:8080 привязывает опубликованный порт на хосте к loopback. s1 s3 s4 s5

Для NVIDIA GPU после установки и настройки NVIDIA Container Toolkit, проверки драйвера и совместимости CUDA замените образ на ghcr.io/ggml-org/llama.cpp:server-cuda, добавьте Docker-опцию --gpus all перед именем образа и замените --n-gpu-layers 0 на --n-gpu-layers all. Это не универсальное требование «вся модель должна помещаться в VRAM»: число выгруженных слоёв и фактическое размещение сверяйте с логом llama-server и выбранным устройством; если запуск с all не помещается, экспериментируйте с числом слоёв без обещаний скорости. Не используйте --privileged, host network или публикацию -p 8080:8080 для локального теста. s1 s3 s5 s8

Как подтвердить ответ модели, а не только доступность порта

После загрузки на том же хосте проверьте curl -f http://127.0.0.1:8080/health: по документации код 503 означает загрузку, 200 — готовность. Затем получите curl -f http://127.0.0.1:8080/v1/models и посмотрите data[0].id; обычно он соответствует пути из -m, но может быть задан --alias. Эти два запроса не доказывают генерацию. s3

Отправьте JSON на POST http://127.0.0.1:8080/v1/chat/completions с model точно из data[0].id, messages с ролью user и текстом Ответь одним словом: привет /no_think, max_tokens 128. Проверьте код HTTP и содержательное choices[0].message.content; если поле пустое, изучите reasoning_content, ответ сервера и лимит токенов, затем повторите контролируемый тест. Карточка Qwen описывает /no_think, а llama-server — chat endpoint и варианты обработки reasoning. Сверьте полученный ответ с заданием, а не принимайте статус HTTP 200 за доказательство качества. Modelium не отправлял этот запрос и не наблюдал ответа. s3 s6

Для GPU-теста дополнительно сверяйте лог с реально обнаруженным CUDA-устройством и числом выгруженных слоёв; отсутствие ошибки от --gpus all или успешный CPU-ответ не доказывают GPU-offload. При ошибке загрузки проверяйте точное имя файла, путь монтирования, права чтения и доступную память; при недоступном GPU — драйвер хоста, runtime NVIDIA и выбранный вариант CUDA-образа. Размер GGUF на диске не равен требуемой памяти при выбранном контексте и настройках сервера. s1 s3 s4 s8

Когда Docker не даёт изоляции и как убрать тест

127.0.0.1 на опубликованном порту — необходимая граница для локального примера, но не подтверждение отсутствия сетевого выхода контейнера или полного закрытия API. Docker отдельно предупреждает: в Engine старше 28.0.0 хосты в том же L2-сегменте могли подключаться даже к localhost-порту. У llama-server есть флаг --api-key, однако /health остаётся публичным; для сетевых клиентов нужны отдельные правила доступа и реальный тест с другого хоста. Если нужен офлайн-контур, контролируйте исходящие соединения и предварительную загрузку весов отдельно — этот текст не подтверждает такую изоляцию. s3 s5

Остановите интерактивный контейнер Ctrl+C; --rm удалит его при остановке, но каталог с GGUF на хосте останется. Следующий шаг — проверить совместимость GGUF и параметры llama.cpp, затем провести собственный тест ответа и GPU backend на вашем железе. Это руководство по первоисточникам, а не отчёт о запуске Modelium. s1 s4