Transformers documentation

Проверки pull request

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Проверки pull request

Когда вы открываете pull request, CI Hugging Face выполняет несколько проверок, которые должны пройти успешно, прежде чем ваш PR будет объединён.

Исправление CI

В большинстве случаев make style достаточно, чтобы пройти проверку качества кода, которая является наиболее частой причиной сбоев.

make style

При сбоях в согласованности репозитория, копиях или автоматически сгенерированных файлах выполните make fix-repo. Эта команда за один проход исправляет стиль, копии, docstrings и автоматически сгенерированные файлы.

make fix-repo

Для более масштабных изменений приведённая ниже последовательность из трёх команд покрывает все проверки. Она тяжелее, но позволяет выявить все проблемы до отправки изменений.

make fix-repo   # auto-fix everything that can be auto-fixed
make typing     # check types and model structure, fix any errors manually
make check-repo # verify all checks pass, fix anything that remains

make typing обнаруживает ошибки типов и нарушения структуры модели, которые вы исправляете вручную. make check-repo выполняет финальную проверку в режиме только для чтения, чтобы вы могли убедиться, что всё готово.

CI иногда работает нестабильно. Если проверка завершилась ошибкой по причине, не связанной с вашим изменением, обратитесь к мейнтейнеру, чтобы он перезапустил её.

Качество кода

Проверка качества кода охватывает форматирование, импорты, проверку типов и правила структуры модели. Она соответствует командам make fix-repo и make typing.

make style (входит в make fix-repo) автоматически исправляет линтинг и форматирование Ruff, порядок импортов в __init__.py и согласованность автоматического сопоставления.

make typing выполняет проверку типов с помощью ty и валидирует правила TRansFormers (TRF), которые охватывают соглашения об именовании классов конфигурации и сигнатуры forward(). Ошибки типов и нарушения правил TRF сообщают конкретный номер правила и должны исправляться вручную. Правила находятся в репозитории mlinter. Запустите python -m utils.mlinter --list-rules, чтобы увидеть все правила TRF, или python -m utils.mlinter --rule TRFXXX, чтобы просмотреть полную документацию по конкретному правилу.

Если для правила TRF требуется исключение, выберите один из этих вариантов (подробнее см. в разделе Подавление нарушений).

  • Добавьте имя вашей модели в список allowlist_models для соответствующего правила в utils/mlinter/rules.toml. Используйте этот вариант, если исключение требуется для всего файла модели.
  • Добавьте # trf-ignore: TRFXXX на той же строке, что и отмеченная конструкция, или на строке непосредственно над ней. Используйте это, если исключение требуется только для одной отмеченной конструкции.

Согласованность репозитория

Проверка согласованности репозитория аналогична make check-repo, за исключением того, что она останавливается при первом же сбое. Она поддерживает внутреннюю согласованность репозитория в следующих категориях: публичные объекты остаются импортируемыми, скопированный код синхронизирован с исходным, а автоматически сгенерированные файлы (заглушки, doctests, метаданные) отражают текущее состояние кода. Для новых моделей также проверяется, что каждый новый класс модели зарегистрирован в автоматических сопоставлениях.

КатегорияЧто проверяетсяИсправлено автоматически?
Файлы инициализацииФайлы __init__.py в src/transformers/models/ актуальныmake fix-repo
Копии и модульность# Copied from — блоки совпадают с исходным кодом, а модульно сгенерированные файлы актуальныmake fix-repo
Docstrings и документацияСтроки документации аргументов соответствуют сигнатурам функций и оглавлению документацииmake fix-repo
Файлы, сгенерированные автоматическиDummies, типизация конвейеров, список doctest, метаданные, таблица зависимостейmake fix-repo
Проверка конфигурацииКлассы конфигурации имеют валидные контрольные точки в docstring, а атрибуты конфигурации соответствуют файлу моделированияСправочник
Назначение рецензентаКаждая директория модели и каждое правило в файле ревьюера по-прежнему доходит до ревьюераСправочник

Назначение рецензента

.github/scripts/codeowners_for_review_action фиксирует, кто ревьюит какие файлы.

Права собственности определяются для каждого файла, начиная с наиболее специфичных.

ГдеПохоже,Используйте для
Файл модели# Reviewers: @login в начальном блоке комментариев файла modular_<model>.py или modeling_<model>.pyмодель, которой требуется кто-то, кроме владельца модальности. Модульный конвертер копирует заголовок в сгенерированный файл моделирования, поэтому тег сохраняется при повторной генерации
Правило пути/src/transformers/<area>/ @login в .github/scripts/codeowners_for_review_actionвсё, что не является моделью
Таблица модальностей@@modality/vision @login, в том же файлекаждая модель, чья страница документации находится в этом разделе docs/source/en/_toctree.yml
Универсальный* @Rocketknight1 @ArthurZuckerничего, кроме этого, не заявляет

Для новой модели не требуется вносить записи в другие места: добавление её страницы документации в _toctree.yml, что уже требуется проверкой оглавления документации, помещает её в соответствующую модальность, а таблица модальностей покрывает её дальше.

make check-repository-consistency запускает utils/check_reviewers.py, который завершается с ошибкой, если модель не назначена никому, кроме общего обработчика, если правило больше не соответствует ни одному файлу, или если таблица модальностей не совпадает с оглавлением. Его резолвер не является зависимостью transformers; он указан в utils/checkers-requirements.txt, который запускатель проверки устанавливает при первом запуске в среде. Если установка невозможна — например, при отсутствии сети — проверка сообщает об этом и проходит, а не блокирует вас. Пути вне src/transformers/models, у которых нет владельца, сообщаются как примечание; список их можно получить с помощью:

python utils/check_reviewers.py --strict

Тесты

CI запускает целевой подмножество тестов в зависимости от того, что изменяет ваш PR. CI выполняет тесты в слегка рандомизированном порядке с помощью pytest-random-order, чтобы выявить связанные тесты. В начале запуска выводится случайное зерно, что позволяет воспроизвести тот же порядок с помощью --random-order-seed=<seed>.

Если тест проходит локально на GPU, но не проходит в CI, установите TRANSFORMERS_TEST_DEVICE="cpu", чтобы проверить, воспроизводится ли ошибка на CPU.

TRANSFORMERS_TEST_DEVICE="cpu" pytest tests/models/my_model/ -v

Разделы ниже объясняют, как работает выбор тестов, какие задачи выполняются и как обрабатывать медленные тесты.

Выбор тестов

CI не запускает полный набор тестов для каждого PR. CI пропускает тесты, помеченные @slow, для каждого PR, а maintainer запускает их на GPU, когда PR переходит на ревью.

utils/tests_fetcher.py отслеживает зависимости импортов в изменённых вами файлах, чтобы определить затронутые тесты, и запускает только их. Он также выявляет регрессии в других моделях, если вы изменяете общие утилиты. Скрипт выводит список изменённых файлов и затронутых тестов, а затем записывает этот список в tests_torch_test_list.txt.

Используйте fetcher, чтобы точно воспроизвести то, что выполняется в CI.

python utils/tests_fetcher.py
python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_preparation/tests_torch_test_list.txt)

Изменение основных файлов, таких как modeling_utils.py или generation/utils.py, запускает все тесты моделей, а не только затронутую подмножество.

Вы также можете запускать все тесты для вашей модели без условий. Прямой запуск — это более быстрый локальный контроль корректности, но он не выявит регрессии в других моделях, вызванные изменениями в общем коде, к которому вы обращались.

pytest tests/models/my_model/ -v

Категории тестовых заданий

Тесты распределены между параллельными CI-заданиями, и каждое задание выбирает файлы по шаблону пути. Соответствующие задания для PR модели:

  • tests_torch: тесты моделирования (tests/models/*/test_modeling_*.py)
  • tests_tokenization: тесты токенизатора (tests/models/*/test_tokenization_*.py)
  • tests_processors: тесты процессоров и экстракторов признаков (tests/models/*/test_(processing|image_processing|feature_extractor)_*.py)
  • tests_generate: тесты генерации
  • pipelines_torch: тесты пайплайнов
  • tests_training_ci: тесты цикла обучения
  • tests_tensor_parallel_ci: тесты тензорного параллелизма
  • tests_fsdp_ci: тесты FSDP

Медленные тесты

Регулярные запуски CI пропускают тесты, помеченные декоратором @slow. Они загружают реальные чекпоинты или требуют значительных вычислительных ресурсов, поэтому выполняются на GPU-инстансах, а мейнтейнеры запускают их, когда ваш PR переходит на этап ревью.

Медленные тесты выполняются на NVIDIA A10, а численные результаты могут незначительно отличаться между аппаратным обеспечением CI и вашей локальной машиной. При добавлении новой модели мейнтейнеры обычно при необходимости корректируют эти значения в тестах.

Запустите медленные тесты локально с помощью команды ниже.

RUN_SLOW=1 python -m pytest tests/models/my_model/ -v

Сборка документации

Задача build_pr_documentation собирает документацию и генерирует её предпросмотр. Бот публикует ссылку на предпросмотр в вашем PR, и проверка должна пройти успешно перед слиянием. Чаще всего причиной сбоев является отсутствующая запись в toctree. Чтобы собрать документацию локально, см. README.md в папке docs.

# Скопировано из syntax

Для новых моделей всегда предпочитайте модульный рабочий процесс (modular_*.py) конструкции # Copied from. По возможности избегайте использования # Copied from.

Механизм # Copied from поддерживает синхронизацию скопированного кода с его исходником. При запуске make fix-repo проверяется каждый блок # Copied from и обновляется в соответствии с оригиналом, поэтому любые правки внутри блока # Copied from будут перезаписаны. Внесите изменения в исходный код и позвольте make fix-repo распространить их.

Базовые формы # Copied from включают следующие.

# Copied from transformers.models.bert.modeling_bert.BertSelfOutput

# Copied from transformers.models.bert.modeling_bert.BertAttention with Bert->Roberta

# Copied from transformers.models.bert.modeling_bert.BertForSequenceClassification with Bert->MobileBert all-casing

Синтаксис with model->newModel выполняет замену строк после копирования. Несколько замен разделяются запятыми и применяются слева направо. Опция all-casing заменяет все варианты регистра сразу (Bert, bert, BERT становятся MobileBert, mobilebert, MOBILEBERT).

Update on GitHub