|
| 1 | +# Inicio rapido de HeartMuLa |
| 2 | + |
| 3 | +En este ejemplo, entrenaremos el modelo HeartMuLa oss 3B de generacion de audio. |
| 4 | + |
| 5 | +## Vision general |
| 6 | + |
| 7 | +HeartMuLa es un transformador autoregresivo de 3B parametros que predice tokens de audio discretos a partir de etiquetas y letras. Los tokens se decodifican con HeartCodec para producir formas de onda. |
| 8 | + |
| 9 | +## Requisitos de hardware |
| 10 | + |
| 11 | +HeartMuLa es un modelo de 3B parametros, lo que lo hace relativamente liviano comparado con modelos grandes de generacion de imagenes como Flux. |
| 12 | + |
| 13 | +- **Minimo:** GPU NVIDIA con 12GB+ de VRAM (p. ej., 3060, 4070). |
| 14 | +- **Recomendado:** GPU NVIDIA con 24GB+ de VRAM (p. ej., 3090, 4090, A10G) para batch sizes mayores. |
| 15 | +- **Mac:** Compatible via MPS en Apple Silicon (requiere ~36GB+ de memoria unificada). |
| 16 | + |
| 17 | +### Requisitos de almacenamiento |
| 18 | + |
| 19 | +> ⚠️ **Advertencia sobre dataset de tokens:** HeartMuLa se entrena con tokens de audio precomputados. SimpleTuner no genera tokens durante el entrenamiento, asi que tu dataset debe proporcionar metadatos `audio_tokens` o `audio_tokens_path`. Los archivos de tokens pueden ser grandes, asi que planifica el espacio en disco. |
| 20 | +
|
| 21 | +> 💡 **Consejo:** Usar cuantizacion `int8-quanto` permite entrenar en GPUs con menos VRAM (p. ej., 12GB-16GB) con minima perdida de calidad. |
| 22 | +
|
| 23 | +## Requisitos previos |
| 24 | + |
| 25 | +Asegurate de tener un entorno Python 3.10+ funcional. |
| 26 | + |
| 27 | +```bash |
| 28 | +pip install simpletuner |
| 29 | +``` |
| 30 | + |
| 31 | +## Configuracion |
| 32 | + |
| 33 | +Se recomienda mantener tus configuraciones organizadas. Crearemos una carpeta dedicada para esta demo. |
| 34 | + |
| 35 | +```bash |
| 36 | +mkdir -p config/heartmula-training-demo |
| 37 | +``` |
| 38 | + |
| 39 | +### Ajustes criticos |
| 40 | + |
| 41 | +Crea `config/heartmula-training-demo/config.json` con estos valores: |
| 42 | + |
| 43 | +<details> |
| 44 | +<summary>Ver ejemplo de config</summary> |
| 45 | + |
| 46 | +```json |
| 47 | +{ |
| 48 | + "model_family": "heartmula", |
| 49 | + "model_type": "lora", |
| 50 | + "model_flavour": "3b", |
| 51 | + "pretrained_model_name_or_path": "HeartMuLa/HeartMuLa-oss-3B", |
| 52 | + "resolution": 0, |
| 53 | + "mixed_precision": "bf16", |
| 54 | + "base_model_precision": "int8-quanto", |
| 55 | + "data_backend_config": "config/heartmula-training-demo/multidatabackend.json" |
| 56 | +} |
| 57 | +``` |
| 58 | +</details> |
| 59 | + |
| 60 | +### Ajustes de validacion |
| 61 | + |
| 62 | +Anade estos valores a tu `config.json` para monitorear el progreso: |
| 63 | + |
| 64 | +- **`validation_prompt`**: Etiquetas o una descripcion del audio (p. ej., "Pop upbeat con sintetizadores brillantes"). |
| 65 | +- **`validation_lyrics`**: (Opcional) Letras para que el modelo cante. Usa una cadena vacia para instrumentales. |
| 66 | +- **`validation_audio_duration`**: Duracion en segundos para clips de validacion (predeterminado: 30.0). |
| 67 | +- **`validation_guidance`**: Escala de guidance (empieza alrededor de 1.5 - 3.0). |
| 68 | +- **`validation_step_interval`**: Con que frecuencia generar muestras (p. ej., cada 100 pasos). |
| 69 | + |
| 70 | +### Funciones experimentales avanzadas |
| 71 | + |
| 72 | +<details> |
| 73 | +<summary>Mostrar detalles experimentales avanzados</summary> |
| 74 | + |
| 75 | + |
| 76 | +SimpleTuner incluye funciones experimentales que pueden mejorar significativamente la estabilidad y el rendimiento del entrenamiento. |
| 77 | + |
| 78 | +* **[Scheduled Sampling (Rollout)](../experimental/SCHEDULED_SAMPLING.md):** reduce el sesgo de exposicion y mejora la calidad de salida dejando que el modelo genere sus propias entradas durante el entrenamiento. |
| 79 | + |
| 80 | +> ⚠️ Estas funciones aumentan la sobrecarga computacional del entrenamiento. |
| 81 | +
|
| 82 | +</details> |
| 83 | + |
| 84 | +## Configuracion del dataset |
| 85 | + |
| 86 | +HeartMuLa requiere un dataset **especifico para audio** con tokens precomputados. |
| 87 | + |
| 88 | +Cada muestra debe proporcionar: |
| 89 | + |
| 90 | +- `tags` (cadena) |
| 91 | +- `lyrics` (cadena; puede estar vacia) |
| 92 | +- `audio_tokens` o `audio_tokens_path` |
| 93 | + |
| 94 | +Los arrays de tokens deben ser 2D con forma `[frames, num_codebooks]` o `[num_codebooks, frames]`. |
| 95 | + |
| 96 | +> 💡 **Nota:** HeartMuLa no usa un codificador de texto separado, asi que no se requiere un backend de text-embeds. |
| 97 | +
|
| 98 | +### Opcion 1: Dataset de Hugging Face (tokens en columnas) |
| 99 | + |
| 100 | +Crea `config/heartmula-training-demo/multidatabackend.json`: |
| 101 | + |
| 102 | +<details> |
| 103 | +<summary>Ver ejemplo de config</summary> |
| 104 | + |
| 105 | +```json |
| 106 | +[ |
| 107 | + { |
| 108 | + "id": "heartmula-demo-data", |
| 109 | + "type": "huggingface", |
| 110 | + "dataset_type": "audio", |
| 111 | + "dataset_name": "your-org/heartmula-audio-tokens", |
| 112 | + "metadata_backend": "huggingface", |
| 113 | + "caption_strategy": "huggingface", |
| 114 | + "config": { |
| 115 | + "audio_caption_fields": ["tags"], |
| 116 | + "lyrics_column": "lyrics" |
| 117 | + } |
| 118 | + } |
| 119 | +] |
| 120 | +``` |
| 121 | +</details> |
| 122 | + |
| 123 | +Asegurate de que tu dataset incluya columnas `audio_tokens` o `audio_tokens_path` junto con los campos de texto. |
| 124 | + |
| 125 | +### Opcion 2: Archivos de audio locales + metadatos de tokens |
| 126 | + |
| 127 | +Crea `config/heartmula-training-demo/multidatabackend.json`: |
| 128 | + |
| 129 | +<details> |
| 130 | +<summary>Ver ejemplo de config</summary> |
| 131 | + |
| 132 | +```json |
| 133 | +[ |
| 134 | + { |
| 135 | + "id": "my-audio-dataset", |
| 136 | + "type": "local", |
| 137 | + "dataset_type": "audio", |
| 138 | + "instance_data_dir": "datasets/my_audio_files", |
| 139 | + "caption_strategy": "textfile", |
| 140 | + "metadata_backend": "discovery", |
| 141 | + "disabled": false |
| 142 | + } |
| 143 | +] |
| 144 | +``` |
| 145 | +</details> |
| 146 | + |
| 147 | +Asegurate de que tu backend de metadatos suministre `audio_tokens` o `audio_tokens_path` para cada muestra. |
| 148 | + |
| 149 | +### Estructura de datos |
| 150 | + |
| 151 | +Coloca tus archivos de audio en `datasets/my_audio_files`. SimpleTuner soporta una amplia gama de formatos incluyendo: |
| 152 | + |
| 153 | +- **Sin perdida:** `.wav`, `.flac`, `.aiff`, `.alac` |
| 154 | +- **Con perdida:** `.mp3`, `.ogg`, `.m4a`, `.aac`, `.wma`, `.opus` |
| 155 | + |
| 156 | +> ℹ️ **Nota:** Para soportar formatos como MP3, AAC y WMA, debes tener **FFmpeg** instalado en tu sistema. |
| 157 | +
|
| 158 | +Para etiquetas y letras, coloca archivos de texto correspondientes junto a tus archivos de audio si usas `caption_strategy: textfile`: |
| 159 | + |
| 160 | +- **Audio:** `track_01.wav` |
| 161 | +- **Etiquetas (Prompt):** `track_01.txt` (Contiene la descripcion de texto, p. ej., "Una balada de jazz lenta") |
| 162 | +- **Letras (Opcional):** `track_01.lyrics` (Contiene el texto de las letras) |
| 163 | + |
| 164 | +Proporciona los arrays de tokens mediante metadatos (por ejemplo, entradas `audio_tokens_path` que apunten a archivos `.npy` o `.npz`). |
| 165 | + |
| 166 | +<details> |
| 167 | +<summary>Ejemplo de estructura del dataset</summary> |
| 168 | + |
| 169 | +```text |
| 170 | +datasets/my_audio_files/ |
| 171 | +├── track_01.wav |
| 172 | +├── track_01.txt |
| 173 | +├── track_01.lyrics |
| 174 | +└── track_01.tokens.npy |
| 175 | +``` |
| 176 | +</details> |
| 177 | + |
| 178 | +> ⚠️ **Nota sobre letras:** HeartMuLa espera una cadena de letras para cada muestra. Para datos instrumentales, proporciona una cadena vacia en lugar de omitir el campo. |
| 179 | +
|
| 180 | +## Entrenamiento |
| 181 | + |
| 182 | +Inicia el entrenamiento especificando tu entorno: |
| 183 | + |
| 184 | +```bash |
| 185 | +simpletuner train env=heartmula-training-demo |
| 186 | +``` |
| 187 | + |
| 188 | +Este comando le dice a SimpleTuner que busque `config.json` dentro de `config/heartmula-training-demo/`. |
| 189 | + |
| 190 | +> 💡 **Consejo (Continuar entrenamiento):** Para continuar un fine-tuning desde una LoRA existente, usa la opcion `--init_lora`: |
| 191 | +> ```bash |
| 192 | +> simpletuner train env=heartmula-training-demo --init_lora=/path/to/existing_lora.safetensors |
| 193 | +> ``` |
| 194 | +
|
| 195 | +## Solucion de problemas |
| 196 | +
|
| 197 | +- **Errores de validacion:** Asegurate de no intentar usar funciones de validacion centradas en imagenes como `num_validation_images` > 1 (mapeado conceptualmente al batch size para audio) o metricas basadas en imagen (puntaje CLIP). |
| 198 | +- **Problemas de memoria:** Si te quedas sin memoria, intenta reducir `train_batch_size` o habilitar `gradient_checkpointing`. |
0 commit comments