Transformers documentation
Comprobaciones de la solicitud de extracción
Comprobaciones de la solicitud de extracción
Cuando abres una pull request, el CI de Hugging Face ejecuta varias comprobaciones que deben superarse antes de que tu PR pueda fusionarse.
- Corregir la CI enumera los comandos que se deben ejecutar localmente para superar las comprobaciones.
- Las secciones posteriores describen lo que valida cada comprobación, como la calidad del código y la coherencia del repositorio.
- Tests describe qué pruebas se ejecutan, las categorías de pruebas y las pruebas lentas.
Corregir la CI
En la mayoría de los casos, make style es suficiente para superar la comprobación de calidad del código, que es el fallo más común.
make style
Para fallos en la consistencia del repositorio, las copias o los archivos generados automáticamente, ejecuta make fix-repo. Corrige el estilo, las copias, las docstrings y los archivos generados automáticamente en una sola pasada.
make fix-repo
Para un cambio más extenso, la secuencia de tres comandos siguiente cubre todas las comprobaciones. Es más pesada, pero detecta todo antes de que hagas 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 remainsmake typing detecta errores de tipos y violaciones de la estructura del modelo que debes corregir manualmente. make check-repo realiza una pasada final de solo lectura para que puedas confirmar que todo está listo.
La CI es ocasionalmente inestable. Si una comprobación falla por algo no relacionado con tu cambio, avisa a un mantenedor para que la vuelva a ejecutar.
Calidad del código
La comprobación de calidad del código abarca el formato, las importaciones, la comprobación de tipos y las reglas de estructura del modelo. Corresponde a make fix-repo y make typing.
make style (incluido en make fix-repo) corrige automáticamente el linting y el formato de Ruff, el orden de importación de __init__.py y la coherencia del auto-mapeo.
make typing realiza la comprobación de tipos con ty y valida las reglas de TRansFormers (TRF), que abarcan las convenciones de nomenclatura de las clases de configuración y las firmas de forward(). Los errores de tipo y las violaciones de TRF informan de un número de regla específico y deben corregirse manualmente. Las reglas se encuentran en el repositorio mlinter. Ejecuta python -m utils.mlinter --list-rules para ver todas las reglas TRF, o python -m utils.mlinter --rule TRFXXX para consultar la documentación completa de una regla específica.
Si una regla de TRF necesita una excepción, elige una de estas opciones (consulta Suprimir violaciones para más detalles).
- Añade el nombre de tu modelo a la lista
allowlist_modelsde la regla correspondiente enutils/mlinter/rules.toml. Utiliza esto cuando el archivo completo del modelo necesite una excepción. - Agrega
# trf-ignore: TRFXXXen la misma línea que la construcción marcada, o en la línea inmediatamente superior. Utiliza esto cuando solo una construcción marcada necesite una excepción.
Consistencia del repositorio
La comprobación de consistencia del repositorio es similar a make check-repo, con la salvedad de que se detiene ante el primer fallo. Mantiene el repositorio internamente coherente en las siguientes categorías: los objetos públicos siguen siendo importables, el código copiado se mantiene sincronizado con su origen y los archivos generados automáticamente (dummies, doctests, metadatos) reflejan el estado actual del código. Para los nuevos modelos, también verifica que cada nueva clase de modelo esté registrada en los auto-mappings.
| Categoría | Lo que valida | ¿Se corrigió automáticamente? |
|---|---|---|
| Archivos de inicialización | Los archivos __init__.py en src/transformers/models/ están actualizados | make fix-repo |
| Copias y modular | Los bloques # Copied from coinciden con su origen y los archivos generados de forma modular están actualizados | make fix-repo |
| Docstrings y documentación | Las docstrings de los argumentos coinciden con las firmas de las funciones y el índice de la documentación | make fix-repo |
| Archivos generados automáticamente | Dummies, tipado de pipeline, lista de doctest, metadatos, tabla de dependencias | make fix-repo |
| Validación de la configuración | Las clases de configuración tienen puntos de control válidos en las docstrings y los atributos de configuración coinciden con el archivo de modelado | Manual |
| Asignación de revisores | Cada directorio de modelo y cada regla en el archivo del revisor sigue llegando a un revisor | Manual |
Asignación de revisores
.github/scripts/codeowners_for_review_action registra quién revisa qué archivos.
La propiedad se resuelve por archivo, priorizando la más específica.
| Donde | Parece | Úsalo para |
|---|---|---|
| El archivo del modelo | # Reviewers: @login en el bloque de comentario inicial de modular_<model>.py o modeling_<model>.py | un modelo que requiere a alguien distinto de su propietario de modalidad. El convertidor modular copia la cabecera en el archivo de modelado generado, por lo que la etiqueta sobrevive a la regeneración |
| Una regla de ruta | /src/transformers/<area>/ @login en .github/scripts/codeowners_for_review_action | cualquier cosa que no sea un modelo |
| La tabla de modalidades | @@modality/vision @login, en el mismo archivo | cada modelo cuya página de documentación se encuentra en esa sección de docs/source/en/_toctree.yml |
| El comodín | * @Rocketknight1 @ArthurZucker | cualquiera nada más lo reclama |
Un modelo nuevo no necesita ninguna entrada en ningún lugar: añadir su página de documentación a _toctree.yml, que la comprobación del índice de contenidos de la documentación ya exige, lo sitúa en una modalidad, y la tabla de esa modalidad lo cubre a partir de ahí.
make check-repository-consistency ejecuta utils/check_reviewers.py, que falla cuando un modelo no tiene ningún revisor asignado salvo el genérico, cuando una regla ya no coincide con ningún archivo, o cuando la tabla de modalidades no coincide con el índice. Su resolutor no es una dependencia de transformers; se lista en utils/checkers-requirements.txt, que el ejecutor de comprobaciones instala en su primera ejecución en un entorno. Si la instalación no puede realizarse, por ejemplo, sin conexión, la comprobación lo informa y pasa en lugar de bloquearte.
Las rutas fuera de src/transformers/models que no tienen propietario se informan como una nota; enuméralas con:
python utils/check_reviewers.py --strict
Pruebas
CI ejecuta un subconjunto específico de pruebas en función de los cambios que introduce tu PR. CI ejecuta las pruebas en un orden ligeramente aleatorio con pytest-random-order para detectar pruebas acopladas. La ejecución imprime la semilla aleatoria al inicio para que puedas reproducir el mismo orden con --random-order-seed=<seed>.
Si una prueba pasa localmente en GPU pero falla en CI, establezca TRANSFORMERS_TEST_DEVICE="cpu" para comprobar si puede reproducir el fallo en CPU.
TRANSFORMERS_TEST_DEVICE="cpu" pytest tests/models/my_model/ -vLas secciones siguientes explican cómo funciona la selección de pruebas, qué trabajos se ejecutan y cómo manejar las pruebas lentas.
Selección de pruebas
CI no ejecuta la suite de pruebas completa en cada PR. CI omite las pruebas decoradas con @slow en cada PR, y un mantenedor las ejecuta en GPU una vez que el PR está en revisión.
utils/tests_fetcher.py rastrea las dependencias de importación de los archivos modificados para identificar las pruebas afectadas y solo ejecuta esas. También detecta regresiones en otros modelos cuando se modifican utilidades compartidas. El fetcher imprime qué archivos cambiaron y qué pruebas se ven afectadas, y luego escribe la lista en tests_torch_test_list.txt.
Use el fetcher para replicar exactamente lo que ejecuta CI.
python utils/tests_fetcher.py
python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_preparation/tests_torch_test_list.txt)Cambiar archivos principales como
modeling_utils.pyogeneration/utils.pyactiva todas las pruebas de modelos, no solo el subconjunto afectado.
También puedes ejecutar todas las pruebas de tu modelo de forma incondicional. Una ejecución directa es una comprobación de sanidad local más rápida, pero no detectará regresiones en otros modelos causadas por el código compartido que modificaste.
pytest tests/models/my_model/ -v
Categorías de tareas de prueba
Las pruebas se dividen entre trabajos de CI en paralelo, y cada trabajo selecciona archivos según un patrón de ruta. Los trabajos relevantes para una PR de un modelo son:
tests_torch: pruebas de modelado (tests/models/*/test_modeling_*.py)tests_tokenization: pruebas del tokenizador (tests/models/*/test_tokenization_*.py)tests_processors: pruebas de procesadores y extractores de características (tests/models/*/test_(processing|image_processing|feature_extractor)_*.py)tests_generate: pruebas de generaciónpipelines_torch: pruebas de pipelinetests_training_ci: pruebas del bucle de entrenamientotests_tensor_parallel_ci: pruebas de paralelismo de tensortests_fsdp_ci: pruebas de FSDP
Pruebas lentas
Las ejecuciones de CI regulares omiten las pruebas decoradas con @slow. Estas descargan puntos de control reales o requieren un cómputo significativo, por lo que se ejecutan en instancias GPU y los mantenedores las activan cuando tu PR está en revisión.
Las pruebas lentas se ejecutan en una NVIDIA A10 y los resultados numéricos pueden variar ligeramente entre el hardware de CI y tu máquina local. Los mantenedores suelen ajustar esos valores en las pruebas si es necesario al agregar un nuevo modelo.
Ejecuta las pruebas lentas localmente con el siguiente comando.
RUN_SLOW=1 python -m pytest tests/models/my_model/ -v
Compilación de la documentación
Un trabajo de build_pr_documentation compila y genera una vista previa de la documentación. Un bot publica un enlace de vista previa en tu PR y la comprobación debe aprobarse antes de fusionar. La mayoría de los fallos se deben a una entrada faltante en el toctree. Para compilar la documentación localmente, consulta el README.md en la carpeta de documentación.
# Copiado de syntax
Para los nuevos modelos, prefiere siempre el flujo de trabajo modular (
modular_*.py) frente a# Copied from. Evita# Copied fromsiempre que sea posible.
El mecanismo # Copied from mantiene el código copiado sincronizado con su origen. Cuando se ejecuta make fix-repo, comprueba cada bloque # Copied from y lo actualiza para que coincida con el original, por lo que las ediciones realizadas dentro de un bloque # Copied from se sobrescriben. Edita el código fuente y deja que make fix-repo propague el cambio.
Las formas básicas de # Copied from incluyen las siguientes.
# 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-casingLa sintaxis with model->newModel aplica sustituciones de cadenas después de copiar. Separe varias sustituciones con comas, que se aplican de izquierda a derecha. La opción all-casing reemplaza todas las variantes de mayúsculas y minúsculas a la vez (Bert, bert, BERT se convierten en MobileBert, mobilebert, MOBILEBERT).