Transformers documentation
Contribuir a 🤗 Transformers
Contribuir a 🤗 Transformers
Reglas de contribución
Hay dos formas de abrir un PR: corregir un issue que está abierto para contribuciones, o abrir un PR independiente que incluya su propia evidencia. También se pueden agregar nuevos modelos con un PR independiente, consulte Adding a new model. El personal de Hugging Face, los mantenedores y algunos contribuidores de larga data están exentos de estas reglas.
Corregir un problema. Vincula el problema con una palabra clave de cierre como Fixes #123 en la descripción de la PR. Puedes trabajar en:
- un problema que abriste, una vez que un mantenedor le haya asignado la etiqueta
triaged - un problema etiquetado con
contributions-welcome - un problema etiquetado con
New model, consulte Añadir un nuevo modelo
Los problemas de otras personas no están abiertos para PRs a menos que un mantenedor lo haya indicado. Las PRs que enlacen un problema en el que no puedes trabajar serán cerradas.
No es necesario pedir permiso antes de trabajar en un problema que cumpla con los requisitos, y no asignamos problemas a personas. Comentarios como “¿puedo trabajar en esto?” o “por favor, asígnenmelo” solo añaden ruido, así que omítelos y abre tu PR. La primera PR para un problema tiene prioridad.
Antes de trabajar en un problema marcado como contributions-welcome o New model, comprueba si alguien ya ha abierto un PR para ello. Si es así, no abras otro. Si detectas errores, deja sugerencias en el PR existente en su lugar. Solo abre un PR en competencia si el existente está fundamentalmente defectuoso o es obsoleto: su autor no ha respondido a los comentarios de revisión ni ha enviado cambios durante dos semanas. Un PR que está a la espera de la revisión de un mantenedor no es obsoleto. En cualquier caso, explica por qué en el problema antes de abrir el tuyo.
PRs independientes. Si nadie ha reportado el problema todavía, puedes abrir un PR sin un issue. Los PRs independientes son para cambios cortos con un impacto real, como la corrección de un error, una mejora de rendimiento o la corrección de un ejemplo roto en la documentación. La descripción del PR necesita la misma evidencia que un issue:
- para un error, un script corto que falla en
mainy pasa con tu corrección, utilizando un checkpoint publicado, una configuración predeterminada o un flujo de trabajo documentado - para una mejora de rendimiento, cifras antes y después en una carga de trabajo realista, como un punto de control publicado o una configuración predeterminada, y el hardware en el que se ejecutó. Un microbenchmark más rápido de una función que no está en una ruta crítica no cuenta.
Si ya existe un problema para el error, tu PR se procesa a través de ese problema, con o sin enlace. Las PRs independientes que corrigen un problema existente, o que no incluyen evidencia, se cerrarán. Estos requisitos no se aplican a los nuevos modelos.
Cambios que requieren un issue previo. Las limpiezas mecánicas que no afectan la corrección ni el rendimiento, y las correcciones masivas de errores tipográficos o de redacción en la documentación, necesitan un issue antes de un PR. Propón el cambio, cómo lo harías y cuántos archivos afecta. Corregir un solo error tipográfico es demasiado pequeño para un PR por cualquiera de las dos vías.
Revisión de PRs de otras personas. Se agradecen las revisiones de la comunidad cuando nos aportan algo nuevo, pero los mantenedores leen cada comentario en una PR y ya ejecutamos nuestras propias herramientas de revisión. Antes de comentar en una PR que no abriste, asegúrate de tener algo específico que decir:
- Si has encontrado un problema o tienes un cambio concreto que proponer, deja un comentario en línea en las líneas relevantes, idealmente como una sugerencia de GitHub que el autor pueda aplicar directamente. Un reproductor ayuda si estás reportando un error.
- Si reportaste el problema que corrige la PR, un breve comentario indicando si resuelve tu caso es realmente útil.
- Por favor, no publiquen resúmenes generales ni informes del tipo “lo probé y funciona”. Las aprobaciones de personas que no son mantenedoras no afectan si un PR se fusiona, y un comentario largo que repite el contenido del PR nos cuesta tiempo sin cambiar el resultado.
La forma en que escribes tu código depende de ti, pero eres responsable de todo lo que envíes, y podemos bloquear cuentas que abran repetidamente problemas o PR de baja calidad. Por favor, respeta también nuestro código de conducta.
What we look for in issues and PRs
- Diagnóstico claro de los errores. Las soluciones rápidas a menudo provocan un aumento innecesario del código o incompatibilidades con otros modelos. Dedicar tiempo a rastrear la causa exacta de un problema, y en particular a localizar el primer commit en el que apareció (por ejemplo, con git bisect), es valioso.
- Minimiza el diff. Revisa tu PR para eliminar cualquier cambio innecesario. Asegúrate de no haber enviado ningún script de pruebas o archivos no relacionados. Añade comentarios solo si son realmente necesarios. Si tu PR puede ser una corrección de 1 línea, haz que sea una corrección de 1 línea. Esto hace que la PR sea mucho más fácil de revisar y mejora las probabilidades de que sea aceptada.
- Tómate el tiempo para reproducir el problema. Muy a menudo, cuando un usuario reporta un problema, la causa real son problemas de entorno en su máquina, o bien diagnostican mal el problema y sugieren una solución inválida. Confiar demasiado en el reporte conduce a malas soluciones, a veces para problemas que ni siquiera existen. Escribir un script de reproducción simple y ejecutarlo para asegurarse de que se vea el problema es de gran valor.
- Compara con otros modelos. El repositorio de Transformers es muy grande y muchos modelos realizan tareas similares. Al corregir un error, es valioso comprobar si el error existe en otros modelos. Si tu PR indica «corregido usando el mismo enfoque que (otro modelo)», con un enlace al código relevante, eso es muy útil para los mantenedores, porque nos indica que la corrección probablemente sea correcta y compatible con el resto de la base de código.
- Eviten PRs de “trabajo innecesario”. No tenemos tiempo para pequeños cambios de estilo o correcciones de errores tipográficos en comentarios, y no aceptamos correcciones de “errores teóricos” detectados por el análisis de código que rara vez, o nunca, causan problemas en la práctica, a menos que un atacante pueda explotarlos.
- Verifica las pruebas localmente y en la CI. Antes de abrir un PR, ejecuta
make fix-repoy usautils/tests_fetcher.pypara ver una lista de pruebas que cubren los archivos que has modificado en la rama de tu PR. Ejecuta esas pruebas localmente y asegúrate de que pasen antes de abrir un PR. Después de abrir tu PR, verifica que la CI esté en verde y corrige cualquier problema antes de pedir a alguien que lo revise. Esto reduce mucho el spam de notificaciones, lo que mantiene a los mantenedores en su sano juicio.
Configuración
Haz un fork de Transformers con el botón Fork en GitHub para obtener una copia en tu cuenta y luego clónalo localmente.
git clone [email protected]:<your Github handle>/transformers.git cd transformersAñade el repositorio de Transformers como un remoto llamado
upstream.originapunta a tu fork yupstreamapunta a la fuente de verdad. Esto te permite sincronizar tumainlocal antes de hacer push aoriginy abrir un PR.git remote add upstream https://github.com/huggingface/transformers.git git remote -v # origin [email protected]:<your Github handle>/transformers.git (fetch) # origin [email protected]:<your Github handle>/transformers.git (push) # upstream https://github.com/huggingface/transformers.git (fetch) # upstream https://github.com/huggingface/transformers.git (push)Mantén tu fork actualizado y crea una rama para trabajar en ella. También puedes sincronizar tu fork desde la interfaz de GitHub con el botón Sync fork.
git checkout main && git pull upstream main && git push origin main git switch -c a-descriptive-name-for-my-branch
Instale la biblioteca en modo editable. Use
[dev]para la mayoría de las contribuciones, ya que incluye las herramientas de desarrollo necesarias para las comprobaciones de estilo y calidad. Use[torch,testing]para contribuciones de modelos, o[quality]para cambios solo en la documentación y correcciones pequeñas cuando no se necesite el conjunto completo de dependencias de desarrollo.pip install -e ".[dev]" # for model contributions pip install -e ".[torch,testing]" # for docs-only changes and small fixes pip install -e ".[quality]"
Windows
En Windows, a menos que estés usando WSL, configura git para convertir los finales de línea CRLF en LF.
git config core.autocrlf input
Una forma de ejecutar el comando make en Windows es con MSYS2.
- Descarga MSYS2 (suponemos que está instalado en
C:\msys64). - Abra la línea de comandos
C:\msys64\msys2.exe(debería estar disponible desde el menú Inicio). - Ejecuta en la shell:
pacman -Syue instalamakeconpacman -S make. - Agrega
C:\msys64\usr\bina tu variable de entorno PATH.
Ahora puedes usar make desde cualquier terminal (PowerShell, cmd.exe, etc.).
Apertura de incidencias
Utilice las plantillas de incidencias y asegúrese de que la incidencia no haya sido reportada previamente (use la barra de búsqueda de GitHub en Issues). Un informe de error debe referirse a un error en Transformers, no en su propio código, y debe afectar a un uso real y a puntos de control reales; un “error teórico” encontrado al leer el código que requiere una configuración muy no estándar para activarse no será clasificado a menos que sea un problema de seguridad. Incluya un script corto y autónomo que reproduzca el error en la última versión publicada o en main, utilizando un punto de control publicado o la configuración predeterminada. Los informes de error sin un reproductor ejecutable no serán clasificados.
Si no estás seguro de si el error está en tu código o en la biblioteca, consulta primero en el foro o en Discord. Esto ayuda a mantener GitHub centrado en problemas de la biblioteca que requieren acción.
Agregar un nuevo modelo
Agregar un modelo a Transformers lo hace disponible para que cualquier persona lo cargue y ajuste o ejecute inferencia. Antes de comenzar la implementación, aísle las diferencias entre su arquitectura y los modelos de última generación recientes que ya están en Transformers. Explique esas diferencias en la issue o el PR para que los revisores puedan comprender rápidamente qué desafíos presenta el modelo, qué partes pueden reutilizar patrones existentes y qué debe estandarizarse entre modelos.
Siga las guías a continuación.
- Añadir un modelo con Transformers modulares — implementa el modelo usando el archivo modular y genera archivos de modelado independientes.
- Generar docstrings automáticamente — usa el decorador
@auto_docstringpara generar docstrings consistentes sin código repetitivo. - Pruebas — escriba y ejecute pruebas de modelos para verificar la corrección y mantener la contribución mantenible. Para los modelos de lenguaje causales, herede del probador de LM causal cuando sea posible. Priorice las pruebas de integración, ya que verifican la ruta completa del procesador, el tokenizador y el modelo contra puntos de control reales.
- Reglas de estructura del modelo — comprueba que tus archivos cumplen las reglas estáticas de estructura del modelo que aplica
make typing.
Algunas adiciones de modelos requieren trabajo de integración adicional.
- Añade componentes de procesamiento de visión si tu modelo requiere entradas de imagen o vídeo.
- Carga dinámica de pesos si los nombres de los parámetros del punto de control publicado no coinciden con la implementación de Transformers.
Cronograma de adición de modelos
Existen cuatro plazos para la incorporación de modelos, que dependen del contribuidor del modelo y de la demanda de la comunidad por una arquitectura.
Integración desde el día 0: hacer que el modelo esté disponible en Transformers el día de su lanzamiento, mediante la publicación de una nueva versión. Ofrecemos ayuda para respaldar las funciones principales más importantes (cuantización, FlashAttention, KV-cache, etc.), revisamos borradores iniciales y, según los plazos, también podemos encargarnos de la implementación del modelo.
Envía un correo electrónico a [email protected] con algunas semanas de antelación, especialmente para arquitecturas novedosas. Iteraremos contigo en un fork privado hasta que tu checkpoint y tu lanzamiento estén listos.
Integración en la misma semana: los modelos de alta demanda suelen incorporarse en el plazo de una semana, incluso cuando el autor no se pone en contacto.
Abre un issue con la plantilla de nuevo modelo para solicitar uno. Los issues con más actividad suben más rápido en la cola.
Integración posterior a la publicación: los modelos sin una demanda fuerte, o para los que no tenemos capacidad de absorberlos, se incorporan después de la publicación aguas arriba.
Los colaboradores externos pueden abrir un PR para un nuevo modelo directamente, con o sin un issue. Antes de comenzar, revisa los issues abiertos de “New model” y los PRs abiertos para asegurarte de que nadie ya esté añadiéndolo. Lo revisaremos y te guiaremos en el proceso.
Lanzamiento centrado en el Hub: publica tu modelo directamente en el Hub mediante el soporte de remote-code de Transformers, sin necesidad de enviar una PR a la rama principal.
Los modelos populares de Hub-first suelen integrarse en Transformers más adelante, lo que habilita documentación de primera clase, mantenimiento y optimización. Hub-first es la forma de menor fricción para añadir un modelo. Sin embargo, puede ser más frágil si un modelo requiere conversión de pesos u otros problemas de compatibilidad hacia atrás.
Docs
Para la referencia de la API generada a partir de archivos de código fuente, utiliza el decorador @auto_docstring cuando sea aplicable. Consulta el README de la documentación para obtener más detalles sobre cómo editar la documentación y la sintaxis que utilizamos.