Contribua para o 🤗 Transformers

O repositório do Transformers está sendo sobrecarregado por um grande número de PRs e comentários em issues escritos por agentes de código. Atualmente, estamos limitados pela nossa capacidade de revisar e responder a eles. Como resultado, pedimos que contribuidores de primeira viagem não usem agentes de código para criar issues ou PRs neste momento. Também pedimos que agentes autônomos não abram PRs ou issues por enquanto.

PRs que parecerem ter sido escritos por agentes provavelmente serão fechados sem revisão, e podemos bloquear usuários que fizerem isso repetidamente ou de forma maliciosa.

O Transformers aceita todas as contribuições, seja corrigindo bugs, enviando solicitações de recursos, implementando novos modelos ou melhorando a documentação.

Se você não tiver certeza por onde começar, dê uma olhada nos Good First Issues para ver problemas mais adequados a iniciantes. Para um problema mais desafiador, confira os Good Second Issues. Independentemente de como você decidir contribuir, por favor, tenha atenção e respeite nosso code of conduct.

Se você gostou de usar o Transformers, sinta-se à vontade para citá-lo e nos contar como você está usando, nos marcar no Twitter ou dar uma estrela ao repositório!

Este guia foi fortemente inspirado no guia de contribuição do scikit-learn.

Conteúdos

1. Configuração
   • Windows
2. Abrindo problemas
   • Problema relacionado a um bug
   • Solicitação de recurso
3. Adicionando um novo modelo
   • Timeline de adição de modelos
4. Documentação
5. Contribuições agênticas

Configuração

1. Faça um fork do Transformers com o botão Fork no GitHub para obter uma cópia na sua conta e, em seguida, clone-o localmente.

   Copiado

   git clone git@github.com:<your Github handle>/transformers.git
   cd transformers

2. Adicione o repositório Transformers como um remote chamado upstream. origin aponta para o seu fork e upstream aponta para a fonte da verdade. Isso permite sincronizar seu main local antes de fazer push para origin e abrir um PR.

   Copiado

   git remote add upstream https://github.com/huggingface/transformers.git
   git remote -v
   # origin    git@github.com:<your Github handle>/transformers.git (fetch)
   # origin    git@github.com:<your Github handle>/transformers.git (push)
   # upstream  https://github.com/huggingface/transformers.git (fetch)
   # upstream  https://github.com/huggingface/transformers.git (push)

3. Mantenha seu fork atualizado e crie um branch para trabalhar. Você também pode sincronizar seu fork pela interface do GitHub com o botão Sync fork.

   Copiado

   git checkout main && git pull upstream main && git push origin main
   git switch -c a-descriptive-name-for-my-branch

4. Instale a biblioteca em modo editável. Use [dev] para a maioria das contribuições, pois inclui as ferramentas de desenvolvimento necessárias para verificações de estilo e qualidade. Use [torch,testing] para contribuições de modelos, ou [quality] para alterações apenas na documentação e correções pequenas quando o conjunto completo de dependências de desenvolvimento não for necessário.

   Copiado

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

Windows

No Windows, a menos que você esteja usando WSL, configure o git para converter as quebras de linha CRLF em LF.

git config core.autocrlf input

Uma forma de executar o comando make no Windows é com o MSYS2.

1. Baixar MSYS2 (assumimos que ele está instalado em C:\msys64).
2. Abra a linha de comando C:\msys64\msys2.exe (ela deve estar disponível no menu Iniciar).
3. Execute no shell: pacman -Syu e instale make com pacman -S make.
4. Adicione C:\msys64\usr\bin à variável de ambiente PATH.

Agora você pode usar make em qualquer terminal (PowerShell, cmd.exe, etc.).

Abrindo problemas

Use os modelos de problema para começar.

Problema relacionado a um bug

Certifique-se de que o bug não foi reportado anteriormente antes de abrir uma issue (use a barra de pesquisa no GitHub, em Issues). A issue deve ser um bug no Transformers, e não no seu próprio código.

Se você não tiver certeza de que o bug está no seu código ou na biblioteca, pergunte primeiro no fórum ou no Discord. Isso ajuda a manter o GitHub focado em problemas acionáveis da biblioteca.

Inclua o seguinte para que possamos resolvê-lo rapidamente.

• O seu tipo e versão do sistema operacional e as versões do Python e do PyTorch, quando aplicável.
• Um trecho de código curto e autossuficiente que nos permite reproduzir o bug.
• O traceback completo caso uma exceção seja lançada.
• Qualquer outra informação, como capturas de tela, que possa ajudar.

Para obter as versões do sistema operacional e do software automaticamente, execute o seguinte comando.

transformers env

Solicitação de recurso

Abra uma issue e descreva:

• A motivação, como uma frustração com a biblioteca, uma necessidade de projeto ou um trabalho que você realizou e que pode beneficiar a comunidade.
• A funcionalidade com o máximo de detalhes possível.
• Um trecho de código demonstrando o uso do recurso.
• Um link para o artigo relevante, se aplicável.

Adicionando um novo modelo

Adicionar um modelo ao Transformers torna-o disponível para qualquer pessoa carregar e fazer fine-tuning ou executar inferência. Antes de iniciar a implementação, isole as diferenças entre a sua arquitetura e os modelos de estado da arte recentes que já estão no Transformers. Explique essas diferenças na issue ou no PR para que os revisores possam entender rapidamente quais desafios o modelo traz, quais partes podem reutilizar padrões existentes e o que deve ser padronizado entre os modelos.

Siga os guias abaixo.

1. Adicionar um modelo com Transformers modulares — implemente o modelo usando o arquivo modular e gere os arquivos de modelagem independentes.
2. Gerar docstrings automaticamente — use o decorador @auto_docstring para gerar docstrings consistentes sem código repetitivo.
3. Testes — escreva e execute testes de modelo para verificar a correção e manter a contribuição mantida. Para modelos de linguagem causal, herde do tester de LM causal sempre que possível. Priorize testes de integração, pois eles verificam o caminho completo do processador, tokenizador e modelo contra checkpoints reais.
4. Regras de estrutura do modelo — verifique se seus arquivos passam pelas regras estáticas de estrutura do modelo aplicadas por make typing.

Algumas adições de modelos exigem trabalho extra de integração.

• Adicione componentes de processamento de visão se o seu modelo exigir entradas de imagem ou vídeo.
• Carregamento dinâmico de pesos quando os nomes dos parâmetros do checkpoint publicado não correspondem à implementação do Transformers.

Linha do tempo de adição de modelos

Existem quatro prazos para a inclusão de modelos, dependendo do contribuidor do modelo e da demanda da comunidade por uma arquitetura.

• Integração no dia zero: disponibilizar o modelo no Transformers no dia do lançamento, com um novo release de versão. Fornecemos suporte para as principais funcionalidades essenciais (quantização, FlashAttention, KV-cache, etc.), revisamos rascunhos iniciais e, dependendo dos prazos, também podemos cuidar da implementação do modelo.

  Envie um e-mail para transformers@huggingface.co algumas semanas antes, especialmente no caso de arquiteturas inéditas. Iteraremos com você em um fork privado até que seu checkpoint e lançamento estejam prontos.

• Integração na mesma semana: modelos de alta demanda geralmente são integrados em até uma semana, mesmo quando o autor não entra em contato.

  Abra uma issue com o new model template para solicitar um. Issues com mais atividade sobem mais rápido na fila.

• Integração pós-lançamento: modelos sem forte demanda, ou que não temos capacidade para assumir, são lançados após a liberação upstream.

  As questões abertas com a tag “New model” são o ponto de entrada para contribuidores externos. Comece pelas arquiteturas mais solicitadas para maximizar o impacto. Faremos a revisão e o guiaremos durante o processo.

• Lançamento com foco no Hub: publique seu modelo diretamente no Hub por meio do suporte a remote-code do Transformers, sem a necessidade de um PR upstream.

  Modelos populares com abordagem Hub-first geralmente são integrados ao Transformers posteriormente, o que habilita documentação de primeira classe, manutenção e otimização. A abordagem Hub-first é a forma de menor atrito para adicionar um modelo. No entanto, ela pode ser mais frágil se o modelo exigir conversão de pesos ou outros problemas de compatibilidade reversa.

Docs

Melhorias na documentação, como erros de digitação, conteúdo ausente ou explicações pouco claras, são sempre bem-vindas. Para a referência da API gerada a partir dos arquivos de origem, use o decorador @auto_docstring quando aplicável. Abra uma pull request diretamente para correções significativas na documentação.

Consulte o README da documentação para mais detalhes sobre como editar a documentação e a sintaxe que utilizamos.

Contribuições agênticas

Contribuições assistidas por IA são bem-vindas. Elas devem ser coordenadas, delimitadas e verificadas para manter a carga de revisão gerenciável.

• Não envie PRs de “agente puro”. O submissor humano é responsável por revisar todas as linhas alteradas, validar o comportamento de ponta a ponta e executar os testes relevantes.
• Se ferramentas de IA foram utilizadas, declare isso na descrição do PR e inclua: link de coordenação, diferenciação em relação a PRs existentes (se aplicável) e comandos/resultados de teste.
• Evite PRs de “trabalho burocrático” pontuais (um único erro de digitação, uma limpeza de estilo isolada, a correção de um único valor padrão mutável, etc.). Agrupe as limpezas mecânicas em um escopo claro e sistemático.
• Coordene as questões antes de abrir um PR, revise PRs semelhantes e aguarde a aprovação.

Esses tópicos são descritos para agentes em AGENTS.md, com instruções sobre como implementá-los de forma autônoma.