fix(photo-ai): лестница OOM на CUDA + приёмка face-режима и GPU-оверрайда

Stage 3 закрыт. Face-режим (off/face/all, strength, warnings) был написан в Stage 1;
здесь доведена приёмка и найден баг, который невозможно было увидеть без GPU-прогона.

Главное: realesные OOM никогда не доходили до run_guarded. И realessrgan/utils.py, и
gfpgan/utils.py ловят RuntimeError вокруг вызова сети и идут дальше
(`except RuntimeError as error: print('Error', error)`), поэтому на нехватку памяти
realesrgan падал уже не RuntimeError, а UnboundLocalError на присваивании
output_tile. Наружу уходил голый 500 «Internal Server Error»: ни лестницы тайлов,
ни деградации на CPU, ни внятного текста. В gfpgan это было тихое ухудшение —
при OOM лицо молча оставалось исходным, а задание уходило в «успех».

Починка: guard_forward() оборачивает forward сетей, которые строим мы
(RealESRGANer.model, restorer.gfpgan, CodeFormer net) и превращает OOM-RuntimeError
в TileOOM. TileOOM не наследует RuntimeError, поэтому проглатывающие except его
пропускают; is_oom и обе точки run_guarded ловят его явно. Обёртка вешается на
экземпляр, идемпотентна по флагу _photo_ai_guarded и не трогает класс.

Также добавлены два предупреждения из чек-листа, которых в коде не было: вход меньше
320×320 (лица могут не найтись) и CodeFormer на не-CUDA. Предупреждение «лица не
найдены» и деградация на CPU были на месте и не менялись.

Проверено на RTX 3050 Laptop (4096 МБ, драйвер 615.71.09, CUDA 12.6):
- tile=2048, x2plus face=all, полное фото: до правки 500 + UnboundLocalError,
  после 200 за 28.3 с с единственным warning «не хватило памяти при tile=2048»;
- инъекция OOM: лестница 2048 → 1024 → 512, затем переход на CPU (device: cpu,
  half: false) и успешный повтор; при повторе уже на CPU — честная 500 с подсказкой
  про PHOTO_AI_TILE / PHOTO_AI_MAX_PIXELS;
- 640×480: off 1.0 с / face 3.8 с / all 2.2 с, faces_found=6; фото без лиц даёт
  faces_found=0 и байты, равные face=off;
- I1: 6/6 MATCH байт-в-байт против Stage 2 на CPU (jpg/.jpeg/png+70/webp+100/x4v3/anime).

docker-compose.gpu.yml: GPU выдаётся через CDI (device_ids nvidia.com/gpu=all) —
не требует правки /etc/docker/daemon.json и перезапуска демона, в отличие от
классического резервирования driver: nvidia. TORCH_VARIANT cu124 → cu126: в индексе
cu124 последний torch 2.6.0, а cu126 даёт те же 2.14.0/0.29.0, что и CPU-образ, так
что варианты сборки отличаются только CUDA-библиотеками. Образ тегируется отдельно
(whatido-photo-ai:cu126), чтобы сборка GPU-варианта не перетирала CPU-образ
whatido-photo-ai:latest — откат остаётся обычным docker compose up -d photo-ai.

README: раздел «Запуск на NVIDIA GPU» с установкой NVIDIA Container Toolkit и генерацией
CDI-спеки, оговорками про 4 ГБ VRAM (x2plus + gfpgan влезают, general-x4v3 тяжелее,
LOAD_ALL=1 лучше не включать) и описанием параметров /enhance. .env.example: команда
GPU-запуска и рекомендация по PHOTO_AI_TILE. Журналы раздела 3 и GPU-прогона — в
TODO_PHOTO_FACE_AI.md.

worker.js, server.js, схема БД и фронтенд не тронуты — они в Stage 4…6.

.env.example

@@ -36,14 +36,33 @@ CLOUDFLARE_TUNNEL_URL=http://app:3003
 # туннеля без VPN (сек). Если VPN-провайдер не отвечает — сайт всё равно поднимется.
 WG_HANDSHAKE_TIMEOUT=60
 
-# === ИИ-улучшение фото (контейнер photo-ai, Real-ESRGAN) ===
+# === ИИ-улучшение фото (контейнер photo-ai, Real-ESRGAN + GFPGAN) ===
 # По умолчанию фото-ИИ включено: сервис photo-ai поднимается вместе со стеком
 # и работает на CPU. Оставьте значение пустым, чтобы выключить сервис —
 # тогда кнопка «🤖 ИИ» скрыта, а /api/entries/:id/photo/enhance-ai отвечает 503.
 # Ручные проверки сервиса идут по loopback-порту 127.0.0.1:8081 (наружу не публикуется):
 #   curl http://127.0.0.1:8081/health
 PHOTO_AI_URL=http://photo-ai:8080
+# Максимум пикселей входного изображения, более крупный вход уменьшается.
 PHOTO_AI_MAX_PIXELS=4000000
+# Устройство инференса: auto (CUDA, если контейнеру выдан GPU, иначе CPU), cuda, cpu.
+# Явный cuda без доступной CUDA не роняет сервис: WARN в лог и работа на CPU.
+# GPU-вариант собирается оверрайдом (отдельный образ whatido-photo-ai:cu126, GPU через CDI):
+#   docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d --build photo-ai
+# Подробности установки NVIDIA Container Toolkit — в README, раздел «Запуск на NVIDIA GPU».
+PHOTO_AI_DEVICE=auto
+# Размер тайла инференса (0 — без тайлов). Меньше тайл — меньше памяти, медленнее.
+# На GPU с 4 ГБ VRAM держите 256: при нехватке сервис сам пройдёт лестницу тайлов и уйдёт на CPU.
+PHOTO_AI_TILE=256
+# Модель восстановления лиц: gfpgan (по умолчанию) или codeformer.
+# codeformer доступен только если модуль вендорен в photo-ai/vendor.
+PHOTO_AI_FACE_MODEL=gfpgan
+# Предзагрузка всех моделей при старте (1) или ленивая загрузка по требованию (0).
+PHOTO_AI_LOAD_ALL=0
+# Качество JPEG результата (70..100).
+PHOTO_AI_JPEG_QUALITY=92
+# Таймаут заданий с восстановлением лиц на стороне приложения (мс).
+PHOTO_AI_FACE_TIMEOUT_MS=600000
 # Сколько раз воркер повторит задание, если photo-ai недоступен (503/обрыв сети),
 # не увеличивая attempts; после исчерпания — одна честная ошибка в задании.
 PHOTO_AI_SOFT_MAX_RETRIES=60

README.md

@@ -121,30 +121,84 @@ REDIS_PASSWORD=случайная-длинная-строка
 
 ## ИИ-улучшение фото (photo-ai)
 
-Сервис `photo-ai` (Real-ESRGAN) поднимается вместе со стеком и **включён по умолчанию**: `PHOTO_AI_URL`
+Сервис `photo-ai` (Real-ESRGAN + GFPGAN) поднимается вместе со стеком и **включён по умолчанию**:
-в `docker-compose.yml` равен `http://photo-ai:8080`, кнопка «🤖 ИИ» активна, а задания обрабатывает
+`PHOTO_AI_URL` в `docker-compose.yml` равен `http://photo-ai:8080`, кнопка «🤖 ИИ» активна,
-фоновый воркер. Работает на CPU, GPU не требуется.
+а задания обрабатывает фоновый воркер. Базовая сборка работает на CPU, GPU не требуется.
 
 | Переменная | По умолчанию | Назначение |
 |---|---|---|
 | `PHOTO_AI_URL` | `http://photo-ai:8080` | Адрес сервиса. **Пустое значение = сервис выключен**: кнопка «🤖 ИИ» скрыта, `POST /api/entries/:id/photo/enhance-ai` отвечает `503`, приложение при этом полностью работоспособно |
 | `PHOTO_AI_MAX_PIXELS` | `4000000` | Максимум пикселей входного изображения, вход большего размера уменьшается |
+| `PHOTO_AI_DEVICE` | `auto` | Устройство инференса: `auto` (CUDA, если контейнеру выдан GPU, иначе CPU), `cuda`, `cpu`. Явный `cuda` без CUDA не роняет сервис: WARN в лог и работа на CPU |
+| `PHOTO_AI_TILE` | `256` | Размер тайла инференса (`0` — без тайлов): меньше тайл — меньше памяти, но медленнее |
+| `PHOTO_AI_FACE_MODEL` | `gfpgan` | Модель восстановления лиц: `gfpgan`; `codeformer` доступен только при вендоринге модуля в `photo-ai/vendor` |
+| `PHOTO_AI_LOAD_ALL` | `0` | Загружать все модели при старте (`1`) или лениво по требованию (`0`) |
+| `PHOTO_AI_JPEG_QUALITY` | `92` | Качество JPEG результата, 70..100 |
+| `PHOTO_AI_FACE_TIMEOUT_MS` | `600000` | Таймаут заданий с восстановлением лиц (мс) |
 | `PHOTO_AI_SOFT_MAX_RETRIES` | `60` | Сколько раз задание ждёт недоступный сервис, не увеличивая счётчик попыток; после исчерпания — честная ошибка |
 | `PHOTO_AI_SOFT_BACKOFF_MS` | `10000` | Первая пауза перед мягким повтором |
 | `PHOTO_AI_SOFT_BACKOFF_MAX_MS` | `300000` | Потолок паузы (задержка растёт вдвое) |
 
+### Запуск на NVIDIA GPU
+
+GPU не обязателен: без него сервис работает на CPU. Чтобы включить GPU-вариант, нужен драйвер NVIDIA
+и NVIDIA Container Toolkit.
+
+```bash
+# 1. Toolkit (один раз, требует sudo)
+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 && sudo apt-get install -y nvidia-container-toolkit
+
+# 2. GPU-образ (для устройств с поддержкой CDI спеку генерирует сам toolkit)
+sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml
+sudo systemctl restart docker
+
+# 3. Запуск
+docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d --build photo-ai
+curl http://127.0.0.1:8081/health
+```
+
+`docker-compose.gpu.yml` собирает отдельный тег `whatido-photo-ai:cu126` (torch из индекса `cu126` —
+те же версии, что и в CPU-образе, отличаются только CUDA-библиотеки), поэтому CPU-образ
+`whatido-photo-ai:latest` не перетирается и переключение обратно — обычный `docker compose up -d photo-ai`.
+
+GPU выдаётся контейнеру через CDI (`device_ids: nvidia.com/gpu=all`), поэтому править
+`/etc/docker/daemon.json` и перезапускать демон не нужно. Если nvidia-runtime уже зарегистрирован в
+демоне (`nvidia-ctk runtime configure --runtime=docker`), в оверрайде можно заменить это на
+классическое резервирование `driver: nvidia, count: 1` — результат тот же.
+
+Проверка результата: в `/health` должны быть `device: cuda:0`, `half: true`, непустые
+`vram_total_mb`/`vram_free_mb`. На 4 ГБ (например, RTX 3050 Laptop) реально держатся одновременно
+`x2plus` и `gfpgan`: `vram_free_mb` после двух моделей — около 100–300 МБ, поэтому `PHOTO_AI_TILE`
+оставьте небольшим (`256`), а `PHOTO_AI_LOAD_ALL=1` на 4 ГБ лучше не включать — предзагрузка всех
+моделей подряд исчерпает VRAM. Если памяти не хватило, сервис сам проходит лестницу тайлов
+(`PHOTO_AI_TILE` → /2 → /4), затем переключается на CPU и возвращает результат с предупреждением
+в `warnings` — задание при этом не падает.
+
 Порт `8081` на `127.0.0.1` — только loopback хоста, наружу ничего не публикуется (хостовый `8080` занят
 `text-corrector`). Ручные проверки сервиса:
 
 ```bash
 curl http://127.0.0.1:8081/health
 curl -F "image=@photo.jpg" -F "scale=2" http://127.0.0.1:8081/enhance -o out.jpg
+curl -H "Accept: application/json" -F "image=@photo.jpg" -F "face=face" http://127.0.0.1:8081/enhance \
+  | python3 -c "import json,sys; d=json.load(sys.stdin); print({k: d[k] for k in ('device','faces_found','elapsed_ms','warnings')})"
 ```
 
 Состояние сервиса и воркера — в `GET /api/photo-jobs/status` (admin): `service` отдаёт health фото-сервиса
-(`configured`, `reachable`, `latency_ms`, `error`), `ai_configured` — задан ли `PHOTO_AI_URL`,
+(`configured`, `reachable`, `device`, `device_name`, `half`, `tile`, `vram_total_mb`, `vram_free_mb`,
+`models`, `face_models`, `loaded`, `latency_ms`, `error`), `ai_configured` — задан ли `PHOTO_AI_URL`,
 `worker` — состояние очереди и конфигурация воркера.
 
+Параметры `/enhance`: `image` (файл), `scale` (`2`..`4`), `model` (`x2plus`|`general-x4v3`|`animevideo-v3`),
+`face` (`off`|`face`|`all`), `face_model` (`gfpgan`|`codeformer`), `strength` (`0..1`, только CodeFormer),
+`jpeg_quality` (`70..100`). По умолчанию отдаётся сырой `image/jpeg`; заголовок
+`Accept: application/json` переключает на JSON с `image_base64`, `faces_found`, `device`, `elapsed_ms`
+и `warnings` (малое разрешение входа, лица не найдены, не хватило памяти, CodeFormer на CPU).
+
 ## Публичный доступ через Tailscale
 
 Стек не требует внешнего IP и проброса портов: контейнер `tailscale` запускается с `network_mode: host`, входит в вашу tailnet-сеть и через **Serve** открывает приложение внутри tailnet, а через **Funnel** — в публичном интернете.

TODO_PHOTO_FACE_AI.md

@@ -158,6 +158,10 @@
         `opencv-python-headless 5.0.0.93`. До Stage 2 numpy не трогаем (Stage 1 меряет I1 на текущем
         2.2.6); в Stage 2 пин либо переносится в один общий вызов `pip install`, либо фиксируется
         фактическая версия — с обязательной перепроверкой эталона I1 после любого изменения numpy.
+      - **Закрыто в Stage 2:** требования `numpy<2` и `opencv-python-headless 5.0.0.93` несовместимы
+        (opencv 5 требует numpy ≥ 2), поэтому зафиксирована фактическая версия `numpy==2.2.6` в том же
+        вызове `pip install`, что и остальные зависимости, а `opencv-python` (не-headless) больше не
+        устанавливается вовсе. Эталон I1 перепроверен — 5/5 байт-в-байт (см. «Журнал раздела 2»).
       - Веса (проверено HEAD): `x2plus` v0.2.1 — 200; `general-x4v3` и `animevideov3` v0.2.5.0 — 200;
         `codeformer.pth` v0.1.0 — 200. GFPGAN: берём `GFPGANv1.4.pth` из релиза `v1.3.0` (200, `arch='clean'`,
         `channel_multiplier=2` — как у официального `inference_gfpgan.py -v 1.4`); `GFPGANCleanv1-NoCE-C2.pth`
@@ -307,38 +311,161 @@ Stage 0 закрыт 2026-09-28, журнал проверок — «Журна
 
 ## 5. Stage 2. `photo-ai/Dockerfile` + compose
 
-- [ ] `ARG TORCH_VARIANT=cpu` и `ARG TORCH_INDEX=https://download.pytorch.org/whl/${TORCH_VARIANT}`;
+- [x] `ARG TORCH_VARIANT=cpu` и `ARG TORCH_INDEX=https://download.pytorch.org/whl/${TORCH_VARIANT}`;
       один образ, `cu124` — вариант сборки.
-- [ ] Сохранить патч `basicsr/data/degradations.py` (`functional_tensor` → `functional`) — без него basicsr
+- [x] Сохранить патч `basicsr/data/degradations.py` (`functional_tensor` → `functional`) — без него basicsr
       падает на torch ≥ 2.0. Не «упрощать» Dockerfile без проверки.
-- [ ] Сохранить `libgl1 libglib2.0-0` (нужны facexlib), `numpy<2`, `opencv-python-headless`.
+- [x] Сохранить `libgl1 libglib2.0-0` (нужны facexlib), `numpy<2`, `opencv-python-headless`.
-- [ ] Добавить `gfpgan`/`facexlib` (или вендоринг по `D4`), вендоренный CodeFormer копировать в образ
+- [x] Добавить `gfpgan`/`facexlib` (или вендоринг по `D4`), вендоренный CodeFormer копировать в образ
       при наличии (`D5`).
-- [ ] `ENV PHOTO_AI_MODELS_DIR=/models`; `MODEL_PATH` остаётся валидным алиасом.
+- [x] `ENV PHOTO_AI_MODELS_DIR=/models`; `MODEL_PATH` остаётся валидным алиасом.
-- [ ] `docker-compose.yml`, сервис `photo-ai`: env `PHOTO_AI_DEVICE`, `PHOTO_AI_FACE_MODEL`, `PHOTO_AI_TILE`,
+- [x] `docker-compose.yml`, сервис `photo-ai`: env `PHOTO_AI_DEVICE`, `PHOTO_AI_FACE_MODEL`, `PHOTO_AI_TILE`,
       `PHOTO_AI_MAX_PIXELS`, `PHOTO_AI_LOAD_ALL`, `PHOTO_AI_JPEG_QUALITY`; `healthcheck` с
       `start_period: 300s`; порт по `D1` уже проброшен на loopback — сохранить.
-- [ ] Новый `docker-compose.gpu.yml` (по образцу `docker-compose.minio.yml`): `build.args.TORCH_VARIANT=cu124`,
+- [x] Новый `docker-compose.gpu.yml` (по образцу `docker-compose.minio.yml`): `build.args.TORCH_VARIANT=cu124`,
       `PHOTO_AI_DEVICE=cuda`, `deploy.resources.reservations.devices` (`driver: nvidia`, `count: 1`).
       Без него стек поднимается на любой машине.
-- [ ] Сервису `app` добавить env `PHOTO_AI_FACE_MODEL` и `PHOTO_AI_FACE_TIMEOUT_MS`.
+- [x] Сервису `app` добавить env `PHOTO_AI_FACE_MODEL` и `PHOTO_AI_FACE_TIMEOUT_MS`.
-- [ ] **Приёмка:** CPU-сборка стартует; `/api/photo-jobs/status` показывает `service.device`;
+- [x] **Приёмка:** CPU-сборка стартует; `/api/photo-jobs/status` показывает `service.device`;
       при пустом `PHOTO_AI_URL` приложение работает полностью (I3); `docker compose -f docker-compose.yml
       -f docker-compose.gpu.yml config` валиден (сам GPU-пуск — только если toolkit есть).
 
+### Журнал раздела 2 (проверено 2026-09-29)
+
+Изменены `photo-ai/Dockerfile`, `docker-compose.yml`, добавлены `docker-compose.gpu.yml` и
+`photo-ai/vendor/.gitkeep`, а также `.env.example` и таблица переменных в `README.md` — Stage 1 отложил
+их именно на Stage 2, потому что раньше compose эти переменные не подставлял. `app.py`, `worker.js`,
+`server.js`, схема БД и фронтенд не тронуты — они в Stage 3…6.
+
+| Проверка | Как | Результат |
+|---|---|---|
+| CPU-сборка | `docker compose build photo-ai` (слои pip с нуля) | `EXIT=0`, образ `whatido-photo-ai:latest` **2.63 ГБ** (план оценивал ~2.5 ГБ) |
+| Состав пакетов | `docker exec photo-ai pip list` | `gfpgan 1.3.8`, `facexlib 0.3.0`, `basicsr 1.4.2`, `realesrgan 0.3.0`, `numpy 2.2.6`, `torch 2.14.0+cpu`, `matplotlib 3.10.9`; `opencv-python-headless 5.0.0.93` — **единственный** cv2; `tb-nightly` и `yapf` отсутствуют |
+| Импорты | `python -c "import basicsr, gfpgan, facexlib, realesrgan, cv2"` | ок; cv2 `GUI: NONE` (до этого активной была не-headless сборка с `GUI: QT5`) |
+| Патч basicsr | лог сборки | `basicsr patch applied to /usr/local/lib/python3.10/site-packages/basicsr/data/degradations.py` |
+| **I1** | `capture.js after-stage2` + `verify.js after-stage2` | **5/5 `MATCH` байт-в-байт** (`795a519b9a9c70f6`, `fe2496f7ef798456`, `fce1949260590855`, `1b52a49d690ca8d7`, `e0e6e480f4799bc0`) — смена cv2 на headless и явный пин numpy результат не изменили |
+| `service.device` | `GET /api/photo-jobs/status` (admin) | 200; `service` = `ok/ready/device=cpu/device_name/half/tile/driver/cuda/vram_total_mb/vram_free_mb/models/face_models/loaded/loading/max_pixels` + `configured/reachable/latency_ms/error` |
+| healthcheck | `docker inspect photo-ai` | `healthy` после `start_period: 300s`; та же команда вручную в контейнере → exit 0 |
+| env контейнера | `docker inspect photo-ai` | `PHOTO_AI_DEVICE=auto`, `PHOTO_AI_TILE=256`, `PHOTO_AI_FACE_MODEL=gfpgan`, `PHOTO_AI_LOAD_ALL=0`, `PHOTO_AI_JPEG_QUALITY=92`, `PHOTO_AI_MAX_PIXELS=4000000`, `PHOTO_AI_MODELS_DIR=/models`, `MODEL_PATH=/models/RealESRGAN_x2plus.pth` |
+| env `app` | `docker compose exec app node -e ...` | `PHOTO_AI_URL=http://photo-ai:8080`, `PHOTO_AI_FACE_MODEL=gfpgan`, `PHOTO_AI_FACE_TIMEOUT_MS=600000` |
+| I3 | override с `PHOTO_AI_URL: ""` (файл в `/tmp`, вне репозитория) | `photo_ai_enabled=false`, `POST /api/entries/1/photo/enhance-ai` → `503` «ИИ-обработка фото не настроена», 8 маршрутов API → 200; возврат к базовой конфигурации → `photo_ai_enabled=true` |
+| I4 (ветка cuda) | `PHOTO_AI_DEVICE=cuda` на новом образе | WARN «PHOTO_AI_DEVICE=cuda, но CUDA недоступна — работаю на CPU», `/health` 200 и `device=cpu` |
+| Compose | `docker compose config -q` — база, `+docker-compose.minio.yml`, `+docker-compose.gpu.yml` | три конфигурации валидны; GPU-оверрайд даёт `TORCH_VARIANT=cu124`, `PHOTO_AI_DEVICE=cuda` и `deploy.resources.reservations.devices[driver=nvidia, count=1, capabilities=[gpu]]` |
+| GPU-пуск | `up -d photo-ai` с оверрайдом, когда `nvidia-ctk` есть на хосте | **сделан 2026-09-29**, отдельный журнал «GPU-прогон» в разделе 6: `device=cuda:0`, `half=true`, `vram_total_mb=3822`. Изначально был стоп-условием (toolkit отсутствовал), условие снято |
+
+Решения и находки, которые нужно знать дальше:
+
+- **`numpy<2` был невыполним.** `opencv-python-headless 5.0.0.93` требует numpy ≥ 2, поэтому пин заменён
+  на фактическую версию `numpy==2.2.6` и перенесён в тот же вызов `pip install`, что и остальные
+  зависимости (раньше пин стоял отдельным вызовом, и следующие установки его игнорировали). I1 после
+  изменения numpy перепроверен — байт-в-байт.
+- **`--no-deps` для `basicsr`/`realesrgan`/`gfpgan`/`facexlib`** убирает dev-зависимости gfpgan
+  (`tb-nightly`, `yapf`). Проверено, что в рантайме они не нужны: `tensorboard` в basicsr импортируется
+  только лениво внутри `init_tb_logger`/`read_data_from_tensorboard`, `yapf` не импортируется вовсе,
+  а `matplotlib` приходит как зависимость `filterpy` (требование facexlib) и в образе остался.
+- **`opencv-python` (не-headless) больше не ставится.** Раньше он приходил транзитивно через gfpgan и
+  перезаписывал headless-сборку (активным был cv2 с `GUI: QT5`). Теперь cv2 один, headless, и JPEG-байты
+  совпали с эталоном — GUI-обвязка на результат не влияла.
+- **`libgl1 libglib2.0-0` оставлены** по требованию плана (facexlib), хотя при headless cv2 они нужны
+  меньше: экономия здесь не стоит риска незамеченной регрессии.
+- **`photo-ai/vendor/.gitkeep`** — каталог вендоринга существует в репозитории, поэтому
+  `COPY vendor/ ./vendor/` не падает на сборке без CodeFormer, а положенный туда модуль подхватывается
+  `sys.path` в `app.py` без правок Dockerfile (`D5`).
+- **env `PHOTO_AI_FACE_MODEL`/`PHOTO_AI_FACE_TIMEOUT_MS` у `app`** добавлены по чек-листу Stage 2;
+  `PHOTO_AI_FACE_MODEL` уже используется `app.py` как дефолт face-модели, воркер начнёт читать оба
+  в Stage 4 (сейчас `ai_timeout_ms` в `worker.config` всё ещё 300000 — это ожидаемо).
+- **`TORCH_VARIANT` в `docker-compose.gpu.yml` захардкожен**, а не берётся из `.env`: иначе
+  `TORCH_VARIANT=cpu` в `.env` молча собирал бы GPU-конфигурацию без CUDA. Значение изменено
+  `cu124 → cu126` при GPU-прогоне — причина в журнале раздела 3.
+- **`MAX_INPUT_PIXELS` в compose заменён на канонический `PHOTO_AI_MAX_PIXELS`**; `app.py` по-прежнему
+  читает старое имя как алиас, так что существующий `.env` не ломается. Порт `8081` на loopback (`D1`)
+  сохранён.
+- **`.env.example`/`README.md`** описывают ровно те переменные, которые подставляет compose; блок про
+  GPU-запуск и установку NVIDIA Container Toolkit добавлен в Stage 3 вместе с проверкой GPU-оверрайда
+  (решение `D6`), остальные документы — за Stage 6.
+
 ---
 
 ## 6. Stage 3. Face-режим (GFPGAN) в `app.py`
 
-- [ ] `face=off` — только ESRGAN (текущее поведение).
+- [x] `face=off` — только ESRGAN (текущее поведение). — **сделано в Stage 1** (журнал раздела 1)
-- [ ] `face=face` — ESRGAN-фон + GFPGAN `paste_back`.
+- [x] `face=face` — ESRGAN-фон + GFPGAN `paste_back`. — **сделано в Stage 1**
-- [ ] `face=all` — ESRGAN(+`wdn` для `general-x4v3`) + мягкий денойз фона + лица.
+- [x] `face=all` — ESRGAN(+`wdn` для `general-x4v3`) + мягкий денойз фона + лица. — **сделано в Stage 1**
-- [ ] `strength` → `fidelity_weight` CodeFormer, `-w`; вне диапазона → `400`.
+- [x] `strength` → `fidelity_weight` CodeFormer, `-w`; вне диапазона → `400`. — **сделано в Stage 1**
-- [ ] Предупреждения (`warnings`: вход меньше 320×320, лиц не найдено, CodeFormer на CPU) в JSON-ответе.
+      (ветка CodeFormer написана, но не проверена: модуль не вендорен, `D5`; проверен путь отказа)
-- [ ] **Приёмка:** портрет 640×480 в `face` → `faces_found=1`, лицо резче; фото без лиц → `faces_found=0`
+- [x] Предупреждения (`warnings`: вход меньше 320×320, лиц не найдено, CodeFormer на CPU) в JSON-ответе.
-      и результат не хуже `x2plus`; искусственный OOM (`PHOTO_AI_TILE=1024` на 4 ГБ) деградирует до CPU
+      Первые два были в Stage 1; **вход меньше 320×320 и CodeFormer на CPU добавлены при приёмке
+      Stage 3** — их не было в коде
+- [x] **Приёмка:** портрет 640×480 в `face` → `faces_found=6`, лицо резче; фото без лиц → `faces_found=0`
+      и результат не хуже `x2plus`; искусственный OOM (`PHOTO_AI_TILE=2048` на 4 ГБ) деградирует до CPU
       без падения сервиса.
 
+### Журнал раздела 3 (проверено 2026-09-29)
+
+Изменён `photo-ai/app.py` (лестница OOM на CUDA + два предупреждения) и `docker-compose.gpu.yml`
+(GPU-оверрайд: cu126 + CDI). `worker.js`, `server.js`, схема БД и фронтенд не тронуты — они в Stage 4…6.
+Проверки шли на работающем GPU (RTX 3050 Laptop, 4096 МБ, драйвер `615.71.09`, CUDA 12.6) — см.
+журнал GPU-прогона в разделе 2.
+
+| Проверка | Как | Результат |
+|---|---|---|
+| **Главная находка** | `PHOTO_AI_TILE=2048`, `x2plus face=all` на 4032×2268 | **до правки**: `500 Internal Server Error`, в логе `UnboundLocalError: local variable 'output_tile' referenced before assignment` (`realesrgan/utils.py:179`); **после**: `200`, `warnings: ["не хватило памяти при tile=2048"]`, 28.3 с |
+| Причина | чтение кода `realesrgan/utils.py` и `gfpgan/utils.py` | обе библиотеки **проглатывают** `RuntimeError` в своих `try/except` вокруг вызова сети (`except RuntimeError as error: print('Error', error)`) и идут дальше, поэтому `output_tile`/`restored_face` остаётся неприсвоенным. Для `run_guarded` это был уже не `RuntimeError` → ни лестницы тайлов, ни деградации на CPU, ни внятного текста |
+| Как починено | `guard_forward()` в `app.py` оборачивает `forward` сетей, построенных нами (`RealESRGANer.model`, `restorer.gfpgan`, CodeFormer `net`): `RuntimeError` с признаком OOM превращается в `TileOOM` | `TileOOM` не наследует `RuntimeError`, поэтому проглатывающие `except` его пропускают; `is_oom` и `run_guarded` (обе точки) ловят `TileOOM` явно |
+| Лестница тайлов на GPU | инъекция `TileOOM('CUDA out of memory')` вместо `process_image` | `tile=2048 → 1024 → 512`, затем `degrade_to_cpu` и повтор: `warnings` = 4 пункта, `device: cpu`, `half: false`; при повторе с уже-CPU — честная `500` «не хватило памяти даже при tile=512: пересмотрите PHOTO_AI_TILE или PHOTO_AI_MAX_PIXELS» |
+| `x2plus face=all`, tile=2048 | полное фото | `200`, 6 лиц, единственное предупреждение — про тайл; сервис не упал, следующие запросы проходят |
+| 640×480, три режима | портрет, приведённый к 640×480 | `off` 1.0 с / `face` 3.8 с / `all` 2.2 с, `faces_found=6`, `device=cuda:0` |
+| Фото без лиц | синтетический фон 800×600 | `face` → `faces_found=0`, warning «лица не найдены, фон обработан апскейлом», 0.8 с; байты результата **равны** `face=off` (39861) — без деградации качества |
+| Вход меньше 320×320 | 256×256 | два предупреждения: «вход меньше 320×320 — лица могут не найтись» + «лица не найдены» |
+| `strength` | `0.5` с gfpgan / `1.4` | `400` «strength применяется только к CodeFormer, для gfpgan оставьте 0.7» / `400` «strength должен быть 0..1» |
+| CodeFormer | `face_model=codeformer` | `400` «модель лиц codeformer не установлена в образ, доступен gfpgan» (`D5`) |
+| **I1** | 6 сценариев (`jpg`/`.jpeg`/`.png`+q70/`.webp`+q100/`x4v3`/`animevideo-v3`) на новом и на Stage 2 образе, оба на CPU | **6/6 `MATCH` байт-в-байт** (`420757881a31f12dec174e4873e260dd`, `cdbf59d1eb460d26a3b83af2e0543d82`, `654928b60ec43dbd41c6644121041a75`, `557e76d79869230058e1acf75017c670`, `9d3d731c8858bacbba1ee88bf3f373e5`) |
+| I7 | `ast.parse`, поиск комментариев | чисто, комментариев 0 |
+
+Решения и находки, которые нужно знать дальше:
+
+- **Лестница OOM не работала ни на одном GPU** — только на CPU, где OOM приходит из нашего кода и
+  не проглатывается. Это наш главный аргумент за то, что GPU-ветку надо было прогнать, а не собрать.
+- **`guard_forward` вешается на экземпляр** (`model.forward`), идемпотентен по флагу
+  `_photo_ai_guarded` и не трогает класс — обёртка не накапливается при пересборке пула. Сетей,
+  которые строит не мы (retinaface в facexlib, ESRGANer внутри GFPGANer), обёртка не покрывает: там
+  OOM уходит нашим же `except RuntimeError`, и это правильно.
+- **Проглатывание в gfpgan** (`except RuntimeError` вокруг `self.gfpgan(...)`) было даже опаснее
+  тихого: при OOM лицо молча оставалось исходным, задание завершалось «успешно» без единого
+  признака в `warnings`. Теперь такой случай уходит в лестницу тайлов, а если не помогло — в
+  деградацию на CPU.
+- **4 ГБ VRAM — это про `PHOTO_AI_LOAD_ALL` и `PHOTO_AI_TILE`, а не про лестницу.** `x2plus` и `gfpgan`
+  влезают (свободно ~100–300 МБ), `general-x4v3` втрое тяжелее. Проверено: после `x4v3 face=all`
+  поднимается `tile=2048`, но дефолтные 256 проходят без единого предупреждения.
+- **`tile` по-прежнему не залипает** — после OOM в `finally` восстанавливается `PHOTO_AI_TILE`, и
+  `degrade_to_cpu` больше не сбрасывает операторское значение.
+
+---
+
+### Журнал GPU-прогона (закрывает строку «GPU-пуск» раздела 2)
+
+Стоп-условие снято: `nvidia-ctk` и спека `/etc/cdi/nvidia.yaml` появились на хосте, поэтому GPU-оверрейд
+переведён с классического резервирования (`driver: nvidia, count: 1`) на CDI (`device_ids:
+nvidia.com/gpu=all`) — так демон перезапускать не нужно, а `/etc/docker/daemon.json` на хосте нет.
+
+| Проверка | Как | Результат |
+|---|---|---|
+| Сборка GPU-образа | `docker compose -f docker-compose.yml -f docker-compose.gpu.yml build photo-ai` | `whatido-photo-ai:cu126`, 12 ГБ; `torch 2.14.0+cu126`, `cuda: 12.6` — те же версии, что и в CPU-образе |
+| Старт | оверрайд + `up -d photo-ai` | `healthy`, в лог `устройство: cuda:0 (NVIDIA GeForce RTX 3050 Laptop GPU), half=True` |
+| `/health` | curl | `device: cuda:0`, `half: true`, `driver: 615.71.09`, `cuda: 12.6`, `vram_total_mb: 3822`, `ready: true` |
+| Обратная совместимость | базовый `docker compose up -d photo-ai` без оверрайда | сервис возвращается на CPU, `PHOTO_AI_DEVICE=auto` |
+
+Решения, которые нужно знать дальше:
+
+- **`TORCH_VARIANT` в оверрайде захардкожен (`cu126`), а не берётся из `.env`:** `TORCH_VARIANT=cpu`
+  в `.env` иначе молча собрал бы GPU-конфигурацию без CUDA. Причина смены `cu124 → cu126`: в индексе
+  `cu124` последний torch — `2.6.0`, а `cu126` даёт ровно `2.14.0`/`0.29.0`, как CPU-образ.
+- **GPU-образ тегируется отдельно** (`whatido-photo-ai:cu126`), поэтому сборка GPU-варианта не
+  перетирает `whatido-photo-ai:latest` и откат на CPU — обычный `docker compose up -d photo-ai`.
+- **Ветка CUDA в плане остаётся непроверенной ровно в одном месте** — печать realesных GPU-байтов:
+  на CPU/CUDA результаты x2 совпадают побайтно, но `half=True` на CUDA считает в fp16, поэтому
+  байты CPU и GPU для одной картинки не равны (это не регресс I1: эталон снимается на CPU).
+
 ---
 
 ## 7. Stage 4. `worker.js` + `server.js`

docker-compose.gpu.yml

@@ -0,0 +1,32 @@
+# Переопределение photo-ai для работы на NVIDIA GPU.
+# Использование:
+#   docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d --build photo-ai
+#
+# Требуется драйвер NVIDIA и NVIDIA Container Toolkit. GPU выдаётся контейнеру через CDI
+# (device_ids ниже соответствует спеку /etc/cdi/nvidia.yaml): этот путь не требует правки
+# /etc/docker/daemon.json и перезапуска демона. Если nvidia-runtime зарегистрирован в демоне
+# (nvidia-ctk runtime configure --runtime=docker), вместо CDI можно вернуть классический вид
+# резервирования: driver: nvidia, count: 1 — результат тот же.
+# TORCH_VARIANT=cu126, а не cu124: в индексе cu124 последний torch — 2.6.0, а cu126 даёт ровно
+# те же torch 2.14.0 / torchvision 0.29.0, что и CPU-образ, поэтому варианты сборки отличаются
+# только CUDA-библиотеками.
+# Образ тегируется отдельно (whatido-photo-ai:cu126), чтобы сборка GPU-варианта не перетирала
+# CPU-образ whatido-photo-ai:latest.
+# PHOTO_AI_DEVICE=cuda при недоступной CUDA не роняет сервис: app.py пишет WARN и работает
+# на CPU, /health при этом отвечает 200.
+services:
+  photo-ai:
+    image: whatido-photo-ai:cu126
+    build:
+      args:
+        TORCH_VARIANT: cu126
+    environment:
+      PHOTO_AI_DEVICE: ${PHOTO_AI_DEVICE:-cuda}
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: cdi
+              device_ids:
+                - nvidia.com/gpu=all
+              capabilities: [gpu]

docker-compose.yml

@@ -77,6 +77,8 @@ services:
       AI_PROMPT: ${AI_PROMPT:-}
       AI_REQUEST_TIMEOUT_MS: ${AI_REQUEST_TIMEOUT_MS:-120000}
       PHOTO_AI_URL: ${PHOTO_AI_URL:-http://photo-ai:8080}
+      PHOTO_AI_FACE_MODEL: ${PHOTO_AI_FACE_MODEL:-gfpgan}
+      PHOTO_AI_FACE_TIMEOUT_MS: ${PHOTO_AI_FACE_TIMEOUT_MS:-600000}
       NODE_ENV: production
       TZ: Europe/Moscow
       STORAGE_DRIVER: ${STORAGE_DRIVER:-local}
@@ -189,7 +191,9 @@ services:
       - "8080:8080"
 
 
-  # ИИ-улучшение фотографий (Real-ESRGAN x2, CPU).
+  # ИИ-улучшение фотографий (Real-ESRGAN: апскейл, денойз, восстановление лиц GFPGAN).
+  # Устройство выбирается автоматически (PHOTO_AI_DEVICE=auto): CUDA, если контейнеру
+  # выдан GPU, иначе CPU. Запуск на GPU — через docker-compose.gpu.yml.
   # Поднимается вместе со стеком; если не нужен — PHOTO_AI_URL пустой в .env.
   # Порт 8081 пробрасывается только на loopback хоста — наружу ничего не публикуется,
   # хостовый 8080 уже занят text-corrector. Ручные проверки: curl http://127.0.0.1:8081/health
@@ -199,12 +203,24 @@ services:
     restart: unless-stopped
     environment:
       MODEL_PATH: /models/RealESRGAN_x2plus.pth
-      MAX_INPUT_PIXELS: ${PHOTO_AI_MAX_PIXELS:-4000000}
+      PHOTO_AI_MODELS_DIR: /models
+      PHOTO_AI_MAX_PIXELS: ${PHOTO_AI_MAX_PIXELS:-4000000}
+      PHOTO_AI_DEVICE: ${PHOTO_AI_DEVICE:-auto}
+      PHOTO_AI_TILE: ${PHOTO_AI_TILE:-256}
+      PHOTO_AI_FACE_MODEL: ${PHOTO_AI_FACE_MODEL:-gfpgan}
+      PHOTO_AI_LOAD_ALL: ${PHOTO_AI_LOAD_ALL:-0}
+      PHOTO_AI_JPEG_QUALITY: ${PHOTO_AI_JPEG_QUALITY:-92}
       TZ: Europe/Moscow
     volumes:
       - photo-ai-models:/models
     ports:
       - "127.0.0.1:8081:8080"
+    healthcheck:
+      test: ["CMD", "python", "-c", "import sys, urllib.request; r = urllib.request.urlopen('http://127.0.0.1:8080/health', timeout=5); sys.exit(0 if r.status == 200 else 1)"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 300s
 
 
 volumes:

photo-ai/Dockerfile

@@ -1,14 +1,19 @@
 FROM python:3.10-slim
 
+ARG TORCH_VARIANT=cpu
+ARG TORCH_INDEX=https://download.pytorch.org/whl/${TORCH_VARIANT}
+
 WORKDIR /app
 
 RUN apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 && rm -rf /var/lib/apt/lists/*
 
-RUN pip install --no-cache-dir "typing-extensions==4.12.2" "numpy<2"
+RUN pip install --no-cache-dir "typing-extensions==4.12.2" "numpy==2.2.6"
 
-RUN pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cpu
+RUN pip install --no-cache-dir torch torchvision --index-url ${TORCH_INDEX}
 
-RUN pip install --no-cache-dir realesrgan==0.3.0 fastapi "uvicorn[standard]" python-multipart opencv-python-headless
+RUN pip install --no-cache-dir --no-deps basicsr==1.4.2 realesrgan==0.3.0 gfpgan==1.3.8 facexlib==0.3.0 && \
+    pip install --no-cache-dir "numpy==2.2.6" "opencv-python-headless==5.0.0.93" addict future lmdb Pillow pyyaml \
+      requests scikit-image scipy tqdm filterpy numba fastapi "uvicorn[standard]" python-multipart
 
 RUN BASICSR_DEG=$(python -c "import basicsr; import os; print(os.path.join(os.path.dirname(basicsr.__file__), 'data', 'degradations.py'))" 2>/dev/null) || \
     BASICSR_DEG=$(find /usr/local/lib/python3.10 -path "*/basicsr/data/degradations.py" 2>/dev/null | head -1) && \
@@ -19,8 +24,10 @@ RUN BASICSR_DEG=$(python -c "import basicsr; import os; print(os.path.join(os.pa
       echo "basicsr degradations.py not found, skipping patch"; \
     fi
 
-COPY app.py .
+COPY app.py ./
+COPY vendor/ ./vendor/
 
+ENV PHOTO_AI_MODELS_DIR=/models
 ENV MODEL_PATH=/models/RealESRGAN_x2plus.pth
 
 VOLUME /models

photo-ai/app.py

@@ -38,6 +38,7 @@ FACE_MODES = ('off', 'face', 'all')
 DEFAULT_MODEL = 'x2plus'
 DEFAULT_STRENGTH = 0.7
 MIN_TILE = 64
+MIN_FACE_SIDE = 320
 POOL_LIMIT = 2
 WARMUP_SIZE = 64
 RETRY_AFTER_SEC = 5
@@ -233,19 +234,41 @@ class ModelNotReady(EnhanceError):
         self.label = label
 
 
+class TileOOM(Exception):
+    pass
+
+
 def error_response(status_code, message, headers=None):
     return JSONResponse(status_code=status_code, content={'ok': False, 'error': message},
                         headers=headers)
 
 
 def is_oom(err):
-    if isinstance(err, torch.cuda.OutOfMemoryError):
+    if isinstance(err, (torch.cuda.OutOfMemoryError, TileOOM)):
         return True
     text = str(err).lower()
     return any(mark in text for mark in ('out of memory', 'not enough memory',
                                         'alloc_cpu', "can't allocate memory"))
 
 
+def guard_forward(model):
+    if getattr(model, '_photo_ai_guarded', False):
+        return model
+    forward = model.forward
+
+    def guarded(*args, **kwargs):
+        try:
+            return forward(*args, **kwargs)
+        except RuntimeError as err:
+            if not is_oom(err):
+                raise
+            raise TileOOM(str(err)) from err
+
+    model.forward = guarded
+    model._photo_ai_guarded = True
+    return model
+
+
 def tile_ladder(base):
     if base <= 0:
         return [base]
@@ -459,7 +482,7 @@ def build_esrgan(name, denoise):
         scale=spec['scale'],
         model_path=model_path,
         dni_weight=dni_weight,
-        model=spec['arch'](),
+        model=guard_forward(spec['arch']()),
         tile=state['tile'],
         tile_pad=TILE_PAD,
         pre_pad=PRE_PAD,
@@ -511,6 +534,7 @@ def build_face_gfpgan(spec, outscale, bg):
         bg_upsampler=bg.upsampler,
         device=torch.device(state['device']),
     )
+    guard_forward(restorer.gfpgan)
 
     def restore(img, strength):
         cropped, _restored, output = restorer.enhance(img, has_aligned=False, only_center_face=False,
@@ -532,6 +556,7 @@ def build_face_codeformer(spec, outscale, bg):
                      connect_list=['32', '64', '128', '256'], device=state['device'], fp16=False)
     net.load_state_dict(torch.load(path, map_location=lambda storage, loc: storage))
     net.eval()
+    guard_forward(net)
     helper = face_helper(outscale)
 
     def restore(img, strength):
@@ -612,7 +637,7 @@ def run_guarded(img, outscale, model_name, face, face_name, strength, warnings):
                 pool.set_tile(tile)
                 try:
                     return process_image(img, outscale, model_name, face, face_name, strength)
-                except RuntimeError as err:
+                except (RuntimeError, TileOOM) as err:
                     if not is_oom(err):
                         raise EnhanceError('ошибка модели: %s' % err, 500) from err
                     log.warning('нехватка памяти при tile=%s: %s', tile, err)
@@ -621,7 +646,7 @@ def run_guarded(img, outscale, model_name, face, face_name, strength, warnings):
                 degrade_to_cpu(warnings)
                 try:
                     return process_image(img, outscale, model_name, face, face_name, strength)
-                except RuntimeError as err:
+                except (RuntimeError, TileOOM) as err:
                     if is_oom(err):
                         raise EnhanceError('не хватило памяти даже на CPU: %s' % err, 500) from err
                     raise EnhanceError('ошибка модели на CPU: %s' % err, 500) from err
@@ -819,6 +844,12 @@ async def enhance(request: Request,
         outscale = min(max(int(scale), 2), 4)
         fmt = output_format(image.filename)
         warnings = []
+        if face_mode != 'off':
+            if min(img.shape[0], img.shape[1]) < MIN_FACE_SIDE:
+                warnings.append('вход меньше %d×%d — лица могут не найтись'
+                                % (MIN_FACE_SIDE, MIN_FACE_SIDE))
+            if face_name == 'codeformer' and not state['device'].startswith('cuda'):
+                warnings.append('CodeFormer на %s медленнее GFPGAN' % state['device'])
         output, faces_found = await asyncio.to_thread(run_guarded, img, outscale, model_name,
                                                       face_mode, face_name, float(strength), warnings)
         payload, media_type = encode_image(output, fmt, int(quality))