MAI/docs/TROUBLESHOOTING_RU.md

Поиск и устранение проблем

1. Не открывается источник видео

Симптом:

• Capture open failed

Проверки:

1. Верный ли SOURCE.
2. Для камеры: правильный ли индекс 0, 1, 2.
3. Для RTSP: доступен ли поток из этой сети.
4. Для UDP: идет ли поток на указанный порт.
5. Для файла: существует ли путь и читается ли файл.

2. Проект запускается, но не использует GPU

Проверки:

1. Установлен ли GPU-вариант torch.
2. Совместимы ли версия CUDA и wheel torch.
3. Видит ли Python CUDA:

import torch
print(torch.cuda.is_available())

4. Не стоит ли CPU-only wheel.

3. В Docker нет GPU

Симптом:

• внутри контейнера torch.cuda.is_available() == False

Проверки:

1. Установлен ли NVIDIA драйвер на хосте.
2. Установлен ли NVIDIA Container Toolkit.
3. Поддерживает ли ваш Docker runtime gpus: all.
4. Не запущен ли контейнер на машине без доступной NVIDIA GPU.

4. В Docker не видна обычная webcam на Windows

Это типичная проблема Windows Docker Desktop.

Практические варианты:

• использовать RTSP;
• использовать UDP-видеопоток;
• использовать внешний capture-процесс вне контейнера;
• запускать локально на Windows без Docker.

5. Есть видео, но нет детекций

Проверки:

1. Тот ли MODEL_PATH.
2. Совместима ли модель с текущим кодом.
3. Правильный ли TARGET_CLASS_ID.
4. Не слишком ли высокий CONF.
5. Реально ли цель различима на этом разрешении.

6. Появляются детекции, но guidance не следует за ними

Важно:

• guidance строится не по "любой текущей рамке YOLO", а по выбранному lock/tracker state;
• при miss может работать удержание через Kalman/KLT;
• статус HOLD и REACQ означают, что проект находится не в чистой детекции.

Проверки:

1. Что в overlay пишется в строках miss, KLT valid, G HOLD или G REACQ.
2. Есть ли свежий track_log_*.csv.
3. Не слишком ли жесткие условия handoff/switch.

7. Не создается guidance_state.json

Проверки:

1. Включен ли GUIDANCE_EXPORT_ENABLE.
2. Есть ли права на запись в каталог.
3. Не держит ли файл другой процесс.

Если в логах есть:

Permission denied: guidance_state.json.tmp

это обычно означает, что файл временно заблокирован другим процессом или watcher'ом.

8. Не работает proto_udp

Проверки:

1. AUTOPILOT_BACKEND = "proto_udp"
2. PROTO_UDP_ENABLE = True
3. Правильные ли HOST и PORT
4. Видит ли сеть UDP-пакеты
5. Совпадает ли формат пакета с приемником

Практическая проверка:

• поднимите простой UDP listener;
• убедитесь, что приходят пакеты при наличии цели.

9. Не работает mavlink

Проверки:

1. Установлен ли pymavlink
2. Верный ли MAVLINK_CONNECTION
3. Доступен ли endpoint
4. Нет ли firewall/маршрутизации, блокирующих UDP

10. Не работает msp

Проверки:

1. Установлен ли pyserial
2. Верный ли MSP_PORT
3. Верный ли MSP_BAUD
4. Есть ли права доступа к порту

11. Видео не пишется

Проверки:

1. SAVE_INFER_VIDEO = True
2. Каталог записи существует
3. OpenCV может открыть VideoWriter
4. Кодек mp4v поддерживается в вашей среде

12. Проект слишком медленный

Проверки:

1. Есть ли GPU.
2. Не работает ли все на CPU.
3. Не слишком ли тяжелый full-frame режим.
4. Не включены ли лишние debug-наложения.
5. Не используется ли SHOW_OUTPUT там, где окно не нужно.

13. Сборка Docker слишком тяжелая

В проекте уже добавлен .dockerignore, который исключает:

• cvat/
• dataset_prep/
• видео
• старые логи
• архивы

Если сборка все равно тяжелая, проверьте:

1. не лежат ли рядом новые большие файлы, не попавшие в ignore;
2. не добавлены ли лишние каталоги в build context.

14. Что сделать перед обращением к разработчику

Подготовьте:

1. какой источник видео использовался;
2. локальный запуск или Docker;
3. backend команд;
4. последние track_log_*.csv и track_summary_*.json;
5. скриншот overlay;
6. точный текст ошибки.