Transformers documentation
Contribua para o 🤗 Transformers
Contribua para o 🤗 Transformers
Regras de contribuição
Existem duas formas de abrir um PR: corrigir uma issue que está aberta para contribuições, ou abrir um PR independente que contenha suas próprias evidências. Novos modelos também podem ser adicionados com um PR independente, veja Adicionando um novo modelo. A equipe da Hugging Face, os mantenedores e alguns contribuidores de longa data estão isentos dessas regras.
Corrigindo um problema. Vincule o problema com uma palavra-chave de fechamento, como Fixes #123, na descrição do PR. Você pode trabalhar em:
- uma issue que você abriu, assim que um mantenedor a rotular como
triaged - uma issue com a etiqueta
contributions-welcome - uma issue com a etiqueta
New model, consulte Adicionando um novo modelo
Problemas de outras pessoas não estão abertos para PRs, a menos que um mantenedor tenha dito o contrário. PRs que vinculam um problema no qual você não pode trabalhar serão fechados.
Você não precisa pedir permissão antes de trabalhar em uma issue que atenda aos critérios, e não atribuímos issues a pessoas. Comentários como “posso trabalhar nisso?” ou “por favor, atribua isso a mim” apenas adicionam ruído, então pule-os e abra seu PR. O primeiro PR para uma issue tem prioridade.
Antes de trabalhar em uma issue de contributions-welcome ou New model, verifique se alguém já abriu um PR para ela. Se sim, não abra outro. Se você notar erros, deixe sugestões no PR existente. Abra um PR concorrente apenas se o existente for fundamentalmente defeituoso ou obsoleto: seu autor não respondeu a comentários de revisão ou não enviou alterações há duas semanas. Um PR que está aguardando revisão de um mantenedor não é obsoleto. De qualquer forma, explique o motivo na issue antes de abrir o seu.
PRs independentes. Se ninguém ainda reportou o problema, você pode abrir um PR sem um issue. PRs independentes são para mudanças curtas com impacto real, como a correção de um bug, uma melhoria de desempenho ou a correção de um exemplo quebrado na documentação. A descrição do PR precisa das mesmas evidências que um issue:
- para um bug, um script curto que falha no
maine passa com sua correção, usando um checkpoint publicado, uma configuração padrão ou um fluxo de trabalho documentado - para uma melhoria de desempenho, números antes e depois em uma carga de trabalho realista, como um checkpoint publicado ou uma configuração padrão, e o hardware em que você executou. Um microbenchmark mais rápido de uma função que não está em um caminho crítico não conta.
Se já existir uma issue para o problema, seu PR passa por essa issue, independentemente de você vinculá-la ou não. PRs isolados que corrigem uma issue existente, ou que vêm sem evidências, serão fechados. Esses requisitos não se aplicam a novos modelos.
Alterações que exigem uma issue antes. Limpezas mecânicas que não afetam a correção ou o desempenho, e correções em massa de erros de digitação ou de redação na documentação, exigem uma issue antes de um PR. Proponha a alteração, como você a faria e quantos arquivos ela afeta. Uma única correção de erro de digitação é pequena demais para um PR em qualquer um dos caminhos.
Revisando PRs de outras pessoas. Revisões da comunidade são bem-vindas quando nos informam algo novo, mas os mantenedores leem todos os comentários em um PR e já executamos nossas próprias ferramentas de revisão. Antes de comentar em um PR que você não abriu, certifique-se de ter algo específico a dizer:
- Se você encontrou um problema ou tem uma mudança concreta para propor, deixe um comentário inline nas linhas relevantes, idealmente como uma sugestão do GitHub que o autor pode aplicar diretamente. Um reprodutor ajuda se você estiver relatando um bug.
- Se você reportou o problema que o PR corrige, uma breve nota indicando se ele resolve o seu caso é muito útil.
- Por favor, não publique resumos gerais ou relatórios do tipo “testei isso e funciona”. Aprovações de pessoas que não são mantenedoras não afetam se um PR será mesclado, e um comentário longo que apenas repete o conteúdo do PR nos custa tempo sem alterar o resultado.
A forma como você escreve seu código fica a seu critério, mas você é responsável por tudo o que submete, e podemos bloquear contas que abrirem repetidamente issues ou PRs de baixa qualidade. Por favor, respeite também nosso código de conduta.
What we look for in issues and PRs
- Diagnóstico claro de bugs. Soluções rápidas frequentemente causam inchaço no código ou incompatibilidades com outros modelos. Dedicar tempo para rastrear a causa exata de um problema, e em particular localizar o primeiro commit em que ele apareceu (por exemplo, com git bisect), é valioso.
- Minimize o diff. Verifique seu PR para eliminar qualquer alteração desnecessária. Certifique-se de que você não commitou nenhum script de teste ou arquivos não relacionados. Adicione comentários apenas se forem realmente necessários. Se seu PR puder ser uma correção de 1 linha, faça-o uma correção de 1 linha. Isso torna o PR muito mais fácil de revisar e melhora as chances de que ele seja aceito.
- Tome o tempo necessário para reproduzir o problema. Muito frequentemente, quando um usuário relata um problema, a causa real está em questões de ambiente na máquina dele, ou ele faz um diagnóstico incorreto do problema e sugere uma solução inválida. Confiar demais no relatório leva a soluções ruins, às vezes para problemas que nem existem! Escrever um script simples de reprodução e executá-lo para ter certeza de que você vê o problema é valioso.
- Compare com outros modelos. O repositório do Transformers é muito grande e muitos modelos fazem coisas semelhantes. Ao corrigir um bug, é valioso verificar se o bug existe em outros modelos. Se a sua PR disser “corrigido usando a mesma abordagem que (outro modelo)”, com um link para o código relevante, isso é muito útil para os mantenedores, pois nos informa que a correção provavelmente está correta e é compatível com o restante da base de código.
- Evite PRs de “trabalho inútil”. Não temos tempo para pequenas mudanças de estilo ou correções de erros de digitação em comentários, e não aceitamos correções para “bugs teóricos” encontrados por análise de código que raramente, ou nunca, causam problemas na prática, a menos que possam ser explorados por um atacante.
- Verifique os testes localmente e no CI. Antes de abrir um PR, execute
make fix-repoe useutils/tests_fetcher.pypara ver a lista de testes que cobrem os arquivos que você alterou no branch do seu PR. Execute esses testes localmente e certifique-se de que eles passam antes de abrir o PR. Depois de abrir o PR, verifique se o CI está verde e corrija quaisquer problemas antes de chamar alguém para revisão! Isso reduz muito o spam de notificações, o que mantém os mantenedores sãos.
Configuração
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.
git clone git@github.com:<your Github handle>/transformers.git cd transformersAdicione o repositório Transformers como um remote chamado
upstream.originaponta para o seu fork eupstreamaponta para a fonte da verdade. Isso permite sincronizar seumainlocal antes de fazer push paraorigine abrir um PR.git remote add upstream https://github.com/huggingface/transformers.git git remote -v # origin git@github.com:<your Github handle>/transformers.git (fetch) # origin git@github.com:<your Github handle>/transformers.git (push) # upstream https://github.com/huggingface/transformers.git (fetch) # upstream https://github.com/huggingface/transformers.git (push)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.
git checkout main && git pull upstream main && git push origin main git switch -c a-descriptive-name-for-my-branch
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.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.
- Baixar MSYS2 (assumimos que ele está instalado em
C:\msys64). - Abra a linha de comando
C:\msys64\msys2.exe(ela deve estar disponível no menu Iniciar). - Execute no shell:
pacman -Syue instalemakecompacman -S make. - 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 issue e verifique se o problema não foi reportado anteriormente (use a barra de pesquisa do GitHub em Issues). Um relatório de bug deve ser sobre um bug no Transformers, não no seu próprio código, e deve afetar o uso real e checkpoints reais; um “bug teórico” encontrado ao ler o código que requer uma configuração muito não padrão para ser acionado não será triado, a menos que seja uma questão de segurança. Inclua um script curto e autossuficiente que reproduz o bug na versão mais recente ou no main, usando um checkpoint publicado ou a configuração padrão. Relatórios de bug sem um reprodutor executável não serão triados.
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.
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.
- Adicionar um modelo com Transformers modulares — implemente o modelo usando o arquivo modular e gere os arquivos de modelagem independentes.
- Gerar docstrings automaticamente — use o decorador
@auto_docstringpara gerar docstrings consistentes sem código repetitivo. - 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.
- 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.
Contribuintes externos podem abrir um PR para um novo modelo diretamente, com ou sem uma issue. Antes de começar, verifique as issues abertas de “New model” e os PRs abertos para garantir que ninguém já esteja adicionando-o. Faremos a revisão e orientaremos você 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
Para a referência de API gerada a partir dos arquivos de origem, use o decorador @auto_docstring quando aplicável. Consulte o README da documentação para mais detalhes sobre como editar a documentação e a sintaxe que utilizamos.