# Contribua para o 🤗 Transformers > [!WARNING] > O repositório do Transformers está sendo sobrecarregado por um grande número de PRs e comentários em issues criados por agentes de código. Atualmente, estamos limitados pela nossa capacidade de revisar e responder a eles. Como resultado, **pedimos que contribuidores de primeira vez 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. Nossa filosofia de agente de código em detalhes Entendemos que agentes de código são ferramentas extremamente poderosas, e muitas pessoas na Hugging Face os utilizam em seu trabalho. No entanto, é importante perceber que **se você simplesmente executa um agente de código e gera um PR para um projeto de código aberto, você é apenas um intermediário entre os revisores e o agente**. Embora fazer isso crie algo que parece muito com uma contribuição útil, na realidade não havia motivo para você estar envolvido; os revisores poderiam simplesmente ter executado o agente de código por conta própria. Se você deseja contribuir de forma útil para o código aberto na era dos agentes, **você precisa fazer coisas que os agentes não conseguem fazer sozinhos**. Em particular, descobrimos que o seguinte é muito útil: - Diagnóstico claro de bugs. Agentes de código tendem a corrigir problemas rapidamente com um workaround, o que frequentemente causa 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](https://git-scm.com/docs/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; agentes de código adoram adicionar três novas funções e comentários de várias linhas para chamar a atenção para todo o trabalho duro que realizaram. Se o seu PR puder ser uma correção de 1 linha, faça-o de 1 linha. Isso torna o PR muito mais fácil de revisar e melhora as chances de ele ser aceito. - Tome o tempo necessário para reproduzir o problema. Muito frequentemente, quando um usuário relata um problema, a causa real é problemas de ambiente em sua máquina, ou eles diagnosticam incorretamente o problema e sugerem uma solução inválida. Muitos agentes de código confiam demais nos comentários do usuário, o que resulta em 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ê está vendo o problema é valioso. - Compare com outros modelos. O repositório do Transformers é muito grande e muitos modelos fazem coisas semelhantes. Quando Ao corrigir um bug, é valioso verificar se o bug existe em outros modelos. Se a sua PR disser "corrigido usando a mesma abordagem de (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. Agentes de código frequentemente analisam o código de forma "estreita" e fazem uma correção que faz com que os modelos diverjam do restante da base de código. - Evite PRs pequenos ou de "trabalho burocrático". No passado, costumávamos aceitá-los, mas, diante do volume atual, simplesmente não os tem tempo para pequenas mudanças de estilo ou correções de erros de digitação em comentários. Você pode agregar valor além do que um agente de código oferece, simplesmente tendo bom senso sobre o que é realmente importante. Agentes de código frequentemente se concentram em "bugs teóricos" encontrados pela análise de código, que raramente, ou nunca, causam problemas na prática. Em geral, não vale a pena corrigi-los, a menos que possam ser explorados por um atacante. - Verifique os testes localmente e no CI. Antes de abrir um PR, execute `make fix-repo` e use `utils/tests_fetcher.py` para veja uma 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 um PR. Após abrir o seu PR, verifique se o CI está verde e corrija quaisquer problemas antes de solicitar a revisão a alguém! Isso reduz muito o spam de notificações, o que mantém os mantenedores sãos. 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 tem certeza por onde começar, dê uma olhada nos [Good First Issues](https://github.com/huggingface/transformers/labels/Good%20First%20Issue) para ver problemas mais acessíveis para iniciantes. Para um problema mais desafiador, confira os [Good Second Issues](https://github.com/huggingface/transformers/labels/Good%20Second%20Issue). Independentemente de como você escolher contribuir, por favor, tenha atenção e respeite nosso [code of conduct](https://github.com/huggingface/transformers/blob/main/CODE_OF_CONDUCT.md). 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](https://github.com/scikit-learn/scikit-learn/blob/main/CONTRIBUTING.md). ## Conteúdos 1. [Configuração](#set-up) - [Windows](#windows) 2. [Abertura de problemas](#opening-issues) - [Problema relacionado a um bug](#bug-related-issue) - [Solicitação de recurso](#feature-request) 3. [Adicionando um novo modelo](#adding-a-new-model) - [Timeline de adição de modelos](#model-addition-timeline) 4. [Documentação](#docs) 5. [Contribuições agênticas](#agentic-contributions) ## Configuração 1. Faça um fork do [Transformers](https://github.com/huggingface/transformers) com o botão **Fork** no GitHub para obter uma cópia na sua conta e, em seguida, clone-o localmente. ```bash git clone git@github.com:/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. ```bash git remote add upstream https://github.com/huggingface/transformers.git git remote -v # origin git@github.com:/transformers.git (fetch) # origin git@github.com:/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**. ```bash 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. ```bash 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](https://learn.microsoft.com/en-us/windows/wsl/), configure o git para converter as quebras de linha `CRLF` em `LF`. ```bash git config core.autocrlf input ``` Uma forma de executar o comando `make` no Windows é com o MSYS2. 1. [Baixe o MSYS2](https://www.msys2.org/) (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](https://github.com/huggingface/transformers/tree/main/.github/ISSUE_TEMPLATE) 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](https://discuss.huggingface.co/) ou no [Discord](https://discord.com/invite/hugging-face-879548962464493619). 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. ```bash 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](https://github.com/huggingface/transformers/blob/main/docs/source/en/modular_transformers.md) — implemente o modelo usando o arquivo modular e gere os arquivos de modelagem independentes. 2. [Gerar docstrings automaticamente](https://github.com/huggingface/transformers/blob/main/docs/source/en/auto_docstring.md) — use o decorador `@auto_docstring` para gerar docstrings consistentes sem código repetitivo. 3. [Testes](https://github.com/huggingface/transformers/blob/main/docs/source/en/testing.md) — 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](https://github.com/huggingface/transformers/blob/main/docs/source/en/modeling_rules.md) — 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](https://github.com/huggingface/transformers/blob/main/docs/source/en/add_vision_processing_components.md) se o seu modelo exigir entradas de imagem ou vídeo. - [Carregamento dinâmico de pesos](https://github.com/huggingface/transformers/blob/main/docs/source/en/weightconverter.md) 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 seu 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](https://github.com/huggingface/transformers/issues/new?assignees=&labels=New+model&projects=&template=new-model-addition.yml) 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"](https://github.com/huggingface/transformers/issues?q=is%3Aopen+is%3Aissue+label%3A%22New+model%22) são o ponto de entrada para contribuidores externos. Comece pelas arquiteturas mais solicitadas para maximizar o impacto. 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](https://github.com/huggingface/transformers/blob/main/docs/source/en/models.md#custom-models) 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`](https://github.com/huggingface/transformers/blob/main/docs/source/en/auto_docstring.md) quando aplicável. Abra uma pull request diretamente para correções significativas na documentação. Consulte o [README](https://github.com/huggingface/transformers/blob/main/docs/README.md) 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. > [!NOTE] > Esses tópicos são descritos para agentes em `AGENTS.md`, com instruções sobre como implementá-los de forma autônoma.