# Verificações de pull request Quando você abre um pull request, o CI do Hugging Face executa várias verificações que precisam ser aprovadas antes que seu PR possa ser mesclado. - [Corrigindo o CI](#fixing-the-ci) lista os comandos a serem executados localmente para passar nas verificações. - As seções seguintes descrevem o que cada verificação valida, como [qualidade do código](#code-quality) e [consistência do repositório](#repository-consistency). - [Testes](#tests) descrevem quais testes são executados, as categorias de testes e os testes lentos. ## Corrigindo o CI Na maioria dos casos, `make style` é suficiente para passar na verificação de qualidade do código, que é a falha mais comum. ```bash make style ``` Para falhas na consistência do repositório, cópias ou arquivos gerados automaticamente, execute `make fix-repo`. Ele corrige o estilo, as cópias, os docstrings e os arquivos gerados automaticamente em uma única passagem. ```bash make fix-repo ``` Para uma alteração maior, a sequência de três comandos abaixo cobre todas as verificações. É mais pesado, mas detecta tudo antes de você fazer o push. ```bash make fix-repo # auto-fix everything that can be auto-fixed make typing # check types and model structure, fix any errors manually make check-repo # verify all checks pass, fix anything that remains ``` `make typing` detecta erros de tipo e violações na estrutura do modelo que você corrige manualmente. `make check-repo` faz uma verificação final somente de leitura para que você possa confirmar que tudo está pronto. > [!NOTE] > O CI é ocasionalmente instável. Se uma verificação falhar por algo não relacionado à sua alteração, solicite a um mantenedor que a reexecute. ## Qualidade do código A verificação de qualidade do código abrange formatação, imports, verificação de tipos e regras de estrutura do modelo. Ela corresponde a `make fix-repo` e `make typing`. `make style` (incluído em `make fix-repo`) corrige automaticamente a linting e a formatação do [Ruff](https://docs.astral.sh/ruff/), a ordem de importação em `__init__.py` e a consistência do mapeamento automático. `make typing` executa a verificação de tipos com [ty](https://docs.astral.sh/ty/) e valida as regras TRansFormers (TRF), que abrangem as convenções de nomenclatura das classes de configuração e as assinaturas de `forward()`. Erros de tipo e violações de TRF relatam um número de regra específico e devem ser corrigidos manualmente. As regras estão no repositório [mlinter](https://github.com/huggingface/transformers-mlinter). Execute `python -m utils.mlinter --list-rules` para ver todas as regras TRF, ou `python -m utils.mlinter --rule TRFXXX` para visualizar a documentação completa de uma regra específica. Se uma regra do TRF precisar de uma exceção, escolha uma das seguintes opções (veja [Suprimindo violações](./modeling_rules#suppressing-violations) para mais detalhes). - Adicione o nome do seu modelo à lista `allowlist_models` da regra correspondente em `utils/mlinter/rules.toml`. Use isso quando o arquivo inteiro do modelo precisar de uma exceção. - Adicione `# trf-ignore: TRFXXX` na mesma linha da construção sinalizada ou na linha imediatamente acima dela. Use isso quando apenas uma construção sinalizada precisar de uma exceção. ## Consistência do repositório A verificação de consistência do repositório é semelhante ao `make check-repo`, com a exceção de que ela interrompe o processo na primeira falha. Ela mantém o repositório internamente consistente entre as categorias abaixo: objetos públicos permanecem importáveis, o código copiado permanece sincronizado com sua origem e os arquivos gerados automaticamente (dummies, doctests, metadados) refletem o estado atual do código. Para novos modelos, ela também verifica se cada nova classe de modelo está registrada nos mapeamentos automáticos. | Categoria | O que ele valida | Corrigido automaticamente? | |---|---|---| | Arquivos de inicialização | Os arquivos `__init__.py` em `src/transformers/models/` estão atualizados | `make fix-repo` | | Cópias e modulares | `# Copied from` os blocos correspondem à sua origem e os arquivos gerados de forma modular estão atualizados | `make fix-repo` | | Docstrings e documentação | As docstrings dos argumentos correspondem às assinaturas das funções e ao sumário da documentação | `make fix-repo` | | Arquivos gerados automaticamente | Dummies, tipagem de pipeline, lista de doctest, metadados, tabela de dependências | `make fix-repo` | | Validação de configuração | As classes de Config possuem checkpoints válidos em docstrings e os atributos de config correspondem ao arquivo de modelagem | Manual | | Atribuição de revisores | Cada diretório de modelo e cada regra no arquivo do revisor ainda atinge um revisor | Manual | ## Atribuição de revisores Quando uma pull request é marcada como pronta para revisão, o workflow `Assign PR Reviewers` solicita até dois revisores, ranqueados pelo número de linhas que a pull request altera nos arquivos dos quais eles são responsáveis. Uma pull request em rascunho não recebe revisores até sair do modo rascunho. O próprio workflow está em [huggingface/transformers-ci](https://github.com/huggingface/transformers-ci) e este repositório o chama; o que permanece aqui são os dados de propriedade que ele lê. A propriedade é resolvida por arquivo, priorizando o mais específico. | Onde | Parece | Use-o para | |---|---|---| | O arquivo do modelo | `# Reviewers: @login` no bloco de comentário inicial de `modular_.py` ou `modeling_.py` | um modelo que precisa de alguém diferente do proprietário da sua modalidade. O conversor modular copia o cabeçalho para o arquivo de modelagem gerado, de modo que a tag sobrevive à regeneração | | Uma regra de caminho | `/src/transformers// @login` em `.github/scripts/codeowners_for_review_action` | qualquer coisa que não seja um modelo | | A tabela de modalidades | `@@modality/vision @login`, no mesmo arquivo | todo modelo cuja página de documentação está localizada naquela seção de `docs/source/en/_toctree.yml` | | O genérico | `* @Rocketknight1 @ArthurZucker` | qualquer outra coisa | Um novo modelo não precisa de nenhuma entrada em lugar nenhum: adicionar sua página de documentação ao `_toctree.yml`, o que a verificação da tabela de conteúdo da documentação já exige, o coloca em uma modalidade, e a tabela da modalidade o cobre a partir daí. Uma revisão só pode ser solicitada a um colaborador do repositório. O workflow solicita cada revisor em uma chamada separada e ignora qualquer pessoa à qual não pode pedir, de modo que uma entrada que nomeia alguém que saiu custa um revisor em vez de todos, e cada ignorância é relatada como um aviso na execução do workflow. Um pull request não pode redirecionar sua própria revisão. `.github/scripts/codeowners_for_review_action` é lido do branch base, nunca do head do pull request, e o gate de segurança do CI do PR bloqueia um pull request que não é de um colaborador de tocar em qualquer coisa fora de `src/`, `tests/`, `docs/` e `utils/` — é por isso que esse arquivo está onde está. A tag `# Reviewers:` é lida do head, já que um novo modelo chega com ela, então cada login que ela nomeia ainda passa pela verificação de colaborador antes de alguém ser solicitado. `make check-repository-consistency` executa `utils/check_reviewers.py`, que falha quando um modelo não é atribuído a ninguém além do revisor genérico, quando uma regra não corresponde mais a nenhum arquivo ou quando a tabela de modalidades diverge da tabela de conteúdo. Ele compartilha seu resolutor com o fluxo de trabalho de atribuição, de modo que os dois não podem divergir. Esse resolutor não é uma dependência de `transformers`; ele está listado em `utils/checkers-requirements.txt`, que o executor do verificador instala na primeira execução em um ambiente. Se a instalação não puder ocorrer — por exemplo, offline —, o verificador relata isso e passa, em vez de bloquear você. Caminhos fora de `src/transformers/models` que não possuem um responsável são relatados como uma observação; liste-os com: ```bash python utils/check_reviewers.py --strict ``` ## Testes O CI executa um subconjunto direcionado de testes com base nas alterações do seu PR. O CI executa os testes em uma ordem levemente randomizada com [pytest-random-order](https://github.com/jbasko/pytest-random-order) para capturar testes acoplados. A execução imprime a semente aleatória no início, para que você possa reproduzir a mesma ordem com `--random-order-seed=`. Se um teste passa localmente na GPU, mas falha no CI, defina `TRANSFORMERS_TEST_DEVICE="cpu"` para verificar se é possível reproduzir a falha na CPU. ```bash TRANSFORMERS_TEST_DEVICE="cpu" pytest tests/models/my_model/ -v ``` As seções abaixo explicam como funciona a seleção de testes, quais jobs são executados e como lidar com testes lentos. ### Seleção de testes O CI não executa a suíte de testes completa em cada PR. O CI ignora os testes decorados com `@slow` em cada PR, e um mantenedor os executa em GPU quando o PR está em revisão. `utils/tests_fetcher.py` rastreia as dependências de importação dos seus arquivos alterados para identificar os testes afetados e executa apenas esses. Ele também detecta regressões em outros modelos quando você modifica utilitários compartilhados. O fetcher exibe quais arquivos foram alterados e quais testes são impactados, e em seguida grava a lista em `tests_torch_test_list.txt`. Use o fetcher para replicar exatamente o que o CI executa. ```bash python utils/tests_fetcher.py python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_preparation/tests_torch_test_list.txt) ``` > [!TIP] > Alterar arquivos principais, como `modeling_utils.py` ou `generation/utils.py`, aciona todos os testes de modelo, não apenas o subconjunto afetado. Você também pode executar todos os testes do seu modelo incondicionalmente. Uma execução direta é uma verificação local de sanidade mais rápida, mas não detectará regressões em outros modelos causadas por código compartilhado que você modificou. ```bash pytest tests/models/my_model/ -v ``` ### Categorias de trabalho de teste Os testes são divididos entre jobs de CI paralelos, e cada job seleciona arquivos por padrão de caminho. Os jobs relevantes para um PR de modelo são: - `tests_torch`: testes de modelagem (`tests/models/*/test_modeling_*.py`) - `tests_tokenization`: testes de tokenizer (`tests/models/*/test_tokenization_*.py`) - `tests_processors`: testes de processador e extrator de recursos (`tests/models/*/test_(processing|image_processing|feature_extractor)_*.py`) - `tests_generate`: testes de geração - `pipelines_torch`: testes de pipeline - `tests_training_ci`: testes do loop de treinamento - `tests_tensor_parallel_ci`: testes de paralelismo de tensor - `tests_fsdp_ci`: testes de FSDP ### Testes lentos As execuções regulares de CI ignoram os testes decorados com `@slow`. Eles baixam checkpoints reais ou exigem computação significativa, portanto, são executados em instâncias de GPU e os mantenedores os acionam quando sua PR está em revisão. Os testes lentos são executados em uma NVIDIA A10, e os resultados numéricos podem variar ligeiramente entre o hardware de CI e sua máquina local. Os mantenedores geralmente ajustam esses valores nos testes, se necessário, ao adicionar um novo modelo. Execute os testes lentos localmente com o comando abaixo. ```bash RUN_SLOW=1 python -m pytest tests/models/my_model/ -v ``` ### Compilação da documentação O job `build_pr_documentation` compila e gera uma pré-visualização da documentação. Um bot publica um link de pré-visualização na sua PR, e a verificação deve ser aprovada antes do merge. A maioria das falhas é causada por uma entrada ausente no `toctree`. Para compilar a documentação localmente, consulte o [README.md](https://github.com/huggingface/transformers/tree/main/docs) na pasta docs. ## Sintaxe `# Copied from` > [!WARNING] > Para novos modelos, prefira sempre o [fluxo de trabalho modular](modular_transformers) (`modular_*.py`) em vez de `# Copied from`. Evite `# Copied from` sempre que possível. O mecanismo `# Copied from` mantém o código copiado sincronizado com a sua origem. Quando `make fix-repo` é executado, ele verifica cada bloco `# Copied from` e o atualiza para corresponder ao original, de modo que as edições feitas dentro de um bloco `# Copied from` são sobrescritas. Edite a origem e deixe que o `make fix-repo` propague a alteração. As formas básicas de `# Copied from` incluem as seguintes. ```py # Copied from transformers.models.bert.modeling_bert.BertSelfOutput # Copied from transformers.models.bert.modeling_bert.BertAttention with Bert->Roberta # Copied from transformers.models.bert.modeling_bert.BertForSequenceClassification with Bert->MobileBert all-casing ``` A sintaxe `with model->newModel` aplica substituições de strings após a cópia. Separe múltiplas substituições com vírgulas, que são aplicadas da esquerda para a direita. A opção `all-casing` substitui todas as variantes de caixa de uma só vez (`Bert`, `bert`, `BERT` se tornam `MobileBert`, `mobilebert`, `MOBILEBERT`).