Inicio rápido de ACE-Step¶

En este ejemplo, entrenaremos el modelo de generación de audio ACE-Step. SimpleTuner soporta actualmente la ruta original ACE-Step v1 3.5B y el entrenamiento LoRA con compatibilidad hacia delante para el bundle ACE-Step v1.5.

Visión general¶

ACE-Step es un modelo de audio basado en transformer y flow-matching diseñado para síntesis de alta calidad. En SimpleTuner:

• base apunta a la ruta de entrenamiento original de ACE-Step v1 3.5B.
• v15-turbo, v15-base y v15-sft apuntan a las variantes del bundle ACE-Step v1.5 cargadas desde ACE-Step/Ace-Step1.5.

Requisitos de hardware¶

ACE-Step es un modelo de 3.5B parámetros, lo que lo hace relativamente liviano comparado con modelos grandes de generación de imágenes como Flux.

• Mínimo: GPU NVIDIA con 12GB+ de VRAM (p. ej., 3060, 4070).
• Recomendado: GPU NVIDIA con 24GB+ de VRAM (p. ej., 3090, 4090, A10G) para batch sizes mayores.
• Mac: Compatible vía MPS en Apple Silicon (requiere ~36GB+ de memoria unificada).

Requisitos de almacenamiento¶

⚠️ Advertencia de uso de disco: El caché VAE para modelos de audio puede ser sustancial. Por ejemplo, un clip de audio de 60 segundos puede producir un archivo latente en caché de ~89MB. Esta estrategia de caché se usa para reducir drásticamente los requisitos de VRAM durante el entrenamiento. Asegúrate de tener suficiente espacio en disco para el caché de tu dataset.

💡 Consejo: Para datasets grandes, puedes usar la opción --vae_cache_disable para deshabilitar la escritura de embeddings a disco. Esto habilita implícitamente el caché bajo demanda, lo que ahorra espacio en disco pero aumentará el tiempo de entrenamiento y el uso de memoria porque las codificaciones se realizan durante el bucle de entrenamiento.

💡 Consejo: Usar cuantización int8-quanto permite entrenar en GPUs con menos VRAM (p. ej., 12GB-16GB) con mínima pérdida de calidad.

Requisitos previos¶

Asegúrate de tener un entorno Python 3.10+ funcional.

pip install simpletuner

Configuración¶

Se recomienda mantener tus configuraciones organizadas. Crearemos una carpeta dedicada para esta demo.

mkdir -p config/acestep-training-demo

Ajustes críticos¶

SimpleTuner soporta actualmente estos flavours de ACE-Step:

• base: ACE-Step v1 3.5B original
• v15-turbo, v15-base, v15-sft: variantes del bundle ACE-Step v1.5

Usa la configuración que corresponda a tu variante objetivo.

Hay presets de ejemplo listos para usar en:

• simpletuner/examples/ace_step/base/default/v1-0.peft-lora
• simpletuner/examples/ace_step/v15-base/default/v1-5.peft-lora

Puedes iniciarlos directamente con simpletuner train example=ace_step/base/default/v1-0.peft-lora o simpletuner train example=ace_step/v15-base/default/v1-5.peft-lora.

Ejemplo ACE-Step v1¶

Crea config/acestep-training-demo/config.json con estos valores:

{
  "model_family": "ace_step",
  "model_type": "lora",
  "model_flavour": "base",
  "pretrained_model_name_or_path": "ACE-Step/ACE-Step-v1-3.5B",
  "resolution": 0,
  "mixed_precision": "bf16",
  "base_model_precision": "int8-quanto",
  "data_backend_config": "config/acestep-training-demo/multidatabackend.json"
}

Ejemplo ACE-Step v1.5¶

Para ACE-Step v1.5, mantén model_family: "ace_step", selecciona un flavour v1.5 y apunta el checkpoint raíz al bundle compartido v1.5:

{
  "model_family": "ace_step",
  "model_type": "lora",
  "model_flavour": "v15-base",
  "pretrained_model_name_or_path": "ACE-Step/Ace-Step1.5",
  "trust_remote_code": true,
  "resolution": 0,
  "mixed_precision": "bf16",
  "base_model_precision": "int8-quanto",
  "data_backend_config": "config/acestep-training-demo/multidatabackend.json"
}

Ajustes de validación¶

Añade estos valores a tu config.json para monitorear el progreso:

• validation_prompt: Una descripción de texto del audio que quieres generar (p. ej., "A catchy pop song with upbeat drums").
• validation_lyrics: (Opcional) Letras para que el modelo cante.
• validation_prompt_library: Usa "audio" para la biblioteca integrada de caption + lyrics.
• validation_audio_duration: Duración en segundos para clips de validación (predeterminado: 30.0).
• validation_guidance: Escala de guidance (predeterminado: ~3.0 - 5.0).
• validation_step_interval: Con qué frecuencia generar muestras (p. ej., cada 100 pasos).

ℹ️ Nota sobre ACE-Step v1.5: SimpleTuner ahora soporta renders de validación integrados para v1.5 con prompt y letras opcionales. Cargar el repositorio upstream v1.5 todavía requiere trust_remote_code: true, y los workflows avanzados de edición/inferencia upstream aún no están expuestos en la pipeline de validación de SimpleTuner.

Funciones experimentales avanzadas¶

Configuración del dataset¶

ACE-Step requiere una configuración de dataset específica para audio.

Para expandir una identidad vocal objetivo entre estilos o géneros, configura el workflow RVC data_transforms descrito en Voice Cloning Data Transforms.

Opción 1: Dataset demo (Hugging Face)¶

Para un inicio rápido, puedes usar el preset preparado ACEStep-Songs.

Crea config/acestep-training-demo/multidatabackend.json:

[
  {
    "id": "acestep-demo-data",
    "type": "huggingface",
    "dataset_type": "audio",
    "dataset_name": "Yi3852/ACEStep-Songs",
    "metadata_backend": "huggingface",
    "caption_strategy": "huggingface",
    "cache_dir_vae": "cache/vae/{model_family}/acestep-demo-data"
  },
  {
    "id": "text-embeds",
    "dataset_type": "text_embeds",
    "default": true,
    "type": "local",
    "cache_dir": "cache/text/{model_family}"
  }
]

Consulta las opciones y requisitos de caption_strategy en DATALOADER.md.

Opción 2: Archivos de audio locales¶

Crea config/acestep-training-demo/multidatabackend.json:

[
  {
    "id": "my-audio-dataset",
    "type": "local",
    "dataset_type": "audio",
    "instance_data_dir": "datasets/my_audio_files",
    "caption_strategy": "textfile",
    "metadata_backend": "discovery",
    "disabled": false
  },
  {
    "id": "text-embeds",
    "dataset_type": "text_embeds",
    "default": true,
    "type": "local",
    "cache_dir": "cache/text/{model_family}"
  }
]

Estructura de datos¶

Coloca tus archivos de audio en datasets/my_audio_files. SimpleTuner soporta una amplia gama de formatos, incluyendo:

• Sin pérdida: .wav, .flac, .aiff, .alac
• Con pérdida: .mp3, .ogg, .m4a, .aac, .wma, .opus

ℹ️ Nota: Para soportar formatos como MP3, AAC y WMA, debes tener FFmpeg instalado en tu sistema.

Para captions y letras, coloca los archivos de texto correspondientes junto a tus archivos de audio:

• Audio: track_01.wav
• Caption (Prompt): track_01.txt (contiene la descripción de texto, p. ej., "A slow jazz ballad")
• Lyrics (Opcional): track_01.lyrics (contiene el texto de las letras)

datasets/my_audio_files/
├── track_01.wav
├── track_01.txt
└── track_01.lyrics

💡 Avanzado: Si tu dataset usa una convención de nombres diferente (p. ej., _lyrics.txt), puedes personalizar esto en tu configuración del dataset.

"audio": {
  "lyrics_filename_format": "{filename}_lyrics.txt"
}

⚠️ Nota sobre lyrics: Si no se encuentra un archivo .lyrics para una muestra, los embeddings de letras se rellenan con ceros. ACE-Step espera condicionamiento con letras; entrenar fuertemente con datos sin letras (instrumentales) puede requerir más pasos para que el modelo aprenda a generar audio instrumental de alta calidad con entradas de letras en cero.

Entrenamiento¶

Inicia el entrenamiento especificando tu entorno:

simpletuner train env=acestep-training-demo

Este comando le dice a SimpleTuner que busque config.json dentro de config/acestep-training-demo/.

💡 Consejo (Continuar entrenamiento): Para continuar el fine-tuning desde una LoRA existente (p. ej., los checkpoints oficiales de ACE-Step o adaptadores de la comunidad), usa la opción --init_lora:

simpletuner train env=acestep-training-demo --init_lora=/path/to/existing_lora.safetensors

Entrenar el embedder de letras (estilo upstream)¶

ℹ️ Nota de versión: lyrics_embedder_train actualmente solo aplica a la ruta de entrenamiento ACE-Step v1. La ruta LoRA forward-compatible de v1.5 en SimpleTuner es solo del decoder.

El trainer upstream de ACE-Step ajusta el embedder de letras junto con el denoiser. Para reflejar ese comportamiento en SimpleTuner (solo full o LoRA estándar):

• Habilítalo: lyrics_embedder_train: true
• Overrides opcionales (de lo contrario se reutilizan el optimizador/scheduler principal):
• lyrics_embedder_lr
• lyrics_embedder_optimizer
• lyrics_embedder_lr_scheduler

Fragmento de ejemplo:

{
  "lyrics_embedder_train": true,
  "lyrics_embedder_lr": 5e-5,
  "lyrics_embedder_optimizer": "torch-adamw",
  "lyrics_embedder_lr_scheduler": "cosine_with_restarts"
}

Los pesos del embedder se guardan con los saves de LoRA y se restauran al reanudar.

Solución de problemas¶

• Errores de validación: Asegúrate de no usar funciones de validación centradas en imagen como num_validation_images > 1 (mapeado conceptualmente a batch size para audio) o métricas basadas en imágenes (puntuación CLIP).
• Problemas de memoria: Si tienes OOM, intenta reducir train_batch_size o habilitar gradient_checkpointing.

Migrar desde el trainer upstream¶

Si vienes de los scripts originales de entrenamiento de ACE-Step, aquí tienes cómo se mapean los parámetros a config.json de SimpleTuner:

Convertir datos sin procesar¶

Si tienes archivos de audio/texto/letras sin procesar y quieres usar el formato de dataset de Hugging Face (como usa la herramienta upstream convert2hf_dataset.py), puedes usar el dataset resultante directamente en SimpleTuner.

El convertidor upstream produce un dataset con columnas tags y norm_lyrics. Para usarlas, configura tu backend así:

{
    "type": "huggingface",
    "dataset_type": "audio",
    "dataset_name": "path/to/converted/dataset",
    "config": {
        "audio_caption_fields": ["tags"],
        "lyrics_column": "norm_lyrics"
    }
}