huggingface-vision-trainer

Hugging Face Vision Model Training предназначен для обучения и fine-tuning компьютерного зрения через Transformers и Hugging Face Jobs. Он покрывает три основных класса задач: детекцию объектов с D-FINE, RT-DETR v2, DETR или YOLOS; классификацию изображений с timm-моделями и Transformers-классификаторами; а также сегментацию и image matting с SAM или SAM2. Руководство рассчитано на работу с облачными GPU Jobs, но описывает и локальный запуск вспомогательных скриптов. Результат обучения должен сохраняться в Hugging Face Hub, потому что среда Jobs эфемерна. Для детекции датасет должен иметь колонку objects с bbox и category; area допустима дополнительно. Поддерживаются xywh в стиле COCO и xyxy в стиле Pascal VOC, категории могут быть числами или строками, а image_id необязателен и при отсутствии создаётся автоматически. Для классификации нужны image и label; label может быть ClassLabel, числом или строкой, а типичные имена label, labels, class и fine_label распознаются автоматически. Для SAM/SAM2 нужны image, бинарная mask и prompt: JSON с bbox или point, отдельная bbox-колонка либо point-колонка. Bbox для prompt должны быть в абсолютном формате xyxy. Неизвестные или собственные датасеты сначала проверяются dataset_inspector.py; отчёт READY означает совместимый формат, NEEDS FORMATTING — необходимость преобразования. Перед затратным запуском проверяются аккаунт Hugging Face, вход через hf auth whoami и токен с правом записи. Jobs требуют тарифный план Pro, Team или Enterprise. Токен передаётся в secrets задания, а в Transformers TrainingArguments после разбора аргументов явно попадает в hub_token до создания Trainer. На неразрушающий локальный запуск скрипты используют PEP 723 inline dependencies и запускаются через uv run. Для облачной задачи в параметрах должны быть push_to_hub и hub_model_id; иначе результаты могут остаться только в эфемерной среде. Рекомендуемый порядок состоит из пяти шагов: проверить аккаунт, токен и датасет; исследовать формат неизвестного датасета; выбрать размер выборки и validation split; подготовить один из object_detection_training.py, image_classification_training.py или sam_segmentation_training.py; затем отправить Job и сохранить идентификатор. Для OD доступны параметры model_name_or_path, dataset_name, image_square_size, train_val_split и ограничения числа samples. Для классификации отдельно задаются image_column_name, label_column_name, batch size и число эпох. Для SAM/SAM2 выбираются prompt_type bbox или point, колонка prompt либо dedicated bbox/point, mask_column_name и настройки заморозки vision или prompt encoder. Время обучения должно быть больше стандартного таймаута в 30 минут. Выбор hardware flavor зависит от размера изображений, модели и объёма данных; в руководстве приведены варианты от T4 до L4, A10G и A100. Для наблюдения используется Trackio, а для оценки стоимости предусмотрен отдельный estimate_cost.py. Типовые проблемы — нехватка VRAM, несовпадение формата датасета, ошибка 401 при отправке в Hub, таймаут, отсутствие test split и слабый mAP. Их нужно устранять проверкой входных колонок, размера batch, таймаута, прав токена и метрик, а не повторным запуском вслепую. Навык не обещает, что любой датасет готов к обучению, и не отменяет проверку лицензии, приватности данных, квоты и бюджета GPU. В нём есть готовые production-oriented скрипты и ссылки на документацию Transformers, Jobs и модели, но конкретные dataset ID, model ID, регион инфраструктуры и стоимость должны быть подтверждены перед отправкой задания.