Transformers documentation

Внесите свой вклад в 🤗 Transformers

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Внесите свой вклад в 🤗 Transformers

Правила внесения вклада

Существует два способа открыть PR: исправить задачу, открытую для участия сообщества, или открыть самостоятельный PR, содержащий собственное обоснование. Новые модели также можно добавить через самостоятельный PR, см. Добавление новой модели. Сотрудники Hugging Face, мейнтейнеры и некоторые давние контрибьюторы освобождены от этих правил.

Исправление проблемы. Свяжите проблему с ключевым словом закрытия, например Fixes #123, в описании PR. Вы можете работать над:

Чужие проблемы не открыты для PR, если это не указано сопровождающим. PR, ссылающийся на проблему, над которой вы не можете работать, будет закрыт.

Не нужно спрашивать разрешение, чтобы работать над подходящей задачей, и мы не назначаем задачи конкретным людям. Комментарии вроде «могу я взяться за это?» или «назначьте, пожалуйста, мне» только создают шум, поэтому пропустите их и создайте свой PR. Первый PR по задаче имеет приоритет.

Прежде чем браться за задачу с меткой contributions-welcome или New model, проверьте, не открыт ли уже PR по ней. Если да, не создавайте новый. Если вы заметили ошибки, оставьте свои предложения в существующем PR. Открывайте конкурирующий PR только в том случае, если существующий содержит фундаментальные ошибки или устарел: его автор не отвечал на комментарии ревью или не вносил изменения в течение двух недель. PR, ожидающий ревью от мейнтейнера, не считается устаревшим. В любом случае объясните причину в задаче перед созданием своего PR.

Самостоятельные PR. Если проблема ещё не была описана в issue, вы можете открыть PR без создания issue. Самостоятельные PR предназначены для небольших изменений с реальным эффектом, таких как исправление ошибки, улучшение производительности или исправление неработающего примера в документации. Описание PR должно содержать те же доказательства, что и issue:

  • для бага — короткий скрипт, который падает на main и проходит с вашим исправлением, с использованием опубликованного чекпоинта, конфигурации по умолчанию или задокументированного рабочего процесса
  • для улучшения производительности, цифры до и после на реалистичной нагрузке, например, опубликованном чекпоинте или конфигурации по умолчанию, а также информация о том, на каком оборудовании вы проводили тесты. Более быстрый микробенчмарк функции, которая не находится на горячем пути выполнения, не считается.

Если для проблемы уже существует соответствующая задача (issue), ваш PR будет рассмотрен в рамках этой задачи независимо от того, указали вы на неё ссылку или нет. Самостоятельные PR, которые исправляют существующую задачу или предоставлены без подтверждающих данных, будут закрыты. Эти требования не распространяются на новые модели.

Изменения, для которых сначала требуется создать issue. Механические правки, не влияющие на корректность или производительность, а также массовые исправления опечаток или формулировок в документации, требуют создания issue перед отправкой PR. Опишите предлагаемое изменение, способ его реализации и количество затронутых файлов. Исправление одной опечатки — слишком мелкое изменение для PR по любому из путей.

Ревью других PR. Ревью от сообщества приветствуются, если они сообщают нам что-то новое, но мейнтейнеры читают каждый комментарий в PR, и мы уже используем собственные инструменты для ревью. Прежде чем комментировать PR, который вы не создали, убедитесь, что у вас есть что-то конкретное, о чем стоит сказать:

  • Если вы нашли проблему или хотите предложить конкретное изменение, оставьте комментарий к соответствующим строкам, в идеале в формате предложения GitHub, которое автор может применить напрямую. При сообщении об ошибке поможет воспроизводящий пример.
  • Если вы сообщали о проблеме, которую исправляет PR, будет очень полезно кратко указать, решает ли он вашу ситуацию.
  • Пожалуйста, не публикуйте общие обобщения или отчёты в духе «Я протестировал, и это работает». Одобрения от лиц, не являющихся мейнтейнерами, не влияют на то, будет ли PR объединён, а длинный комментарий, который лишь пересказывает PR, отнимает у нас время, не меняя результата.

Способ написания кода зависит от вас, но вы несете ответственность за все, что отправляете, и мы можем заблокировать аккаунты, которые регулярно создают низкокачественные issues или PR. Пожалуйста, также соблюдайте наш code of conduct.

What we look for in issues and PRs
  • Чёткая диагностика ошибок. Быстрые обходные решения часто приводят к раздуванию кода или несовместимости с другими моделями. Тратить время на поиск точной причины проблемы, в частности на определение первого коммита, в котором она появилась (например, с помощью git bisect), — это ценно.
  • Минимизируйте diff. Проверьте свой PR, чтобы исключить любые ненужные изменения. Убедитесь, что вы не закоммитили тестовые скрипты или нерелевантные файлы. Добавляйте комментарии только в том случае, если они действительно необходимы. Если ваш PR может быть исправлением в одну строку, сделайте его таким. Это значительно упрощает ревью и повышает шансы на принятие PR.
  • Потратьте время на воспроизведение проблемы. Очень часто, когда пользователь сообщает о проблеме, её реальной причиной являются проблемы с окружением на его машине, либо он неверно диагностирует проблему и предлагает недействительное решение. Слишком большое доверие к сообщению приводит к плохим решениям, иногда для проблем, которые вообще не существуют! Написание простого скрипта для воспроизведения и его запуск, чтобы убедиться, что проблема видна, очень ценны.
  • Сравнивайте с другими моделями. Репозиторий Transformers очень большой, и многие модели выполняют похожие задачи. При исправлении ошибки полезно проверить, есть ли она в других моделях. Если в вашем PR указано «исправлено с использованием того же подхода, что и в (другая модель)», с ссылкой на соответствующий код, это очень поможет мейнтейнерам, поскольку показывает, что исправление, скорее всего, корректно и совместимо с остальной частью кодовой базы.
  • Избегайте «пустых» PR. У нас нет времени на мелкие стилистические правки или исправление опечаток в комментариях, и мы не принимаем исправления «теоретических багов», найденных статическим анализом кода, которые на практике почти никогда не вызывают проблем, если только ими не может воспользоваться злоумышленник.
  • Проверяйте тесты локально и в CI. Перед созданием PR выполните make fix-repo и используйте utils/tests_fetcher.py, чтобы получить список тестов, покрывающих файлы, которые вы изменили в ветке вашего PR. Запустите эти тесты локально и убедитесь, что они проходят, прежде чем открывать PR. После открытия PR убедитесь, что CI зелёный, и исправьте все проблемы, прежде чем звать кого-либо на ревью! Это значительно снижает количество уведомлений, что помогает мейнтейнерам сохранять рассудок.

Настройка

  1. Сделайте форк Transformers с помощью кнопки Fork на GitHub, чтобы получить копию в вашем аккаунте, а затем клонируйте её локально.

    git clone git@github.com:<your Github handle>/transformers.git
    cd transformers
  2. Добавьте репозиторий Transformers в качестве удалённого репозитория с именем upstream. origin указывает на ваш форк, а upstream — на исходный репозиторий. Это позволяет синхронизировать локальную ветку main перед отправкой в origin и созданием PR.

    git remote add upstream https://github.com/huggingface/transformers.git
    git remote -v
    # origin    git@github.com:<your Github handle>/transformers.git (fetch)
    # origin    git@github.com:<your Github handle>/transformers.git (push)
    # upstream  https://github.com/huggingface/transformers.git (fetch)
    # upstream  https://github.com/huggingface/transformers.git (push)
  3. Держите свою ветку в актуальном состоянии и создайте новую ветку для работы. Вы также можете синхронизировать свою ветку через интерфейс GitHub с помощью кнопки Sync fork.

    git checkout main && git pull upstream main && git push origin main
    git switch -c a-descriptive-name-for-my-branch
  4. Установите библиотеку в режиме редактирования. Для большинства вкладов используйте [dev], так как он включает инструменты разработки, необходимые для проверки стиля и качества. Для вклада в модели используйте [torch,testing], а для изменений только в документации и небольших исправлений, когда не требуется полный набор зависимостей для разработки, — [quality].

    pip install -e ".[dev]"
    
    # for model contributions
    pip install -e ".[torch,testing]"
    
    # for docs-only changes and small fixes
    pip install -e ".[quality]"

Windows

В Windows, если вы не используете WSL, настройте git на преобразование окончаний строк CRLF в LF.

git config core.autocrlf input

Один из способов выполнить команду make в Windows — использовать MSYS2.

  1. Скачайте MSYS2 (мы предполагаем, что он установлен в C:\msys64).
  2. Откройте командную строку C:\msys64\msys2.exe (она должна быть доступна из меню Пуск).
  3. Выполните в оболочке: pacman -Syu и установите make с помощью pacman -S make.
  4. Добавьте C:\msys64\usr\bin в переменную окружения PATH.

Теперь вы можете использовать make из любого терминала (PowerShell, cmd.exe и т. д.).

Создание проблем

Используйте шаблоны для создания issue и убедитесь, что проблема еще не была описана (используйте строку поиска на GitHub в разделе Issues). Сообщение об ошибке должно касаться бага в Transformers, а не в вашем собственном коде, и оно должно влиять на реальное использование и реальные контрольные точки; «теоретический баг», найденный при чтении кода и требующий для воспроизведения очень нестандартной конфигурации, не будет рассматриваться, если это не проблема безопасности. Включите короткий, самодостаточный скрипт, воспроизводящий баг в последней версии или на ветке main, с использованием опубликованной контрольной точки или конфигурации по умолчанию. Сообщения об ошибках без исполняемого примера воспроизведения не будут рассматриваться.

Если вы не уверены, что ошибка находится в вашем коде или в библиотеке, сначала задайте вопрос на форуме или в Discord. Это помогает сохранять фокус GitHub на конкретных проблемах с библиотекой.

Добавление новой модели

Добавление модели в Transformers делает её доступной для загрузки, дообучения и выполнения инференса любым пользователем. Перед началом реализации определите различия между вашей архитектурой и актуальными передовыми моделями, уже присутствующими в Transformers. Опишите эти различия в issue или PR, чтобы ревьюеры могли быстро понять, какие сложности несёт модель, какие части можно реализовать с переиспользованием существующих паттернов и что следует стандартизировать между моделями.

Следуйте инструкциям ниже.

  1. Добавление модели с помощью модульных Transformers — реализуйте модель с использованием модульного файла и сгенерируйте автономные файлы моделирования.
  2. Автоматическая генерация docstrings — используйте декоратор @auto_docstring, чтобы генерировать единообразные docstrings без лишнего кода.
  3. Тестирование — напишите и запустите тесты модели, чтобы проверить корректность и обеспечить поддерживаемость вклада. Для каузальных языковых моделей по возможности наследуйтесь от тестера каузальной LM. Приоритизируйте интеграционные тесты, поскольку они проверяют полный путь процессора, токенизатора и модели по реальным чекпоинтам.
  4. Правила структуры модели — убедитесь, что ваши файлы соответствуют статическим правилам структуры модели, которые проверяет make typing.

Для добавления некоторых моделей требуется дополнительная интеграционная работа.

Сроки добавления моделей

Существуют четыре временных рамки для добавления моделей в зависимости от того, кто является их автором, и от спроса сообщества на конкретную архитектуру.

  • Интеграция в день релиза: мы делаем модель доступной в Transformers в день её выпуска вместе с новым релизом версии. Мы оказываем помощь в поддержке ключевых основных функций (квантование, FlashAttention, KV-кэш и т. д.), рецензируем ранние черновики и, в зависимости от сроков, можем взять на себя реализацию модели.

    Напишите на transformers@huggingface.co за несколько недель до релиза, особенно если речь идет о новых архитектурах. Мы будем совместно дорабатывать ваш код в приватном форке, пока ваш чекпоинт и релиз не будут готовы.

  • Интеграция в течение недели: модели с высоким спросом обычно появляются в течение недели, даже если автор не выходит на связь.

    Откройте issue с помощью шаблона для новой модели, чтобы запросить её. Issues с большей активностью поднимаются в очереди быстрее.

  • Интеграция после релиза: модели, не пользующиеся высоким спросом, или те, на которые у нас нет ресурсов, добавляются после релиза в исходном репозитории.

    Внешние участники могут открыть PR для новой модели напрямую, с issue или без него. Прежде чем начать, проверьте открытые issue с меткой “New model” и открытые PR, чтобы убедиться, что никто уже не добавляет эту модель. Мы проведём ревью и поможем вам на каждом этапе.

  • Релиз с упором на Hub: публикуйте свою модель непосредственно на Hub с помощью поддержки remote-code в Transformers, без необходимости отправлять PR в основной репозиторий.

    Популярные модели, изначально размещённые на Hub, часто позже интегрируются в Transformers, что обеспечивает полноценную документацию, поддержку и оптимизацию. Подход Hub-first — это самый простой способ добавить модель. Однако он может оказаться менее надёжным, если для модели требуется конвертация весов или возникают другие проблемы с обратной совместимостью.

Документация

Для справочника API, генерируемого из исходных файлов, используйте декоратор @auto_docstring, когда это уместно. Подробности о том, как редактировать документацию и какой синтаксис мы используем, см. в README документации.

Update on GitHub