Устранение неполадок¶
Интеграция с LiteLLM/Portkey
Этот раздел покрывает проблемы установки и GPU. Troubleshooting для llm-gateway-adapter (LiteLLM/Portkey guardrail integration) — в гайде по интеграции с LiteLLM → §Troubleshooting.
GPU не обнаружен¶
Симптом: CUDA available: False или Model loaded on CPU.
Решение 1: Проверьте nvidia-smi на хосте.
Решение 2: Проверьте NVIDIA Container Toolkit.
Решение 3: Проверьте устройства.
CUDA out of memory¶
Симптом: CUDA out of memory.
Все 3 ML-сервиса требуют суммарно ~20 GB VRAM. Система поставляется только в полной конфигурации.
Решение:
# Проверьте использование памяти
nvidia-smi
# Убедитесь, что GPU имеет минимум 24 GB VRAM
# Если текущая GPU недостаточна — замените на GPU с 24+ GB VRAM
# (см. секцию 2.1 — Требования к GPU)
# Проверьте, нет ли посторонних процессов, занимающих VRAM
nvidia-smi --query-compute-apps=pid,name,used_memory --format=csv
# Остановите посторонние GPU-процессы, если найдены
# После чего перезапустите систему:
docker compose down
docker compose up -d
На серверах с несколькими GPU
OOM часто означает, что модель села на уже занятую карту (по умолчанию — GPU 0), а не на свободную. Явно выберите целевое устройство — см. Выбор GPU-устройства и работа с MIG (для нарезанных MIG-карт — Выбор MIG-инстанса).
Контейнер использует не тот GPU (GPU 0 вместо выбранного / MIG)¶
Симптом: задан конкретный GPU через NVIDIA_VISIBLE_DEVICES или device_ids, но контейнер всё равно грузит модель на GPU 0 (часто → CUDA out of memory, если GPU 0 уже занят).
Причина 1 — конфликт двух механизмов выбора. Одновременно заданы NVIDIA_VISIBLE_DEVICES в environment и device_ids в deploy.resources. Оставьте только один (см. Выбор GPU-устройства).
Причина 2 — карта в режиме MIG, выбор по индексу. Если целевая карта нарезана на MIG-инстансы, селектор по индексу (NVIDIA_VISIBLE_DEVICES: 7 или device_ids: ['7']) игнорируется, и контейнер падает на дефолтный GPU 0. MIG-инстанс адресуется только по UUID — см. Выбор MIG-инстанса.
Диагностика:
# Что реально видит контейнер (должен быть один нужный девайс):
docker exec llm-firewall-threat-detector nvidia-smi -L
# В режиме MIG? (колонка "MIG M." = Enabled у нарезанной карты)
nvidia-smi
# Получить UUID MIG-инстансов для NVIDIA_VISIBLE_DEVICES:
nvidia-smi -L
Решение: перейти на выбор по UUID (для MIG — по MIG-UUID), убрать блок deploy.resources.reservations.devices, добавить runtime: nvidia. Полный рецепт — на странице Конфигурация, разделы «Выбор MIG-инстанса» и «Параметризация UUID через .env».
Note
Хардкод device_map={"": 0} в коде ML-сервисов означает «первое видимое устройство» и корректен — фиксить нужно видимость устройств на уровне Docker, а не код.
Низкая производительность¶
Симптом: GPU utilization низкий, latency высокая.
# Мониторинг во время запросов
watch -n 0.5 nvidia-smi
# Если GPU utilization близок к 0% — модель не загрузилась на GPU
# (это нештатное состояние: ML-сервисы поддерживаются только на GPU).
# Проверьте переменные окружения:
# THREAT_DETECTOR_ML_DEVICE=cuda (не "gpu"!)
# TRANSLATION_SERVICE_MODEL_DEVICE=cuda
# CONTENT_SAFETY_ML_DEVICE=cuda
# Проверьте логи загрузки модели
docker compose logs threat-detector | grep -i "cpu\|fallback\|device"
NVIDIA driver not detected¶
Симптом: WARNING: The NVIDIA Driver was not detected.
# Проверьте драйвер
cat /proc/driver/nvidia/version
# Если ошибка — переустановите драйвер
sudo apt install -y nvidia-driver-535
sudo reboot
ML модели не загружаются¶
Симптом: Health check не проходит, сервис в restart loop.
# Проверьте логи
docker compose logs --tail=200 threat-detector
# Типичные причины:
# 1. Недостаточно RAM для загрузки модели
# 2. Модель не найдена по указанному пути
# 3. Несовместимая версия CUDA
# Проверка доступного RAM
free -h
# Проверка модели внутри контейнера
docker exec llm-firewall-threat-detector ls -la /models/
docker exec llm-firewall-content-safety ls -la /app/models/ 2>/dev/null || echo "No /app/models"
OPA/Policy sync ошибки¶
Симптом: PDP возвращает ошибки, политики не применяются.
# Проверьте OPA
curl -s http://localhost:8181/health | python3 -m json.tool
# Проверьте MinIO bucket
docker exec llm-firewall-minio-init mc ls myminio/policies/
# Проверьте наличие bundle
curl -s http://localhost:9000/policies/policies/default/bundle.tar.gz -o /dev/null -w "%{http_code}"
# Должен вернуть 200
# Принудительная пересборка bundle
curl -X POST http://localhost:8000/api/v1/sync/force
Ошибки БД¶
Симптом: Сервисы не запускаются, ошибки миграции.
# Проверьте PostgreSQL
docker compose logs postgres
# Проверьте миграции
docker compose logs profiles-registry-migrate
docker compose logs admin-api-migrate
# Ручной запуск миграции
docker compose run --rm profiles-registry-migrate alembic upgrade head
docker compose run --rm admin-api-migrate alembic upgrade head
Перезапуск после сбоя¶
# Перезапуск GPU-контейнеров
docker compose restart translation-service threat-detector content-safety
# Если не помогает — сброс GPU
sudo nvidia-smi --gpu-reset
# Полный перезапуск системы
docker compose down
docker compose up -d
Полезные команды диагностики¶
# === Информация о GPU ===
nvidia-smi -q
# === Проверка драйвера ===
cat /proc/driver/nvidia/version
# === Статус всех контейнеров ===
docker compose ps
# === Использование ресурсов контейнерами ===
docker stats --no-stream
# === Логи конкретного сервиса ===
docker compose logs --tail=100 <service-name>
# === Проверка сети между контейнерами ===
docker exec llm-firewall-gateway curl -s http://threat-detector:8090/healthz
# === Процессы на GPU ===
nvidia-smi --query-compute-apps=pid,name,used_memory --format=csv
# === Проверка Redis ===
docker exec llm-firewall-redis redis-cli ping
docker exec llm-firewall-redis redis-cli info memory
# === Проверка PostgreSQL ===
docker exec llm-firewall-postgres psql -U postgres -c "SELECT datname, pg_size_pretty(pg_database_size(datname)) FROM pg_database;"