Инструменты и окружение CV-инженера

Окружение курса

Код курса вы запускаете у себя: прогнать модель на своём кадре, замерить, сколько это заняло, посмотреть, где она ошиблась. Соберём окружение под это одним заходом — версии здесь жёсткие, и половина вопросов «почему у меня не работает» снимается именно на этом шаге.

Python и виртуальное окружение

Берите Python 3.13 — на нём собран и прогнан весь курс. Версии новее брать не советуем: научные пакеты выпускают готовые сборки с задержкой, и пока сборки нет, pip пытается компилировать пакет прямо у вас, что на Windows обычно кончается стеной ошибок компилятора.

Заведите папку под курс и создайте в ней окружение, чтобы жёсткие версии курса не разъехались с другими вашими проектами:

mkdir cv-course
cd cv-course
python -m venv .venv

Активация зависит от системы: source .venv/bin/activate на Linux и macOS, .venv\Scripts\Activate.ps1 в PowerShell, .venv\Scripts\activate.bat в cmd. После активации в начале строки терминала появится (.venv).

PyTorch ставится не с PyPI

Это первое место, где легко потерять несколько часов. Обычная команда pip install torch под Windows ставит колесо, собранное без CUDA — платформы вычислений на видеокартах NVIDIA, через которую считает вся экосистема зрения. Ошибки при этом не будет: код запустится, обучение молча уйдёт на процессор и станет медленнее в десятки раз. Поэтому torch берётся из индекса PyTorch, а ключ -i (короткая запись --index-url) на этот индекс и указывает:

pip install torch==2.13.0 torchvision==0.28.0 -i https://download.pytorch.org/whl/cu130

Хвост cu130 — версия CUDA, под которую собрано колесо. Она должна быть не новее той, что поддерживает ваш драйвер: со старым драйвером берите cu126, а если видеокарты нет вовсе — cpu. Версию драйвера показывает nvidia-smi, там же в правом верхнем углу написана максимальная поддерживаемая CUDA.

Остальное ставится обычным способом. Соберите файл requirements.txt:

numpy==2.4.6
scipy==1.18.0
pillow==12.3.0
pyyaml==6.0.3
tqdm==4.70.0
requests==2.34.2
opencv-python==5.0.0.93
ultralytics==8.4.115
timm==1.0.28
albumentations==2.0.8
kornia==0.8.3
supervision==0.29.1
transformers==5.14.1
imagehash==4.3.2
onnx==1.22.0
onnxruntime-gpu==1.28.0
rfdetr==1.9.3
pytorch-lightning==2.6.5
accelerate==1.14.0
peft==0.20.0
torchmetrics==1.9.0
pycocotools==2.0.11
faster-coco-eval==1.7.2
lap==0.5.13
filterpy==1.4.5
rapidocr==3.9.2
Levenshtein==0.27.4
fiftyone==1.20.0
pandas==3.0.5
matplotlib==3.11.1
kagglehub==1.0.2
ezc3d==1.7.2
huggingface-hub==1.26.0
datasets==5.0.1
onvif-python==0.3.1
psutil==7.2.2
py-cpuinfo==9.0.0
av==18.0.0

pip install -r requirements.txt

Версии выписаны точные, и это не занудство: соседние выпуски ultralytics и opencv регулярно расходятся между собой, а разбирать потом чужой конфликт зависимостей дольше, чем поставить нужные версии сразу. Тяжёлое сюда не входит: инструменты экспорта моделей ставятся отдельно, когда понадобятся.

И ещё две команды следом

Установка на строке fiftyone притормозит: этот пакет тянет за собой собственную базу MongoDB. Заодно он приносит с собой чужой opencv. Поэтому сразу после установки выполните:

pip install --force-reinstall --no-deps opencv-python==5.0.0.93

Дело в том, что FiftyOne объявляет зависимость opencv-python-headless<5 и ставит версию 4.10. У OpenCV две сборки под разными именами — обычная opencv-python и opencv-python-headless, та же библиотека без оконной части, для серверов без экрана. Обе кладут на диск один и тот же пакет cv2, поэтому чужая 4.10 перебивает нашу 5.0.0.93, и без этой команды проверка ниже напечатает opencv 4.10. Команда ставит нужную сборку последней и тем самым возвращает и версию, и окна: cv2.imshow у вас работать будет. --no-deps нужен, чтобы вместе с ней не переустановился numpy.

Прописать это строкой в requirements.txt нельзя: pip сверяет весь файл целиком и отказывается ставить пару, которая противоречит объявленным границам FiftyOne. Отсюда и отдельная команда — она эти границы обходит сознательно. Ограничение у FiftyOne устарело: с opencv 5 он и наборы читает, и своё приложение открывает, а до того, какая из двух сборок положила cv2, ему дела нет. После этого pip check будет жаловаться на несошедшиеся границы — так и задумано, окружение от этого не ломается.

Вторая команда — пакет для работы с лицами:

pip install --no-deps insightface==1.0.1

Флаг --no-deps здесь по той же причине, что и отдельная команда выше. insightface объявляет зависимостью onnxruntime — сборку под процессор, — и при обычной установке кладёт её рядом с onnxruntime-gpu из списка. Две сборки в одном окружении делят между собой одно имя onnxruntime и спорят за то, какие устройства доступны; на видеокарте после этого не считается ничего. Остальные зависимости insightface в списке уже есть, так что отключать их безопасно. GPU-сборка при этом умеет и процессор: если видеокарты нет, всё то же самое считается на нём, только медленнее.

Проверка

Соберите файл check.py и запустите его. Он ничего не качает и в сеть не ходит — только смотрит, что пакеты встали и видна ли видеокарта:

import cv2
import torch
import ultralytics

print("torch       ", torch.__version__)
print("сборка CUDA ", torch.version.cuda or "нет — это сборка под процессор")
print("карта видна ", torch.cuda.is_available())

if torch.cuda.is_available():
    card = torch.cuda.get_device_properties(0)
    print("устройство  ", card.name)
    print("видеопамять ", f"{card.total_memory / 1024**3:.1f} ГБ")

print("opencv      ", cv2.__version__)
print("ultralytics ", ultralytics.__version__)

Вот что он печатает на машине, где собирался курс:

Ключевые строки — вторая и третья. Если в сборке CUDA стоит прочерк, значит поставилось колесо с PyPI: переставьте torch командой с --index-url. Если сборка с CUDA, а карта видна всё равно False, дело в драйвере — он старше, чем версия CUDA в колесе.

А главная строка здесь — видеопамять. Её объём решает, какая модель у вас влезет и с каким размером входа; марка и поколение карты влияют куда меньше. Курс сделан на карте с 8 ГБ, и примеры обучения подобраны так, чтобы в эти 8 ГБ помещаться.

Если подходящей видеокарты нет

Библиотеки зрения по умолчанию считают на картах NVIDIA. У AMD своя платформа, ROCm: под Linux на ней работают и PyTorch, и Ultralytics, под Windows поддержка появилась недавно и покрывает только свежие карты — Radeon RX 9070 и 9070 XT, RX 9060 XT, RX 7900 XTX, PRO W7900, AI PRO R9700. Для Radeon постарше под Windows рабочего пути нет: остаётся Linux или облако. У Apple Silicon свой ускоритель, MPS: прогнать готовую модель хватает, обучать на нём не стоит.

Своей карты может не быть вовсе — тогда остаётся облако, и бесплатных лимитов на учебные прогоны там хватает. Как завести Google Colab и Kaggle и что там с ограничениями — отдельный шаг ниже в этом уроке.

И не всё в курсе вообще требует видеокарты: замеры скорости, экспорт моделей, ускорение под процессор, работа с документами и распознавание текста проходятся на обычном ноутбуке.

Редактор

Подойдёт любой. Если выбираете — VS Code с расширениями Python и Pylance; после создания окружения выберите его интерпретатором проекта через Ctrl+Shift+P → Python: Select Interpreter и путь внутри .venv. Часть материала удобнее гонять в блокнотах Jupyter — это страницы, где код разбит на ячейки: каждая запускается отдельно, вывод появляется прямо под ней, а переменные остаются общими на весь блокнот. Открывает их у вас на машине расширение Jupyter — поставьте вместе с двумя предыдущими. Облачные Colab и Kaggle — те же блокноты, только в браузере: там ставить ничего не нужно.