Transformers documentation
Проверки pull request
Проверки pull request
Когда вы открываете pull request, CI Hugging Face выполняет несколько проверок, которые должны пройти успешно, прежде чем ваш PR будет объединён.
- Исправление CI содержит список команд, которые нужно выполнить локально, чтобы пройти проверки.
- В последующих разделах описано, что именно проверяет каждая проверка, например качество кода и согласованность репозитория.
- Тесты описывают, какие тесты запускаются, категории тестов и медленные тесты.
Исправление 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 remainsmake 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).