Como contribuir para o Diffusers 🧨

Se você usar um agente de IA para contribuir, certifique-se de ler a seção Contribuições assistidas por IA e agênticas para conhecer nossas expectativas e diretrizes.

Nós ❤️ contribuições da comunidade de código aberto! Todos são bem-vindos, e todos os tipos de participação –não apenas código– são valorizados e apreciados. Responder perguntas, ajudar outros, se comunicar e melhorar a documentação são todos imensamente valiosos para a comunidade, então não tenha medo e envolva-se se você estiver disposto!

Todos são convidados a começar dizendo 👋 em nosso canal público do Discord. Discutimos as últimas tendências em modelos de difusão, fazemos perguntas, mostramos projetos pessoais, nos ajudamos com contribuições ou apenas conversamos ☕.

Independentemente da forma como você escolher contribuir, nos esforçamos para fazer parte de uma comunidade aberta, acolhedora e gentil. Por favor, leia nosso código de conduta e tenha o cuidado de respeitá-lo durante suas interações. Também recomendamos que você se familiarize com as diretrizes éticas que orientam nosso projeto e pedimos que você siga os mesmos princípios de transparência e responsabilidade.

Valorizamos enormemente o feedback da comunidade, então não tenha medo de se manifestar se você acredita ter um feedback valioso que possa ajudar a melhorar a biblioteca - toda mensagem, comentário, issue e pull request (PR) é lida e considerada.

Visão geral

Você pode contribuir de muitas formas, desde responder perguntas em issues e discussões até adicionar novos modelos de difusão à biblioteca principal.

A seguir, apresentamos uma visão geral das diferentes formas de contribuir, classificadas pelo tempo de dedicação necessário, em ordem crescente. Todas elas são valiosas para a comunidade.

• 1. Fazer e responder perguntas no GitHub Discussions ou no Discord.
• 2. Abrindo novas questões na aba GitHub Issues.
• 3. Resolvendo problemas na aba de Issues do GitHub.
• 4. Corrija um problema simples, marcado com o rótulo “Good first issue”, veja aqui.
• 5. Contribua para a documentação.
• 6. Publique um pipeline ou modelo no Hub como código remoto com Modular Diffusers.
• 7. Contribua para os exemplos.
• 8. Corrija um problema mais difícil, marcado com o rótulo “Good second issue”, veja aqui.
• 9. Assuma uma issue do programa MVP do Diffusers.
• 10. Adicione um novo pipeline, modelo ou scheduler à biblioteca. Para essa contribuição, geralmente trabalhamos diretamente com os autores do modelo; como contribuidor da comunidade, comece no Hub (6) em vez disso. Consulte as issues abertas “New Pipeline/Model” e “New scheduler” e leia a Design Philosophy primeiro.

Como dito anteriormente, todas as contribuições são valiosas para a comunidade. A seguir, explicaremos cada contribuição com um pouco mais de detalhe.

Para as contribuições 4 a 10, exceto a 6, que está no Hub, você precisará abrir um PR. O processo é explicado em detalhes em Abertura de um pull request.

1. Fazer e responder perguntas nas Discussões do GitHub ou no Discord

Qualquer dúvida ou comentário relacionado à biblioteca Diffusers pode ser feito em GitHub Discussions ou no Discord. Tais dúvidas e comentários incluem (mas não se limitam a):

• Relatos de experimentos de treinamento ou inferência com o objetivo de compartilhar conhecimento
• Apresentação de projetos pessoais
• Perguntas sobre exemplos de treinamento não oficiais
• Propostas de projeto
• Feedback geral
• Resumos de artigos
• Pedir ajuda em projetos pessoais que são construídos sobre a biblioteca Diffusers
• Perguntas gerais
• Questões éticas sobre modelos de difusão
• …

Toda pergunta feita nas GitHub Discussions ou no Discord incentiva ativamente a comunidade a compartilhar conhecimento publicamente e pode muito bem ajudar um iniciante no futuro que tenha a mesma dúvida que você está tendo. Por favor, faça todas as perguntas que você tiver. No mesmo espírito, você ajuda imensamente a comunidade ao responder a essas perguntas, pois dessa forma você está documentando publicamente o conhecimento para que todos possam aprender.

Por favor, tenha em mente que quanto mais esforço você dedicar ao fazer ou responder a uma pergunta, maior será a qualidade do conhecimento documentado publicamente. Da mesma forma, perguntas bem formuladas e bem respondidas criam um banco de dados de conhecimento de alta qualidade acessível a todos, enquanto perguntas ou respostas mal formuladas reduzem a qualidade geral do banco de dados de conhecimento público. Em resumo, uma pergunta ou resposta de alta qualidade é precisa, concisa, relevante, fácil de entender, acessível e bem formatada/bem formulada. Para mais informações, consulte a seção Como escrever um bom issue.

OBSERVAÇÃO sobre canais: GitHub Discussions é indexado por mecanismos de busca e cada tópico pode ser vinculado, portanto, perguntas e respostas postadas ali permanecem encontráveis para a próxima pessoa com o mesmo problema. Em contraste, o Discord tem um formato de chat que convida a uma comunicação rápida e direta. Embora seja provável que você receba uma resposta para sua pergunta mais rapidamente no Discord, sua pergunta não será mais visível com o passar do tempo, e é muito mais difícil encontrar informações postadas há algum tempo. Por isso, recomendamos o GitHub Discussions para perguntas e respostas destinadas a durar. Se uma conversa no Discord levar a uma conclusão interessante, poste o resultado como uma discussão para que leitores futuros possam encontrá-lo.

2. Abrindo novas issues na aba de issues do GitHub

A biblioteca 🧨 Diffusers é robusta e confiável graças aos usuários que nos notificam sobre os problemas que encontram. Então, obrigado por reportar um problema.

Lembre-se de que as issues do GitHub são reservadas para perguntas técnicas diretamente relacionadas à biblioteca Diffusers, relatórios de bugs, solicitações de recursos ou feedback sobre o design da biblioteca.

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.

Considere as seguintes diretrizes ao abrir uma nova issue:

• Certifique-se de que você já pesquisou se o seu problema já foi questionado antes (use a barra de pesquisa no GitHub em Issues).
• Nunca relate um novo problema em outro problema (relacionado). Se outro problema for altamente relacionado, abra um novo problema mesmo assim e faça um link para o problema relacionado.
• Certifique-se de que seu problema esteja escrito em inglês.
• Verifique se o seu problema pode ser resolvido atualizando para a versão mais recente do Diffusers. Antes de postar o seu problema, certifique-se de que python -c "import diffusers; print(diffusers.__version__)" é maior ou corresponde à versão mais recente do Diffusers.
• Lembre-se de que quanto mais esforço você dedicar ao abrir uma nova issue, maior será a qualidade da sua resposta e melhor será a qualidade geral das issues do Diffusers.

Novos problemas geralmente incluem o seguinte.

2.1. Relatórios de bugs reproduzíveis e mínimos

Um relatório de bug deve sempre ter um trecho de código reproduzível e ser o mais mínimo e conciso possível. Isso significa, em mais detalhes:

• Reduza o escopo do bug o máximo possível, não envie o arquivo de código inteiro.
• Formate seu código.
• Não inclua nenhuma biblioteca externa, exceto Diffusers, dependendo delas.
• Sempre forneça todas as informações necessárias sobre o seu ambiente; para isso, você pode executar diffusers-cli env no seu shell e copiar e colar as informações exibidas na issue.
• Explique o problema. Se o leitor não souber qual é o problema e por que ele é um problema, (ele/ela) não poderá resolvê-lo.
• Sempre certifique-se de que o leitor possa reproduzir seu problema com o mínimo de esforço possível. Se seu trecho de código não puder ser executado devido a bibliotecas ausentes ou variáveis indefinidas, o leitor não poderá ajudá-lo. Certifique-se de que seu trecho de código reproduzível seja o mais mínimo possível e possa ser copiado e colado em um shell Python simples.
• Se, para reproduzir o seu problema, for necessário um modelo e/ou um conjunto de dados, certifique-se de que o leitor tem acesso a esse modelo ou conjunto de dados. Você sempre pode enviar o seu modelo ou conjunto de dados para o Hub para facilitar o download. Tente manter o seu modelo e conjunto de dados o menor possível, para tornar a reprodução do seu problema o mais simples possível.

Para mais informações, consulte a seção Como escrever um bom problema.

Você pode abrir um relatório de bug aqui.

2.2. Solicitações de recursos

Uma solicitação de recurso de primeira classe aborda os seguintes pontos:

1. Primeiro, a motivação:

• Isso está relacionado a um problema/frustração com a biblioteca? Se sim, por favor, explique o porquê. O ideal é fornecer um trecho de código que demonstre o problema.
• Isso está relacionado a algo de que você precisaria para um projeto? Adoraríamos saber mais!
• É algo em que você trabalhou e que acredita que pode beneficiar a comunidade? Excelente! Conte-nos qual problema ele resolveu para você.

2. Escreva um parágrafo completo descrevendo o recurso;
3. Forneça um trecho de código que demonstre seu uso futuro;
4. Caso isso esteja relacionado a um artigo, por favor, anexe um link;
5. Anexe quaisquer informações adicionais (desenhos, capturas de tela, etc.) que você ache que possam ajudar.

Você pode abrir uma solicitação de recurso aqui.

2.3 Feedback

Feedback sobre o design da biblioteca e por que ele é bom ou não ajuda imensamente os mantenedores principais a construir uma biblioteca amigável ao usuário. Para entender a filosofia por trás da filosofia de design atual, por favor, dê uma olhada aqui. Se você sentir que uma certa escolha de design não se encaixa na filosofia de design atual, explique por quê e como ela deveria ser alterada. Se uma certa escolha de design segue a filosofia de design demais, restringindo assim casos de uso, explique por quê e como ela deveria ser alterada. Se uma certa escolha de design é muito útil para você, deixe também uma nota, pois esse é um ótimo feedback para futuras decisões de design.

Você pode abrir uma questão sobre o feedback aqui.

2.4 Perguntas técnicas

As perguntas técnicas são principalmente sobre por que determinado código da biblioteca foi escrito de uma certa maneira, ou o que uma certa parte do código faz. Por favor, certifique-se de fazer um link para o código em questão e forneça detalhes sobre por que essa parte do código é difícil de entender.

Você pode abrir uma issue sobre uma questão técnica aqui.

2.5 Proposta para adicionar um novo modelo, agendador ou pipeline

Se a comunidade de modelos de difusão lançou um novo modelo, pipeline ou scheduler que você gostaria de ver na biblioteca Diffusers, por favor, forneça as seguintes informações:

• Breve descrição do pipeline de difusão, modelo ou agendador e link para o artigo ou lançamento público.
• Link para qualquer uma de suas implementações de código aberto.
• Link para os pesos do modelo, caso estejam disponíveis.

Além disso, não se esqueça de marcar o autor original do componente (modelo, agendador, pipeline, etc.) pelo handle do GitHub, se você conseguir encontrá-lo.

Se você quiser trazer o modelo para o Diffusers por conta própria, consulte Publicar um pipeline ou modelo no Hub e Adicionar pipelines, modelos, agendadores.

Você pode abrir uma solicitação para um modelo/pipeline/agendador aqui.

3. Resolvendo problemas na aba de problemas do GitHub

Responder a problemas no GitHub pode exigir algum conhecimento técnico de Diffusers, mas incentivamos todos a tentarem, mesmo que você não tenha 100% de certeza de que sua resposta está correta. Algumas dicas para dar uma resposta de alta qualidade a um problema:

• Seja o mais conciso e minimalista possível.
• Mantenha o foco no assunto. A resposta ao problema deve tratar apenas do problema em questão.
• Forneça links para códigos, artigos ou outras fontes que comprovem ou incentivem seu ponto.
• Responda em código. Se um simples trecho de código for a resposta para o problema ou mostrar como o problema pode ser resolvido, forneça um trecho de código totalmente reproduzível.

Além disso, muitos problemas tendem a ser simplesmente fora do tópico, duplicados de outros problemas ou irrelevantes. É de grande ajuda para os mantenedores se você puder responder a esses problemas, incentivando o autor do problema a ser mais preciso, fornecer o link para um problema duplicado ou redirecioná-los para GitHub Discussions ou Discord.

Se você verificou que o relatório de bug emitido está correto e requer uma correção no código-fonte, por favor, consulte as seções a seguir.

Para todas as contribuições, exceto 6, você precisa abrir um PR. A seção Abertura de um pull request explica como fazer isso.

4. Corrigindo um “Good first issue”

Boas primeiras questões são marcadas pelo rótulo Good first issue. Geralmente, a questão já explica como uma possível solução deve ser para facilitar a correção. Se a questão não tiver sido fechada e você quiser tentar corrigi-la, basta deixar a mensagem “I would like to try this issue.”. Geralmente, há três cenários:

• a.) A descrição do problema já propõe uma correção. Nesse caso, e se a solução fizer sentido para você, você pode abrir um PR ou um PR em rascunho para corrigi-lo.
• b.) A descrição da issue não propõe uma correção. Nesse caso, proponha uma correção você mesmo em um comentário na issue. Algumas frases descrevendo a abordagem são suficientes. Aguarde a confirmação de alguém da equipe do Diffusers antes de abrir um PR.
• c.) Já existe um PR aberto para corrigir o problema, mas o problema ainda não foi fechado. Se o PR ficou obsoleto, você pode simplesmente abrir um novo PR e fazer um link para o PR obsoleto. PRs frequentemente ficam obsoletos se o contribuidor original que queria corrigir o problema de repente não consegue mais encontrar tempo para prosseguir. Isso frequentemente acontece em código aberto e é muito normal. Nesse caso, a comunidade ficará muito feliz se você der uma nova tentativa e aproveitar o conhecimento do PR existente. Se já existe um PR e ele está ativo, você pode ajudar o autor dando sugestões, revisando o PR ou até mesmo perguntando se pode contribuir para o PR.

5. Contribuir para a documentação

Uma boa biblioteca sempre tem uma boa documentação! A documentação oficial costuma ser um dos primeiros pontos de contato para novos usuários da biblioteca, e, portanto, contribuir para a documentação é uma contribuição de alto valor.

Contribuir para a biblioteca pode assumir muitas formas:

• Corrigindo erros de ortografia ou gramática.
• Corrija a formatação incorreta do docstring. Se você notar que a documentação oficial está sendo exibida de forma estranha ou que um link está quebrado, ficaremos muito felizes se você dedicar um tempo para corrigi-lo.
• Corrija a forma ou as dimensões de um tensor de entrada ou saída na docstring.
• Esclarecer a documentação que é difícil de entender ou incorreta.
• Atualize exemplos de código desatualizados.
• Traduzindo a documentação para outro idioma.

Tudo que é exibido em a página oficial da documentação do Diffusers faz parte da documentação oficial e pode ser corrigido ou ajustado na fonte da documentação respectiva.

Por favor, dê uma olhada em esta página sobre como verificar as alterações feitas na documentação localmente.

6. Publique um pipeline ou modelo no Hub

Com o Modular Diffusers, um pipeline pode existir como código remoto em qualquer repositório do Hub. Qualquer pessoa pode carregá-lo com from_pretrained(..., trust_remote_code=True), sem esperar por uma liberação do Diffusers. Se você é um contribuidor da comunidade trazendo um novo pipeline ou modelo, comece aqui. Veja custom blocks para publicar um pipeline e custom models para publicar um modelo.

Informe-nos na solicitação de modelo correspondente (abra uma se não houver): fornecemos feedback sobre a implementação e destacamos as que gostamos em nossa coleção Community Modular Diffusers Blocks. A partir disso, decidimos como suportar o modelo na biblioteca: podemos incorporar sua versão, trabalhar com os autores em uma versão oficial ou simplesmente direcionar as pessoas para a sua. Informe-nos também onde encontrou dificuldades ao longo do caminho: APIs confusas, documentação ausente, bugs. Esse feedback é tão valioso para nós quanto o pipeline.

7. Contribuir com exemplos de treinamento

Os exemplos do Diffusers são uma coleção de scripts de treinamento que residem em examples.

Suportamos dois tipos de exemplos de treinamento:

• Exemplos oficiais de treinamento
• Exemplos de treinamento de pesquisa

Os exemplos de treinamento de pesquisa estão localizados em examples/research_projects, enquanto os exemplos de treinamento oficiais incluem todas as pastas sob examples, exceto as pastas research_projects e community. Os exemplos de treinamento oficiais são mantidos pelos mantenedores principais do Diffusers, enquanto os exemplos de treinamento de pesquisa são mantidos pela comunidade. Isso ocorre pelo mesmo motivo pelo qual a biblioteca mantém um conjunto pequeno de pipelines oficiais e pipelines da comunidade ativos no Hub: não é viável para os mantenedores principais manter todos os possíveis métodos de treinamento para modelos de difusão. Se os mantenedores principais do Diffusers e a comunidade considerarem um determinado paradigma de treinamento muito experimental ou não popular o suficiente, o código de treinamento correspondente deve ser colocado na pasta research_projects e mantido pelo autor.

Tanto os exemplos oficiais de treinamento quanto os de pesquisa consistem em um diretório que contém um ou mais scripts de treinamento, um arquivo requirements.txt e um arquivo README.md. Para que o usuário possa fazer uso dos exemplos de treinamento, é necessário clonar o repositório:

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

bem como para instalar todas as dependências adicionais necessárias para o treinamento:

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

Portanto, ao adicionar um exemplo, o arquivo requirements.txt deve definir todas as dependências do pip necessárias para o seu exemplo de treinamento, de modo que, uma vez que todas sejam instaladas, o usuário possa executar o script de treinamento do exemplo. Veja, por exemplo, o arquivo requirements.txt do DreamBooth.

Os exemplos de treinamento da biblioteca Diffusers devem seguir a seguinte filosofia:

• Todo o código necessário para executar os exemplos deve estar em um único arquivo Python.
• Deve ser possível executar o exemplo pela linha de comando com python <your-example>.py --args.
• Os exemplos devem ser mantidos simples e servir como um exemplo de como usar o Diffusers para treinamento. O objetivo dos scripts de exemplo é não criar modelos de difusão de última geração, mas sim reproduzir esquemas de treinamento conhecidos sem adicionar muita lógica personalizada. Como consequência desse ponto, nossos exemplos também buscam servir como bons materiais educacionais.

Para contribuir com um exemplo, é altamente recomendável consultar exemplos já existentes, como dreambooth, para ter uma ideia de como eles devem ser estruturados. Recomendamos fortemente que os colaboradores utilizem a Accelerate library, pois ela está profundamente integrada ao Diffusers. Quando um script de exemplo estiver funcionando, certifique-se de adicionar um README.md abrangente que descreva exatamente como usar o exemplo. Este README deve incluir:

• Um exemplo de comando para executar o script de exemplo mostrado aqui.
• Um link para alguns resultados de treinamento (logs, modelos, etc.) que mostram o que o usuário pode esperar, conforme mostrado aqui.
• Se você estiver adicionando um exemplo de treinamento não oficial/de pesquisa, por favor, não se esqueça de adicionar uma frase informando que você é o responsável pela manutenção desse exemplo de treinamento, incluindo seu handle do git, conforme mostrado aqui.

Se você está contribuindo com os exemplos oficiais de treinamento, certifique-se também de adicionar um teste à sua pasta, como examples/dreambooth/test_dreambooth.py. Isso não é necessário para exemplos de treinamento não oficiais.

8. Corrigindo um “Good second issue”

Bons segundos problemas são marcados pelo rótulo Good second issue. Geralmente, são mais complicados de resolver do que os Bons primeiros problemas, a descrição oferece menos orientações sobre a correção e é necessário ter um bom entendimento da biblioteca.

Se você estiver interessado em resolver um bom segundo problema, compartilhe sua opinião sobre o problema e a abordagem que tem em mente como um comentário, em poucas frases, e obtenha um reconhecimento de um mantenedor antes de abrir o PR. Se um PR já tiver sido aberto para o problema, mas não tiver sido mesclado, verifique para entender o motivo antes de propor algo novo.

9. Assumendo uma questão de MVP do Diffusers

O programa MVP do Diffusers lista as questões em que mais precisamos de ajuda. Elas funcionam como bons segundos issues, mas são mais difíceis e levam mais tempo, e o programa recompensa os contribuidores que as assumem. Compartilhe sua abordagem como um comentário primeiro e obtenha um reconhecimento de um mantenedor antes de abrir o PR. O programa também tem uma trilha de ideias: nos conte uma ideia que aumentaria o impacto do Diffusers, em poucas frases e sem detalhes de implementação.

10. Adicionando pipelines, modelos e agendadores

Se você é o autor do modelo, entre em contato para que possamos coordenar a integração com você: abra uma solicitação de recurso ou deixe um comentário se já houver uma aberta.

Se você é um contribuidor da comunidade, comece por um repositório no Hub, consulte Publicar um pipeline ou modelo no Hub e nos informe, na solicitação de recurso, que você tem interesse em enviá-lo para o upstream.

Pipelines, models e schedulers são as peças mais importantes da biblioteca Diffusers. Eles fornecem acesso fácil às tecnologias de difusão mais avançadas e, assim, permitem que a comunidade construa poderosas aplicações de IA generativa.

Ao adicionar um novo modelo, pipeline ou scheduler, você pode habilitar um novo caso de uso poderoso para qualquer uma das interfaces de usuário que dependem do Diffusers, o que pode ter um valor imenso para todo o ecossistema de IA generativa.

Quando o suporte a um novo modelo ou pipeline é lançado

Um novo modelo ou pipeline pode ser incluído em uma versão se você coordenar a integração com a equipe do Diffusers com antecedência. Sinta-se à vontade para nos contatar, seja por meio de uma issue no repositório do Diffusers ou enviando um e-mail para [email protected].

Um lançamento não ocorre automaticamente quando uma solicitação de pull request de um modelo ou pipeline é mesclada. Antes de um lançamento, os mantenedores primeiro verificam que a integração está completa e que os testes de lançamento passam.

O suporte a um novo modelo ou pipeline normalmente é incluído na próxima versão secundária. A integração é mesclada em main e o ramo de lançamento é criado a partir dele. O lançamento contém todas as alterações mescladas desde o lançamento anterior, e não apenas a integração do modelo ou pipeline.

As notas de versão destacam o novo modelo ou pipeline e também resumem as outras alterações incluídas na versão. As versões de correção (patch) são normalmente reservadas para correções em uma versão existente.

O Diffusers tem alguns pedidos de recursos abertos para os três componentes - sinta-se à vontade para dar uma olhada neles, caso ainda não saiba qual componente específico gostaria de adicionar:

• Modelo ou pipeline
• Agendador

Antes de adicionar qualquer um dos três componentes, é fortemente recomendável que você leia o Guia de Filosofia para entender melhor o design de qualquer um dos três componentes. Tenha em mente que não podemos mesclar adições de modelos, agendadores ou pipelines que diverjam significativamente da nossa filosofia de design, pois isso levará a inconsistências na API. Se você discordar fundamentalmente de uma escolha de design, abra um Issue de Feedback para que possamos discutir se um determinado padrão de design/escolha de design deve ser alterado em toda a biblioteca e se devemos atualizar nossa filosofia de design. A consistência em toda a biblioteca é muito importante para nós.

Certifique-se de adicionar links para o repositório de código original/paper na PR e, idealmente, também marcar diretamente o autor original na PR para que ele possa acompanhar o progresso e, potencialmente, ajudar com perguntas.

Se você estiver em dúvida ou travado no PR, não hesite em deixar uma mensagem pedindo uma primeira revisão ou ajuda.

Copiado de mechanism

Um recurso único e importante a ser compreendido ao adicionar qualquer código de pipeline, modelo ou scheduler é o mecanismo # Copied from. Você verá isso em todo o codebase do Diffusers, e a razão pela qual o utilizamos é para manter o codebase fácil de entender e manter. Marcar código com o mecanismo # Copied from força o código marcado a ser idêntico ao código do qual foi copiado. Isso facilita atualizar e propagar alterações entre muitos arquivos sempre que você executa make fix-copies.

Por exemplo, no exemplo de código abaixo, StableDiffusionPipelineOutput é o código original e AltDiffusionPipelineOutput usa o mecanismo # Copied from para copiá-lo. A única diferença é a mudança do prefixo da classe de Stable para 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.
    """

Para saber mais, leia esta seção do post no blog ~Don’t~ Repeat Yourself*.

Como escrever um bom problema

Quanto melhor a sua issue for escrita, maiores serão as chances de ela ser resolvida rapidamente.

1. Certifique-se de que você usou o modelo correto para o seu problema. Você pode escolher entre Bug Report, Feature Request, Feedback about API Design, New model/pipeline/scheduler addition ou um problema em branco. Certifique-se de escolher o correto ao abrir a new issue. Perguntas de uso pertencem às GitHub Discussions, não a um problema.
2. Seja preciso: Dê ao seu problema um título adequado. Tente formular a descrição do seu problema da forma mais simples possível. Quanto mais preciso você for ao enviar um problema, menos tempo levará para entendê-lo e, potencialmente, resolvê-lo. Certifique-se de abrir um problema para apenas um problema e não para vários. Se você encontrou vários problemas, simplesmente abra vários problemas. Se o seu problema for um bug, tente ser o mais preciso possível sobre qual é o bug - você não deve apenas escrever “Error in diffusers”.
3. Reprodutibilidade: Sem um trecho de código reproduzível == sem solução. Se você encontrar um bug, os mantenedores precisam ser capazes de reproduzi-lo. Certifique-se de incluir um trecho de código que possa ser copiado e colado em um interpretador Python para reproduzir o problema. Certifique-se de que seu trecho de código funciona, ou seja, que não há imports faltando ou links para imagens ausentes, … Seu problema deve conter uma mensagem de erro e um trecho de código que possa ser copiado e colado sem nenhuma alteração para reproduzir exatamente a mesma mensagem de erro. Se o seu problema usa pesos de modelo locais ou dados locais que não podem ser acessados pelo leitor, o problema não pode ser resolvido. Se você não puder compartilhar seus dados ou modelo, tente criar um modelo fictício ou dados fictícios.
4. Minimalista: Tente ajudar o leitor a entender o problema o mais rápido possível, mantendo-se o mais conciso que puder. Remova todo o código / toda a informação irrelevante para o problema. Se você encontrou um bug, tente criar o exemplo de código mais simples possível para demonstrar o seu problema; não despeje todo o seu fluxo de trabalho no problema assim que encontrar um bug. Por exemplo, se você treina um modelo e obtém um erro em algum ponto durante o treinamento, você deve primeiro tentar entender qual parte do código de treinamento é responsável pelo erro e tentar reproduzi-lo com algumas linhas. Tente usar dados fictícios em vez de conjuntos de dados completos.
5. Contexto: Conte-nos em que você estava trabalhando quando encontrou o bug ou precisou do recurso, como um aplicativo construído com Diffusers, um projeto de pesquisa ou um agente que você executou para encontrar bugs na biblioteca. Uma ou duas frases são suficientes, e um link para o projeto é bem-vindo. Recebemos mais issues e PRs do que podemos lidar de uma vez, então o contexto nos ajuda a priorizar pelo impacto.
6. Adicione links. Se você estiver se referindo a uma nomenclatura, método ou modelo específico, certifique-se de fornecer um link para que o leitor possa entender melhor o que você quer dizer. Se estiver se referindo a um PR ou issue específico, certifique-se de vinculá-lo à sua issue. Não assuma que o leitor sabe do que você está falando. Quanto mais links você adicionar à sua issue, melhor.
7. Formatação. Certifique-se de formatar bem a sua issue, formatando o código com a sintaxe de código Python e as mensagens de erro com a sintaxe de código normal. Consulte a documentação oficial de formatação do GitHub para mais informações.
8. Pense no seu problema não como um chamado a ser resolvido, mas sim como uma bela entrada em uma enciclopédia bem escrita. Cada problema adicionado é uma contribuição para o conhecimento de acesso público. Ao adicionar um problema bem redigido, você não apenas facilita a resolução do seu problema pelos mantenedores, mas também ajuda toda a comunidade a compreender melhor um determinado aspecto da biblioteca.

Como escrever um bom PR

1. Comece sempre por uma issue. Encontre a issue que seu pull request aborda ou abra uma se ninguém o fez, e dê aos mantenedores a chance de responder antes de você escrever código. O fluxo de trabalho que melhor funciona para nós é abrir uma issue, depois uma discussão sobre a solução e, em seguida, um PR baseado nessa discussão. Isso nos permite focar nosso tempo nas issues de maior impacto, concordar sobre o escopo antes que o código exista e evitar trabalho duplicado. Mencione o número da issue na descrição do PR (por exemplo, Fixes #1234) para que os dois fiquem vinculados.
2. Seja um camaleão. Entenda os padrões de design e a sintaxe existentes e certifique-se de que suas adições de código se integrem perfeitamente à base de código atual. Pull requests que divergirem significativamente dos padrões de design ou das interfaces de usuário existentes não serão mesclados.
3. Seja extremamente focado. Uma pull request deve resolver um problema e apenas um problema. Certifique-se de não cair na armadilha de “também corrigir outro problema enquanto estamos adicionando isso”. É muito mais difícil revisar pull requests que resolvem múltiplos problemas não relacionados de uma vez.
4. Corrija padrões, não casos isolados. Um único problema pode se estender por vários arquivos: se o mesmo bug se repete em diferentes partes da base de código, procure todas as instâncias e corrija-as em um único PR com um escopo claro e sistemático (por exemplo, “corrigir padrões mutáveis em todos os agendadores”), em vez de um PR por instância.
5. O título da sua pull request deve ser um resumo da sua contribuição. Para indicar um trabalho em andamento, prefixe o título com [WIP]; isso evita trabalho duplicado e separa a PR das que estão prontas para serem mescladas.
6. Tente formular e formatar seu texto conforme explicado em Como escrever um bom issue.
7. Revise o próprio diff antes de abrir o PR. Leia-o como um revisor faria e corrija o que encontrar. Recomendamos fortemente executar a skill self-review: ela aplica o mesmo critério do revisor de CI @claude. Configure seu agente conforme descrito em Coding with AI agents e siga AI-assisted and agentic contributions. Mencione na descrição as observações que você deixou deliberadamente como estão, para que o revisor saiba que foi uma decisão e não uma falha.
8. Certifique-se de que os testes existentes sejam aprovados.
9. Adicione testes de alta cobertura. Sem testes de qualidade = sem merge.

• Se você estiver adicionando novos testes @slow, verifique se eles passam usando RUN_SLOW=1 python -m pytest tests/test_my_new_model.py. O CircleCI não executa os testes lentos, mas o GitHub Actions os executa todas as noites!

10. Todos os métodos públicos devem ter docstrings informativos que funcionem bem com markdown. Veja pipeline_latent_diffusion.py para um exemplo.
11. Devido ao crescimento rápido do repositório, é importante garantir que nenhum arquivo que aumente significativamente o peso do repositório seja adicionado. Isso inclui imagens, vídeos e outros arquivos não textuais. Preferimos aproveitar um dataset hospedado no hf.co, como hf-internal-testing ou huggingface/documentation-images, para armazenar esses arquivos. Se for uma contribuição externa, sinta-se à vontade para adicionar as imagens ao seu PR e pedir a um membro da Hugging Face para migrar suas imagens para este dataset.

Como abrir um PR

Antes de escrever código, recomendamos fortemente que você pesquise nos PRs ou issues existentes para ter certeza de que ninguém já está trabalhando na mesma coisa. Se você não tiver certeza, é sempre uma boa ideia abrir um issue para obter algum feedback.

Você precisará de conhecimento básico de git para poder contribuir com o 🧨 Diffusers. O git não é a ferramenta mais fácil de usar, mas tem o melhor manual. Digite git --help em um shell e aproveite. Se você prefere livros, Pro Git é uma referência muito boa.

Siga estas etapas para começar a contribuir (versões do Python suportadas):

1. Faça o fork do repositório clicando no botão “Fork” na página do repositório. Isso cria uma cópia do código na sua conta de usuário do GitHub.

2. Clone seu fork para o disco local e adicione o repositório base como um remote:

   Copiado

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

3. Crie um novo branch para conter suas alterações de desenvolvimento:

   Copiado

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

Não trabalhe no ramo main.

4. Configure um ambiente de desenvolvimento executando o seguinte comando em um ambiente virtual:

   Copiado

   $ pip install -e ".[dev]"

Se você já clonou o repositório, talvez precise executar git pull para obter as alterações mais recentes da biblioteca.

5. Desenvolva os recursos em seu branch.

À medida que você trabalha nos recursos, deve se certificar de que a suíte de testes passa. Você deve executar os testes impactados pelas suas alterações da seguinte forma:

$ pytest tests/<TEST_TO_RUN>.py

Antes de executar os testes, verifique se você instalou as dependências necessárias para os testes. Você pode fazer isso com este comando:

$ pip install -e ".[test]"

Você também pode executar a suíte de testes completa com o seguinte comando, mas agora que o Diffusers cresceu bastante, é necessário um computador potente para produzir um resultado em um tempo razoável. Aqui está o comando:

$ make test

🧨 O Diffusers depende de black e isort para formatar seu código-fonte de forma consistente. Após fazer alterações, aplique as correções automáticas de estilo e as verificações de código que não podem ser automatizadas em uma única execução com:

$ make style

🧨 O Diffusers também usa ruff e alguns scripts personalizados para verificar erros de codificação. O controle de qualidade é executado no CI, mas você também pode executar as mesmas verificações com:

$ make quality

Quando estiver satisfeito com suas alterações, adicione os arquivos alterados usando git add e crie um commit com git commit para registrar suas alterações localmente:

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

É uma boa ideia sincronizar sua cópia do código com o repositório original regularmente. Dessa forma, você pode lidar rapidamente com as alterações:

$ git pull upstream main

Envie as alterações para sua conta usando:

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

6. Quando estiver satisfeito, acesse a página do seu fork no GitHub. Clique em ‘Pull request’ para enviar suas alterações aos mantenedores do projeto para revisão.

7. É normal que os mantenedores peçam alterações. Isso acontece até com os contribuidores principais! Para que todos possam ver as alterações na solicitação de pull, trabalhe em seu branch local e envie as alterações para seu fork. Elas aparecerão automaticamente na solicitação de pull.

Testes

Um conjunto extensivo de testes é incluído para testar o comportamento da biblioteca e vários exemplos. Os testes da biblioteca podem ser encontrados na pasta de testes.

Gostamos de pytest e pytest-xdist porque é mais rápido. A partir da raiz do repositório, veja como executar os testes com pytest para a biblioteca:

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

Na verdade, é assim que o make test é implementado!

Você pode especificar um conjunto menor de testes para testar apenas o recurso em que está trabalhando.

Por padrão, os testes lentos são ignorados. Defina a variável de ambiente RUN_SLOW como yes para executá-los. Isso baixará vários gigabytes de modelos — certifique-se de ter espaço em disco suficiente e uma boa conexão com a Internet, ou muita paciência!

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

unittest é totalmente suportado, veja como executar testes com ele:

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

Sincronizando o main do fork com o main upstream (HuggingFace)

Para evitar acionar o repositório de origem, o que adiciona notas de referência a cada PR de origem e envia notificações desnecessárias aos desenvolvedores envolvidos nesses PRs, ao sincronizar o branch principal de um repositório forkado, siga estas etapas:

1. Quando possível, evite sincronizar com o upstream usando um branch e um PR no repositório clonado. Em vez disso, faça o merge diretamente no main do repositório clonado.
2. Se um PR for absolutamente necessário, use as seguintes etapas após fazer o checkout do seu branch:

$ 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

Guia de estilo

Para as strings de documentação, o 🧨 Diffusers segue o estilo Google.

Programando com agentes de IA

O repositório mantém a configuração do agente de IA em .ai/, que também é publicado como um plugin de agente para que as habilidades de tarefas sob demanda sejam instaladas em uma única etapa.

• Somente leitura para contribuidores — .ai/ é mantido pelos mantenedores principais. Por favor, não edite arquivos sob .ai/ (ou os links simbólicos de nível raiz AGENTS.md / CLAUDE.md, ou os .agents/skills / .claude/skills instalados) no seu PR. Se você encontrar algo ausente ou incorreto, abra uma issue ou sinalize no PR e um mantenedor fará a atualização.
• Guidelines — .ai/AGENTS.md é carregado em cada sessão de agente por meio dos links simbólicos raiz AGENTS.md / CLAUDE.md ; os guias de referência sob .ai/references/ são lidos sob demanda quando um link é seguido:
  • .ai/AGENTS.md — diretrizes de codificação de nível superior
  • .ai/references/models.md — padrão de atenção, regras de implementação de modelos, convenções comuns
  • .ai/references/pipelines.md — convenções de pipeline
  • .ai/references/modular.md — convenções de pipeline modular e lista de verificação de conversão
  • .ai/references/testing.md — camadas de teste obrigatórias, mixins de tester, regras para componentes fictícios
  • .ai/references/review-rules.md — o que os revisores procuram
• Skills (sob .ai/skills/, carregadas sob demanda para tarefas específicas):
  • model-integration — adicionar um novo modelo ou pipeline ao diffusers de ponta a ponta (estrutura de arquivos, lista de verificação de integração, layout de testes, conversão de pesos)
  • self-review — revise suas alterações em relação às regras do projeto antes de abrir um PR
  • diffusers-cli — executar pipelines e inspecionar schemas a partir do terminal
  • custom-blocks — empacotando uma subclasse de ModularPipelineBlocks para o Hub

Independentemente do caminho que você seguir, peça ao seu agente para confirmar a própria configuração antes de começar — python utils/check_ai.py verifica se os guias e as skills estão consistentes, e diffusers-cli skills list mostra quais skills ele realmente possui.

Contribuições assistidas por IA e agênticas

Agentes de IA são bem-vindos para contribuir com o Diffusers. Recomendamos que você configure seu agente com o guia de agentes do Diffusers e utilize as habilidades específicas de tarefa relevantes, como model-integration e self-review. Instale o plugin (ou as habilidades individuais) conforme descrito acima e, em seguida, siga o guia para definir o escopo, implementar, testar e revisar sua contribuição. Você continua sendo responsável por compreender, testar e manter as alterações no seu PR.

Contribuições assistidas por IA são bem-vindas, mas devem ser coordenadas, delimitadas e verificadas para manter a carga de revisão gerenciável. PRs que não seguirem essas diretrizes podem ser fechados sem uma revisão detalhada.

• Coordene antes de abrir um PR. Encontre ou abra uma issue, revise PRs semelhantes (abertos e fechados recentemente) e aguarde um reconhecimento explícito de um mantenedor naquela issue antes de abrir um PR. Isso nos dá a chance de discutir o escopo, evitar trabalho duplicado e confirmar a abordagem.
• Corrija padrões, não casos isolados. Se você identificar um problema recorrente, pesquise na base de código por instâncias semelhantes e abra um único problema com um escopo claro e sistemático (por exemplo, “corrigir padrões mutáveis em todos os agendadores”) em vez de muitos problemas ou PRs para instâncias individuais.
• Autoavaliação antes de abrir. Execute a skill self-review — ela avalia seu diff com base em .ai/references/review-rules.md, o mesmo critério usado pelo revisor de CI @claude — e trate o que ela relatar — é um auxiliar, não é autoritativo, e pode estar errado. Foque nos problemas bloqueantes que fazem sentido para você e limpe o máximo possível o código morto/não utilizado. Se você discordar de uma sugestão, está tudo bem deixá-la para o revisor discutir depois que o PR for aberto — as notas que você compartilha (veja abaixo) informam ao revisor que foi uma decisão deliberada.
• Compartilhe suas anotações de autoavaliação. Publique o relatório final de autoavaliação — a rodada que reflete o diff que você está enviando — no PR, na descrição ou como um comentário, incluindo as observações que você optou por não corrigir e o motivo. Isso ajuda o revisor a ver o que já foi verificado e quais decisões foram intencionais, e geralmente economiza algumas rodadas de idas e vindas.
• Mantenha a comunicação do seu PR concisa. Tudo o que um revisor lê no seu PR — a descrição, as mensagens de commit, os comentários e as respostas, os comentários de código — deve ser fácil para um humano entender. Se o seu agente redigiu o texto, não apenas dê uma olhada rápida. Leia-o e peça ao agente para revisar até que ele diga algo sensato e conciso que você mesmo escreveria. Você é o autor de tudo o que publica.
• Include in the PR description:
  • Um link de coordenação para a issue ou discussão em que um mantenedor reconheceu o trabalho.
  • Os comandos de teste que você executou e seus resultados (cole a saída relevante, não apenas “tests pass”).
  • Suas notas de autoavaliação (ou um link para o comentário da PR que as contém), conforme descrito acima.

Se você é autor de um modelo ou faz parte de uma equipe que mantém oficialmente um modelo, incentivamos o uso de agentes para a integração de um novo modelo. Siga a configuração recomendada do repositório e utilize a habilidade model-integration. Coordene o escopo com os mantenedores antes de abrir um PR — consulte Adicionando pipelines, modelos e agendadores.