Контрольні точки та ваги

Де шукається контрольна точка

Посилання на модель без компонента каталогу, наприклад LibreYOLO9t.pt, визначається відносно weights/ у поточному робочому каталозі. Якщо існує weights/LibreYOLO9t.pt, використовується цей файл; якщо файл із такою назвою існує в самому робочому каталозі, використовується він; інакше weights/LibreYOLO9t.pt стає ціллю завантаження.

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

from libreyolo import LibreYOLO, SAMPLE_IMAGE # Назва файла без шляху перетворюється на weights/LibreYOLO9t.pt;# якщо файла ще немає, його буде завантажено туди.model = LibreYOLO("LibreYOLO9t.pt")print(model(SAMPLE_IMAGE).boxes)

from libreyolo import LibreYOLO # Шлях із компонентом каталогу використовується точно як записано,# файл ніколи не отримується з мережі.model = LibreYOLO("/opt/models/LibreYOLO9t.pt")print(model.family, model.size, model.task)

Автоматичне завантаження

Коли визначеного шляху не існує, LibreYOLO розбирає назву файла, щоб отримати сімейство, розмір і задачу, а потім запитує URL-адресу завантаження у відповідного сімейства. Більшість сімейств створює її на основі організації LibreYOLO у Hugging Face, де кожна контрольна точка має власний репозиторій, названий за файлом:

https://huggingface.co/LibreYOLO/<name>/resolve/main/<name>.pt

Суфікс варіанта датасету залишається частиною назви репозиторію, тому контрольна точка, навчена на даних, відмінних від типових для сімейства, визначається у власному репозиторії й не перезаписує типову.

Саме передавання виконується захищено, оскільки обрізаний файл ваг згодом спричиняє незрозумілу помилку. Завантаження потоково записується у файл .part і атомарно переміщується на місце лише після завершення, тому перерваний процес ніколи не залишає наполовину записану контрольну точку за кінцевим шляхом. Перерване передавання поновлюється зі зміщення в байтах із використанням валідатора HTTP і починається з нуля, якщо сервер указує на зміну об'єкта. Після помилок виконується три повторні спроби з експоненційною затримкою. Паралельні процеси, націлені на той самий шлях, використовують файл блокування, тому два одночасні запуски навчання завантажують файл лише один раз. Якщо сімейство отримує файл зі стороннього хоста, а не з організації LibreYOLO, воно може зафіксувати контрольну суму й відхилити файл у разі невідповідності.

Якщо встановлено HF_TOKEN або токен кешовано у ~/.cache/huggingface/token, він додається як bearer-токен. Його додають лише до URL-адрес huggingface.co, тому сімейство, що завантажує з іншого хоста, ніколи його не отримує.

Не кожне сімейство підтримує автоматичне завантаження. Деякі навмисно не повертають URL-адресу, оскільки опубліковані ваги не можна розповсюджувати, і повідомлення про помилку пояснює, що потрібно надати натомість. Інші виводять повідомлення про ліцензію до початку передавання. Це повідомлення під час виконання сигналізує, що умови контрольної точки вужчі за умови коду, тому його варто прочитати, а не прокручувати.

Організація Hugging Face

Опубліковані ваги розміщено на huggingface.co/LibreYOLO, по одному репозиторію на контрольну точку. Кожен репозиторій містить ліцензію, і вона не обов'язково однакова в межах сімейства: сімейство з кодом під ліцензією MIT може мати ваги з іншою ліцензією. Репозиторій є авторитетним джерелом. На сторінці кожної моделі в розділах «Контрольні точки» та «Ліцензування» наведено опубліковані контрольні точки сімейства й їхні ліцензії.

Робота офлайн

Коли файли вже доступні локально, бібліотека не потребує мережевого доступу. Є два способи роботи:

Заздалегідь заповніть каталог weights/ поруч із місцем запуску завдання. Достатньо один раз отримати контрольні точки на підключеному комп'ютері, а потім скопіювати каталог; описаний вище етап визначення знайде їх і не звертатиметься до мережі.

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

До датасетів застосовується окреме правило: вони визначаються в ~/datasets або в каталозі, указаному змінною LIBREYOLO_DATASETS_DIR, якщо її встановлено.

Безпека завантаження

Контрольні точки є pickle-файлами, а pickle може виконати довільний код під час відкриття. LibreYOLO вважає кожен файл ваг недовіреним і завантажує його через шлях PyTorch із weights_only=True, що обмежує засіб десеріалізації тензорами й невеликим набором безпечних типів. Це стосується переданого вами файла, а не лише файлів, завантажених LibreYOLO. У збірці PyTorch, надто старій для підтримки цього аргументу, завантаження відхиляється, а не виконується небезпечно.

Деякі upstream-контрольні точки навчання містять об'єкти, які відхиляє обмежений засіб десеріалізації, наприклад об'єкт конфігурації з фреймворку, у якому їх навчено. LibreYOLO не потребує цих об'єктів метаданих, тому під час перетворення кожен заблокований клас замінюється інертним підставним класом, який задовольняє засіб десеріалізації, нічого не виконуючи, а до перетвореного файла потрапляють лише тензори. Чутливі назви модулів повністю відхиляються, а не підміняються, і цикл повторних спроб обмежено, тому файл, створений для нескінченної послідовності заблокованих класів, завершує роботу безпечно. Решту цього шляху описано в розділі імпорт наявних ваг.

Метадані контрольної точки

Контрольна точка LibreYOLO є словником, ключ model якого містить словник стану PyTorch. Схема v1.0 вимагає дев'ять ключів, які разом дають фабриці змогу ідентифікувати файл без розбору його назви чи здогадів за формами тензорів.

Задачі з додатковою структурою записують її поруч із цими ключами. Контрольні точки пози додають num_keypoints і keypoint_dim, а також можуть додавати сигми OKS для кожної ключової точки. Контрольні точки OCR вбудовують повний набір символів CTC, тож файл є самодостатнім. Контрольні точки відновлення можуть записувати тип погіршення та коефіцієнт збільшення. Контрольні точки засобу навчання додають стан поновлення, зокрема epoch, стан оптимізатора й ваги EMA; опубліковані ваги для інференсу не повинні його містити.

Файл, що відповідає всім дев'ятьом ключам, завантажується через шлях метаданих. Інакше він або перетворюється, якщо сімейство розпізнає його структуру, або завантажується через шлях сумісності з попередженням про відсутні дані.

Перевірка контрольної точки

# Читає метадані без створення моделі та повідомляє,# чи відповідають вони схемі.libreyolo metadata path=weights/LibreYOLO9t.pt

libreyolo metadata path=weights/LibreYOLO9t.pt --json

from libreyolo.utils.serialization import (    load_untrusted_torch_file,    validate_checkpoint_metadata,) loaded = load_untrusted_torch_file("weights/LibreYOLO9t.pt") # Повертає список проблем. Порожній список означає відповідність файла схемі v1.0.print(validate_checkpoint_metadata(loaded))print(loaded["model_family"], loaded["size"], loaded["task"], loaded["nc"])

libreyolo metadata ніколи не створює модель, тому працює з файлом, сімейство якого не встановлено, і з файлом, щодо якого ви не впевнені.