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 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 e consistência do repositório.
• Testes 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.

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.

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.

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.

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, 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 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. 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 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.

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 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.

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.

Uma pull request não pode redirecionar a própria revisão. .github/scripts/codeowners_for_review_action é lido da branch base, nunca do head da pull request, e o gate de segurança do CI da PR bloqueia uma 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:

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 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=<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.

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.

python utils/tests_fetcher.py
python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_preparation/tests_torch_test_list.txt)

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.

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.

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 na pasta docs.

# Copiado da sintaxe

Para novos modelos, prefira sempre o fluxo de trabalho modular (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.

# 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).