Hugging Face's logo

PEFT documentation

Внесение вклада в PEFT

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.21.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Внесение вклада в PEFT

Мы с радостью принимаем вклады в PEFT. Если вы планируете внести свой вклад, пожалуйста, прочитайте это, чтобы сделать процесс максимально плавным.

Обсудите и получите одобрение перед созданием PR

Прежде чем открыть pull request (в том числе draft), создайте или найдите issue в huggingface/peft и обсудите ваше предложение по внесению изменений. Если уже существует issue, над которым кто-то работает, выразил намерение взяться за него или у которого есть открытый PR, не отправляйте отдельный PR. Дождитесь явного одобрения предложения со стороны maintainer PEFT или члена Hugging Face. Если вы открываете issue, сохраняйте длину и сложность описания соразмерными сложности задачи. Часто краткое описание с примером воспроизведения ценнее длинного описания.

Комментарий с одобрением содержит сообщение /peft-triage approved. Дополнительно в нём может быть указано имя назначенного участника, например /peft-triage approved username или /peft-triage approved @username. Создание PR для задачи, к которой вы не назначены, приведёт к закрытию данного PR.

Свяжите одобренную открытую задачу с описанием вашего PR, используя #123, huggingface/peft#123 или https://github.com/huggingface/peft/issues/123. В качестве исключения мейнтейнеры могут указать конкретные длительные обсуждения, на которые можно ссылаться по их полному URL в GitHub без отдельного комментария с одобрением. Если вы ссылаетесь на несколько задач или обсуждений, достаточно одной корректной ссылки.

Автоматизированный процесс проверяет PR на наличие утверждённых открытых issues или discussions. PR без корректной ссылки автоматически закрывается с пояснением. Вы можете получить одобрение issue, обновить описание PR и повторно открыть тот же PR; пожалуйста, не создавайте замену. Если вы считаете, что ваш PR был закрыт по ошибке, напишите мейнтейнерам в PR.

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

Установка

Выполните следующие шаги, чтобы начать вносить вклад:

  1. Сделайте форк репозитория, нажав кнопку «Fork» на странице репозитория. Это создаст копию кода в вашем аккаунте GitHub.

  2. Склонируйте ваш форк на локальный диск и добавьте базовый репозиторий как удалённый. Приведённая ниже команда предполагает, что ваш публичный SSH-ключ загружен на GitHub. Подробнее см. в этом руководстве.

    git clone git@github.com:<your Github handle>/peft.git
cd peft
git remote add upstream https://github.com/huggingface/peft.git

  3. Создайте новую ветку для хранения изменений в процессе разработки и делайте это для каждого нового PR, над которым вы работаете.

    Начните с синхронизации вашей ветки main с веткой upstream/main (подробнее в документации GitHub):

    git checkout main
git fetch upstream
git merge upstream/main

    После того как ветка main будет синхронизирована, создайте новую ветку от неё:

    git checkout -b a-descriptive-name-for-my-changes

    Не работайте в ветке main.

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

    pip install -e ".[test]"

    (Если PEFT уже был установлен в виртуальном окружении, удалите его с помощью pip uninstall peft перед повторной установкой.)

Если вы впервые создаёте pull request, следуйте руководству Creating a pull request от GitHub.

Тесты и проверки качества кода

Независимо от типа вклада (если только речь не идёт только о документации), перед созданием PR следует выполнить тесты и проверки качества кода, чтобы убедиться, что ваш вклад не нарушает работу проекта и соответствует его стандартам.

Запуск тестов и проверок

Мы предоставляем Makefile для запуска необходимых тестов. Выполните код ниже для модульного тестирования:

make test

Выполните одну из следующих команд, чтобы только проверить или проверить и исправить качество и стиль кода:

make quality  # just check
make style  # check and fix

Запуск make quality также проверяет, упомянуты ли все методы/классы из публичного API PEFT (то есть всё, что перечислено в peft.__all__) в документации. Эти ошибки нельзя исправить с помощью make style: чтобы устранить их, необходимо добавить документацию для новых элементов публичного API в документацию.

Вы также можете настроить pre-commit для автоматического выполнения этих исправлений в качестве Git commit hooks.

$ pip install pre-commit
$ pre-commit install

Запуск всех тестов может занять много времени, поэтому в процессе разработки эффективнее запускать только тесты, относящиеся к вашим изменениям, например, с помощью:

pytest tests/<test-file-name> -k <name-of-test>

Это должно завершиться значительно быстрее и позволит ускорить итерации.

Добавление тестов

Общий гид по добавлению новых тестов — в tests/README.md.

Если ваше изменение касается конкретного аппаратного обеспечения (например, требует CUDA), посмотрите в tests/test_gpu_examples.py и tests/test_common_gpu.py, чтобы понять, имеет ли смысл добавить туда тесты. Если ваше изменение может повлиять на сохранение и загрузку моделей, запустите тесты с флагом --regression, чтобы запустить регрессионные тесты.

Устаревшие PR

Возможно, что во время работы над вашим PR базовый код изменится из-за слияния других изменений. Если это произойдёт – особенно при наличии конфликта слияния – пожалуйста, обновите вашу ветку с последними изменениями. Это может быть merge или rebase, и мы выполним squash and merge PR, когда он будет готов. Избегайте force push, чтобы упростить процесс ревью.

Описание PR

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

Длина и сложность описания PR должны соответствовать объёму изменений. Для тривиального изменения в одну строку не нужно десять абзацев объяснений. Не пересказывайте то, что очевидно из просмотра diff (например, «Исправил опечатку в ‘foobaar’»).

Если ваш код содержит нетривиальные изменения, имеет смысл добавить комментарии, объясняющие эти изменения. Например, если вам пришлось несколько раз переделывать реализацию, потому что самый очевидный подход не сработал, это хороший признак того, что комментарий в коде необходим.

При необходимости укажите, как вы протестировали изменения, например, показав команду pytest или код для воспроизведения.

Отзыв рецензента

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

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

После того как вы учтёте замечания ревьюера, сообщите ему, что PR готов к повторному рассмотрению.

Исправления ошибок

Опишите обстоятельства, приведшие к ошибке. Если существует соответствующая задача, укажите ссылку на неё (например, «Resolves #12345»).

В идеале исправление ошибки должно сопровождаться тестом, воспроизводящим её. Тест должен завершаться с ошибкой при текущей версии кода и проходить успешно после применения исправления. Добавьте в тест комментарий со ссылкой на соответствующую issue или PR. Без теста в будущем будет сложнее предотвратить регрессии.

Улучшения документации

Мы будем рады получить исправления битых ссылок и дополнения к отсутствующей или непонятной документации. Также мы высоко ценим помощь в уходе за примерами: их актуализацию и проверку на работоспособность в быстро меняющейся среде.

Пожалуйста, не отправляйте pull request, которые только исправляют опечатки, так как они обычно создают больше работы, чем экономят. Такие изменения лучше объединять с более существенными правками (например, исправлением битых ссылок или расширением/обновлением документации).

Добавить новый метод дообучения PEFT

Новые методы эффективной дообучения с ограничением параметров (parameter-efficient fine-tuning) разрабатываются постоянно. Если вы хотите добавить в PEFT новый и перспективный метод, следуйте этим шагам.

  1. Если вы не автор оригинальной статьи, проверьте наличие существующих реализаций и убедитесь с авторами, что они не планируют сами отправить PR.
  2. Откройте issue с предложением и дождитесь явного одобрения, как описано выше, прежде чем приступать к основной работе по интеграции, перечисленной ниже.
  3. Проверьте последние коммиты, чтобы найти новые методы PEFT, добавленные в качестве источника вдохновения.
  4. После утверждения предложения может быть полезно рано открыть черновик PR, как только метод в целом заработает и первые тесты пройдут, а затем запросить обратную связь. В описании черновика PR сослайтесь на утверждённую issue.

Основная интеграция нового метода PEFT

  • Создайте issue в huggingface/peft и получите явное одобрение, прежде чем вкладывать слишком много усилий.
  • Укажите источник метода, как правило, это финальная статья или другой стабильный первоисточник. Мы стремимся избегать работ, которые всё ещё проходят рецензирование, поскольку реализация должна быть стабильной.
  • Добавьте новую запись PeftType в src/peft/utils/peft_types.py.
  • Создайте новый пакет тюнера в src/peft/tuners/ с файлами, необходимыми для вашего метода (обычно: config.py, model.py, layer.py и __init__.py).
  • Зарегистрируйте метод в тюнере в файле __init__.py с помощью register_peft_method(...).
  • Экспортируйте новый конфиг/модель из src/peft/tuners/__init__.py и src/peft/__init__.py.
  • Если методу нужны модули по умолчанию для моделей Transformers, добавьте соответствующее отображение в src/peft/utils/constants.py.
  • Добавьте метод в тестовую матрицу в tests/test_custom_models.py, так как это самые широкие и быстрые тесты. Убедитесь, что тесты проходят с помощью pytest tests/test_custom_models.py -k <method-name> -v, и исправьте ошибки, если они есть.
  • Перед отправкой выполните проверки стиля и качества с помощью make style.
  • В описании PR опишите метод, укажите ссылку на статью, обобщите компромиссы и перечислите добавленные изменения.

Полный PR для добавления нового метода PEFT

  • Убедитесь, что аргументы конфигурации, специфичные для метода, имеют понятные имена и сопровождаются пояснениями. Не предполагайте, что пользователь досконально знает статью.
  • Следуйте правилам именования и кодирования PEFT.
  • Убедитесь, что вы случайно не закоммитили нерелевантные изменения, например, изменения в нерелевантных файлах, внесённые форматировщиком кода.
  • Если некоторые решения по реализации не являются тривиальными, задокументируйте их с помощью комментария в коде.
  • Завершите полный набор тестов (test_config.py, test_decoder_models.py и т. д.), добавив метод PEFT в матрицу тестов. Убедитесь, что тесты проходят.
  • Добавьте документацию в docs/source/package_reference/ с кратким описанием, ссылкой на статью, примером использования и блоками autodoc. Опишите преимущества и недостатки по сравнению с другими методами, такими как LoRA. Зарегистрируйте эту страницу документации в docs/source/_toctree.yml.
  • Добавьте исполняемый пример в examples/ (можно скопировать существующий пример) с кратким README.md.
  • Проверьте бенчмарки в method_comparison/ и добавьте настройки экспериментов для вашего нового метода. Это хорошее место, чтобы убедиться, что метод PEFT обучается как ожидается. Включите одну или две разумные конфигурации бенчмарка (одну по умолчанию и одну, оптимизированную под бенчмарк).
  • Рекомендуется: добавить поддержку универсальной квантизации. Вместо того чтобы явно добавлять типы слоёв квантизации для каждого метода квантизации, поддержите универсальную квантизацию. В качестве примера посмотрите, как это реализовано в BOFT. Расширьте https://github.com/huggingface/peft/blob/main/tests/test_quantization.py, добавив туда ваш метод PEFT. При необходимости обратитесь к мейнтейнерам за помощью.

Внесение изменений в существующие методы PEFT

Если вы вносите изменения в метод PEFT, которые потенциально могут изменить его выходные данные и тем самым сделать недействительными уже обученные контрольные точки, необходимо принять дополнительные меры предосторожности. Подробности описаны в https://github.com/huggingface/peft/blob/main/.ai/skills/peft-method-changes/SKILL.md. Инструкции там предназначены как для людей, так и для ИИ.

Добавить другие функции

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

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

Изменения в коде должны быть реализованы с сохранением обратной совместимости. Например, существующий код должен продолжать работать так же, как и раньше, после слияния функции.

Update on GitHub

←torch.compile Устранение неполадок→