Knowledgebase

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update

3.3 Установка пакетов nvidia-container-toolkit

В документации пример дан с фиксацией версии через переменную NVIDIA_CONTAINER_TOOLKIT_VERSION:

export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.20.1-1
sudo apt-get install -y \
    nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
    nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
    libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
    libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

3.4 Конфигурация Docker для работы с NVIDIA runtime

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

mkdir -p ~/services/llama-swap
mkdir -p ~/services/llama-swap/models
cd ~/services/llama-swap

touch docker-compose.yml
touch config.yaml

services:
  llama-swap:
    # CUDA 12:
    # image: ghcr.io/mostlygeek/llama-swap:cuda
    # CUDA 13:
    image: ghcr.io/mostlygeek/llama-swap:cuda13

    ports:
      - "3000:8080"

    environment:
      # Переменные для NVIDIA Container Runtime
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=all
      - NVIDIA_DISABLE_REQUIRE=true
    volumes:
      - ./models:/models
      - ./config.yaml:/app/config.yaml
    restart: unless-stopped

cd ~/services/llama-swap/models

wget https://huggingface.co/unsloth/Qwen3.8-27B-GGUF/resolve/main/Qwen3.8-27B-UD-Q4_K_XL.gguf

ls -lh ~/services/llama-swap/models

models:
  main:
    ttl: 10800
    aliases:
      - qwen3.8-27b-ud-q4
    cmd: |
      llama-server
      --host 127.0.0.1
      --port ${PORT}

      --model /models/Qwen3.8-27B-UD-Q4_K_XL.gguf
      --alias qwen3.8-27b-ud-q4

      --flash-attn on
      --load-mode none
      --cont-batching
      --webui-mcp-proxy

      --n-gpu-layers 99
      --ctx-size 262144

      --temp 0.7
      --top-p 0.8
      --top-k 20
      --min-p 0.0
      --presence-penalty 1.5

      --cache-type-k q8_0
      --cache-type-v q8_0

      --reasoning off

Что означают параметры llama-swap (верхняя часть)

• models: — список моделей, которыми будет управлять llama-swap.
• main: — внутренний ID модели (может быть любым удобным именем).
• ttl: 10800 — время жизни (в секундах), после которого неиспользуемый upstream можно выгрузить/остановить (экономия VRAM/RAM).
• aliases: — список алиасов (имен модели), которые клиент может передавать в OpenAI‑запросах как model. В нашем примере клиент указывает qwen3.8-27b-ud-q4, а llama-swap понимает, какой upstream запустить.
• cmd: — команда запуска upstream‑сервера. llama-swap подставляет ${PORT} и запускает процесс, затем проксирует к нему OpenAI‑совместимые запросы. Механика «swap» описана в документации проекта: llama-swap смотрит model в запросе и при необходимости заменяет запущенный upstream на нужный.

Что означают ключевые параметры llama-server (внутри cmd)

Сетевые параметры:

• --host 127.0.0.1 — upstream слушает только loopback внутри окружения (безопаснее: снаружи виден только llama-swap).
• --port ${PORT} — порт задаёт llama-swap (вам не нужно фиксировать его вручную).

Модель:

• --model /models/...gguf — путь к GGUF‑файлу (мы примонтировали ./models как /models).
• --alias ... — алиас модели на стороне llama-server (удобно для отображения/маршрутизации).

Производительность/память:

• --n-gpu-layers 99 — сколько слоёв модели держать в VRAM (ускоряет генерацию). В актуальных сборках допустимы числа, а также значения auto/all.
  Практика: если не уверены — используйте all или уменьшайте число при нехватке VRAM.
• --ctx-size 262144 — размер контекста (в токенах). Большой контекст требует заметно больше памяти под KV‑кэш; при ошибках OOM уменьшайте это значение.
• --cache-type-k q8_0 и --cache-type-v q8_0 — тип квантования KV‑кэша (уменьшает потребление памяти ценой некоторого влияния на качество/скорость). Список допустимых типов описан в документации llama-server.
• --flash-attn on — принудительное включение Flash Attention (технология оптимизации GPU-вычислений, часто помогает производительности; также в документации llama.cpp отмечается как важный флаг в ряде режимов и конфигураций).
• --cont-batching — continuous/dynamic batching (лучше утилизация GPU при нескольких запросах).

Загрузка модели:

• --load-mode none — режим загрузки «без mmap» (для единовременной загрузки модели в VRAM)
  Если ваша сборка llama-server не понимает --load-mode, замените на --no-mmap (опция описана в llama-server).

Сэмплинг (управляет «креативностью»):

• --temp, --top-p, --top-k, --min-p, --presence-penalty — параметры сэмплинга и штрафов, влияющие на разнообразие ответа. Описание --top-k/--top-p/--min-p/--presence-penalty есть в llama-server.

Reasoning/Thinking:

• --reasoning off — отключает «reasoning/thinking» режим (если сборка/модель его поддерживает).

Документация llama-server: https://github.com/ggml-org/llama.cpp/tree/master/tools/server

6.2 Запуск llama-swap

Из каталога ~/services/llama-swap выполните:

docker compose up -d

Проверка статуса:

docker compose ps

Если статус Up — сервис запущен.

Локально на ВМ интерфейс будет доступен по адресу:

http://localhost:3000

http://{внешний_IP}:{внешний_порт}