Docker Compose стек за AI в production
Моделът сам по себе си не е услуга. Услуга става, когато пред него има входна врата, кеш, измерване и аларми. В този урок сглобяваме пет слоя в един docker-compose.yml: Nginx → Redis → vLLM → Prometheus → Grafana, плюс вариант за ARM64 машина с Ollama.
kv_cache_usage_perc вместо gpu_cache_usage_perc; грешките се броят през request_success_total{finished_reason="error"}). Поправени са грешки в стария пример: паролата в redis.conf не се замества от променлива; флагът --quantization awq не върви с обикновен модел; скриптът чакаше 5 „здрави“ услуги, а healthcheck имаха 3; липсваха exporter-ите за Redis и Nginx; алармата за „GPU памет“ мереше пропускателна способност. Таблото с ID 21118 води към чуждо табло — заменено с официалното от vLLM. За ARM64: vLLM вече има -aarch64 образи, а Ollama има вграден OpenAI-съвместим API, затова LiteLLM е по избор.
01Какво ще научиш
- Как минава една заявка през петте слоя и какво добавя всеки от тях.
- Как да опишеш целия стек в един файл: закрепени версии, health checks, правилен ред на стартиране, тайни извън git.
- Как Nginx пази модела с ограничение на заявките и как Redis спестява GPU с кеш на повтарящи се въпроси.
- Кои метрики на vLLM да следиш, как да пишеш аларми и как да вдигнеш готово табло в Grafana.
- Как да стартираш безопасно със скрипт и как да вдигнеш същия стек на ARM64 машина с Ollama.
02Преди да започнеш
- Минал си Блок 1 · Част 1 (vLLM и inference) — знаеш какво е PagedAttention и OpenAI-съвместим API.
- Linux машина с NVIDIA GPU, Docker Engine и Docker Compose (командата е
docker compose, без тире). - Инсталиран NVIDIA Container Toolkit — без него контейнерите не виждат GPU.
- Акаунт в Hugging Face и токен, ако моделът е със заявен достъп (например Llama).
- Около 50 GB свободно място за модели и данни.
03Стъпки
-
Архитектурата: пет слоя за една заявка
Всяка заявка минава през пет слоя, преди да стигне до модела и обратно. Защо слоеве, а не само модел? Защото моделът не умее да се пази от претоварване, не помни вече дадени отговори и не казва кога боледува. Всеки слой поема едно от тези неща.
Слой Порт Работа Nginx 80 / 443 Входна врата: TLS, ограничение на заявките, балансиране, health check. Redis 6379 (вътрешен) Кеш на отговорите за еднакви въпроси, с TTL 1 час. vLLM 8000 Генерира: PagedAttention, continuous batching, OpenAI-съвместим API. Prometheus 9090 Събира метрики на всеки 15 s, пази 15 дни история, оценява аларми. Grafana 3000 Табла в реално време: пропускателност, латентност, GPU, кеш, грешки. структура на проектаai-production/ ├── docker-compose.yml # главният файл ├── .env # тайни — НЕ в git ├── config/ │ ├── nginx/conf.d/vllm.conf # upstream + ограничение на заявките │ ├── redis/redis.conf # памет, persistence │ └── prometheus/ │ ├── prometheus.yml # какво се събира │ └── alerts.yml # правила за аларми ├── data/ │ ├── models/ # кеш на Hugging Face │ ├── prometheus/ grafana/ redis/ └── scripts/ ├── start.sh # стартиране с проверки └── health_check.sh # проверка от cron -
docker-compose.yml — целият стек в един файл
Три правила правят файла „production“: закрепени версии (утре
latestможе да е друго и нищо да не тръгне), health checks (Nginx тръгва едва когато моделът е зареден) и навън е само входната врата — vLLM, Grafana и Prometheus слушат само наlocalhost, а Redis и exporter-ите са само във вътрешната мрежа.YAML · docker-compose.yml# AI production стек · docker compose up -d · версии сверени на 01.10.2026 services: vllm: image: vllm/vllm-openai:v0.30.0 # закрепена версия restart: unless-stopped ipc: host # споделена памет за PyTorch (по документацията на vLLM) environment: HF_TOKEN: ${HF_TOKEN} volumes: - ./data/models:/root/.cache/huggingface ports: - "127.0.0.1:8000:8000" # само localhost — навън е Nginx command: > --model ${MODEL_NAME:-meta-llama/Llama-3.1-8B-Instruct} --served-model-name ${SERVED_MODEL_NAME:-llama3} --max-model-len ${MAX_MODEL_LEN:-16384} --max-num-seqs ${MAX_NUM_SEQS:-256} --gpu-memory-utilization 0.90 healthcheck: test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"] interval: 30s timeout: 10s retries: 5 start_period: 180s # моделът се зарежда минути deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] redis: image: redis:8.10-alpine restart: unless-stopped # redis.conf НЕ чете ${ПРОМЕНЛИВИ} — паролата се подава оттук command: ["redis-server", "/usr/local/etc/redis/redis.conf", "--requirepass", "${REDIS_PASSWORD}"] environment: REDIS_PASSWORD: ${REDIS_PASSWORD} volumes: - ./config/redis/redis.conf:/usr/local/etc/redis/redis.conf:ro - ./data/redis:/data healthcheck: test: ["CMD-SHELL", "redis-cli -a \"$$REDIS_PASSWORD\" --no-auth-warning ping | grep -q PONG"] interval: 10s timeout: 5s retries: 3 nginx: image: nginx:1.30-alpine # стабилният клон restart: unless-stopped depends_on: vllm: { condition: service_healthy } redis: { condition: service_healthy } volumes: - ./config/nginx/conf.d:/etc/nginx/conf.d:ro ports: - "80:80" # - "443:443" ← когато добавиш TLS сертификат healthcheck: test: ["CMD", "nginx", "-t"] interval: 30s prometheus: image: prom/prometheus:v3.15.0 restart: unless-stopped command: - --config.file=/etc/prometheus/prometheus.yml - --storage.tsdb.path=/prometheus - --storage.tsdb.retention.time=15d - --web.enable-lifecycle # презареждане на конфигурацията без рестарт volumes: - ./config/prometheus:/etc/prometheus:ro - ./data/prometheus:/prometheus ports: - "127.0.0.1:9090:9090" grafana: image: grafana/grafana:13.2.3 restart: unless-stopped depends_on: [prometheus] environment: GF_SECURITY_ADMIN_USER: ${GRAFANA_USER:-admin} GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASS} volumes: - ./data/grafana:/var/lib/grafana ports: - "127.0.0.1:3000:3000" # ── exporter-и: превеждат Redis, Nginx и GPU на езика на Prometheus ── redis-exporter: image: oliver006/redis_exporter:v1.92.1 restart: unless-stopped environment: REDIS_ADDR: redis://redis:6379 REDIS_PASSWORD: ${REDIS_PASSWORD} nginx-exporter: image: nginx/nginx-prometheus-exporter:1.5.3 restart: unless-stopped command: ["--nginx.scrape-uri=http://nginx:8080/stub_status"] gpu-exporter: image: nvcr.io/nvidia/k8s/dcgm-exporter:${DCGM_EXPORTER_TAG} # таг — от каталога NVIDIA NGC restart: unless-stopped cap_add: [SYS_ADMIN] deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] networks: default: name: ai-network✅Правило: закрепвай версии, обновявай съзнателноВерсиите по-горе са сверени на 01.10.2026. Когато обновяваш, сменяй една по една и пусни проверката от раздел „Проверка“. Ако моделът е AWQ или GPTQ, вземи готов квантуван checkpoint — vLLM сам разпознава квантуването от конфигурацията му. Флаг--quantization awqвърху обикновен модел води до грешка при старт.bash · .env (НЕ се качва в git)# echo ".env" >> .gitignore ← задължително HF_TOKEN=<твоят-hugging-face-токен> MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct SERVED_MODEL_NAME=llama3 MAX_MODEL_LEN=16384 MAX_NUM_SEQS=256 GRAFANA_USER=admin GRAFANA_PASS=<силна-парола> REDIS_PASSWORD=<силна-парола> DCGM_EXPORTER_TAG=<текущ-таг-от-NGC> -
Nginx: входната врата
Nginx има три задачи: защита (ограничение на заявките от един адрес), ефективност (постоянни връзки към vLLM) и мащаб (пул от сървъри, в който утре добавяш втори vLLM). Статистиката за Prometheus е на отделен вътрешен порт 8080, който не се публикува навън.
nginx · config/nginx/conf.d/vllm.conf# Зоните за ограничение (файловете в conf.d са в http контекста) limit_req_zone $binary_remote_addr zone=ai_per_ip:10m rate=10r/s; limit_req_zone $server_name zone=ai_global:10m rate=100r/s; upstream vllm_backend { server vllm:8000 max_fails=3 fail_timeout=30s; # server vllm-2:8000; ← втора инстанция при нужда keepalive 32; keepalive_timeout 65s; } server { listen 80; server_name _; client_max_body_size 10m; send_timeout 300s; proxy_read_timeout 300s; # таймаут между две четения, не общо време add_header X-Content-Type-Options nosniff; add_header X-Frame-Options DENY; # add_header Strict-Transport-Security "max-age=31536000" always; ← само след TLS location /v1/ { limit_req zone=ai_per_ip burst=20 nodelay; limit_req zone=ai_global burst=100 nodelay; limit_req_status 429; proxy_pass http://vllm_backend; proxy_http_version 1.1; proxy_set_header Connection ""; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Request-ID $request_id; proxy_buffering off; # поточно предаване (SSE) } location /health { proxy_pass http://vllm_backend/health; access_log off; } error_page 429 /429.json; location = /429.json { default_type application/json; return 429 '{"error":"Rate limit exceeded","retry_after":1}'; } error_page 502 503 504 /5xx.json; location = /5xx.json { default_type application/json; return 503 '{"error":"Service temporarily unavailable"}'; } } # Вътрешен порт само за nginx-exporter (не е публикуван в compose) server { listen 8080; location /stub_status { stub_status; access_log off; } }⚠️Капан: дълго генериране и 504proxy_read_timeoutе времето между две последователни четения от vLLM. Ако отговорът се генерира цял и чак тогава се праща, а това трае повече от 300 s, Nginx връща 504. При поточно предаване всяко парче нулира брояча — затова за дълги отговори включвайstream. -
Redis: кеш за повтарящи се въпроси
В обучителни системи (например RAG за Moodle) едни и същи въпроси се задават многократно. Кешираме отговора за един час: при попадение отговорът идва от паметта, без да се пипа GPU. Кешираме само предвидими заявки — без поточно предаване и с ниска temperature, иначе ще връщаме „замразен“ отговор там, където се иска разнообразие.
💡Пример за мащаба (илюстративен)Ако в група от 50 курсисти 80% от въпросите са вариации на „Обясни RAG“ или „Как се инсталира Ollama“, само първата заявка генерира, а останалите вземат кеша. Колкото по-висок е делът на попаденията, толкова повече GPU остава за нови въпроси. Числата зависят от твоята аудитория — измери ги с/cache/stats, не ги приемай наготово.ini · config/redis/redis.confmaxmemory 4gb maxmemory-policy allkeys-lru # при запълване изхвърля най-отдавна ползваните ключове save 900 1 save 300 10 dbfilename dump.rdb dir /data protected-mode yes # паролата идва от compose (--requirepass) tcp-keepalive 300Python · redis_cache_middleware.py (слой пред vLLM в твоя RAG API)import os, time, json, hashlib import redis, httpx from fastapi import FastAPI, Request from fastapi.responses import JSONResponse app = FastAPI() r = redis.Redis(host="redis", port=6379, password=os.environ["REDIS_PASSWORD"], decode_responses=True) VLLM = os.environ.get("VLLM_URL", "http://vllm:8000") def cache_key(model, messages, temperature): payload = json.dumps({"m": model, "msg": messages, "t": temperature}, sort_keys=True) return "llm:" + hashlib.sha256(payload.encode()).hexdigest()[:16] @app.post("/v1/chat/completions") async def cached_chat(request: Request): body = await request.json() temperature = body.get("temperature", 0.2) use_cache = not body.get("stream") and temperature < 0.5 if use_cache: key = cache_key(body.get("model"), body.get("messages", []), temperature) hit = r.get(key) if hit: r.incr("stats:cache_hits") return JSONResponse(json.loads(hit), headers={"X-Cache": "HIT"}) t0 = time.time() async with httpx.AsyncClient(timeout=300) as client: resp = await client.post(f"{VLLM}/v1/chat/completions", json=body) result = resp.json() if use_cache and resp.status_code == 200: r.setex(key, 3600, json.dumps(result)) # TTL 1 час r.incr("stats:cache_misses") return JSONResponse(result, status_code=resp.status_code, headers={"X-Cache": "MISS", "X-Latency-ms": str(round((time.time() - t0) * 1000))}) @app.get("/cache/stats") def cache_stats(): hits = int(r.get("stats:cache_hits") or 0) misses = int(r.get("stats:cache_misses") or 0) total = hits + misses return {"hits": hits, "misses": misses, "hit_rate_pct": round(hits / total * 100, 1) if total else 0}⛔Никога парола в кодаСтарата версия на този урок имаше паролата на Redis направо в Python файла. Паролите идват само от средата (.env→environment) — кодът отива в git, паролата — никога. -
Prometheus: какво мерим и кога алармираме
Без измерване си сляп. За AI услуга следим: пропускателност (токени/s), латентност (P50/P99), опашка (чакащи заявки), KV кеш, грешки и температура на GPU. Имената на метриките по-долу са от текущата документация на vLLM (v1).
YAML · config/prometheus/prometheus.ymlglobal: scrape_interval: 15s evaluation_interval: 15s rule_files: - alerts.yml scrape_configs: - job_name: vllm scrape_interval: 5s static_configs: [{ targets: ["vllm:8000"] }] # вграден /metrics - job_name: gpu static_configs: [{ targets: ["gpu-exporter:9400"] }] - job_name: redis static_configs: [{ targets: ["redis-exporter:9121"] }] - job_name: nginx static_configs: [{ targets: ["nginx-exporter:9113"] }] - job_name: prometheus static_configs: [{ targets: ["localhost:9090"] }]YAML · config/prometheus/alerts.ymlgroups: - name: ai_production rules: - alert: LargeWaitingQueue expr: vllm:num_requests_waiting > 50 for: 1m labels: { severity: warning } annotations: { summary: "Над 50 чакащи заявки — помисли за втора инстанция" } - alert: HighP99Latency expr: histogram_quantile(0.99, sum by (le) (rate(vllm:e2e_request_latency_seconds_bucket[5m]))) > 10 for: 2m labels: { severity: warning } annotations: { summary: "P99 латентност над 10 s" } - alert: CriticalLatency expr: histogram_quantile(0.99, sum by (le) (rate(vllm:e2e_request_latency_seconds_bucket[5m]))) > 30 for: 1m labels: { severity: critical } annotations: { summary: "P99 над 30 s — системата е задръстена" } - alert: KVCacheFull expr: vllm:kv_cache_usage_perc > 0.95 # 1 = 100% for: 5m labels: { severity: warning } annotations: { summary: "KV кешът е над 95% за 5 минути" } - alert: HighErrorRate expr: sum(rate(vllm:request_success_total{finished_reason="error"}[5m])) / sum(rate(vllm:request_success_total[5m])) > 0.05 for: 2m labels: { severity: critical } annotations: { summary: "Над 5% от заявките завършват с грешка" } - alert: GPUTemperatureHigh expr: DCGM_FI_DEV_GPU_TEMP > 80 for: 3m labels: { severity: warning } annotations: { summary: "GPU над 80 °C — провери охлаждането" }⚠️Капан: стари имена на метрикиМного примери в интернет още ползватvllm:gpu_cache_usage_perc,vllm:num_requests_swappedилиvllm:request_failure_total. В текущия vLLM (v1) те не съществуват и алармата просто никога не се задейства — тихо. Провери имената в/metricsна своята версия. -
Grafana: таблото
Не рисувай таблото от нулата. В репото на vLLM има готово табло (
examples/observability/prometheus_grafana/grafana.json) — внасяш го в Grafana и добавяш свои панели. Ключовите заявки:PromQL · заявки за панелите# Пропускателност: генерирани токени в секунда rate(vllm:generation_tokens_total[1m]) # Латентност P50 / P95 / P99 histogram_quantile(0.50, sum by (le) (rate(vllm:e2e_request_latency_seconds_bucket[5m]))) histogram_quantile(0.99, sum by (le) (rate(vllm:e2e_request_latency_seconds_bucket[5m]))) # Време до първия токен P95 histogram_quantile(0.95, sum by (le) (rate(vllm:time_to_first_token_seconds_bucket[5m]))) # Заявки: работещи и чакащи vllm:num_requests_running vllm:num_requests_waiting # KV кеш (0–1) vllm:kv_cache_usage_perc # Попадения в prefix кеша rate(vllm:prefix_cache_hits_total[5m]) / rate(vllm:prefix_cache_queries_total[5m]) # GPU (DCGM) DCGM_FI_DEV_GPU_UTIL DCGM_FI_DEV_GPU_TEMPКругова диаграма вече е вградена в Grafana — старият плъгин
grafana-piechart-panelне е нужен. -
Безопасно стартиране и проверка от cron
Скриптът прави четири неща преди да каже „готово“: проверява изискванията, стартира, чака health checks и пуска истинска заявка от край до край. Чакаме само услугите, които имат healthcheck — останалите никога няма да бъдат „healthy“.
bash · scripts/start.sh#!/bin/bash set -euo pipefail cd "$(dirname "$0")/.." log(){ echo "[$(date +%H:%M:%S)] $1"; } err(){ echo "[ГРЕШКА] $1" >&2; exit 1; } [[ -f .env ]] || err ".env липсва — копирай от .env.example" command -v docker >/dev/null || err "Docker не е инсталиран" docker info >/dev/null 2>&1 || err "Docker daemon не работи" nvidia-smi >/dev/null 2>&1 || err "Не виждам NVIDIA GPU" FREE=$(df ./data --output=avail -BG | tail -1 | tr -d ' G') [[ ${FREE:-0} -gt 50 ]] || log "ВНИМАНИЕ: под 50 GB свободно в ./data" mkdir -p data/{models,prometheus,grafana,redis} docker compose up -d log "Чакам health checks (до 5 мин)..." TOTAL=3 # vllm, redis, nginx — само те имат healthcheck for i in $(seq 1 60); do OK=$(docker compose ps --format '{{.Health}}' | grep -c '^healthy$' || true) [[ $OK -ge $TOTAL ]] && { log "Всички $TOTAL са healthy"; break; } [[ $i -eq 60 ]] && err "Изтече времето — виж: docker compose logs vllm" sleep 5 done log "Тест от край до край..." curl -sf http://localhost/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"llama3","messages":[{"role":"user","content":"Кажи OK"}],"max_tokens":5}' \ | python3 -c "import json,sys; print(json.load(sys.stdin)['choices'][0]['message']['content'])" log "Готово · API: http://localhost/v1 · Grafana: http://localhost:3000"bash · scripts/health_check.sh (cron: */5 * * * *)#!/bin/bash cd "$(dirname "$0")/.." ALERT_EMAIL="ops@example.com" # твоят адрес; изисква настроен mail ISSUES=() up(){ [[ $(curl -so /dev/null -w "%{http_code}" --connect-timeout 5 "$1") == 200 ]]; } up http://localhost:8000/health || ISSUES+=("vLLM не отговаря") up http://localhost/health || ISSUES+=("Nginx не отговаря") docker compose exec -T redis sh -c 'redis-cli -a "$REDIS_PASSWORD" --no-auth-warning ping' \ | grep -q PONG || ISSUES+=("Redis не отговаря") TEMP=$(nvidia-smi --query-gpu=temperature.gpu --format=csv,noheader 2>/dev/null | head -1) [[ -n $TEMP && $TEMP -gt 85 ]] && ISSUES+=("GPU: ${TEMP} °C") if (( ${#ISSUES[@]} )); then printf '%s\n' "${ISSUES[@]}" | mail -s "AI стек: тревога" "$ALERT_EMAIL" logger -t ai-health "ALERT: ${ISSUES[*]}" fi🛡️Защо махнахме admin API на PrometheusФлагът--web.enable-admin-apiпозволява триене на данни през HTTP. В production не ти трябва — по-малко отворени врати, по-малко риск. -
Вариант за ARM64 машина (например с NVIDIA GB10)
На ARM64 машина с NVIDIA GPU (като системите с GB10) най-простият път е Ollama 🔒 локално: образът е мултиархитектурен и има вграден OpenAI-съвместим API на
/v1. Nginx, Redis, Prometheus и Grafana са мултиархитектурни — остават същите. Ако искаш vLLM и на ARM64, той вече публикува образи с таг-aarch64(напримерv0.30.0-aarch64).YAML · docker-compose.arm64.yml (сменя само слоя за inference)services: ollama: image: ollama/ollama:0.35.0 # linux/arm64 и amd64 restart: unless-stopped environment: OLLAMA_NUM_PARALLEL: "8" # паралелни заявки на модел OLLAMA_MAX_LOADED_MODELS: "3" OLLAMA_KEEP_ALIVE: "60m" OLLAMA_FLASH_ATTENTION: "1" volumes: - ./data/ollama:/root/.ollama ports: - "127.0.0.1:11434:11434" healthcheck: test: ["CMD", "ollama", "list"] interval: 15s timeout: 10s retries: 3 deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] # redis, nginx, prometheus, grafana — както в основния файл. # В vllm.conf смени upstream на: server ollama:11434; # Клиентите викат същото: POST /v1/chat/completions✅LiteLLM — по избор, не задължителноЩом Ollama отговаря на OpenAI формат, кодът ти (LangChain, RAG) работи без преводач. LiteLLM 🔒 локално си струва, когато искаш един вход към няколко модела, резервен модел при отказ или отчет на разходите.⚠️Непроверено: GPU метрики на GB10GB10 ползва обща (unified) памет за CPU и GPU. Дали DCGM exporter дава всички полета на тази платформа, не сме проверили — ако панелите за GPU са празни, ползвайnvidia-smiв health скрипта и метриките на самия модел-сървър.
04Проверка
Чеклист преди пускане
.envе попълнен и е в.gitignore.docker compose up -dминава без грешки; vllm, redis и nginx са healthy.curl http://localhost/healthвръща 200.- Заявка за чат през Nginx връща отговор.
- Grafana показва метрики на vLLM.
/cache/statsпоказва попадения (ако ползваш кеш слоя).- Над зададения лимит Nginx връща 429.
- Правилата са заредени в Prometheus (Status → Rules).
health_check.shе в crontab.- Направен е benchmark: латентност и пропускателност са записани.
Тест
1. Redis е с maxmemory-policy allkeys-lru. Какво става, когато паметта се запълни при нов запис?
2. vllm:num_requests_waiting е 85 от 3 минути. Коя аларма се задейства първа?
3. proxy_read_timeout е 300 s, а отговор без поточно предаване се генерира 350 s. Какво става?
4. Защо vLLM, Grafana и Prometheus са вързани към localhost, а навън е само Nginx?
05Какво следва
06Източници
- Compose file reference — синтаксисът на
docker-compose.yml: healthcheck, depends_on, deploy. - Docker: GPU в Compose — резервиране на NVIDIA GPU.
- vLLM: Docker — официалният образ,
--ipc=host, ARM64 образи. - vLLM: метрики — пълният списък с метрики за Prometheus.
- vLLM: пример Prometheus + Grafana — готовото табло
grafana.json. - Nginx limit_req — ограничение на заявките, burst и nodelay.
- Redis: конфигурация — maxmemory-policy и persistence.
- Prometheus: съхранение — retention и TSDB.
- NVIDIA DCGM Exporter — GPU метрики за Prometheus.
- redis_exporter и nginx-prometheus-exporter — метрики на Redis и Nginx.
- Ollama: OpenAI съвместимост — вграденият
/v1API. - LiteLLM — прокси към много модели в OpenAI формат.