Усунення несправностей

Помилки згруповано за текстом повідомлення. Якщо вашого повідомлення тут немає, поширені запитання пояснюють ситуації, які не є несправностями, а libreyolo models повідомляє, що саме може завантажити ваше встановлення.

ModuleNotFoundError з назвою пакета, який ви не імпортували

Деяким сімействам потрібна необов'язкова додаткова залежність. У повідомленні вказано відсутній пакет, а не назву додаткової залежності, тому виправлення не завжди очевидне зі стека викликів.

Запустіть libreyolo models. Для кожного сімейства з відсутньою залежністю буде показано точну команду pip, яка його вмикає, тож зіставляти пакет із додатковою залежністю самостійно не потрібно. libreyolo models --json виводить ті самі відомості як об'єкт.

На сторінці встановлення перелічено всі додаткові залежності та їхнє призначення.

Для інференсу ONNX потрібен onnxruntime

ImportError: ONNX inference requires onnxruntime. Install with: pip install onnxruntime

Базовий пакет не залежить від середовища виконання, оскільки потрібний варіант визначає ваше обладнання. Установіть onnxruntime для CPU або onnxruntime-gpu для CUDA. Обидва надають той самий модуль onnxruntime, тому встановлюйте лише один.

Модель ONNX не знайдено

FileNotFoundError: ONNX model not found: <path>

Шлях визначається відносно робочого каталогу, а не скрипту. Повідомлення також з'являється, коли експорт непомітно записав файл в інше місце: export() повертає записаний шлях, тому збережіть повернене значення замість припущення про ім'я.

NotImplementedError від train()

Не кожне сімейство підтримує навчання. Деякі перенесено лише для передбачення, валідації та експорту, і їхній train() спричиняє помилку замість імітації роботи.

Причину пояснено у відповідному пункті поширених запитань. Щоб перевірити конкретне сімейство до написання скрипту навчання, перегляньте його сторінку моделі.

NotImplementedError від export()

Сімейство може підтримувати задачу, але не її експорт. Часто це трапляється з EoMT: export() приймає семантичну задачу й спричиняє помилку для segment і panoptic, оскільки потрібний їм контракт середовища виконання для масок запитів не визначено.

NotImplementedError: LibreEoMT instance and panoptic export need query-mask runtime contracts.

На сторінці кожного сімейства є матриця експорту з перевіреними поєднаннями задач і форматів.

Нестача пам'яті CUDA

Спочатку зменште batch, потім imgsz. Обидва параметри приблизно пропорційно впливають на пам'ять, але batch можна зменшити, не змінюючи того, що бачить модель.

Якщо збій стається під час валідації, а не навчання, валідація має власний розмір пакета, тому зменште і його.

У Windows GPU, який керує дисплеєм, має ще один режим збою, схожий на випадкову помилку CUDA, а не на нестачу пам'яті: драйвер скидає GPU, який не відповідає довше за граничний час, і припиняє поточний процес. Тривалі ядра на карті, підключеній до монітора, можуть спричинити цей збій.

Ваги не завантажуються

Під час першого використання ваги отримуються з Hugging Face й кешуються локально. У поширених запитаннях описано розташування кешу та повністю автономну роботу.

Якщо завантаження повертає 404, перевірте передане ім'я файла. URL утворюється з нього разом із суфіксом задачі, тому ім'я, що не відповідає опублікованій контрольній точці, створює неіснуючий URL. Точні опубліковані імена файлів наведено в таблиці контрольних точок кожної сторінки моделі.

Навчання зависає або перезапускається у Windows

Windows не має fork, тому робочі процеси завантажувача даних запускаються повторним імпортом вашого скрипту. Без захисної умови if __name__ == "__main__": кожен процес повторно запускає виклик навчання, що призводить до взаємного блокування або нескінченного створення процесів.

def main():
    ...  # створіть модель і викличте train()

if __name__ == "__main__":
    main()

workers=0 також запобігає цьому ціною пропускної здатності. Захисна умова є кращим виправленням.

Дві несправності без помилки

Решта цієї сторінки присвячена помилкам. Ці дві ситуації гірші, оскільки код працює й повертає те, що здається правильним.

Індексування одного результату

predict() повертає один Results для одного зображення та список для кількох. Індексування результату одного зображення вибирає виявлення, а не зображення:

result = model.predict("image.jpg")   # об'єкт Results
result.boxes                          # усі виявлення, правильно
result[0].boxes                       # ОДНЕ виявлення, без повідомлення

Помилки немає, оскільки індексування Results є припустимою операцією, що повертає підмножину. Код, написаний для форми списку, непомітно повідомляє одну рамку на зображення. Індексуйте лише те, що точно є списком.

Читання метрик як атрибутів

val() повертає звичайний словник із ключами назв метрик, а не об'єкт із доступом через атрибути:

metrics = model.val(data="coco8.yaml")
metrics["metrics/mAP50-95"]   # правильно
metrics.box.map               # AttributeError

Ключі мають простори імен metrics/ і speed/. Один раз виведіть словник, щоб побачити результат своєї задачі, оскільки набір залежить від неї.

Перевірка датасету перед навчанням

Більшість збоїв навчання спричиняють проблеми датасету. libreyolo doctor data.yaml виконує перевірки справності датасету виявлення й повідомляє результати за рівнем серйозності, що швидше за читання стека викликів із першої епохи.

from libreyolo import doctor

report = doctor.diagnose("data.yaml", imgsz=640)
if report.errors:
    ...

Каталог перевірок наведено для команди doctor.