Cómo contribuir a Diffusers 🧨

Si usas un agente de IA para contribuir, asegúrate de leer la sección Contribuciones asistidas por IA y agénticas para conocer nuestras expectativas y directrices.

¡Amamos ❤️ las contribuciones de la comunidad de código abierto! Todos son bienvenidos y se valoran y agradecen todos los tipos de participación, no solo el código. Responder preguntas, ayudar a otros, establecer contacto y mejorar la documentación son de inmenso valor para la comunidad, así que no tengas miedo y participa si te animas.

Se anima a todos a empezar saludando con 👋 en nuestro canal público de Discord. Hablamos de las últimas tendencias en modelos de difusión, hacemos preguntas, mostramos proyectos personales, nos ayudamos mutuamente con contribuciones o simplemente pasamos el rato ☕.

Sea cual sea la forma en que decidas contribuir, nos esforzamos por ser parte de una comunidad abierta, acogedora y amable. Por favor, lee nuestro código de conducta y ten en cuenta respetarlo durante tus interacciones. También te recomendamos que te familiarices con las directrices éticas que guían nuestro proyecto y te pedimos que te apegues a los mismos principios de transparencia y responsabilidad.

Valoramos enormemente la retroalimentación de la comunidad, así que no tengas miedo de expresarte si crees que tienes comentarios valiosos que puedan ayudar a mejorar la biblioteca: cada mensaje, comentario, issue y pull request (PR) se lee y se considera.

Resumen

Puedes contribuir de muchas maneras, desde responder preguntas en issues y discusiones hasta añadir nuevos modelos de difusión a la biblioteca principal.

A continuación, presentamos un resumen de las diferentes formas de contribuir, ordenadas por el tiempo de dedicación requerido, en orden ascendente. Todas son valiosas para la comunidad.

• 1. Hacer y responder preguntas en GitHub Discussions o en Discord.
• 2. Abriendo nuevos problemas en la pestaña GitHub Issues.
• 3. Responder a los problemas en la pestaña GitHub Issues.
• 4. Corrige un problema sencillo, marcado con la etiqueta “Good first issue”, ver aquí.
• 5. Contribuir a la documentación.
• 6. Publica un pipeline o un modelo en el Hub como código remoto con Modular Diffusers.
• 7. Contribuye a los examples.
• 8. Corrige un problema más difícil, marcado con la etiqueta “Good second issue”, ver aquí.
• 9. Asumir un problema del programa MVP de Diffusers.
• 10. Añade un nuevo pipeline, modelo o scheduler a la biblioteca. Para esta contribución, normalmente trabajamos directamente con los autores del modelo; como contribuidor de la comunidad, comienza en el Hub (6) en su lugar. Consulta los issues abiertos “New Pipeline/Model” y “New scheduler”, y lee primero la Design Philosophy.

Como se dijo antes, todas las contribuciones son valiosas para la comunidad. A continuación, explicaremos cada contribución con un poco más de detalle.

Para las contribuciones 4 a 10, excepto la 6, que se encuentra en el Hub, será necesario abrir un PR. Se explica en detalle cómo hacerlo en Opening a pull request.

1. Hacer y responder preguntas en GitHub Discussions o en Discord

Cualquier pregunta o comentario relacionado con la biblioteca Diffusers puede hacerse en GitHub Discussions o en Discord. Dichas preguntas y comentarios incluyen (pero no se limitan a):

• Informes de experimentos de entrenamiento o inferencia con el objetivo de compartir conocimientos
• Presentación de proyectos personales
• Preguntas sobre ejemplos de entrenamiento no oficiales
• Propuestas de proyecto
• Comentarios generales
• Resúmenes de artículos
• Solicitar ayuda en proyectos personales que se construyen sobre la biblioteca Diffusers
• Preguntas generales
• Preguntas éticas sobre los modelos de difusión
• …

Cada pregunta que se formula en GitHub Discussions o en Discord fomenta activamente que la comunidad comparta conocimiento de forma pública y, muy probablemente, le será de gran ayuda a un principiante en el futuro que tenga la misma duda que tú. Por favor, no dudes en plantear cualquier pregunta que tengas. En el mismo espíritu, ayudas enormemente a la comunidad al responder a este tipo de preguntas, ya que de esta manera documentas públicamente el conocimiento para que todos puedan aprender de él.

Tenga en cuenta que cuanto más esfuerzo invierta en formular o responder una pregunta, mayor será la calidad del conocimiento documentado públicamente. De la misma manera, las preguntas bien formuladas y bien respondidas crean una base de datos de conocimiento de alta calidad accesible para todos, mientras que las preguntas o respuestas mal formuladas reducen la calidad general de la base de datos de conocimiento público. En resumen, una pregunta o respuesta de alta calidad es precisa, concisa, relevante, fácil de entender, accesible y con un buen formato/bien formulada. Para obtener más información, consulte la sección Cómo escribir un buen issue.

NOTA sobre canales: GitHub Discussions está indexado por los motores de búsqueda y cada hilo puede enlazarse, por lo que las preguntas y respuestas publicadas allí siguen siendo localizables para la siguiente persona que tenga el mismo problema. En cambio, Discord tiene un formato de chat que invita a una comunicación rápida de ida y vuelta. Si bien es probable que te tome menos tiempo obtener una respuesta a tu pregunta en Discord, tu pregunta dejará de ser visible con el tiempo y resulta mucho más difícil encontrar información publicada hace un tiempo. Por lo tanto, recomendamos GitHub Discussions para preguntas y respuestas destinadas a perdurar. Si una conversación en Discord conduce a una conclusión interesante, publica el resultado como una discusión para que los lectores futuros puedan encontrarlo.

2. Abrir nuevos problemas en la pestaña de problemas de GitHub

La biblioteca 🧨 Diffusers es robusta y fiable gracias a los usuarios que nos notifican los problemas que encuentran. Así que, gracias por reportar un problema.

Recuerda que los issues de GitHub están reservados para preguntas técnicas directamente relacionadas con la biblioteca Diffusers, informes de errores, solicitudes de funciones o comentarios sobre el diseño de la biblioteca.

In a nutshell, this means that everything that is not related to the code of the Diffusers library (including the documentation) should not be asked as an issue, but rather on GitHub Discussions or Discord.

Tenga en cuenta las siguientes directrices al abrir un nuevo problema:

• Asegúrate de haber buscado si tu problema ya fue planteado antes (usa la barra de búsqueda de GitHub en Issues).
• Por favor, no informes un problema nuevo en otro problema (relacionado). Si otro problema está altamente relacionado, abre un problema nuevo de todos modos y enlázalo con el problema relacionado.
• Asegúrate de que tu problema esté escrito en inglés.
• Comprueba si tu problema podría resolverse actualizando a la última versión de Diffusers. Antes de publicar tu problema, asegúrate de que python -c "import diffusers; print(diffusers.__version__)" sea superior o coincida con la última versión de Diffusers.
• Recuerda que cuanto más esfuerzo inviertas en abrir un nuevo problema, mayor será la calidad de tu respuesta y mejor será la calidad general de los problemas de Diffusers.

Los nuevos problemas suelen incluir lo siguiente.

2.1. Informes de errores reproducibles y mínimos

Un informe de error debe incluir siempre un fragmento de código reproducible y ser lo más minimalista y conciso posible. Esto significa, en detalle:

• Reduce el alcance del error lo más posible; no publiques todo tu archivo de código.
• Formatea tu código.
• No incluya ninguna biblioteca externa, excepto Diffusers, que depende de ellas.
• Siempre proporciona toda la información necesaria sobre tu entorno; para ello, puedes ejecutar diffusers-cli env en tu shell y copiar y pegar la información mostrada en el issue.
• Explica el problema. Si el lector no sabe cuál es el problema y por qué lo es, no podrá resolverlo.
• Siempre asegúrate de que quien lea tu publicación pueda reproducir el problema con el mínimo esfuerzo posible. Si tu fragmento de código no se puede ejecutar por falta de librerías o variables no definidas, no podrán ayudarte. Asegúrate de que tu fragmento de código reproducible sea lo más mínimo posible y que se pueda copiar y pegar en una simple consola de Python.
• Si para reproducir tu problema se requiere un modelo y/o un conjunto de datos, asegúrate de que el lector tenga acceso a ese modelo o conjunto de datos. Siempre puedes subir tu modelo o conjunto de datos al Hub para que sea fácilmente descargable. Intenta mantener tu modelo y conjunto de datos lo más pequeños posible, para que la reproducción de tu problema sea lo más sencilla posible.

Para obtener más información, consulte la sección Cómo escribir un buen issue.

Puedes abrir un informe de error aquí.

2.2. Solicitudes de funciones

Una solicitud de función de clase mundial aborda los siguientes puntos:

1. Primero, la motivación:

• ¿Está relacionado con un problema o frustración con la biblioteca? Si es así, explica por qué. Lo ideal es proporcionar un fragmento de código que demuestre el problema.
• ¿Está relacionado con algo que necesitarías para un proyecto? ¡Nos encantaría saber más!
• ¿Es algo en lo que has trabajado y crees que podría beneficiar a la comunidad? ¡Genial! Cuéntanos qué problema te resolvió.

2. Escribe un párrafo completo que describa la función;
3. Proporciona un fragmento de código que demuestre su uso futuro;
4. En caso de que esto esté relacionado con un artículo, adjunta un enlace;
5. Adjunta cualquier información adicional (dibujos, capturas de pantalla, etc.) que creas que pueda ser de ayuda.

Puedes abrir una solicitud de funcionalidad aquí.

2.3 Retroalimentación

La retroalimentación sobre el diseño de la biblioteca y las razones por las que es bueno o no ayuda enormemente a los mantenedores principales a construir una biblioteca fácil de usar. Para comprender la filosofía detrás de la filosofía de diseño actual, por favor echa un vistazo aquí. Si sientes que una cierta elección de diseño no se ajusta a la filosofía de diseño actual, explica por qué y cómo debería cambiarse. Si una cierta elección de diseño sigue la filosofía de diseño en exceso, limitando así los casos de uso, explica por qué y cómo debería cambiarse. Si una cierta elección de diseño es muy útil para ti, también deja una nota, ya que esta es una gran retroalimentación para futuras decisiones de diseño.

Puedes abrir un problema sobre la retroalimentación aquí.

2.4 Preguntas técnicas

Las preguntas técnicas se refieren principalmente a por qué cierto código de la biblioteca se escribió de una manera específica o a qué hace una parte concreta del código. Asegúrate de enlazar al código en cuestión y de proporcionar detalles sobre por qué esta parte del código resulta difícil de entender.

Puedes abrir un problema sobre una pregunta técnica aquí.

2.5 Propuesta para añadir un nuevo modelo, programador o pipeline

Si la comunidad de modelos de difusión ha publicado un nuevo modelo, pipeline o scheduler que desees ver en la biblioteca Diffusers, proporciona la siguiente información:

• Breve descripción del pipeline de difusión, el modelo o el programador, y enlace al artículo o a la publicación pública.
• Enlace a cualquiera de sus implementaciones de código abierto.
• Enlace a los pesos del modelo si están disponibles.

Además, no olvides etiquetar al autor original del componente (modelo, programador, pipeline, etc.) con su nombre de usuario de GitHub si puedes encontrarlo.

Si quieres llevar el modelo a Diffusers por tu cuenta, consulta Publicar un pipeline o un modelo en el Hub y Añadir pipelines, modelos y schedulers.

Puedes abrir una solicitud para un modelo/pipeline/planificador aquí.

3. Responder a los problemas en la pestaña de problemas de GitHub

Responder a problemas en GitHub puede requerir cierto conocimiento técnico de Diffusers, pero animamos a todos a intentarlo, incluso si no están 100% seguros de que su respuesta sea correcta. Algunos consejos para dar una respuesta de alta calidad a un problema:

• Sé lo más conciso y minimalista posible.
• Mantente en el tema. Una respuesta al problema debe tratar sobre el problema y solo sobre el problema.
• Proporcione enlaces a código, artículos u otras fuentes que demuestren o respalden su punto.
• Responde con código. Si un fragmento de código simple es la respuesta al problema o muestra cómo se puede resolver, proporciona un fragmento de código completamente reproducible.

Además, muchos problemas tienden a ser simplemente fuera de tema, duplicados de otros problemas o irrelevantes. Es de gran ayuda para los mantenedores si puedes responder a dichos problemas, animando al autor del problema a ser más preciso, proporcionar el enlace a un problema duplicado o redirigirlos a GitHub Discussions o Discord.

Si has verificado que el informe de error emitido es correcto y requiere una corrección en el código fuente, consulta las siguientes secciones.

Para todas las contribuciones, excepto 6, es necesario abrir un PR. La sección Opening a pull request explica cómo hacerlo.

4. Corregir un “Good first issue”

Los primeros problemas recomendados se marcan con la etiqueta Good first issue. Por lo general, el problema ya explica cómo debería verse una posible solución para que sea más fácil de corregir. Si el problema no ha sido cerrado y deseas intentar solucionarlo, puedes dejar un mensaje que diga “I would like to try this issue.”. Por lo general, hay tres escenarios:

• a.) La descripción del problema ya propone una solución. En este caso, y si la solución te parece razonable, puedes abrir un PR o un PR en borrador para corregirlo.
• b.) La descripción del problema no propone una solución. En este caso, propón una solución tú mismo en un comentario del problema. Bastan unas pocas frases que describan el enfoque. Espera a que alguien del equipo de Diffusers lo confirme antes de abrir una PR.
• c.) Ya existe una PR abierta para corregir el problema, pero el problema aún no se ha cerrado. Si la PR ha quedado obsoleta, simplemente puedes abrir una nueva PR y enlazarla con la PR obsoleta. Las PRs a menudo quedan obsoletas si el contribuidor original que quería corregir el problema de repente ya no puede encontrar tiempo para continuar. Esto ocurre con frecuencia en el código abierto y es muy normal. En este caso, la comunidad estará muy agradecida si lo intentas de nuevo y aprovechas el conocimiento de la PR existente. Si ya hay una PR y está activa, puedes ayudar al autor dando sugerencias, revisando la PR o incluso preguntando si puedes contribuir a la PR.

5. Contribuir a la documentación

¡Una buena biblioteca siempre tiene buena documentación! La documentación oficial suele ser uno de los primeros puntos de contacto para los nuevos usuarios de la biblioteca, y por lo tanto contribuir a la documentación es una contribución de gran valor.

Contribuir a la biblioteca puede adoptar muchas formas:

• Corregir errores ortográficos o gramaticales.
• Corrige el formato incorrecto de la docstring. Si ves que la documentación oficial se muestra de forma extraña o que un enlace está roto, nos encantaría que dedicaras un momento a corregirlo.
• Corrige la forma o las dimensiones de un tensor de entrada o salida en una docstring.
• Aclarar la documentación que sea difícil de entender o incorrecta.
• Actualizar ejemplos de código desactualizados.
• Traducir la documentación a otro idioma.

Todo lo que se muestra en la página oficial de documentación de Diffusers forma parte de la documentación oficial y puede corregirse o ajustarse en la fuente de documentación correspondiente.

Por favor, echa un vistazo a esta página sobre cómo verificar los cambios realizados en la documentación de forma local.

6. Publicar un pipeline o un modelo en el Hub

Con Modular Diffusers, un pipeline puede existir como código remoto en cualquier repositorio del Hub. Cualquiera puede cargarlo con from_pretrained(..., trust_remote_code=True), sin esperar a una liberación de Diffusers. Si eres un contribuidor de la comunidad que está incorporando un nuevo pipeline o modelo, empieza aquí. Consulta custom blocks para publicar un pipeline y custom models para publicar un modelo.

Avísanos en la solicitud de modelo correspondiente (abre una si no existe): damos retroalimentación sobre la implementación y destacamos las que nos gustan en nuestra colección Community Modular Diffusers Blocks. A partir de ahí, decidimos cómo soportar el modelo en la biblioteca: podemos incorporar tu versión, trabajar con los autores en una oficial o simplemente dirigir a la gente a la tuya. Cuéntanos también dónde encontraste dificultades en el proceso: APIs confusas, documentación faltante, errores. Esa retroalimentación nos vale tanto como el pipeline.

7. Contribuir con ejemplos de entrenamiento

Los ejemplos de Diffusers son una colección de scripts de entrenamiento que se encuentran en examples.

Admitimos dos tipos de ejemplos de entrenamiento:

• Ejemplos oficiales de entrenamiento
• Ejemplos de entrenamiento de investigación

Los ejemplos de entrenamiento de investigación se encuentran en examples/research_projects, mientras que los ejemplos de entrenamiento oficiales incluyen todas las carpetas bajo examples excepto las carpetas research_projects y community. Los ejemplos de entrenamiento oficiales son mantenidos por los mantenedores principales de Diffusers, mientras que los ejemplos de entrenamiento de investigación son mantenidos por la comunidad. Esto es por la misma razón por la que la biblioteca mantiene un conjunto pequeño de pipelines oficiales y pipelines de la comunidad activos en el Hub: no es viable para los mantenedores principales mantener todos los posibles métodos de entrenamiento para modelos de difusión. Si los mantenedores principales de Diffusers y la comunidad consideran que un cierto paradigma de entrenamiento es demasiado experimental o no lo suficientemente popular, el código de entrenamiento correspondiente debe colocarse en la carpeta research_projects y ser mantenido por el autor.

Tanto los ejemplos oficiales de entrenamiento como los de investigación consisten en un directorio que contiene uno o más scripts de entrenamiento, un archivo requirements.txt y un archivo README.md. Para que el usuario pueda hacer uso de los ejemplos de entrenamiento, es necesario clonar el repositorio:

git clone https://github.com/huggingface/diffusers

así como para instalar todas las dependencias adicionales necesarias para el entrenamiento:

cd diffusers
pip install -r examples/<your-example-folder>/requirements.txt

Por lo tanto, al añadir un ejemplo, el archivo requirements.txt debe definir todas las dependencias de pip necesarias para tu ejemplo de entrenamiento, de modo que, una vez instaladas, el usuario pueda ejecutar el script de entrenamiento del ejemplo. Consulta, por ejemplo, el archivo requirements.txt de DreamBooth.

Los ejemplos de entrenamiento de la biblioteca Diffusers deben seguir la siguiente filosofía:

• Todo el código necesario para ejecutar los ejemplos debe encontrarse en un único archivo de Python.
• Se debe poder ejecutar el ejemplo desde la línea de comandos con python <your-example>.py --args.
• Los ejemplos deben mantenerse simples y servir como ejemplo de cómo usar Diffusers para el entrenamiento. El propósito de los scripts de ejemplo no es crear modelos de difusión de última generación, sino reproducir esquemas de entrenamiento conocidos sin añadir demasiada lógica personalizada. Como consecuencia de esto, nuestros ejemplos también buscan ser buenos materiales educativos.

Para contribuir con un ejemplo, se recomienda encarecidamente revisar ejemplos existentes, como dreambooth, para tener una idea de cómo deberían ser. Aconsejamos firmemente a los colaboradores que utilicen la Accelerate library, ya que está estrechamente integrada con Diffusers. Una vez que un script de ejemplo funcione, asegúrese de agregar un README.md completo que indique exactamente cómo usar el ejemplo. Este README debe incluir:

• Un ejemplo de comando para ejecutar el script de ejemplo tal como se muestra aquí.
• Un enlace a algunos resultados de entrenamiento (registros, modelos, etc.) que muestren lo que el usuario puede esperar, como se muestra aquí.
• Si estás añadiendo un ejemplo de entrenamiento no oficial/de investigación, no olvides añadir una frase en la que indiques que mantienes este ejemplo de entrenamiento, incluyendo tu usuario de git, como se muestra aquí.

Si estás contribuyendo a los ejemplos de entrenamiento oficiales, asegúrate también de añadir una prueba a su carpeta, como examples/dreambooth/test_dreambooth.py. Esto no es necesario para los ejemplos de entrenamiento no oficiales.

8. Corregir un “Good second issue”

Los buenos segundos problemas están marcados con la etiqueta Good second issue. Suelen ser más complicados de resolver que los buenos primeros problemas, la descripción ofrece menos orientación sobre la solución y requieren un conocimiento adecuado de la biblioteca.

Si te interesa abordar un buen segundo problema, comparte tu opinión sobre el problema y el enfoque que tienes en mente como comentario, en unas pocas frases, y obtén un reconocimiento de un mantenedor antes de abrir la PR. Si ya se ha abierto una PR para el problema pero no se fusionó, revisa para entender por qué antes de proponer algo nuevo.

9. Asumir un problema MVP de Diffusers

El programa MVP de Diffusers enumera los problemas en los que más necesitamos ayuda. Funcionan como los Good second issues, pero son más difíciles y requieren más tiempo, y el programa recompensa a los colaboradores que los asumen. Comparte tu enfoque como comentario primero y obtén un reconocimiento de un mantenedor antes de abrir la PR. El programa también tiene una vía de ideas: cuéntanos una idea que aumentaría el impacto de Diffusers, en unas pocas frases y sin detalles de implementación.

10. Agregar pipelines, modelos y programadores

Si eres el autor del modelo, ponte en contacto con nosotros para que podamos coordinar la integración contigo: abre una solicitud de función o deja un comentario si ya hay una abierta.

Si eres un contribuidor de la comunidad, comienza con un repositorio de Hub, consulta Cómo publicar un pipeline o un modelo en el Hub e infórmalo en la solicitud de funcionalidad que estás interesado en integrarlo en el proyecto principal.

Los pipelines, los modelos y los schedulers son las piezas más importantes de la librería Diffusers. Proporcionan un acceso sencillo a las tecnologías de difusión más avanzadas y, por lo tanto, permiten a la comunidad construir potentes aplicaciones de IA generativa.

Al añadir un nuevo modelo, pipeline o scheduler, es posible habilitar un nuevo caso de uso potente para cualquiera de las interfaces de usuario que dependen de Diffusers, lo cual puede tener un valor inmenso para todo el ecosistema de IA generativa.

Cuando se libera el soporte para un nuevo modelo o pipeline

Es posible que un nuevo modelo o pipeline se incluya en una versión si coordinas la integración con el equipo de Diffusers con antelación. No dudes en ponerte en contacto con nosotros, ya sea a través de un issue en el repositorio de Diffusers o enviando un correo electrónico a [email protected].

Una publicación no se realiza automáticamente cuando se fusiona una solicitud de extracción de un modelo o pipeline. Antes de una publicación, los mantenedores primero verifican que la integración esté completa y que las pruebas de publicación se ejecuten correctamente.

El soporte para un nuevo modelo o pipeline normalmente se incluye en la próxima versión menor. La integración se fusiona en main y la rama de liberación se crea a partir de ella. La liberación contiene todos los cambios fusionados desde la liberación anterior, y no solo la integración del modelo o pipeline.

Las notas de la versión destacan el nuevo modelo o pipeline y también resumen los demás cambios incluidos en la versión. Las versiones de parche suelen reservarse para corregir errores en una versión existente.

Diffusers tiene algunas solicitudes de funciones abiertas para los tres componentes; si aún no sabes qué componente específico te gustaría agregar, no dudes en echarles un vistazo:

• Modelo o pipeline
• Programador

Antes de añadir cualquiera de los tres componentes, se recomienda encarecidamente leer la Guía de filosofía para comprender mejor el diseño de cualquiera de los tres componentes. Tenga en cuenta que no podemos fusionar adiciones de modelos, programadores o pipelines que se desvíen significativamente de nuestra filosofía de diseño, ya que esto provocaría inconsistencias en la API. Si no está de acuerdo con una decisión de diseño, abra un issue de retroalimentación para que se pueda discutir si un cierto patrón de diseño/decisión de diseño debe cambiarse en toda la biblioteca y si debemos actualizar nuestra filosofía de diseño. La coherencia en toda la biblioteca es muy importante para nosotros.

Asegúrate de añadir enlaces al código original y al paper en la PR, e idealmente también notifica directamente al autor original en la PR para que pueda seguir el progreso y, potencialmente, ayudar con preguntas.

Si tienes dudas o te has atascado en la PR, no dudes en dejar un mensaje para solicitar una primera revisión o ayuda.

Copiado de mechanism

Una característica única e importante que hay que entender al añadir cualquier código de pipeline, modelo o scheduler es el mecanismo # Copied from. Verás este mecanismo por todo el código de Diffusers, y la razón por la que lo usamos es para mantener el código fácil de entender y de mantener. Marcar código con el mecanismo # Copied from obliga a que el código marcado sea idéntico al código del que se copió. Esto facilita actualizar y propagar cambios en muchos archivos cada vez que ejecutas make fix-copies.

Por ejemplo, en el ejemplo de código siguiente, StableDiffusionPipelineOutput es el código original y AltDiffusionPipelineOutput utiliza el mecanismo # Copied from para copiarlo. La única diferencia es cambiar el prefijo de la clase de Stable a Alt.

# Copied from diffusers.pipelines.stable_diffusion.pipeline_output.StableDiffusionPipelineOutput with Stable->Alt
class AltDiffusionPipelineOutput(BaseOutput):
    """
    Output class for Alt Diffusion pipelines.

    Args:
        images (`List[PIL.Image.Image]` or `np.ndarray`)
            List of denoised PIL images of length `batch_size` or NumPy array of shape `(batch_size, height, width,
            num_channels)`.
        nsfw_content_detected (`List[bool]`)
            List indicating whether the corresponding generated image contains "not-safe-for-work" (nsfw) content or
            `None` if safety checking could not be performed.
    """

Para obtener más información, lee esta sección de la publicación de blog ~No repitas~ a ti mismo*.

Cómo escribir un buen issue

Cuanto mejor esté redactado tu problema, mayores serán las probabilidades de que se resuelva rápidamente.

1. Asegúrate de que hayas utilizado la plantilla correcta para tu problema. Puedes elegir entre Bug Report, Feature Request, Feedback about API Design, New model/pipeline/scheduler addition o un problema en blanco. Asegúrate de seleccionar la correcta al abrir a new issue. Las preguntas de uso deben publicarse en GitHub Discussions, no en un problema.
2. Sé preciso: Dá a tu problema un título adecuado. Intenta formular la descripción de tu problema de la forma más simple posible. Cuanto más preciso seas al enviar un problema, menos tiempo se tardará en entenderlo y, potencialmente, resolverlo. Asegúrate de abrir un problema para un solo problema y no para varios. Si encontraste varios problemas, simplemente abre varios problemas. Si tu problema es un error, intenta ser lo más preciso posible sobre cuál es el error: no deberías escribir solo “Error en diffusers”.
3. Reproducibilidad: Un fragmento de código no reproducible == ninguna solución. Si encuentras un error, los mantenedores deben poder reproducirlo. Asegúrate de incluir un fragmento de código que pueda copiarse y pegarse en un intérprete de Python para reproducir el problema. Asegúrate de que tu fragmento de código funcione, es decir, que no falten importaciones ni enlaces a imágenes, … Tu problema debe contener un mensaje de error y un fragmento de código que pueda copiarse y pegarse sin ningún cambio para reproducir exactamente el mismo mensaje de error. Si tu problema utiliza pesos de modelo locales o datos locales a los que el lector no puede acceder, el problema no puede resolverse. Si no puedes compartir tus datos o tu modelo, intenta crear un modelo o datos ficticios.
4. Minimalista: Intente ayudar al lector a comprender el problema lo más rápido posible manteniéndose lo más conciso posible. Elimine todo el código o toda la información que no sea relevante para el problema. Si ha encontrado un error, intente crear el ejemplo de código más sencillo posible para demostrar su problema; no vuelque todo su flujo de trabajo en el problema en cuanto haya encontrado un error. Por ejemplo, si entrena un modelo y obtiene un error en algún punto durante el entrenamiento, primero debe intentar comprender qué parte del código de entrenamiento es responsable del error e intentar reproducirlo con un par de líneas. Intente usar datos ficticios en lugar de conjuntos de datos completos.
5. Contexto: Cuéntanos en qué estabas trabajando cuando encontraste el error o necesitaste la funcionalidad, como una aplicación construida con Diffusers, un proyecto de investigación o un agente que ejecutaste para encontrar errores en la biblioteca. Una o dos frases son suficientes, y un enlace al proyecto es bienvenido. Recibimos más problemas y PR de los que podemos manejar a la vez, por lo que el contexto nos ayuda a priorizar por impacto.
6. Añade enlaces. Si te refieres a una nomenclatura, un método o un modelo en particular, asegúrate de proporcionar un enlace para que el lector comprenda mejor a qué te refieres. Si te refieres a una PR o un issue específicos, asegúrate de enlazarlos a tu issue. No asumas que el lector sabe de qué estás hablando. Cuantos más enlaces añadas a tu issue, mejor.
7. Formato. Asegúrate de formatear bien tu incidencia, usando la sintaxis de código de Python para el código y la sintaxis de código normal para los mensajes de error. Consulta la documentación oficial de formato de GitHub para obtener más información.
8. Piensa en tu problema no como un ticket por resolver, sino como una hermosa entrada en una enciclopedia bien escrita. Cada problema añadido es una contribución al conocimiento de acceso público. Al añadir un problema bien redactado, no solo facilitas a los mantenedores la resolución de tu problema, sino que ayudas a toda la comunidad a comprender mejor un aspecto determinado de la biblioteca.

Cómo escribir un buen PR

1. Comienza siempre desde un problema. Busca el problema que aborda tu solicitud de extracción o abre uno si nadie lo ha hecho, y da a los mantenedores la oportunidad de responder antes de escribir código. El flujo de trabajo que mejor nos funciona es abrir un problema, luego tener una discusión sobre la solución y, a continuación, crear una solicitud de extracción basada en esa discusión. Esto nos permite centrar nuestro tiempo en los problemas de mayor impacto, acordar el alcance antes de que exista código y evitar el trabajo duplicado. Menciona el número del problema en la descripción de la solicitud de extracción (p. ej. Fixes #1234) para que ambos estén vinculados.
2. Sé un camaleón. Comprende los patrones de diseño y la sintaxis existentes y asegúrate de que las adiciones a tu código se integren de manera fluida en la base de código actual. Las solicitudes de extracción (pull requests) que se desvíen significativamente de los patrones de diseño o las interfaces de usuario existentes no se fusionarán.
3. Concéntrate en un solo objetivo. Una solicitud de extracción debe resolver un problema y solo uno. Asegúrate de no caer en la trampa de “aprovechar para arreglar otro problema mientras lo añadimos”. Es mucho más difícil revisar solicitudes de extracción que resuelven varios problemas no relacionados a la vez.
4. Corrige patrones, no casos aislados. Un problema puede abarcar muchos archivos: si el mismo error se repite en toda la base de código, busca todas las instancias y corrígelas en un solo PR con un alcance claro y sistemático (p. ej. “fix mutable defaults across all schedulers”), en lugar de un PR por cada instancia.
5. El título de tu pull request debe ser un resumen de su contribución. Para indicar que se trata de un trabajo en curso, antepón [WIP] al título; esto evita el trabajo duplicado y separa el PR de los que están listos para fusionarse.
6. Intenta formular y formatear tu texto tal como se explica en Cómo escribir un buen issue.
7. Revisa tu propio diff antes de abrir la PR. Léelo como lo haría un revisor y corrige lo que encuentres. Recomendamos encarecidamente ejecutar la habilidad self-review: aplica el mismo criterio que el revisor de CI @claude. Configura tu agente tal como se describe en Coding with AI agents y sigue las indicaciones de AI-assisted and agentic contributions. Menciona en la descripción los hallazgos que decidiste dejar tal cual, para que el revisor sepa que fue una decisión y no un descuido.
8. Asegúrate de que las pruebas existentes pasen.
9. Añade pruebas con alta cobertura. Sin pruebas de calidad, no hay fusión.

• Si estás añadiendo nuevas pruebas @slow, asegúrate de que se superen usando RUN_SLOW=1 python -m pytest tests/test_my_new_model.py. CircleCI no ejecuta las pruebas lentas, ¡pero GitHub Actions las ejecuta cada noche!

10. Todos los métodos públicos deben tener docstrings informativos que funcionen bien con markdown. Consulte pipeline_latent_diffusion.py como ejemplo.
11. Debido al rápido crecimiento del repositorio, es importante asegurarse de que no se añadan archivos que lo sobrecarguen significativamente. Esto incluye imágenes, videos y otros archivos que no sean de texto. Preferimos aprovechar un dataset alojado en hf.co, como hf-internal-testing o huggingface/documentation-images, para colocar estos archivos. Si se trata de una contribución externa, puedes añadir las imágenes a tu PR y pedir a un miembro de Hugging Face que migre tus imágenes a este dataset.

Cómo abrir una PR

Antes de escribir código, le recomendamos encarecidamente que busque entre los PRs o issues existentes para asegurarse de que nadie esté trabajando ya en lo mismo. Si no está seguro, siempre es buena idea abrir un issue para obtener algo de retroalimentación.

Necesitarás conocimientos básicos de git para poder contribuir a 🧨 Diffusers. git no es la herramienta más fácil de usar, pero tiene el mejor manual. Escribe git --help en una terminal y disfruta. Si prefieres libros, Pro Git es una referencia muy buena.

Siga estos pasos para comenzar a contribuir (versiones de Python compatibles):

1. Haz una bifurcación del repositorio haciendo clic en el botón ‘Fork’ en la página del repositorio. Esto crea una copia del código en tu cuenta de usuario de GitHub.

2. Clona tu bifurcación en tu disco local y añade el repositorio base como remoto:

   Copiado

   $ git clone [email protected]:<your GitHub handle>/diffusers.git
   $ cd diffusers
   $ git remote add upstream https://github.com/huggingface/diffusers.git

3. Crea una nueva rama para guardar tus cambios de desarrollo:

   Copiado

   $ git checkout -b a-descriptive-name-for-my-changes

No trabajes en la rama main.

4. Configura un entorno de desarrollo ejecutando el siguiente comando en un entorno virtual:

   Copiado

   $ pip install -e ".[dev]"

Si ya has clonado el repositorio, es posible que necesites git pull para obtener los cambios más recientes de la librería.

5. Desarrolla las funciones en tu rama.

Mientras trabajas en las funciones, debes asegurarte de que la suite de pruebas pase. Debes ejecutar las pruebas afectadas por tus cambios de la siguiente manera:

$ pytest tests/<TEST_TO_RUN>.py

Antes de ejecutar las pruebas, asegúrate de instalar las dependencias necesarias para las pruebas. Puedes hacerlo con este comando:

$ pip install -e ".[test]"

También puedes ejecutar la suite de pruebas completa con el siguiente comando, pero ahora que Diffusers ha crecido mucho, se necesita una máquina potente para obtener un resultado en un tiempo razonable. Este es el comando:

$ make test

🧨 Diffusers se basa en black y isort para formatear su código fuente de manera consistente. Después de realizar cambios, aplica las correcciones automáticas de estilo y las verificaciones de código que no se pueden automatizar en un solo paso con:

$ make style

🧨 Diffusers también utiliza ruff y algunos scripts personalizados para detectar errores de codificación. El control de calidad se ejecuta en CI; sin embargo, también puedes ejecutar las mismas comprobaciones con:

$ make quality

Cuando estés satisfecho con tus cambios, añade los archivos modificados usando git add y realiza un commit con git commit para registrar tus cambios localmente:

$ git add modified_file.py
$ git commit -m "A descriptive message about your changes."

Es buena idea sincronizar tu copia del código con el repositorio original con regularidad. De esta forma, puedes tener en cuenta los cambios rápidamente:

$ git pull upstream main

Empuja los cambios a tu cuenta usando:

$ git push -u origin a-descriptive-name-for-my-changes

6. Una vez que estés satisfecho, ve a la página web de tu fork en GitHub. Haz clic en ‘Pull request’ para enviar tus cambios a los mantenedores del proyecto para su revisión.

7. No pasa nada si los mantenedores te piden cambios. ¡También les ocurre a los contribuyentes principales! Para que todos puedan ver los cambios en la Pull request, trabaja en tu rama local y sube los cambios a tu fork. Aparecerán automáticamente en la pull request.

Pruebas

Se incluye una amplia suite de pruebas para verificar el comportamiento de la biblioteca y varios ejemplos. Las pruebas de la biblioteca se encuentran en la carpeta de pruebas.

Nos gusta pytest y pytest-xdist porque es más rápido. Desde la raíz del repositorio, así es como se ejecutan las pruebas con pytest para la biblioteca:

$ python -m pytest -n auto --dist=loadfile -s -v ./tests/

¡De hecho, así es como se implementa make test!

Puedes especificar un conjunto más pequeño de pruebas para probar solo la funcionalidad en la que estás trabajando.

Por defecto, las pruebas lentas se omiten. Establezca la variable de entorno RUN_SLOW en yes para ejecutarlas. Esto descargará varios gigabytes de modelos: asegúrese de tener suficiente espacio en disco y una buena conexión a Internet, ¡o mucha paciencia!

$ RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./tests/

unittest tiene soporte completo; así es como se ejecutan las pruebas con él:

$ python -m unittest discover -s tests -t . -v
$ python -m unittest discover -s examples -t examples -v

Sincronizar el main bifurcado con el main de upstream (HuggingFace)

Para evitar enviar pings al repositorio de origen, lo que añade notas de referencia a cada PR de origen y envía notificaciones innecesarias a los desarrolladores involucrados en estas PRs, al sincronizar la rama principal de un repositorio bifurcado, siga estos pasos:

1. Cuando sea posible, evita sincronizar con el repositorio de origen mediante una rama y una PR en el repositorio bifurcado. En su lugar, fusiona directamente en la rama principal del repositorio bifurcado.
2. Si una PR es absolutamente necesaria, usa los siguientes pasos después de hacer checkout de tu rama:

$ git checkout -b your-branch-for-syncing
$ git pull --squash --no-commit upstream main
$ git commit -m '<your message without GitHub references>'
$ git push --set-upstream origin your-branch-for-syncing

Guía de estilo

Para las cadenas de documentación, 🧨 Diffusers sigue el estilo de Google.

Programación con agentes de IA

El repositorio mantiene la configuración de agentes de IA en .ai/, que también se publica como un plugin de agente para que las habilidades de tareas bajo demanda se instalen en un solo paso.

• Solo lectura para colaboradores — .ai/ es mantenido por los mantenedores principales. Por favor, no edites los archivos bajo .ai/ (ni los enlaces simbólicos de nivel raíz AGENTS.md / CLAUDE.md, ni los .agents/skills / .claude/skills instalados) en tu PR. Si encuentras algo que falta o está incorrecto, abre un issue o señálalo en la PR y un mantenedor lo actualizará.
• Guidelines — .ai/AGENTS.md se carga en cada sesión de agente a través de los enlaces simbólicos de la raíz AGENTS.md / CLAUDE.md ; las guías de referencia bajo .ai/references/ se leen bajo demanda cuando se sigue un enlace:
  • .ai/AGENTS.md — directrices de codificación de nivel superior
  • .ai/references/models.md — patrón de atención, reglas de implementación de modelos, convenciones comunes
  • .ai/references/pipelines.md — convenciones de pipeline
  • .ai/references/modular.md — convenciones de pipelines modulares y lista de verificación para la conversión
  • .ai/references/testing.md — capas de prueba obligatorias, mixins de tester, reglas de componentes simulados
  • .ai/references/review-rules.md — lo que buscan los revisores
• Skills (bajo .ai/skills/, cargadas bajo demanda para tareas específicas):
  • model-integration — añadir un nuevo modelo o pipeline a diffusers de principio a fin (estructura de archivos, lista de verificación de integración, estructura de pruebas, conversión de pesos)
  • self-review — revisa tus cambios en contra de las reglas del proyecto antes de abrir un PR
  • diffusers-cli — ejecutar pipelines e inspeccionar esquemas desde la terminal
  • custom-blocks — empaquetar una subclase de ModularPipelineBlocks para el Hub

Sea cual sea la ruta que elijas, pide a tu agente que confirme su propia configuración antes de empezar: python utils/check_ai.py comprueba que las guías y las habilidades son coherentes, y diffusers-cli skills list muestra qué habilidades tiene realmente.

Contribuciones asistidas por IA y agénticas

Los agentes de IA son bienvenidos para contribuir a Diffusers. Les animamos a configurar su agente con la guía de agentes de Diffusers y a utilizar las habilidades específicas de la tarea pertinentes, como model-integration y self-review. Instale el plugin (o las habilidades individuales) tal como se describe arriba y, a continuación, siga la guía para definir el alcance, implementar, probar y revisar su contribución. Usted sigue siendo responsable de comprender, probar y mantener los cambios en su PR.

Se aceptan contribuciones asistidas por IA, pero deben estar coordinadas, acotadas y verificadas para mantener la carga de revisión manejable. Las PR que no sigan estas directrices pueden cerrarse sin una revisión detallada.

• Coordina antes de abrir un PR. Busca o abre un issue, revisa PRs similares (abiertos y cerrados recientemente) y espera una confirmación explícita de un mantenedor en ese issue antes de abrir un PR. Esto nos da la oportunidad de discutir el alcance, evitar trabajo duplicado y confirmar el enfoque.
• Corrige patrones, no casos aislados. Si detectas un problema recurrente, busca instancias similares en la base de código y abre un único issue con un alcance claro y sistemático (p. ej., “corregir valores predeterminados mutables en todos los schedulers”) en lugar de muchos issues o PRs para instancias individuales.
• Autoevaluación antes de abrir. Ejecuta la habilidad self-review: revisa tu diff contra .ai/references/review-rules.md, el mismo criterio que utiliza el revisor de CI @claude, y aborda lo que informe. Es un asistente, no una autoridad, y puede estar equivocado. Céntrate en los problemas bloqueantes que te parezcan razonables y limpia el código muerto o no utilizado en la medida de lo posible. Si no estás de acuerdo con una sugerencia, no hay problema en dejarla para que el revisor la discuta después de abrir el PR: las notas que compartas (ver abajo) le indican al revisor que fue una decisión deliberada.
• Comparte tus notas de autoevaluación. Publica el informe final de autoevaluación, es decir, la ronda que refleja el diff que estás enviando, en el PR, ya sea en la descripción o como comentario, e incluye los hallazgos que decidiste no corregir y el motivo. Esto ayuda al revisor a ver qué se ha verificado ya y qué decisiones fueron deliberadas, y suele ahorrar algunas rondas de ida y vuelta.
• Mantén la comunicación de tu PR concisa. Todo lo que un revisor lee en tu PR: la descripción, los mensajes de commit, los comentarios y respuestas, los comentarios de código, debe ser fácil de entender para una persona. Si tu agente lo redactó, no lo leas solo a grandes rasgos. Léelo y pídele al agente que lo revise hasta que diga algo coherente y conciso que tú mismo escribirías. Eres el autor de todo lo que publicas.
• Include in the PR description:
  • Un enlace de coordinación al problema o la discusión donde un mantenedor reconoció el trabajo.
  • Los comandos de prueba que ejecutaste y sus resultados (pega la salida relevante, no solo “tests pass”).
  • Tus notas de autoevaluación (o un enlace al comentario de la PR que las contiene), tal como se describió anteriormente.

Si eres autor de un modelo o formas parte de un equipo que mantiene oficialmente un modelo, te animamos a utilizar agentes para la integración de un nuevo modelo. Sigue la configuración recomendada del repositorio y utiliza la habilidad model-integration. Coordina el alcance con los mantenedores antes de abrir un PR; consulta Adding pipelines, models, schedulers.