Hugging Face's logo

Diffusers documentation

Как внести вклад в Diffusers 🧨

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

and get access to the augmented documentation experience

to get started

Как внести вклад в Diffusers 🧨

Если вы используете ИИ-агента для участия в разработке, обязательно ознакомьтесь с разделом Вклад с помощью ИИ и агентные вклады, где описаны наши ожидания и рекомендации.

Мы ❤️ вклады от сообщества с открытым исходным кодом! Все приветствуются, и все виды участия – не только написание кода – ценятся и высоко оцениваются. Ответы на вопросы, помощь другим, установление контактов и улучшение документации имеют огромную ценность для сообщества, поэтому не бойтесь и присоединяйтесь, если вы готовы к этому!

Каждый может начать с приветствия 👋 в нашем публичном канале Discord. Мы обсуждаем последние тренды в диффузионных моделях, задаём вопросы, делимся личными проектами, помогаем друг другу с вкладами в проект или просто общаемся ☕. Join us on Discord

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

Мы высоко ценим обратную связь от сообщества, поэтому не стесняйтесь высказываться, если у вас есть ценные замечания, которые помогут улучшить библиотеку: каждое сообщение, комментарий, issue и pull request (PR) читаются и рассматриваются.

Обзор

Вы можете вносить вклад самыми разными способами: от ответов на вопросы в issues и discussions до добавления новых диффузионных моделей в основную библиотеку.

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

    1. Задавать и отвечать на вопросы в GitHub Discussions или в Discord.
    1. Создание новых проблем на вкладке GitHub Issues.
    1. Ответы на вопросы на вкладке GitHub Issues.
    1. Исправьте простую проблему, отмеченную меткой «Good first issue», см. здесь.
    1. Внесите вклад в документацию.
    1. Опубликуйте пайплайн или модель на Hub как удалённый код с помощью Modular Diffusers.
    1. Внесите свой вклад в примеры.
    1. Разберитесь с более сложной проблемой, отмеченной меткой «Good second issue», см. здесь.
    1. Возьмите задачу из программы Diffusers MVP.
    1. Добавьте новый пайплайн, модель или планировщик в библиотеку. Обычно для такого вклада мы работаем напрямую с авторами модели; если вы являетесь участником сообщества, начните с Hub (6). Ознакомьтесь с открытыми задачами «New Pipeline/Model» и «New scheduler», а также сначала прочитайте Design Philosophy.

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

Для вкладов с 4 по 10, за исключением 6, который находится на Hub, вам нужно открыть PR. Подробная инструкция по этому процессу приведена в разделе Opening a pull request.

1. Задавать и отвечать на вопросы в GitHub Discussions или в Discord

Любые вопросы или комментарии, связанные с библиотекой Diffusers, можно задать в GitHub Discussions или в Discord. К таким вопросам и комментариям относятся (но не ограничиваются ими):

  • Отчёты об экспериментах по обучению или инференсу с целью обмена знаниями
  • Презентация личных проектов
  • Вопросы к неофициальным примерам обучения
  • Предложения по проектам
  • Общая обратная связь
  • Краткие описания статей
  • Обращение за помощью по личным проектам, созданным на основе библиотеки Diffusers
  • Общие вопросы
  • Этические вопросы, связанные с диффузионными моделями
  • …

Каждый вопрос, заданный в GitHub Discussions или в Discord, активно поощряет сообщество к публичному обмену знаниями и вполне может помочь начинающему в будущем, у которого возникнет тот же вопрос, что и у вас. Пожалуйста, задавайте любые вопросы, которые у вас могут возникнуть. В том же духе вы оказываете сообществу огромную помощь, отвечая на такие вопросы, поскольку таким образом вы публично документируете знания для всех, кто хочет учиться.

Please keep in mind that the more effort you put into asking or answering a question, the higher the quality of the publicly documented knowledge. In the same way, well-posed and well-answered questions create a high-quality knowledge database accessible to everybody, while badly posed questions or answers reduce the overall quality of the public knowledge database. In short, a high quality question or answer is precise, concise, relevant, easy-to-understand, accessible, and well-formatted/well-posed. For more information, please have a look through the How to write a good issue section.

ПРИМЕЧАНИЕ о каналах: GitHub Discussions индексируется поисковыми системами, и на каждый тред можно дать ссылку, поэтому вопросы и ответы, опубликованные там, остаются доступными для поиска для следующего человека с той же проблемой. В отличие от этого, Discord имеет формат чата, который располагает к быстрому обмену сообщениями. Скорее всего, вы получите ответ на свой вопрос в Discord быстрее, но со временем ваш вопрос перестанет быть видимым, и найти информацию, опубликованную давно, будет гораздо сложнее. Поэтому мы рекомендуем использовать GitHub Discussions для вопросов и ответов, которые должны сохраниться надолго. Если обсуждение в Discord приводит к интересному выводу, опубликуйте результат в виде дискуссии, чтобы будущие читатели могли его найти.

2. Создание новых проблем на вкладке GitHub issues

Библиотека 🧨 Diffusers отличается надёжностью и стабильностью благодаря пользователям, которые сообщают нам о возникающих проблемах. Спасибо, что вы сообщили об ошибке.

Помните, что вопросы на GitHub предназначены для технических вопросов, непосредственно связанных с библиотекой Diffusers, сообщений об ошибках, запросов на добавление функций или обратной связи по дизайну библиотеки.

In a nutshell, this means that everything that is not related to the code of the Diffusers library (including the documentation) should not be asked as an issue, but rather on GitHub Discussions or Discord.

При создании нового обращения учитывайте следующие рекомендации:

  • Убедитесь, что вы проверили, не задавали ли уже ваш вопрос (используйте строку поиска на GitHub в разделе Issues).
  • Пожалуйста, никогда не сообщайте о новой проблеме в рамках другой (связанной) проблемы. Если другая проблема тесно связана, всё равно создайте новую проблему и добавьте ссылку на связанную.
  • Убедитесь, что ваша проблема описана на английском языке.
  • Проверьте, можно ли решить вашу проблему, обновив Diffusers до последней версии. Перед созданием обращения убедитесь, что python -c "import diffusers; print(diffusers.__version__)" возвращает версию, равную или более новую, чем последняя версия Diffusers.
  • Помните, что чем больше усилий вы приложите к созданию нового вопроса, тем выше будет качество ответа и тем лучше станет общее качество вопросов в Diffusers.

Новые проблемы обычно включают следующее.

2.1. Воспроизводимые минимальные отчеты об ошибках

Отчёт об ошибке всегда должен содержать воспроизводимый фрагмент кода и быть максимально минимальным и лаконичным. Это означает следующее:

  • По возможности сузьте область поиска ошибки, не выкладывайте весь файл кода целиком.
  • Форматируйте код.
  • Не включайте внешние библиотеки, кроме тех, от которых зависит Diffusers.
  • Всегда Always указывайте всю необходимую информацию о вашей среде; для этого выполните в терминале diffusers-cli env и скопируйте отобразившуюся информацию в issue.
  • Опишите проблему. Если читатель не понимает, в чём заключается проблема и почему она является проблемой, он не сможет её решить.
  • Всегда убедитесь, что читатель может воспроизвести вашу проблему с минимальными усилиями. Если ваш фрагмент кода не запускается из-за отсутствующих библиотек или неопределённых переменных, читатель не сможет вам помочь. Убедитесь, что ваш воспроизводимый фрагмент кода максимально минимален и его можно скопировать и вставить в простую Python-консоль.
  • Если для воспроизведения вашей проблемы требуется модель и/или набор данных, убедитесь, что у читателя есть к ним доступ. Вы всегда можете загрузить свою модель или набор данных в Hub, чтобы их было легко скачать. Старайтесь делать модель и набор данных как можно меньшими, чтобы воспроизведение вашей проблемы было максимально простым.

Для получения дополнительной информации ознакомьтесь с разделом Как написать хороший issue.

Вы можете открыть отчет об ошибке здесь.

2.2. Заявки на новые функции

Хорошее предложение по улучшению функциональности охватывает следующие пункты:

  1. Сначала мотивация:
  • Связано ли это с проблемой или неудобством в работе с библиотекой? Если да, пожалуйста, объясните почему. Лучше всего предоставить фрагмент кода, демонстрирующий проблему.
  • Это связано с чем-то, что вам понадобится для проекта? Мы будем рады узнать об этом!
  • Это то, над чем вы работали и что, по вашему мнению, может быть полезно сообществу? Отлично! Расскажите, какую проблему это решило для вас.
  1. Напишите полный абзац, описывающий функцию;
  2. Предоставьте фрагмент кода, демонстрирующий его будущее использование;
  3. Если это связано со статьёй, пожалуйста, приложите ссылку;
  4. Приложите любую дополнительную информацию (чертежи, скриншоты и т. д.), которая, по вашему мнению, может помочь.

Вы можете открыть запрос на новую функцию здесь.

2.3 Обратная связь

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

Вы можете открыть вопрос с обратной связью здесь.

2.4 Технические вопросы

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

Вы можете открыть вопрос по технической теме здесь.

2.5 Предложение о добавлении новой модели, планировщика или конвейера

Если сообщество диффузионных моделей выпустило новую модель, конвейер или планировщик, которые вы хотели бы видеть в библиотеке Diffusers, пожалуйста, предоставьте следующую информацию:

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

Также не забудьте указать автора исходного компонента (модели, планировщика, конвейера и т. д.) через его GitHub-аккаунт, если вам удалось его найти.

Если вы хотите самостоятельно добавить модель в Diffusers, см. Публикация пайплайна или модели на Hub и Добавление пайплайнов, моделей и планировщиков.

Вы можете открыть запрос на модель/пайплайн/планировщик здесь.

3. Ответы на вопросы на вкладке GitHub issues

Ответы на вопросы в GitHub могут потребовать некоторых технических знаний о Diffusers, но мы рекомендуем всем попробовать, даже если вы не на 100% уверены в правильности своего ответа. Некоторые советы, как дать качественный ответ на вопрос:

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

Кроме того, многие обращения часто оказываются не по теме, дублируют другие обращения или не имеют отношения к проекту. Вы окажете большую помощь разработчикам, если будете отвечать на такие обращения, побуждая их авторов быть более точными, указывать ссылку на дублирующее обращение или направляя их в GitHub Discussions или Discord.

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

Для всех вкладов, кроме 6, необходимо открыть PR. Раздел Opening a pull request объясняет, как это сделать.

4. Исправление «Good first issue»

Good first issues are marked by the Good first issue label. Usually, the issue already explains how a potential solution should look so that it is easier to fix. If the issue hasn’t been closed and you would like to try to fix this issue, you can just leave a message “I would like to try this issue.”. There are usually three scenarios:

  • a.) В описании проблемы уже предложено решение. В этом случае, если предложенное решение кажется вам разумным, вы можете открыть PR или черновик PR для его реализации.
  • b.) Описание проблемы не содержит предложения по её решению. В этом случае предложите решение самостоятельно в комментарии к проблеме. Достаточно нескольких предложений, описывающих подход. Дождитесь подтверждения от кого-либо из команды Diffusers, прежде чем открывать PR.
  • c.) Уже существует открытый PR для исправления проблемы, но сама проблема ещё не закрыта. Если PR устарел, вы можете просто открыть новый PR и сослаться на устаревший. PR часто устаревают, если первоначальный автор, который хотел исправить проблему, внезапно не находит времени для продолжения работы. Это часто случается в open-source и является вполне нормальным. В этом случае сообщество будет очень радо, если вы попробуете снова, используя знания из существующего PR. Если PR уже существует и активен, вы можете помочь автору, предложив свои идеи, проведя ревью PR или даже спросив, можете ли вы внести свой вклад в этот PR.

5. Внесите вклад в документацию

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

Внесение вклада в библиотеку может принимать самые разные формы:

  • Исправление орфографических или грамматических ошибок.
  • Исправьте неверное форматирование docstring. Если вы видите, что официальная документация отображается некорректно или ссылка сломана, мы будем очень рады, если вы уделите время её исправлению.
  • Исправьте форму или размерности тензора входных или выходных данных в docstring.
  • Уточните документацию, которая трудно поддаётся пониманию или содержит неточности.
  • Обновите устаревшие примеры кода.
  • Перевод документации на другой язык.

Всё, что отображается на официальной странице документации Diffusers, является частью официальной документации и может быть исправлено или скорректировано в соответствующем источнике документации.

Пожалуйста, ознакомьтесь с этой страницей о том, как локально проверить внесённые в документацию изменения.

6. Опубликуйте конвейер или модель на Hub

С помощью Modular Diffusers пайплайн может существовать в виде удалённого кода в любом репозитории Hub. Любой может загрузить его с помощью from_pretrained(..., trust_remote_code=True), не дожидаясь релиза Diffusers. Если вы являетесь участником сообщества, который добавляет новый пайплайн или модель, начните с этого раздела. См. custom blocks, чтобы опубликовать пайплайн, и custom models, чтобы опубликовать модель.

Сообщите нам в соответствующем запросе на модель (создайте его, если такого нет): мы дадим обратную связь по реализации и добавим понравившиеся нам варианты в коллекцию Community Modular Diffusers Blocks. На основе этого мы решаем, как поддержать модель в библиотеке: мы можем интегрировать вашу версию в основной код, работать с авторами над официальным вариантом или просто направлять пользователей к вашей реализации. Также сообщите, с какими трудностями вы столкнулись: непонятные API, отсутствие документации, ошибки. Эта обратная связь для нас так же ценна, как и сам пайплайн.

7. Внесите свой вклад в примеры обучения

Примеры Diffusers — это набор скриптов обучения, расположенных в examples.

Мы поддерживаем два типа обучающих примеров:

  • Официальные примеры обучения
  • Примеры обучения для исследований

Примеры обучения для исследований находятся в examples/research_projects, тогда как официальные примеры обучения включают все папки под examples, за исключением папок research_projects и community. Официальными примерами обучения занимаются основные сопровождающие Diffusers, а примерами обучения для исследований — сообщество. Причина та же, по которой библиотека поддерживает на Hub небольшой набор официальных пайплайнов и пайплайнов сообщества: основным сопровождающим невозможно поддерживать все возможные методы обучения диффузионных моделей. Если основные сопровождающие Diffusers и сообщество считают определённую парадигму обучения слишком экспериментальной или недостаточно популярной, соответствующий код обучения следует поместить в папку research_projects и поддерживать её автору.

Оба набора примеров — для обучения и исследований — представляют собой каталог, содержащий один или несколько скриптов обучения, файл requirements.txt и файл README.md. Чтобы пользователь мог воспользоваться примерами обучения, необходимо клонировать репозиторий:

git clone https://github.com/huggingface/diffusers

а также для установки всех дополнительных зависимостей, необходимых для обучения:

cd diffusers
pip install -r examples/<your-example-folder>/requirements.txt

Поэтому при добавлении примера файл requirements.txt должен определять все зависимости pip, необходимые для вашего примера обучения, чтобы после их установки пользователь мог запустить скрипт обучения из примера. См., например, файл requirements.txt для DreamBooth.

Примеры обучения в библиотеке Diffusers должны следовать следующей философии:

  • Весь код, необходимый для запуска примеров, должен находиться в одном Python-файле.
  • Пример должен запускаться из командной строки с помощью python <your-example>.py --args.
  • Примеры следует сохранять простыми и использовать в качестве примера того, как применять Diffusers для обучения. Цель примеров — не создать диффузионные модели уровня state-of-the-art, а воспроизвести известные схемы обучения, не добавляя слишком много собственной логики. В качестве побочного результата этого подхода наши примеры также стремятся стать хорошим учебным материалом.

Чтобы внести свой вклад с примером, настоятельно рекомендуется изучить уже существующие примеры, такие как dreambooth, чтобы понять, как они должны выглядеть. Мы настоятельно рекомендуем контрибьюторам использовать Accelerate library, поскольку она тесно интегрирована с Diffusers. Когда примерный скрипт заработает, убедитесь, что вы добавили подробный README.md, в котором точно описано, как использовать пример. Этот README должен включать:

  • Пример команды для запуска демонстрационного скрипта, показанный здесь.
  • Ссылка на результаты обучения (логи, модели и т. д.), демонстрирующие, чего можно ожидать, как показано здесь.
  • Если вы добавляете неофициальный/исследовательский пример обучения, не забудьте добавить предложение о том, что вы поддерживаете этот пример обучения, с указанием вашего git-идентификатора, как показано здесь.

Если вы вносите изменения в официальные примеры обучения, убедитесь, что вы также добавили тест в соответствующую папку, например examples/dreambooth/test_dreambooth.py. Для неофициальных примеров обучения это не требуется.

8. Исправление «Хорошей второй задачи»

Хорошие задачи для второго участия отмечены меткой Good second issue. Обычно они сложнее, чем хорошие задачи для первого участия: в описании меньше подсказок по исправлению, а для их решения требуется уверенное понимание библиотеки.

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

9. Решение задачи MVP в Diffusers

Программа Diffusers MVP содержит список задач, в которых нам особенно нужна помощь. Они похожи на Good second issues, но сложнее и требуют больше времени, а программа поощряет участников, которые берутся за их решение. Сначала опишите свой подход в комментарии и получите подтверждение от мейнтейнера, прежде чем открывать PR. В программе также есть трек ideas: расскажите нам об одной идее, которая повысит влияние Diffusers, в нескольких предложениях и без деталей реализации.

10. Добавление конвейеров, моделей и планировщиков

Если вы являетесь автором модели, пожалуйста, свяжитесь с нами, чтобы мы могли согласовать процесс интеграции: создайте запрос на добавление функции или оставьте комментарий, если такой запрос уже открыт.

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

Pipelines, models и schedulers — это важнейшие компоненты библиотеки Diffusers. Они обеспечивают простой доступ к передовым технологиям диффузии, что позволяет сообществу создавать мощные приложения генеративного ИИ.

Добавление новой модели, конвейера или планировщика может открыть мощный новый сценарий использования для любого пользовательского интерфейса, основанного на Diffusers, что может иметь огромную ценность для всей экосистемы генеративного ИИ.

Когда выходит поддержка новой модели или конвейера

Новая модель или конвейер может быть включена в релиз, если вы заранее согласуете интеграцию с командой Diffusers. Вы можете связаться с нами, создав issue в репозитории Diffusers или отправив письмо на [email protected].

Выпуск не происходит автоматически при слиянии pull request с моделью или конвейером. Перед выпуском сопровождающие сначала проверяют, что интеграция завершена и тесты выпуска проходят.

Поддержка новой модели или конвейера, как правило, включается в следующую минорную версию. Интеграция сливается в ветку main, из которой затем создаётся ветка релиза. Релиз содержит все изменения, слитые с момента предыдущего релиза, а не только интеграцию конкретной модели или конвейера.

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

В Diffusers есть несколько открытых запросов на новые функции для всех трёх компонентов — если вы пока не решили, какой именно компонент хотите добавить, можете просто просмотреть их:

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

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

Если вы не уверены в чём-то или застряли при работе над PR, не стесняйтесь оставить сообщение с просьбой о первичном ревью или помощи.

Скопировано из mechanism

Уникальная и важная особенность, которую необходимо понимать при добавлении любого кода конвейера, модели или планировщика, — это механизм # Copied from. Вы встретите его повсюду в кодовой базе Diffusers, и мы используем его, чтобы код оставался простым для понимания и поддержки. Пометка кода с помощью механизма # Copied from заставляет помеченный код оставаться идентичным коду, из которого он был скопирован. Это упрощает обновление и распространение изменений по множеству файлов при каждом запуске make fix-copies.

Например, в приведённом ниже примере кода StableDiffusionPipelineOutput — это исходный код, а AltDiffusionPipelineOutput копирует его с помощью механизма # Copied from. Единственное отличие — смена префикса класса с Stable на Alt.

# Copied from diffusers.pipelines.stable_diffusion.pipeline_output.StableDiffusionPipelineOutput with Stable->Alt
class AltDiffusionPipelineOutput(BaseOutput):
    """
    Output class for Alt Diffusion pipelines.

    Args:
        images (`List[PIL.Image.Image]` or `np.ndarray`)
            List of denoised PIL images of length `batch_size` or NumPy array of shape `(batch_size, height, width,
            num_channels)`.
        nsfw_content_detected (`List[bool]`)
            List indicating whether the corresponding generated image contains "not-safe-for-work" (nsfw) content or
            `None` if safety checking could not be performed.
    """

Чтобы узнать больше, прочитайте этот раздел статьи ~Don’t~ Repeat Yourself*.

Как написать хороший issue

Чем лучше оформлен ваш вопрос, тем выше шансы, что он будет быстро решён.

  1. Убедитесь, что вы использовали правильный шаблон для вашего обращения. Вы можете выбрать между Сообщением об ошибке, Запросом функции, Отзывом о проектировании API, Добавлением новой модели/конвейера/планировщика или пустым обращением. Убедитесь, что вы выбрали правильный вариант при создании нового обращения. Вопросы по использованию следует задавать в GitHub Discussions, а не в обращениях.
  2. Будьте точны: дайте вашей проблеме подходящее название. Старайтесь формулировать описание проблемы как можно проще. Чем точнее вы описываете проблему при её создании, тем меньше времени потребуется на её понимание и потенциальное решение. Убедитесь, что вы создаёте отдельную проблему для каждой конкретной проблемы, а не объединяете несколько в одну. Если вы обнаружили несколько проблем, просто создайте несколько отдельных проблем. Если ваша проблема — это ошибка, постарайтесь максимально точно описать, в чём именно она заключается: не ограничивайтесь фразой «Ошибка в diffusers».
  3. Воспроизводимость: отсутствие воспроизводимого фрагмента кода означает отсутствие решения. Если вы столкнулись с ошибкой, разработчики должны иметь возможность её воспроизвести. Убедитесь, что вы включили фрагмент кода, который можно скопировать и вставить в интерпретатор Python для воспроизведения проблемы. Убедитесь, что ваш фрагмент кода работает, то есть в нём нет отсутствующих импортов или битых ссылок на изображения и т. д. Ваше обращение должно содержать сообщение об ошибке и фрагмент кода, который можно скопировать и вставить без каких-либо изменений для воспроизведения точно такого же сообщения об ошибке. Если в вашем обращении используются локальные веса модели или локальные данные, к которым читатель не имеет доступа, решить проблему невозможно. Если вы не можете поделиться своими данными или моделью, попробуйте создать тестовую модель или тестовые данные.
  4. Минимализм: Постарайтесь помочь читателю понять суть проблемы как можно быстрее, оставаясь максимально лаконичным. Уберите весь код и всю информацию, не относящуюся к проблеме. Если вы нашли баг, постарайтесь создать самый простой пример кода, демонстрирующий проблему, а не вываливать в issue весь свой рабочий процесс. Например, если при обучении модели возникает ошибка на каком-то этапе, сначала определите, какая часть кода обучения отвечает за ошибку, и попробуйте воспроизвести её на нескольких строках. Старайтесь использовать тестовые данные вместо полных датасетов.
  5. Контекст: Расскажите, над чем вы работали, когда столкнулись с ошибкой или потребовалась новая функция: например, приложение на базе Diffusers, исследовательский проект или агент, который вы запускали для поиска багов в библиотеке. Достаточно одного-двух предложений, а ссылка на проект будет приветствоваться. Мы получаем больше проблем и PR, чем можем обработать одновременно, поэтому контекст помогает нам расставлять приоритеты по степени влияния.
  6. Добавляйте ссылки. Если вы упоминаете определённое имя, метод или модель, обязательно укажите ссылку, чтобы читатель лучше понял, о чём идёт речь. Если вы ссылаетесь на конкретный PR или issue, убедитесь, что привязали его к вашему issue. Не предполагайте, что читатель знает, о чём вы говорите. Чем больше ссылок вы добавите в свой issue, тем лучше.
  7. Форматирование. Убедитесь, что ваш вопрос оформлен аккуратно: код оформите с помощью синтаксиса Python, а сообщения об ошибках — с помощью обычного синтаксиса кода. Подробнее см. в официальной документации GitHub по форматированию.
  8. Рассматривайте вашу проблему не как тикет, который нужно решить, а как красиво оформленную статью в энциклопедии. Каждая добавленная проблема — это вклад в общедоступные знания. Оформив проблему грамотно, вы не только облегчаете работу сопровождающим, но и помогаете всему сообществу лучше понять определённый аспект библиотеки.

Как написать хороший PR

  1. Всегда начинайте с issue. Найдите issue, на который направлен ваш pull request, или создайте новый, если никто этого не сделал, и дайте мейнтейнерам возможность ответить, прежде чем вы начнёте писать код. Рабочий процесс, который лучше всего подходит нам, — это создание issue, затем обсуждение решения, а после этого PR, основанный на этом обсуждении. Это позволяет нам сосредоточить время на наиболее значимых issue, согласовать объём работ до написания кода и избежать дублирования усилий. Укажите номер issue в описании PR (например, Fixes #1234), чтобы связать их.
  2. Будьте хамелеоном. Изучите существующие паттерны проектирования и синтаксис, чтобы ваши дополнения к коду органично вписывались в текущую кодовую базу. Pull requests, существенно отличающиеся от существующих паттернов проектирования или пользовательских интерфейсов, не будут приняты.
  3. Будьте предельно сфокусированы. Pull request должен решать одну проблему и только одну. Не попадайтесь в ловушку «пока мы это добавляем, давайте сразу починим и другую проблему». Гораздо сложнее ревьюить pull requests, которые решают несколько несвязанных проблем одновременно.
  4. Исправляйте паттерны, а не единичные случаи. Одна проблема может затрагивать множество файлов: если один и тот же баг повторяется по всему кодовому основанию, найдите все его вхождения и исправьте их в одном PR с чётким системным охватом (например, «исправить изменяемые значения по умолчанию во всех планировщиках»), а не создавайте отдельный PR для каждого вхождения.
  5. Заголовок вашего pull request должен быть кратким описанием вклада. Чтобы указать, что работа ещё ведётся, добавьте в начало заголовка [WIP]; это позволяет избежать дублирования работы и отделяет данный PR от тех, которые готовы к слиянию.
  6. Старайтесь формулировать и оформлять текст так, как описано в Как написать хороший issue.
  7. Перед созданием PR просмотрите собственный diff. Прочитайте его глазами ревьюера и исправьте найденные проблемы. Настоятельно рекомендуем использовать навык self-review: он применяет тот же критерий оценки, что и CI-ревьюер @claude. Настройте своего агента, как описано в разделе Кодирование с ИИ-агентами, и следуйте рекомендациям из раздела Вклад с помощью ИИ и агентов. В описании укажите те замечания, которые вы намеренно оставили без изменений, чтобы ревьюер понимал, что это было осознанное решение, а не упущение.
  8. Убедитесь, что существующие тесты проходят.
  9. Добавляйте тесты с высоким покрытием. Отсутствие тестов качества = отсутствие слияния.
  • Если вы добавляете новые тесты с меткой @slow, убедитесь, что они проходят с помощью команды RUN_SLOW=1 python -m pytest tests/test_my_new_model.py. CircleCI не запускает медленные тесты, но GitHub Actions выполняет их каждую ночь!
  1. Все публичные методы должны иметь информативные docstrings, хорошо работающие с markdown. Пример — pipeline_latent_diffusion.py.
  2. В связи с быстрым ростом репозитория важно убедиться, что в него не добавляются файлы, которые значительно увеличивают его размер. Сюда входят изображения, видео и другие нетекстовые файлы. Мы предпочитаем размещать такие файлы в хостингуемом на hf.co dataset, например hf-internal-testing или huggingface/documentation-images. Если вы вносите внешний вклад, вы можете добавить изображения в свой PR и попросить члена команды Hugging Face перенести ваши изображения в этот dataset.

Как открыть PR

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

Для участия в разработке 🧨 Diffusers потребуются базовые навыки работы с git. git — не самый простой инструмент, но у него есть превосходная документация. Введите git --help в терминале и наслаждайтесь. Если вы предпочитаете книги, Pro Git — отличный справочник.

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

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

  2. Склонируйте ваш форк на локальный диск и добавьте базовый репозиторий как удалённый:

    $ git clone [email protected]:<your GitHub handle>/diffusers.git
$ cd diffusers
$ git remote add upstream https://github.com/huggingface/diffusers.git

  3. Создайте новую ветку для хранения изменений в процессе разработки:

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

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

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

    $ pip install -e ".[dev]"

Если вы уже клонировали репозиторий, возможно, вам потребуется выполнить git pull, чтобы получить последние изменения в библиотеке.

  1. Разрабатывайте функции на своей ветке.

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

$ pytest tests/<TEST_TO_RUN>.py

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

$ pip install -e ".[test]"

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

$ make test

🧨 Diffusers использует black и isort для единообразного форматирования исходного кода. После внесения изменений выполните автоматические стилистические правки и проверки кода, которые невозможно автоматизировать, одной командой:

$ make style

🧨 Diffusers также использует ruff и несколько пользовательских скриптов для проверки ошибок в коде. Контроль качества выполняется в CI, однако вы можете запустить те же проверки с помощью:

$ make quality

Когда вы будете довольны внесёнными изменениями, добавьте изменённые файлы с помощью git add и создайте коммит с помощью git commit, чтобы зафиксировать изменения локально:

$ git add modified_file.py
$ git commit -m "A descriptive message about your changes."

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

$ git pull upstream main

Отправьте изменения на свой аккаунт с помощью:

$ git push -u origin a-descriptive-name-for-my-changes

  1. Когда вы будете довольны результатом, перейдите на страницу вашего форка на GitHub. Нажмите «Pull request», чтобы отправить свои изменения создателям проекта на ревью.

  2. Ничего страшного, если сопровождающие проекта попросят вас внести изменения. Это случается даже с основными участниками! Чтобы все могли увидеть изменения в Pull request, работайте в своей локальной ветке и отправляйте изменения в свой форк. Они автоматически появятся в pull request.

Тесты

В состав библиотеки входит обширный набор тестов для проверки её поведения и нескольких примеров. Тесты библиотеки находятся в каталоге tests.

Мы предпочитаем pytest и pytest-xdist, потому что это быстрее. Из корня репозитория тесты для библиотеки запускаются с помощью pytest следующим образом:

$ python -m pytest -n auto --dist=loadfile -s -v ./tests/

На самом деле, именно так реализована команда make test!

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

По умолчанию медленные тесты пропускаются. Чтобы запустить их, установите переменную окружения RUN_SLOW в значение yes. Это приведёт к загрузке моделей объёмом в несколько гигабайт — убедитесь, что у вас достаточно места на диске и стабильное интернет-соединение, либо запаситесь терпением!

$ RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./tests/

unittest полностью поддерживается, вот как запускать тесты с его помощью:

$ python -m unittest discover -s tests -t . -v
$ python -m unittest discover -s examples -t examples -v

Синхронизация форка main с upstream (HuggingFace) main

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

  1. По возможности избегайте синхронизации с upstream с помощью ветки и PR в форке. Вместо этого выполняйте слияние непосредственно в main форка.
  2. Если PR абсолютно необходим, выполните следующие шаги после переключения на вашу ветку:
$ git checkout -b your-branch-for-syncing
$ git pull --squash --no-commit upstream main
$ git commit -m '<your message without GitHub references>'
$ git push --set-upstream origin your-branch-for-syncing

Стиль

Для строк документации 🧨 Diffusers придерживается стиля Google.

Программирование с ИИ-агентами

Репозиторий хранит конфигурацию ИИ-агента в .ai/, которая также публикуется как плагин агента, чтобы навыки для задач по требованию устанавливались в один шаг.

  • Только для чтения для контрибьюторов — .ai/ поддерживается основными мейнтейнерами. Пожалуйста, не редактируйте файлы в .ai/ (или символьные ссылки AGENTS.md / CLAUDE.md в корне, или установленные .agents/skills / .claude/skills) в вашем PR. Если вы обнаружите что-то пропущенное или неверное, создайте issue или отметьте это в PR, и мейнтейнер обновит содержимое.
  • Guidelines — .ai/AGENTS.md загружается в каждую сессию агента через корневые AGENTS.md / CLAUDE.md символические ссылки; справочные руководства в .ai/references/ читаются по мере необходимости при переходе по ссылке:
    • .ai/AGENTS.md — основные правила написания кода
    • .ai/references/models.md — шаблон внимания, правила реализации моделей, общие соглашения
    • .ai/references/pipelines.md — соглашения по пайплайнам
    • .ai/references/modular.md — соглашения о модульных конвейерах и чек-лист конвертации
    • .ai/references/testing.md — обязательные уровни тестирования, миксины тестировщика, правила для dummy-компонентов
    • .ai/references/review-rules.md — на что обращают внимание рецензенты
  • Skills (под .ai/skills/, загружаются по запросу для конкретных задач):
    • model-integration — добавление новой модели или конвейера в diffusers от начала до конца (структура файлов, чек-лист интеграции, структура тестов, конвертация весов)
    • self-review — проверьте свои изменения на соответствие правилам проекта перед созданием PR
    • diffusers-cli — запуск пайплайнов и просмотр схем из терминала
    • custom-blocks — упаковка подкласса ModularPipelineBlocks для Hub

Какой бы путь вы ни выбрали, попросите агента подтвердить свою конфигурацию перед началом работы — python utils/check_ai.py проверяет согласованность руководств и навыков, а diffusers-cli skills list показывает, какие навыки у него действительно есть.

Вклад с использованием ИИ и агентных систем

AI-агенты приветствуются для участия в разработке Diffusers. Мы рекомендуем настроить вашего агента с помощью руководства для агентов Diffusers и использовать соответствующие навыки для конкретных задач, такие как model-integration и self-review. Установите плагин (или отдельные навыки) в соответствии с описанным выше процессом, затем следуйте руководству, чтобы определить объём, реализовать, протестировать и проверить свой вклад. Вы несёте ответственность за понимание, тестирование и поддержку изменений в вашем PR.

Вклад с использованием ИИ приветствуется, но он должен быть скоординирован, ограничен по объёму и проверен, чтобы нагрузка на ревью оставалась управляемой. PR, не соответствующие этим рекомендациям, могут быть закрыты без детального ревью.

  • Согласуйте действия перед созданием PR. Найдите или создайте issue, просмотрите похожие PR (открытые и недавно закрытые) и дождитесь явного подтверждения от мейнтейнера в этом issue перед созданием PR. Это даст нам возможность обсудить объём работ, избежать дублирования и подтвердить выбранный подход.
  • Исправляйте паттерны, а не единичные случаи. Если вы заметили повторяющуюся проблему, найдите в кодовой базе похожие случаи и создайте один issue с чётким системным охватом (например, «исправить изменяемые значения по умолчанию во всех планировщиках»), а не множество issues или PR для отдельных случаев.
  • Самопроверка перед открытием. Запустите навык self-review — он проверяет ваш diff по правилам из .ai/references/review-rules.md, той же шкале, которую использует CI-ревьюер @claude, — и устраните выявленные проблемы. Это вспомогательный инструмент, а не авторитетный источник, поэтому он может ошибаться. Сосредоточьтесь на блокирующих проблемах, которые вам понятны, и по возможности удалите мёртвый/неиспользуемый код. Если вы не согласны с каким-либо предложением, можно оставить его для обсуждения ревьюером после открытия PR — ваши комментарии (см. ниже) сообщат ревьюеру, что это было осознанное решение.
  • Поделитесь заметками от самопроверки. Опубликуйте итоговый отчёт о самопроверке — тот раунд, который отражает дифф, который вы отправляете, — в PR, в описании или в виде комментария, включая замечания, которые вы намеренно не исправили, и объяснение причин. Это помогает ревьюеру понять, что уже было проверено и какие решения были приняты осознанно, и обычно экономит несколько раундов переписки.
  • Держите коммуникацию в PR краткой. Всё, что ревьюер читает в вашем PR — описание, сообщения коммитов, комментарии и ответы, комментарии в коде — должно быть легко понятно человеку. Если текст составил ваш агент, не ограничивайтесь беглым просмотром. Прочитайте его и попросите агента переработать, пока он не станет осмысленным и лаконичным, как если бы вы написали его сами. Вы — автор всего, что публикуете.
  • Include in the PR description:
    • Ссылка на координационную задачу или обсуждение, в котором maintainer подтвердил работу.
    • Команды тестирования, которые вы выполнили, test commands you ran и их результаты (вставьте соответствующий вывод, а не просто «тесты пройдены»).
    • Ваши заметки по самопроверке (или ссылка на комментарий к PR, содержащий их), как описано выше.

Если вы являетесь автором модели или входите в команду, официально поддерживающую модель, мы рекомендуем использовать агентов для интеграции новой модели. Следуйте рекомендуемой настройке репозитория и используйте навык model-integration. Согласуйте объём работ с мейнтейнерами перед созданием PR — см. Добавление пайплайнов, моделей и планировщиков.

Update on GitHub

←Проекты, созданные с помощью Diffusers Этические принципы Diffusers→