DiffuGen: generador avanzado de imágenes locales con integración MCP

⭐ Nuevo : Ahora incluye compatibilidad con el servidor OpenAPI e integración con OpenWebUI OpenAPI Tools (se requiere la versión 0.60.0 de OWUI) para una generación y visualización de imágenes fluidas en las interfaces de chat. OpenAPI es independiente del servidor MCP y permite la integración en tus propios proyectos.

📃 Índice de contenidos

• Introducción
• Entendiendo MCP y DiffuGen
• Características
• Requisitos del sistema
• Instalación
• Instrucciones de configuración de IDE
• Uso
  • Uso del servidor OpenAPI
  • Parámetros predeterminados por modelo
  • Solicitar a un LLM que genere imágenes
  • Referencia de parámetros
  • Recomendaciones de parámetros específicos del modelo
  • Cambios de parámetros predeterminados
  • Notas de uso de la línea de comandos
• Configuración
  • Enfoque de configuración
  • Anulaciones de variables de entorno
  • Configuración de configuraciones específicas de IDE
  • Elementos clave de configuración
  • Opciones específicas de IDE
  • Personalización de parámetros predeterminados
  • Actualización de archivos de configuración
• Uso avanzado
  • Uso del servidor OpenAPI
• Licencia
• Expresiones de gratitud
• Contacto

🚀 Introducción

DiffuGen es un potente sistema de generación de imágenes basado en MCP que integra modelos de IA de vanguardia directamente en su flujo de trabajo de desarrollo. Integra a la perfección los modelos Flux (Flux Schnell, Flux Dev) y las variantes de Stable Diffusion (SDXL, SD3, SD1.5) en una interfaz unificada, lo que le permite aprovechar las ventajas únicas de cada familia de modelos sin cambiar de herramienta. Con un control integral de parámetros y compatibilidad con múltiples GPU, DiffuGen escala desde bocetos conceptuales rápidos en hardware de bajo consumo hasta imágenes con calidad de producción en sistemas de alto rendimiento.

Construido sobre la implementación altamente optimizada de stable-diffusion.cpp , DiffuGen ofrece un rendimiento excepcional incluso en hardware modesto manteniendo una salida de alta calidad.

🧠 Entendiendo MCP y DiffuGen

¿Qué es MCP?

MCP (Protocolo de Contexto de Modelo) es un protocolo que permite a los LLM (Grandes Modelos de Lenguaje) acceder a herramientas y servicios personalizados. En resumen, un cliente MCP (como Cursor, Windsurf, Roo Code o Cline) puede realizar solicitudes a los servidores MCP para acceder a las herramientas que estos proporcionan.

DiffuGen como servidor MCP

DiffuGen funciona como un servidor MCP que proporciona capacidades de generación de texto a imagen. Implementa el protocolo MCP para permitir que los IDE compatibles envíen solicitudes de generación y reciban imágenes generadas.

El servidor expone dos herramientas principales:

1. generate_stable_diffusion_image : Generar con modelos de difusión estable
2. generate_flux_image : Generar con modelos Flux

Arquitectura técnica

DiffuGen consta de varios componentes clave:

• setup-diffugen.sh : La utilidad de instalación completa y el descargador y administrador de modelos
• diffugen.py : el script principal de Python que implementa la funcionalidad del servidor MCP y define las herramientas de generación
• diffugen.sh : un iniciador de scripts de shell que configura el entorno e inicia el servidor Python
• diffugen.json : archivo de configuración de plantilla para la integración de MCP con varios IDE (para copiar en la configuración de MCP del IDE)
• stable-diffusion.cpp : La implementación optimizada en C++ de Stable Diffusion utilizada para la generación de imágenes reales

El sistema funciona mediante:

1. Recibir datos de solicitud y parámetros de un cliente MCP
2. Procesando la solicitud a través del servidor Python
3. Llamar al binario stable-diffusion.cpp con los parámetros apropiados
4. Guardar la imagen generada en un directorio de salida configurado
5. Devolver la ruta y los metadatos de la imagen generada al cliente

Acerca de stable-diffusion.cpp

stable-diffusion.cpp es una implementación en C++ altamente optimizada del algoritmo Stable Diffusion. En comparación con la implementación de referencia de Python, ofrece:

• Velocidad de inferencia significativamente más rápida (hasta 3-4 veces más rápida)
• Menor uso de memoria (funciona en GPU con tan solo 4 GB de VRAM)
• Núcleos CUDA optimizados para GPU NVIDIA
• Compatibilidad con diversos métodos de muestreo y formatos de modelos
• Soporte para cuantificación de modelos para un mejor rendimiento
• No hay dependencias de Python para el proceso de generación del núcleo

Esto permite a DiffuGen proporcionar una generación de imágenes de alta calidad con un rendimiento excepcional, incluso en configuraciones de hardware modestas.

✨ Características

• Compatibilidad con múltiples modelos : genere imágenes utilizando varios modelos, incluidos Flux Schnell, Flux Dev, SDXL, SD3 y SD1.5
• Integración con MCP : se integra perfectamente con IDE que admiten MCP (Cursor, Windsurf, Roo Code, Cline, etc.)
• Servidor OpenAPI : interfaz API REST adicional para acceso HTTP directo a capacidades de generación de imágenes
• Multiplataforma : funciona en Linux, macOS y Windows (vía nativa o WSL)
• Control de parámetros : ajuste sus generaciones con controles para:
  • Dimensiones de la imagen (ancho/alto)
  • Pasos del muestreo
  • Escala CFG
  • Valores de semilla
  • Indicaciones negativas (solo para modelos SD, Flux no admite indicaciones negativas).
  • Métodos de muestreo
• Aceleración CUDA : utiliza la aceleración de GPU para una generación de imágenes más rápida
• Interfaz de lenguaje natural : genere imágenes utilizando comandos simples de lenguaje natural
• Recuperación inteligente de errores : gestión robusta de errores con procedimientos de recuperación que tienen en cuenta las operaciones
• Configuración fácil de usar : script de configuración interactivo con manejo de interrupciones mejorado
• Seguimiento de recursos : gestión de recursos con reconocimiento de sesiones para una limpieza eficiente
• Interfaz personalizable : compatibilidad con logotipos artísticos ANSI personalizados y mejoras visuales

💻 Requisitos del sistema

Requisitos mínimos:

• CPU : procesador de 4 núcleos (Intel i5/AMD Ryzen 5 o equivalente)
• RAM : 8 GB de memoria del sistema
• Almacenamiento : 5 GB de espacio libre en disco (se prefiere SSD para una carga más rápida del modelo)
• Python : 3.8 o más reciente
• GPU : Gráficos integrados o GPU dedicada de nivel básico (opcional)
• Red : Conexión de banda ancha para descargas de modelos (5+ Mbps)

Requisitos recomendados:

• CPU : procesador de 8 o más núcleos (Intel i7/i9 o AMD Ryzen 7/9)
• RAM : 16 GB+ de memoria del sistema
• GPU : GPU NVIDIA con 6 GB+ de VRAM (RTX 2060 o superior para un rendimiento óptimo)
• Almacenamiento : más de 20 GB de espacio libre en SSD
• Python : 3.10 o más reciente (3.11 ofrece el mejor rendimiento)
• Red : Conexión de alta velocidad (más de 20 Mbps) para descargas de modelos eficientes

📥 Instalación

Instalación automática (recomendada)

La forma más sencilla de instalar DiffuGen es utilizando el script de instalación proporcionado:

Siga las instrucciones interactivas para completar la instalación.

El script de configuración hará lo siguiente:

• Instalar las dependencias necesarias
• Clonar y compilar stable-diffusion.cpp
• Configurar un entorno virtual de Python
• Descargar modelos seleccionados (Nota: algunos modelos también requieren modelos Clip\VAE)
• Configurar rutas de archivos para su sistema

Instalación manual

Si prefiere instalarlo manualmente, siga estos pasos:

1. Clonar los repositorios:

2. Construya stable-diffusion.cpp:

Con CUDA:

Sin CUDA:

3. Crear y activar un entorno virtual de Python:

4. Descargue los modelos requeridos (estructura que se muestra a continuación):

Puede descargar los modelos de las siguientes fuentes:

Nota: La descarga del modelo puede tardar un poco dependiendo de tu conexión a internet. El modelo SDXL tiene aproximadamente 6 GB, el SD3 unos 13 GB, el SD1.5 unos 4 GB y los modelos Flux entre 8 y 13 GB cada uno.

5. Actualizar rutas de archivos en la configuración:

Establecer el script de shell como ejecutable

Enfoque de configuración : DiffuGen utiliza un único archivo de configuración ( diffugen.json ) como fuente de confianza para todas las configuraciones. El flujo de trabajo es el siguiente:

1. Edite diffugen.json en el directorio raíz de DiffuGen con la configuración deseada
2. Ejecute la opción 5 en setup_diffugen.sh para actualizar automáticamente las rutas en este archivo
3. Copie el contenido de diffugen.json al archivo de configuración MCP de su IDE

El archivo contiene todas las configuraciones necesarias:

• Rutas de archivo (comando, SD_CPP_PATH, models_dir, output_dir)
• Parámetros del modelo predeterminados (pasos, cfg_scale, sampling_method)
• Configuración de uso de VRAM
• Metadatos para la integración IDE

Instrucciones de configuración de IDE

Configuración con cursor

1. Descargar e instalar Cursor
2. Vaya a Configuración del cursor > MCP y haga clic en "Agregar nuevo servidor MCP global".
3. Copie el contenido del archivo diffugen.json de su DiffuGen y péguelo en ~/.cursor/mcp.json
4. Actualizar servidores MCP en Configuración > MCP
5. Utilice DiffuGen abriendo el panel de chat de IA (Ctrl+K o Cmd+K) y solicitando la generación de imágenes

Configuración con Windsurf

1. Descargar e instalar Windsurf
2. Vaya a Windsurf > Configuración > Configuración avanzada o Paleta de comandos > Abrir página de configuración de Windsurf
3. Desplácese hacia abajo hasta la sección Cascada y haga clic en "Agregar servidor" > "Agregar servidor personalizado +"
4. Copie el contenido del archivo diffugen.json de su DiffuGen y péguelo en ~/.codeium/windsurf/mcp_config.json
5. Utilice DiffuGen a través de la interfaz de chat de Cascade

Configuración con Roo Code

1. Descargar e instalar Roo Code
2. Localice el archivo de configuración MCP para Roo Code
3. Copie el contenido del archivo diffugen.json de su DiffuGen en la configuración MCP de Roo Code
4. Utilice DiffuGen a través de la función de asistente de IA

Configuración con Cline

1. Descargue e instale Cline
2. Copie el contenido del archivo diffugen.json de DiffuGen en la configuración MCP de Cline
3. Utilice DiffuGen a través del chat de IA o la interfaz de comandos

Configuración con Claude en Anthropic Console

Claude puede usar DiffuGen si lo ha configurado como servidor MCP en su sistema. Al solicitarle a Claude que genere imágenes, especifique el uso de DiffuGen y proporcione los parámetros que desea usar.

🎮 Uso

Para iniciar el servidor DiffuGen manualmente:

O usando Python directamente:

Debería ver: DiffuGen ready cuando el servidor se haya iniciado correctamente.

Uso del servidor OpenAPI

El servidor OpenAPI proporciona una interfaz API REST para acceso HTTP directo a las funciones de generación de imágenes de DiffuGen. Esto se suma a la integración con MCP y puede ser útil para:

• Acceso directo a la API HTTP
• Integración con otras herramientas que no admiten MCP
• Aplicaciones personalizadas que necesitan acceso programático

Para obtener instrucciones de configuración detalladas y opciones de configuración avanzadas, consulte la Guía de integración de OpenAPI .

Para iniciar el servidor OpenAPI:

El servidor se puede configurar para usar un host o puerto diferente si es necesario. Por defecto, se ejecuta en:

• Anfitrión: 0.0.0.0
• Puerto: 8080

El servidor estará disponible en http://0.0.0.0:8080 con documentación interactiva en http://0.0.0.0:8080/docs .

Las imágenes generadas se guardan en el directorio /output de forma predeterminada. Si no se puede acceder a este directorio, el servidor creará automáticamente un directorio output en el directorio de trabajo actual. Las imágenes se sirven a través del punto de conexión /images .

Integración con OpenWebUI

1. Abra la configuración de OpenWebUI (icono de engranaje)
2. Vaya a la sección "Herramientas"
3. Haga clic en el botón "+" para agregar un nuevo servidor de herramientas
4. Introduzca los siguientes datos:
   • URL: http://0.0.0.0:5199
   • Clave API: (dejar en blanco)
5. Haga clic en "Guardar"

Una vez añadido, DiffuGen aparecerá en la lista de herramientas disponibles al hacer clic en el icono de herramientas en la interfaz de chat. Los siguientes puntos finales estarán disponibles:

• generate_stable_image_generate_stable_post : Generar con difusión estable
• generate_flux_image_endpoint_generate_flux_post : Generar con modelos Flux
• list_models_models_get : Lista de modelos disponibles

Ejemplo usando curl:

Ejemplo usando solicitudes de Python:

Parámetros predeterminados por modelo

Cada modelo tiene parámetros predeterminados específicos optimizados para obtener mejores resultados:

Estos parámetros predeterminados se pueden personalizar agregando una sección default_params al archivo de configuración MCP de su IDE:

Solo necesita especificar los parámetros que desea anular: cualquier valor no especificado utilizará los valores predeterminados integrados.

Nota : Para obtener ejemplos y recomendaciones de líneas de comandos específicas del modelo, consulte la sección Recomendaciones de parámetros específicos del modelo .

Solicitar a un LLM que genere imágenes

A continuación se muestran ejemplos de cómo pedirle a un asistente de IA que genere imágenes con DiffuGen:

Solicitudes básicas:

Con especificación del modelo:

Con parámetros avanzados:

Referencia de parámetros

DiffuGen se puede utilizar desde la línea de comandos con la siguiente sintaxis básica:

Ejemplo:

Este comando genera una imagen utilizando parámetros predeterminados (modelo flux-schnell, resolución 512x512, etc.) y la guarda en el directorio de salida configurado.

A continuación se muestran los parámetros que se pueden utilizar con DiffuGen (aplicables tanto a la interfaz MCP como a la línea de comandos):

Estos parámetros se pueden especificar al solicitar a un asistente de IA que genere imágenes o al usar la interfaz de línea de comandos. Los parámetros se pasan en diferentes formatos según la interfaz:

• En MCP/AI Assistant : parameter=value (p. ej., model=sdxl, width=768, height=512 )
• En la línea de comandos : --parameter value (por ejemplo, --model sdxl --width 768 --height 512 )

Los valores predeterminados se seleccionan para ofrecer buenos resultados desde el primer momento con un tiempo de espera mínimo. Para obtener imágenes de mayor calidad, considere aumentar los pasos o cambiar a modelos como sdxl.

Recomendaciones de parámetros específicos del modelo

Nota : Estas recomendaciones se basan en la sección Parámetros predeterminados por modelo y proporcionan ejemplos prácticos.

Para obtener mejores resultados al utilizar modelos específicos a través de la línea de comando:

Modelos de flujo (flux-schnell, flux-dev)

Modelos SD estándar (sdxl, sd3, sd15)

Cambios de parámetros predeterminados

La interfaz de línea de comandos de DiffuGen utiliza los siguientes valores predeterminados si no se especifica lo contrario en la configuración:

• Modelo predeterminado: si no se especifica, se utilizan modelos apropiados para la función (flux-schnell para funciones Flux, sd15 para funciones SD)
• Método de muestreo predeterminado: euler (mejor para modelos de flujo)
• Escala CFG predeterminada: 1.0 para modelos Flux, 7.0 para modelos SD estándar
• Pasos predeterminados: 8 para flux-schnell, 20 para otros modelos
• Dimensiones predeterminadas: 512 x 512 píxeles

Al usar la línea de comandos, no es necesario especificar estos parámetros a menos que desee sobrescribir los predeterminados. Si utiliza parámetros específicos con frecuencia, considere agregarlos a su archivo de configuración en lugar de especificarlos en cada línea de comandos.

Notas de uso de la línea de comandos

• Las imágenes generadas se guardan en el directorio de salida configurado con nombres de archivo basados en la marca de tiempo y los parámetros.
• Puede generar múltiples imágenes en secuencia ejecutando el comando varias veces
• Para el procesamiento por lotes, considere crear un script de shell que llame a DiffuGen con diferentes parámetros
• Para ver todas las opciones de línea de comandos disponibles, ejecute ./diffugen.sh --help
• El mismo motor impulsa tanto la interfaz MCP como la herramienta de línea de comandos, por lo que la calidad y las capacidades son idénticas.

⚙️ Configuración

Enfoque de configuración

DiffuGen utiliza un único enfoque de configuración centrado en el archivo diffugen.json :

1. Archivo de configuración principal : diffugen.json en el directorio raíz de DiffuGen es la única fuente de verdad para todas las configuraciones
2. Integración IDE : copie el contenido de diffugen.json al archivo de configuración MCP de su IDE
3. Variables de entorno : para un uso avanzado, puede anular la configuración con variables de entorno

Anulaciones de variables de entorno

Para un uso avanzado, puede anular la configuración mediante variables de entorno:

• SD_CPP_PATH : Anula la ruta a stable-diffusion.cpp
• DIFFUGEN_OUTPUT_DIR : Anula el directorio de salida
• DIFFUGEN_DEFAULT_MODEL : Anular el modelo predeterminado
• DIFFUGEN_VRAM_USAGE : Anular la configuración de uso de VRAM
• CUDA_VISIBLE_DEVICES : Controla qué GPU se utilizan para la generación

Configuración de configuraciones específicas de IDE

DiffuGen permite tener diferentes configuraciones para distintos IDE mediante el uso de variables de entorno en la configuración MCP de cada IDE. Esto permite mantener un único archivo diffugen.json base y personalizar los parámetros por IDE.

La prioridad de configuración funciona de la siguiente manera:

1. Variables de entorno (máxima prioridad)
2. Configuración del archivo diffugen.json local (configuración base)

Ejemplo: diferentes directorios de salida para diferentes IDE

Para el cursor (en ~/.cursor/mcp.json ):

Para Windsurf (en ~/.codeium/windsurf/mcp_config.json ):

Ejemplo: Diferentes modelos predeterminados y configuraciones de VRAM

Este enfoque le permite personalizar el comportamiento de DiffuGen por IDE mientras sigue utilizando la misma instalación subyacente.

Elementos clave de configuración

Comando y argumentos

• comando : Ruta completa al script diffugen.sh (debe ser la ruta absoluta)
• args : argumentos adicionales de la línea de comandos para pasar al script (normalmente se dejan vacíos)

Variables de entorno

• CUDA_VISIBLE_DEVICES : Controla qué GPU se utilizan para la generación
  • "0" : utiliza solo la primera GPU
  • "1" : utiliza solo la segunda GPU
  • "0,1" : utilizar tanto la primera como la segunda GPU
  • "-1" : Deshabilitar CUDA y usar solo CPU
• SD_CPP_PATH : Ruta al directorio de instalación de stable-diffusion.cpp
  • Esto se utiliza para localizar el binario stable-diffusion.cpp y los modelos
• default_model : El modelo predeterminado que se utilizará cuando no se especifique ninguno

Configuración de recursos

• models_dir : Directorio que contiene los archivos del modelo
  • Debe apuntar al directorio models dentro de su instalación stable-diffusion.cpp
• output_dir : Directorio donde se guardarán las imágenes generadas
  • Debe ser escribible por el usuario que ejecuta DiffuGen
• vram_usage : controla la estrategia de uso de VRAM
  • "adaptive" : ajusta automáticamente el uso de la memoria según la VRAM disponible
  • "minimal" : utiliza una VRAM mínima a costa de la velocidad
  • "balanced" : Equilibrar el uso de la memoria y la velocidad (predeterminado)
  • "maximum" : utiliza la máxima VRAM disponible para obtener el mejor rendimiento

Opciones específicas de IDE

Cada IDE tiene opciones específicas que puedes personalizar en el archivo diffugen.json :

Opciones del cursor

Opciones de windsurf

Personalización de parámetros predeterminados

Puede personalizar los parámetros predeterminados para cada modelo en la sección default_params :

Actualización de archivos de configuración

Al utilizar el script de configuración automática, se crea un archivo diffugen.json configurado correctamente con las rutas correctas para su sistema cuando ejecuta la opción 5. Para integrar DiffuGen con su IDE:

1. Ejecute la opción 5 en setup_diffugen.sh para actualizar las rutas en diffugen.json
2. Copiar todo el contenido del archivo diffugen.json generado
3. Péguelo en el archivo de configuración MCP de su IDE (por ejemplo, ~/.cursor/mcp.json )
4. Reinicie su IDE para aplicar los cambios

La principal ventaja de este enfoque es una única fuente de verdad para la configuración, lo que facilita el mantenimiento y la actualización de la configuración de DiffuGen.

📃 Uso avanzado

El módulo Python DiffuGen se puede importar y utilizar programáticamente en sus propios scripts de Python:

Uso del servidor OpenAPI

También puedes utilizar el servidor OpenAPI mediante programación en tus aplicaciones:

🔍 Solución de problemas

Problemas comunes y soluciones

1. Modelos faltantes o rutas incorrectas
   • Asegúrese de que todos los archivos del modelo se descarguen y se coloquen en los directorios correctos
   • Compruebe que las rutas en el archivo de configuración estén configuradas correctamente
   • Verificar que los permisos de archivo permitan el acceso de lectura a los archivos del modelo
2. Problemas con CUDA/GPU
   • Asegúrese de que sus controladores NVIDIA estén actualizados
   • Establezca CUDA_VISIBLE_DEVICES para apuntar a una GPU específica
   • Si se queda sin VRAM, intente utilizar un modelo más pequeño o reducir las dimensiones.
3. Problemas de calidad de la imagen
   • Aumentar pasos para una mejor calidad (a costa del tiempo de generación)
   • Ajuste la escala CFG: más alta para una adherencia más rápida, más baja para la creatividad
   • Pruebe diferentes métodos de muestreo (dpm++2m suele proporcionar buenos resultados)
   • Utilice indicaciones más detalladas con descripciones de estilo específicas
4. Errores de permisos de archivos
   • Asegúrese de que el directorio de salida pueda ser escrito por el usuario que ejecuta DiffuGen
   • Compruebe que todos los scripts tengan permisos de ejecución ( chmod +x diffugen.sh )

Obtener ayuda

Si encuentra problemas que no se abordan aquí, puede:

• Consulte el repositorio de GitHub para encontrar problemas y soluciones
• Ejecutar con el registro de depuración habilitado: DEBUG=1 ./diffugen.sh "your prompt"
• Contacte a los desarrolladores a través de problemas de GitHub

🌟 Contribuyendo

¡Agradecemos sus contribuciones a DiffuGen! Para contribuir:

1. Bifurcar el repositorio
2. Crear una rama de características
3. Realiza tus cambios
4. Enviar una solicitud de extracción

Asegúrese de que su código siga los estándares de codificación del proyecto e incluya pruebas adecuadas.

📄 Licencia

Este proyecto está licenciado bajo la licencia Apache: consulte el archivo de LICENCIA para obtener más detalles.

• Todos los modelos tienen licencia de su respectiva distribución y no están autorizados ni proporcionados de ninguna manera por CLOUDWERX.DEV.
• HuggingFace.co se utiliza para descargar modelos y no está afiliado de ninguna manera con CLOUDWERX.DEV

🙏 Agradecimientos

• stable-diffusion.cpp para la implementación optimizada de C++
• IA de estabilidad para modelos de difusión estable
• Black Forest Labs por sus modelos Flux
• Abrazando la cara para los enlaces de descarga
• Todos los contribuyentes al protocolo MCP

📬 Contacto

• GitHub: CLOUDWERX-DEV
• Sitio web: cloudwerx.dev
• Correo electrónico: sysop@cloudwerx.dev
• Discord: Únete a nuestro servidor