Контракти інтеграції моделей Transformers

Опубліковано 3 листопада 2026

30 липня 2026 року Transformers увімкнув масштабовану скалярну увагу (SDPA) PyTorch для T5. Як побічний ефект, декодер UMT5 отримав можливість звертатися до майбутніх токенів. Під час навчання він міг підглядати відповідь, яку мав передбачити. Нічого не зламалося, і помилка залишалася в main майже два місяці.

Коли ми згодом повторно відтворили ці коміти, невелика модель UMT5, що працювала на CPU, виявила помилку в кожному з них. Цей допис присвячено цій моделі та тестам, побудованим навколо неї.

Чому помилки потрапляють у main

Transformers підтримує понад 750 типів моделей, а його набір тестів великий: понад 88 000 тестів на CPU у main і понад 200 000 тестів на GPU під час щоденного запуску. Тести моделей — лише частина цього: ми також тестуємо пайплайни, навчання, розподілене виконання, квантизацію та ядра уваги.

Інтеграційні тести завантажують справжні контрольні точки та перевіряють API моделі на реальному обладнанні. Запускати все це під час кожного PR означало б тримати велику кількість GPU зайнятими цілий день, що непрактично. На момент, коли запланований запуск виявить регресію, вона вже може бути в main.

Наш підхід полягає в тому, щоб натомість зменшити модель. Ми створюємо фікстуру: невелику модель, створену з конфігурації справжньої контрольної точки, з меншою кількістю вужчих шарів, але з усіма наявними типами шарів, а також без змін у файлах її токенізатора та процесора. Її публікують один раз, а потім повторно використовують. Ми запускаємо «швидкі інтеграційні тести» для неї на недорогому CPU-раннері. У нашому дослідженні CPU експериментальна фікстура UMT5 використовувала 66 МБ ваг; вихідна контрольна точка має розмір 1 227 МБ.

Це також стосується дуже великих моделей: деякі з них не вміщуються на наших стандартних GPU-раннерах, але їхні фікстури працюють на CPU.

Інтегратори моделей уже створюють крихітні тестові моделі (контрольні точки Transformers tiny-random-*). Ми хотіли отримати спільний рецепт і перевірки, які виходять за межі завантаження моделі та виконання прямого проходу. Помилка UMT5 без проблем пройшла б звичайний прямий прохід.

Фікстури не замінять повні інтеграційні тести, але під час PR вони дають нам шанс виявити помилки до того, як ті потраплять у main.

Представляємо контракти інтеграції моделей

transformers-mic — це запропонований стандарт пакування таких тестів. Контракт інтеграції моделі (MIC) складається з трьох частин:

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

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

Контракт охоплює архітектуру та сценарій використання, а не одну контрольну точку: сумісні контрольні точки можуть спільно використовувати фікстуру, водночас кожна з них зберігає власні очікувані результати. Ми публікуємо їх у huggingface-mic.

Наприклад, контракт SmolLM генерує текст із таких підказок, як «The capital of France is», і порівнює ідентифікатори токенів із записаною відповіддю. Після завантаження моделі й токенізатора код генерації, спрощений до однієї підказки, має вигляд:

inputs = tokenizer("The capital of France is", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=4, do_sample=False)
new_tokens = outputs[:, inputs["input_ids"].shape[1]:]
print(tokenizer.batch_decode(new_tokens, skip_special_tokens=True))

Він також порівнює втрати під час навчання, перевіряє, що градієнти є скінченними, і підтверджує, що крок оптимізатора змінює ваги. Дивіться повний файл usage.md.

Датасет fleet на Hub фіксує кожен MIC на незмінній ревізії разом із версіями пакетів, використаними для запису його базових результатів. Кожен запуск CI записує ревізію fleet, яку він використовував, тож ми можемо відтворити її пізніше.

Під час PR ми вибираємо MIC на основі файлів, які змінює патч.

Регресія UMT5

Ми повторно запускали зафіксовані MIC на комітах Transformers за п’ять місяців. Невелика фікстура UMT5 виявила регресію від моменту її появи 30 липня 2026 року до виправлення 28 вересня. Логарифмічні ймовірності міток відрізнялися від перевіреного базового результату на 1,22, а втрати під час навчання — приблизно на 0,20.

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

Потім ми скасували виправлення у гілці для перевірки в CI Transformers. Перевірка завершилася невдачею з тими самими відмінностями, а крок запуску вибраного контракту T5 тривав на CPU 13,4 секунди без урахування підготовки.

Результати повторного запуску та демонстрація CI містять вимірювання та деталі відтворення.

Як зменшуються моделі

Перший рецепт був простим: зменшити розмірність і залишити менше шарів. Для змішаних архітектур цього було недостатньо. Немає сенсу залишати два шари, якщо обидва використовують ковзну увагу, а шари з повною увагою зникають.

Тепер рецепт складається з чотирьох кроків:

Зменшити конфігурацію. Почати зі справжньої контрольної точки та зменшити розміри прихованих представлень, кількість голів уваги й глибину. Зберегти різні типи шарів, зокрема поєднання ковзної та повної уваги або щільних шарів і MoE-шарів. Деяким архітектурам потрібні додаткові правила, щоб зберегти сумісність компонентів. Ми також вивчаємо власні тести Transformers для моделі: ModelTester у test_modeling_<model>.py уже вручну вибирає невелику конфігурацію, тож беремо його розміри для будь-якої ширини, яку наше загальне правило не знає за назвою.
Зберегти препроцесинг без змін. Зберегти словник, спеціальні токени та розмірності входу й побайтно скопіювати файли токенізатора та процесора. Завантаження і препроцесинг є частиною того, що ми хочемо тестувати.
Створити та перевірити ваги. Спробувати випадкові ваги з фіксованим seed і змінити входи, щоб перевірити реакцію моделі. Якщо вона не реагує, спробувати навчити її на невеликій порції прикладів контракту. Повторно завантажити збережену модель і перевірити, що виходи, втрати та градієнти є скінченними. Невдалі збірки відхилити.
Зафіксувати й записати. Зберегти прийняті ваги та виміряти відтворювані виходи на завідомо справній збірці Transformers. Перевірити базові результати для кожної підтримуваної платформи та точності, а потім опублікувати зафіксований знімок. CI повторно використовує його; він не перебудовує фікстуру для кожного PR.

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

Звіт про зменшення Llama 4 Scout показує, як це виглядає на великій моделі. 108,6 мільярда параметрів перетворюються на 44,7 мільйона. Стек vision зменшується з 34 шарів до 2, а мовний стек — з 48 до 4, при цьому зберігаються перевірені типи шарів і стиль маршрутизації MoE.

Створення MIC за допомогою агентів

Наш CLI, tmic, створює контракт і будує фікстуру. Для нової моделі LLM створює чернетку коду використання та маніфесту, а запуски на CPU і GPU вимірюють кандидатні базові результати. LLM створює чернетку, але не затверджує її. Зміни очікувань потребують перевірки людиною.

Щоб спробувати це на своїй машині, використайте вихідну контрольну точку замість org/model:

pip install "transformers-mic[runtime]" "hf-doc-builder @ git+https://github.com/huggingface/doc-builder.git"
hf auth login
tmic run org/model --local-only --fixtures-only --no-history --bill-to ''

На вашій машині команда створює чернетку контракту, будує фікстуру та записує її базові результати, просячи вас перевірити кожен крок, і зупиняється до завантаження будь-чого. Для нової моделі чернетка надходить від LLM через Inference Providers, а оплата списується з вашого облікового запису (--bill-to ''). Документація CLI описує окремі кроки.

Ми використовували агентів для створення MIC для різних сімейств моделей. Коли вони натикалися на крайовий випадок, ми виправляли сам рецепт, а не одну фікстуру, за допомогою експертів із моделей. Опубліковані моделі та наявні прогалини наведені у просторі покриття.

Випадкові ваги проти перенавчання

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

Тож ми навчили її на кількох тонах, поєднаних зі словами на кшталт «red» і «green». Ми не навчали її розпізнавання мовлення, а лише робили зміни аудіо помітними в її виходах. У нашому дослідженні ініціалізації ваг фікстури Whisper із випадковими вагами виявили 18 із 24 внесених несправностей. Фікстури з перенавчанням виявили всі 24.

Це дає нам два способи створення ваг:

Почати з випадкових ваг і фіксованого seed.
Перенавчити на кількох прикладах, наприклад «The capital of France is» => «Paris».

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

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

Відкриті питання

Станом на 1 листопада 2026 року завдання MIC у CI Transformers повідомляє про помилки, але не блокує PR. Чи має воно блокувати PR, залежить від речей, які ми ще не виміряли:

Скільки реальних помилок воно виявляє під час PR, а не лише під час повторних запусків?
Як часто воно змушує нас переслідувати хибні тривоги?
Скільки роботи потребує перевірка базових результатів?

Ми також не знаємо, скільки помилок, як-от помилка декодування Whisper з допомогою, проявляються лише на справжніх вагах, або чи виявляє перенавчання реальні помилки, які пропускають випадкові ваги.

Покриття все ще неповне — як для сімейств моделей, так і для API, якими користуються люди. Коли регресія прослизає, ми можемо додати відсутній сценарій використання та повторно запустити його на зламаній і виправленій версіях. Ми зберігатимемо наявні тести, доки не буде враховано їхнє покриття.

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

Хочете допомогти? Виберіть модель без покриття з простору покриття, спробуйте робочий процес tmic і додайте сценарій використання або перевірте згенерований контракт.