{"id":22677797,"url":"https://github.com/bghira/simpletuner","last_synced_at":"2026-04-14T22:01:53.302Z","repository":{"id":170406643,"uuid":"646537482","full_name":"bghira/SimpleTuner","owner":"bghira","description":"A general fine-tuning kit geared toward image/video/audio diffusion models.","archived":false,"fork":false,"pushed_at":"2026-04-10T14:09:02.000Z","size":32563,"stargazers_count":2804,"open_issues_count":31,"forks_count":276,"subscribers_count":19,"default_branch":"main","last_synced_at":"2026-04-10T14:24:17.293Z","etag":null,"topics":["diffusers","diffusion-models","fine-tuning","flux-dev","machine-learning","stable-diffusion"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bghira.png","metadata":{"files":{"readme":"README.es.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-05-28T18:01:02.000Z","updated_at":"2026-04-10T13:59:29.000Z","dependencies_parsed_at":"2024-04-24T02:59:05.284Z","dependency_job_id":"f243ce43-4ed8-43fc-acae-c91a3c23621b","html_url":"https://github.com/bghira/SimpleTuner","commit_stats":null,"previous_names":["bghira/simpletuner"],"tags_count":174,"template":false,"template_full_name":null,"purl":"pkg:github/bghira/SimpleTuner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bghira%2FSimpleTuner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bghira%2FSimpleTuner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bghira%2FSimpleTuner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bghira%2FSimpleTuner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bghira","download_url":"https://codeload.github.com/bghira/SimpleTuner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bghira%2FSimpleTuner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31817128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diffusers","diffusion-models","fine-tuning","flux-dev","machine-learning","stable-diffusion"],"created_at":"2024-12-09T18:01:54.354Z","updated_at":"2026-04-14T22:01:53.268Z","avatar_url":"https://github.com/bghira.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SimpleTuner 💹\n\n\u003e ℹ️ No se envían datos a terceros salvo a través de los flags opt-in `report_to`, `push_to_hub` o webhooks que deben configurarse manualmente.\n\n**SimpleTuner** está orientado a la simplicidad, con un enfoque en que el código sea fácil de entender. Esta base de código sirve como un ejercicio académico compartido y se agradecen las contribuciones.\n\nSi quieres unirte a nuestra comunidad, nos puedes encontrar [en Discord](https://discord.gg/JGkSwEbjRb) a través de Terminus Research Group.\nSi tienes alguna pregunta, no dudes en contactarnos allí.\n\n\u003cimg width=\"1944\" height=\"1657\" alt=\"image\" src=\"https://github.com/user-attachments/assets/af3a24ec-7347-4ddf-8edf-99818a246de1\" /\u003e\n\n\n## Tabla de contenidos\n\n- [Filosofía de diseño](#filosofía-de-diseño)\n- [Tutorial](#tutorial)\n- [Características](#características)\n  - [Características principales de entrenamiento](#características-principales-de-entrenamiento)\n  - [Compatibilidad de arquitectura de modelos](#compatibilidad-de-arquitectura-de-modelos)\n  - [Técnicas avanzadas de entrenamiento](#técnicas-avanzadas-de-entrenamiento)\n  - [Características específicas del modelo](#características-específicas-del-modelo)\n  - [Guías de inicio rápido](#guías-de-inicio-rápido)\n- [Requisitos de hardware](#requisitos-de-hardware)\n- [Kit de herramientas](#kit-de-herramientas)\n- [Instalación](#instalación)\n- [Solución de problemas](#solución-de-problemas)\n\n## Filosofía de diseño\n\n- **Simplicidad**: Apuntar a buenos valores predeterminados para la mayoría de los casos de uso, de modo que se requiera menos ajuste.\n- **Versatilidad**: Diseñado para manejar un amplio rango de cantidades de imágenes, desde pequeños datasets hasta colecciones extensas.\n- **Funciones de vanguardia**: Solo incorpora funciones con eficacia comprobada, evitando agregar opciones sin probar.\n\n## Tutorial\n\nPor favor, explora completamente este README antes de iniciar el [nuevo tutorial de Web UI](/documentation/webui/TUTORIAL.md) o el [tutorial clásico de línea de comandos](/documentation/TUTORIAL.md), ya que este documento contiene información vital que podrías necesitar primero.\n\nPara un inicio rápido configurado manualmente sin leer toda la documentación ni usar interfaces web, puedes usar la guía de [Quick Start](/documentation/QUICKSTART.md).\n\nPara sistemas con memoria limitada, consulta el [documento de DeepSpeed](/documentation/DEEPSPEED.md), que explica cómo usar 🤗Accelerate para configurar DeepSpeed de Microsoft para el offload del estado del optimizador. Para sharding basado en DTensor y paralelismo de contexto, lee la [guía de FSDP2](/documentation/FSDP2.md), que cubre el nuevo flujo FullyShardedDataParallel v2 dentro de SimpleTuner.\n\nPara entrenamiento distribuido multi-nodo, [esta guía](/documentation/DISTRIBUTED.md) ayudará a ajustar las configuraciones de las guías INSTALL y Quickstart para que sean adecuadas para entrenamiento multi-nodo y optimizadas para datasets de imágenes con miles de millones de muestras.\n\n---\n\n## Características\n\nSimpleTuner ofrece soporte de entrenamiento integral en múltiples arquitecturas de modelos de difusión con disponibilidad consistente de funciones:\n\n### Características principales de entrenamiento\n\n- **Web UI fácil de usar** - Gestiona todo el ciclo de vida de entrenamiento desde un panel moderno\n- **Entrenamiento multimodal** - Pipeline unificado para modelos generativos de **Imagen, Video y Audio**\n- **Entrenamiento multi-GPU** - Entrenamiento distribuido en múltiples GPUs con optimización automática\n- **Caché avanzada** - Embeddings de imagen, video, audio y captions en caché en disco para entrenamientos más rápidos\n- **Aspect bucketing** - Soporte para tamaños y relaciones de aspecto variadas en imagen/video\n- **Concept sliders** - Targeting compatible con sliders para LoRA/LyCORIS/full (vía LyCORIS `full`) con muestreo positivo/negativo/neutral y fuerza por prompt; ver la [guía de Slider LoRA](/documentation/SLIDER_LORA.md)\n- **Optimización de memoria** - La mayoría de los modelos entrenables en GPU de 24G, muchos en 16G con optimizaciones\n- **Integración con DeepSpeed y FSDP2** - Entrena modelos grandes en GPUs más pequeñas con sharding de optim/grad/param, atención paralela de contexto, gradient checkpointing y offload del estado del optimizador\n- **Entrenamiento en S3** - Entrena directamente desde almacenamiento en la nube (Cloudflare R2, Wasabi S3)\n- **Soporte EMA** - Pesos de media móvil exponencial para mayor estabilidad y calidad\n- **Trackers de experimentos personalizados** - Coloca un `accelerate.GeneralTracker` en `simpletuner/custom-trackers` y usa `--report_to=custom-tracker --custom_tracker=\u003cname\u003e`\n\n### Funciones multiusuario y empresariales\n\nSimpleTuner incluye una plataforma completa de entrenamiento multiusuario con funciones de nivel empresarial - **gratuita y de código abierto, para siempre**.\n\n- **Orquestación de workers** - Registra workers de GPU distribuidos que se conectan automáticamente a un panel central y reciben trabajos vía SSE; soporta workers efímeros (lanzados en la nube) y persistentes (siempre activos); ver la [Guía de orquestación de workers](/documentation/experimental/server/WORKERS.md)\n- **Integración SSO** - Autenticación con LDAP/Active Directory u OIDC (Okta, Azure AD, Keycloak, Google); ver la [Guía de autenticación externa](/documentation/experimental/server/EXTERNAL_AUTH.md)\n- **Control de acceso basado en roles** - Cuatro roles por defecto (Viewer, Researcher, Lead, Admin) con 17+ permisos granulares; define reglas de recursos con patrones glob para restringir configs, hardware o proveedores por equipo\n- **Organizaciones y equipos** - Estructura multi-tenant jerárquica con cuotas basadas en topes; los límites de org definen máximos absolutos, los de equipo operan dentro de los límites de la org\n- **Cuotas y límites de gasto** - Aplica topes de costo (diario/mensual), límites de concurrencia de trabajos y límites de tasa de envío a nivel de org, equipo o usuario; acciones: bloquear, advertir o requerir aprobación\n- **Cola de trabajos con prioridades** - Cinco niveles de prioridad (Low → Critical) con planificación de fair-share entre equipos, prevención de starvation para trabajos con esperas largas y overrides de prioridad de admin\n- **Flujos de aprobación** - Reglas configurables disparan aprobaciones para trabajos que exceden umbrales de costo, usuarios nuevos o solicitudes de hardware específicas; aprueba vía UI, API o respuesta por email\n- **Notificaciones por email** - Integración SMTP/IMAP para estado de trabajos, solicitudes de aprobación, alertas de cuota y notificaciones de finalización\n- **API keys y permisos con alcance** - Genera API keys con expiración y alcance limitado para pipelines CI/CD\n- **Audit logging** - Registra todas las acciones de usuarios con verificación de cadena para cumplimiento; ver la [Guía de auditoría](/documentation/experimental/server/AUDIT.md)\n\nPara detalles de despliegue, consulta la [Guía Enterprise](/documentation/experimental/server/ENTERPRISE.md).\n\n### Compatibilidad de arquitectura de modelos\n\n| Modelo | Parámetros | PEFT LoRA | Lycoris | Full-Rank | ControlNet | Cuantización | Flow Matching | Codificadores de texto |\n|--------|------------|-----------|---------|-----------|------------|--------------|---------------|------------------------|\n| **Stable Diffusion XL** | 3.5B | ✓ | ✓ | ✓ | ✓ | int8/nf4 | ✗ | CLIP-L/G |\n| **Stable Diffusion 3** | 2B-8B | ✓ | ✓ | ✓* | ✓ | int8/fp8/nf4 | ✓ | CLIP-L/G + T5-XXL |\n| **Flux.1** | 12B | ✓ | ✓ | ✓* | ✓ | int8/fp8/nf4 | ✓ | CLIP-L + T5-XXL |\n| **Flux.2** | 32B | ✓ | ✓ | ✓* | ✗ | int8/fp8/nf4 | ✓ | Mistral-3 Small |\n| **ACE-Step** | 3.5B | ✓ | ✓ | ✓* | ✗ | int8 | ✓ | UMT5 |\n| **HeartMuLa** | 3B | ✓ | ✓ | ✓* | ✗ | int8 | ✗ | Ninguno |\n| **Chroma 1** | 8.9B | ✓ | ✓ | ✓* | ✗ | int8/fp8/nf4 | ✓ | T5-XXL |\n| **Auraflow** | 6.8B | ✓ | ✓ | ✓* | ✓ | int8/fp8/nf4 | ✓ | UMT5-XXL |\n| **PixArt Sigma** | 0.6B-0.9B | ✗ | ✓ | ✓ | ✓ | int8 | ✗ | T5-XXL |\n| **Sana** | 0.6B-4.8B | ✗ | ✓ | ✓ | ✗ | int8 | ✓ | Gemma2-2B |\n| **Lumina2** | 2B | ✓ | ✓ | ✓ | ✗ | int8 | ✓ | Gemma2 |\n| **Kwai Kolors** | 5B | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ChatGLM-6B |\n| **LTX Video** | 5B | ✓ | ✓ | ✓ | ✗ | int8/fp8 | ✓ | T5-XXL |\n| **LTX Video 2** | 19B | ✓ | ✓ | ✓* | ✗ | int8/fp8 | ✓ | Gemma3 |\n| **Wan Video** | 1.3B-14B | ✓ | ✓ | ✓* | ✗ | int8 | ✓ | UMT5 |\n| **HiDream** | 17B (8.5B MoE) | ✓ | ✓ | ✓* | ✓ | int8/fp8/nf4 | ✓ | CLIP-L + T5-XXL + Llama |\n| **Cosmos2** | 2B-14B | ✗ | ✓ | ✓ | ✗ | int8 | ✓ | T5-XXL |\n| **OmniGen** | 3.8B | ✓ | ✓ | ✓ | ✗ | int8/fp8 | ✓ | T5-XXL |\n| **Qwen Image** | 20B | ✓ | ✓ | ✓* | ✗ | int8/nf4 (req.) | ✓ | T5-XXL |\n| **SD 1.x/2.x (Legacy)** | 0.9B | ✓ | ✓ | ✓ | ✓ | int8/nf4 | ✗ | CLIP-L |\n\n*✓ = Compatible, ✗ = No compatible, * = Requiere DeepSpeed para entrenamiento full-rank*\n\n### Técnicas avanzadas de entrenamiento\n\n- **TREAD** - Dropout por token para modelos transformer, incluido el entrenamiento de Kontext\n- **Entrenamiento con pérdida enmascarada** - Mejor convergencia con guía de segmentación/profundidad\n- **Regularización de prior** - Mayor estabilidad de entrenamiento para consistencia de personajes\n- **Gradient checkpointing** - Intervalos configurables para optimización de memoria/velocidad\n- **Funciones de pérdida** - L2, Huber, Smooth L1 con soporte de scheduling\n- **Ponderación SNR** - Ponderación Min-SNR gamma para mejorar la dinámica de entrenamiento\n- **Group offloading** - Staging de módulos por grupo a CPU/disco en Diffusers v0.33+ con streams CUDA opcionales\n- **Barridos de adaptadores de validación** - Adjunta temporalmente adaptadores LoRA (individuales o presets JSON) durante la validación para medir renders solo de adaptador o comparativos sin tocar el training loop\n- **Hooks de validación externos** - Sustituye el pipeline de validación integrado o los pasos post-upload por tus scripts, para ejecutar checks en otra GPU o reenviar artefactos a cualquier proveedor cloud que elijas ([detalles](/documentation/OPTIONS.md#validation_method))\n- **Regularización CREPA** - Alineación de representación entre frames para video DiTs ([guía](/documentation/experimental/VIDEO_CREPA.md))\n- **Formatos de I/O de LoRA** - Carga/guarda LoRAs PEFT en layout estándar de Diffusers o claves estilo ComfyUI `diffusion_model.*` (Flux/Flux2/Lumina2/Z-Image detectan automáticamente entradas ComfyUI)\n\n### Características específicas del modelo\n\n- **Flux Kontext** - Conditioning de edición y entrenamiento image-to-image para modelos Flux\n- **PixArt two-stage** - Soporte de pipeline eDiff para PixArt Sigma\n- **Modelos de flow matching** - Scheduling avanzado con distribuciones beta/uniforme\n- **HiDream MoE** - Aumento de pérdida de puerta Mixture of Experts\n- **Entrenamiento con T5 enmascarado** - Mayor detalle fino para Flux y modelos compatibles\n- **Fusión QKV** - Optimizaciones de memoria y velocidad (Flux, Lumina2)\n- **Integración TREAD** - Enrutamiento selectivo de tokens para la mayoría de modelos\n- **Wan 2.x I2V** - Presets de etapa alta/baja más un fallback de time-embedding 2.1 (ver quickstart de Wan)\n- **Classifier-free guidance** - Reintroducción opcional de CFG para modelos destilados\n\n### Guías de inicio rápido\n\nHay guías detalladas de inicio rápido disponibles para todos los modelos soportados:\n\n- **[Guía de TwinFlow Few-Step (RCGM)](/documentation/distillation/TWINFLOW.md)** - Habilita pérdida auxiliar RCGM para generación de pocos pasos/un paso (modelos de flow o difusión vía diff2flow)\n- **[Guía de Flux.1](/documentation/quickstart/FLUX.md)** - Incluye soporte de edición Kontext y fusión QKV\n- **[Guía de Flux.2](/documentation/quickstart/FLUX2.md)** - **NUEVO**. Último y enorme modelo Flux con codificador de texto Mistral-3\n- **[Guía de Z-Image](/documentation/quickstart/ZIMAGE.md)** - LoRA Base/Turbo con adaptador asistente + aceleración TREAD\n- **[Guía de ACE-Step](/documentation/quickstart/ACE_STEP.md)** - **NUEVO**. Entrenamiento de modelo de generación de audio (text-to-music)\n- **[Guía de HeartMuLa](/documentation/quickstart/HEARTMULA.md)** - **NUEVO**. Entrenamiento de modelo de audio autoregresivo (text-to-audio)\n- **[Guía de Chroma](/documentation/quickstart/CHROMA.md)** - Transformer de flow-matching de Lodestone con schedules específicos de Chroma\n- **[Guía de Stable Diffusion 3](/documentation/quickstart/SD3.md)** - Entrenamiento full y LoRA con ControlNet\n- **[Guía de Stable Diffusion XL](/documentation/quickstart/SDXL.md)** - Pipeline completo de entrenamiento SDXL\n- **[Guía de Auraflow](/documentation/quickstart/AURAFLOW.md)** - Entrenamiento de modelos de flow-matching\n- **[Guía de PixArt Sigma](/documentation/quickstart/SIGMA.md)** - Modelo DiT con soporte de dos etapas\n- **[Guía de Sana](/documentation/quickstart/SANA.md)** - Modelo ligero de flow-matching\n- **[Guía de Lumina2](/documentation/quickstart/LUMINA2.md)** - Modelo de flow-matching de 2B parámetros\n- **[Guía de Kwai Kolors](/documentation/quickstart/KOLORS.md)** - Basado en SDXL con encoder ChatGLM\n- **[Guía de LongCat-Video](/documentation/quickstart/LONGCAT_VIDEO.md)** - Flow-matching text-to-video e image-to-video con Qwen-2.5-VL\n- **[Guía de LongCat-Video Edit](/documentation/quickstart/LONGCAT_VIDEO_EDIT.md)** - Variante de conditioning-first (image-to-video)\n- **[Guía de LongCat-Image](/documentation/quickstart/LONGCAT_IMAGE.md)** - Modelo bilingüe de flow-matching 6B con encoder Qwen-2.5-VL\n- **[Guía de LongCat-Image Edit](/documentation/quickstart/LONGCAT_EDIT.md)** - Variante de edición de imagen que requiere latents de referencia\n- **[Guía de LTX Video](/documentation/quickstart/LTXVIDEO.md)** - Entrenamiento de difusión de video\n- **[Guía de Hunyuan Video 1.5](/documentation/quickstart/HUNYUANVIDEO.md)** - Flow-matching T2V/I2V de 8.3B con etapas de SR\n- **[Guía de Wan Video](/documentation/quickstart/WAN.md)** - Flow-matching de video con soporte TREAD\n- **[Guía de HiDream](/documentation/quickstart/HIDREAM.md)** - Modelo MoE con funciones avanzadas\n- **[Guía de Cosmos2](/documentation/quickstart/COSMOS2IMAGE.md)** - Generación de imagen multimodal\n- **[Guía de OmniGen](/documentation/quickstart/OMNIGEN.md)** - Modelo unificado de generación de imagen\n- **[Guía de Qwen Image](/documentation/quickstart/QWEN_IMAGE.md)** - Entrenamiento a gran escala de 20B parámetros\n- **[Guía de Stable Cascade Stage C](/quickstart/STABLE_CASCADE_C.md)** - LoRAs de prior con validación combinada prior+decoder\n- **[Guía de Kandinsky 5.0 Image](/documentation/quickstart/KANDINSKY5_IMAGE.md)** - Generación de imagen con Qwen2.5-VL + Flux VAE\n- **[Guía de Kandinsky 5.0 Video](/documentation/quickstart/KANDINSKY5_VIDEO.md)** - Generación de video con HunyuanVideo VAE\n\n---\n\n## Requisitos de hardware\n\n### Requisitos generales\n\n- **NVIDIA**: RTX 3080+ recomendado (probado hasta H200)\n- **AMD**: 7900 XTX 24GB y MI300X verificados (uso de memoria más alto que NVIDIA)\n- **Apple**: M3 Max+ con 24GB+ de memoria unificada para entrenamiento LoRA\n\n### Guías de memoria por tamaño de modelo\n\n- **Modelos grandes (12B+)**: A100-80G para full-rank, 24G+ para LoRA/Lycoris\n- **Modelos medianos (2B-8B)**: 16G+ para LoRA, 40G+ para entrenamiento full-rank\n- **Modelos pequeños (\u003c2B)**: 12G+ suficiente para la mayoría de tipos de entrenamiento\n\n**Nota**: La cuantización (int8/fp8/nf4) reduce significativamente los requisitos de memoria. Consulta las [guías de inicio rápido](#guías-de-inicio-rápido) para requisitos específicos por modelo.\n\n## Instalación\n\nSimpleTuner se puede instalar vía pip para la mayoría de los usuarios:\n\n```bash\n# Base installation (CPU-only PyTorch)\npip install simpletuner\n\n# CUDA users (NVIDIA GPUs)\npip install 'simpletuner[cuda]'\n\n# CUDA 13 / Blackwell users (NVIDIA B-series GPUs)\npip install 'simpletuner[cuda13]' --extra-index-url https://download.pytorch.org/whl/cu130\n\n# ROCm users (AMD GPUs)\npip install 'simpletuner[rocm]' --extra-index-url https://download.pytorch.org/whl/rocm7.1\n\n# Apple Silicon users (M1/M2/M3/M4 Macs)\npip install 'simpletuner[apple]'\n```\n\nPara instalación manual o setup de desarrollo, consulta la [documentación de instalación](/documentation/INSTALL.md).\n\n## Solución de problemas\n\nHabilita logs de depuración para más detalle agregando `export SIMPLETUNER_LOG_LEVEL=DEBUG` a tu archivo de entorno (`config/config.env`).\n\nPara análisis de rendimiento del loop de entrenamiento, configurar `SIMPLETUNER_TRAINING_LOOP_LOG_LEVEL=DEBUG` agrega marcas de tiempo que destacan problemas en tu configuración.\n\nPara una lista completa de opciones disponibles, consulta [esta documentación](/documentation/OPTIONS.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbghira%2Fsimpletuner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbghira%2Fsimpletuner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbghira%2Fsimpletuner/lists"}