training/NOTES.md

MiniMax H3 LoRA — anime loop i2v (projeto h3_loop)

Objetivo

LoRA de MiniMax H3 (FL2VA) no dataset AdwolfCzar/anime_loop_2d_dataset_captioned_29-07. Fase 1 ("quick"): 2 épocas nos ~3.9k clipes do mega_curated para validar o pipeline completo. Fase 2: treino com o dataset completo (loopcut_000..005, ~49 GB) ou o que couber. Foco de uso: image2video (primeiro frame → vídeo). Task de treino: i2va.

RUNBOOK — caminho das pedras (para o próximo agente/treino)

Sequência exata que funcionou, com os custos medidos. Scripts em scripts/, configs em configs/.

1. Ambiente: usar /venv/main (torch 2.10.0+cu130 — NÃO troque torch; nightly quebra CUBLAS). uv pip install -e . no fork Akane commit c4b84fa. uv pip install tensorboard (não vem). Se o venv der Permission denied: sudo chown -R claude:claude /venv/main.
2. Downloads (hf CLI com xet, muito rápido): pesos Comfy-Org/MiniMax-H3 (DiT bf16 66 GB + TE nvfp4 15 GB + 2 VAEs) e dataset. TE bf16 (48 GB) é desnecessário — nvfp4 funciona em Blackwell para cache E sampling do trainer.
3. Análise quantitativa do dataset ANTES de tudo (ffprobe em paralelo): fps real, SAR/DAR (DVDs 720×480 são anamórficos!), nb_frames, áudio. Sem isso o treino sai distorcido/errado.
4. Normalização (normalize_videos.py, ~30 jobs, ~15 min/4k clipes): 24 fps CFR + setsar=1
   • scale por SAR. Nunca treinar fonte com fps misto (uncanny motion) ou pixel anamórfico.
5. Extensão de loops (extend_loops.py): tiling do ciclo até escada 124/90/73/56 (canvas do H3 começa em ~124f; treinar 22f não é validado por ninguém). Loops = tiling limpo.
6. Buckets multi-res (assign_buckets.py): 3 áreas (512×288 / 640×384 / 832×480, 55/28/17), symlinks, sem upscale. Multi-res é OBRIGATÓRIA no H3 (RoPE por área) + jitter 0.2 no treino.
7. Smoke test (smoke_train.sh): 10 steps + sampling + checkpoint + resume (leg 2 com --max_train_steps 15 valida autoresume de verdade). Incluir os itens MAIS PESADOS por bucket.
8. Cache (cache_quick.sh): batch 24 + workers 16, SERIAL (latents → TE). Medido na 5090: latents ~4,5 h + TE ~1,5 h para 3.885 itens ≈ 31,7 GB. NUNCA rodar TE em paralelo com latents na mesma GPU (medido: piora ambos). Batch >24 não ajuda (VAE é o gargalo, GPU 100%).
9. Treino (train_quick.sh via tmux + tee log): receita anti-destilação completa (ver seção Receita). ~13 s/it na 5090 no regime 124f multi-res. Sampling+checkpoint a cada 500 steps.
10. Uploader HF (hf_uploader.py) ativo DESDE o smoke; repo gated manual, nunca "minimax" no nome.
11. Monitorar: loss média SOBE com preservation ligada — é normal, olhar val/loss de vídeo; watchdog de stall (freeze silencioso near-OOM = step 10x mais lento, não crasha).

Armadilhas que já custaram tempo aqui:

• ffmpeg pesado em paralelo durante CARGA do DiT → 6× mais lento (carga é CPU-bound); durante steps de treino, ok.
• Jupyter cria .ipynb_checkpoints root-owned dentro de output/ quando o usuário navega — rm -rf falha; usar sudo rm ou ignorar.
• Nunca pkill -f com padrão que casa com o próprio comando composto; matar por PID exato.
• Nunca apagar cache com processo de treino/cache vivo apontando para ele.
• Cache TOML separado do train TOML (batch alto só no cache; treino EXIGE batch_size=1).
• --save_last_n_steps_state 1500 limita states em disco (cada state = 859 MB).

Ambiente (medido em 2026-08-10)

• Vast.ai, RTX 5090 32 GB (sm_120), 124 GB RAM, 32 vCPU, disco 600 GB (overlay, não persistente)
• Python 3.12.13 em /venv/main, torch 2.10.0+cu130 (combinação validada pela comunidade)
• Trainer: fork AkaneTendo25/musubi-tuner, branch minimax-h3, commit c4b84fa (pin do relatório 2026-08-10)
• Instalação: uv pip install -e . (torch não é tocado — extras cu130 não instalados)
• ffmpeg 6.1.1 do sistema

Pesos

Comfy-Org/MiniMax-H3 → /workspace/models/MiniMax-H3/

• diffusion_models/minimax_h3_fl2va_bf16.safetensors (~66 GB; int8 convrot na carga)
• text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors (~15 GB; Blackwell OK)
• vae/minimax_h3_video_vae_fp16.safetensors, vae/minimax_h3_audio_vae_fp32.safetensors

Dataset — fatos medidos (mega_curated)

• 3.889 mp4 + 3.889 .txt (captions sidecar dentro do zip; jsonl tem 6.855 linhas, 2.966 com caption nula — os .txt do zip estão completos)
• Áudio: nenhum clipe tem trilha → h3_target_mode = "video" (sem audio VAE no cache, sequência menor)
• fps caótico: ~24 (2239), 25 (341), ~30 (182), centenas de variantes 22–29 (VFR/telecine)
• Resoluções: 720×480 anamórfico (SAR 853:720 e 186:157, ambos DAR ~16:9) ×1852; 1920×1080 ×1093; 1280×720 ×354; 704×396 ×245; 1270×720 ×104; 960×720 ×35; 640×480 ×7
• Frames pós-conversão 24fps, snap 17n+5: 22×1706, 39×875, 56×480, 73×199, 90×173, 107×114, 124×139; 4 itens < 22 frames (descartados)

Normalização (não-destrutiva)

scripts/normalize_videos.py: fonte /workspace/datasets/mega_curated (intocada) → /workspace/datasets/mega_24: 24 fps CFR (fps=24), pixels quadrados (scale por SAR + setsar=1), libx264 crf 15 preset fast, sem áudio. Clipes com <22 frames pós-conversão são pulados.

Buckets multi-resolução (obrigatório no H3 — RoPE normalizado por área)

Diretiva do usuário (10/08): resolução pequena/média, 1024×576 é alto demais. scripts/assign_buckets.py (seed 42, sem upscale, estratificado por resolução de origem):

• v288 [512×288] ×2138 (~55%) — movimento barato
• v384 [640×384] ×1087 (~28%) — bucket principal
• v480 [832×480] ×660 (~17%) — âncora de densidade média (v576 descartado; caches v384/v480 de smoke reaproveitados, cache v576 removido) Views por symlink em /workspace/datasets/train_quick/; manifest em configs/bucket_manifest_quick.csv.

Receita de treino (relatórios info/ de 09-10/08 + docs do fork)

• guidance 4 + schedule sigma + form normalized; preservation 0.02; spatial density jitter 0.2
• SEM adapter do Ostris; SDPA (flash_attn quebra int8 convrot); int8 convrot fwd bf16; AdaLN rank 16
• rank/alpha 32 (estilo amplo), LR 1e-4 AdamW8bit (recomendação do trainer), warmup 50
• batch físico 1 (obrigatório no H3), gradient_accumulation = 1
• 5090 32 GB: blocks_to_swap 24 h2d_only ring 2 pinned; PYTORCH_ALLOC_CONF=expandable_segments:True
• Sampling i2v durante treino: 3 primeiros-frames do próprio dataset + captions como estão (--i), TE nvfp4
• max_frames 124 (regime de extensão de loops — ver seção Extensão de loops)

Fase 2 — dimensionamento (medido)

• loopcut_000..005: 19.747 mp4 (~50 GB descomprimido), zero overlap de nomes com mega_curated
• Dataset completo fase 2 = loopcut (19.7k) + mega_curated (3.9k) ≈ 23,6k clipes
• Normalização 24fps concluída 10/08 06:5x: 19.746 ok (1 duplicata), zero falhas, 43 GB em loopcut_24
• Extensão de loops (mesma escada 124/90/73/56) → loopcut_24_ext, iniciada em seguida
• Extensão loopcut concluída: 4.592 tiled + 15.154 linked (clipes naturalmente longos), só 8,3 GB. Histograma: 124f×16490 (84%!), 107×1774, 90×1100, 73×269, 56×113
• Config fase 2 deve reintroduzir diversidade de duração: sub-datasets por bucket com max_frames 124/90/73 via symlinks (per-dataset max_frames no TOML, sem re-encode)
• Disco p/ fase 2: caches ~100-140 GB estimados, 341 GB livres — cabe; recalcular antes do caching

Log de execução

• 2026-08-10 04:1x: downloads iniciados (modelos ~86 GB, dataset completo ~52 GB) — xet, muito rápido
• 2026-08-10 04:2x: normalização 3.889 clipes lançada (30 jobs paralelos)

Incidentes

• 2026-08-10 04:47: smoke #1 (buckets antigos c/ v576) caiu no step 1 com FileNotFoundError — causa: remoção do cache v576 com o processo ainda vivo (erro operacional meu, não bug do trainer). Antes de cair validou: carga DiT bf16→int8 convrot (~2 min), sampling i2v 3/3 (pico 14,8 GiB), 1 step com loss 0.546 a 4,8 s/it. Smoke #2 relançado com buckets novos.

Extensão de loops (decisão técnica minha após pergunta do usuário, 2026-08-10 ~05:30)

Faixa publicada do H3 começa em 124 frames (5,17s); mediana do dataset era 42f. Como os clipes são loops seamless, cada clipe é estendido por tiling do ciclo até um alvo sorteado (seed determinística): 124f 55% / 90f 20% / 73f 15% / 56f 10%. Justificativa: canvas publicado do H3 comeca em ~124f; 44% do dataset natural estava em 22f (nunca validado por ninguem no canal); caso worldx documenta acao esticada ao gerar mais longo que o treinado. Contra: custo ~2,4x/step; canal treina 39-73f sem quebra especifica de duracao. Decisao: casar treino com regime de geracao (5s) vence o custo. Clipes ja maiores que o alvo ficam no comprimento natural (cap 124, symlink sem re-encode). Ensina movimento cíclico no regime real de geração (~5s). scripts/extend_loops.py → /workspace/datasets/mega_24_ext; max_frames=124; sampling --f 124. Custo: step médio ~2x vs regime 73f. Block swap mantido em 24 (teste com 16 não mostrou ganho; folga de VRAM protege contra freeze near-OOM, e o custo do swap no H3 é ~5% — compute-bound).

Smoke test (2026-08-10 ~05:10)

• Leg 1 (buckets novos 288/384/480): PASSOU exit 0 — 10 steps, loss 0.895→0.156, ~5-7 s/it (inclui overhead de saves), VRAM pico 23,5 GiB c/ swap 24, RAM 26 GB
• Sampling i2v 3/3 nas 3 resoluções: denoising 13,5s (512×288), 21s (640×384), 33s (832×480) a 20 steps; pico sampling 14-15 GiB; mp4+json escritos
• Checkpoint validado: 600 tensores LoRA, dim/alpha 32/32, 569 MB (fp32); state 859 MB
• Carga DiT bf16→int8: ~2 min sem contenção de CPU (com 24 ffmpeg paralelos: 6× mais lento — lição: pausar normalização pesada durante fases de carga)
• Leg 2 (resume + swap 16) em execução: valida autoresume e mede ganho de velocidade com menos swap
• Uploader HF verificado durante smoke (NOTES/configs subiram para AdwolfCzar/minih33-loop-i2v, gated manual)

Probe 124f + lançamento (2026-08-10 05:36-05:42)

• Probe 5 steps no regime estendido: PASSOU exit 0, ~12-13 s/it, loss 0.167→0.101, VRAM ~18 GiB no início dos steps (dimensionado pelos itens mais pesados nos smoke buckets)
• Sampling 124f: 35s (512×288) / 62s (640×384) / 108s (832×480) de denoising por vídeo; pico 16,7 GiB; ~3,5 min por evento de sampling (a cada 500 steps → overhead ~1%)
• 05:42 lançado tmux h3quick: cache completo (3.885 itens; batch final 24) → treino 2 épocas encadeado
• Log: /workspace/logs/quick_pipeline.log

Medições de cache (10/08 06:00-06:40)

• Latents batch 4: ~7 s/item; batch 12: ~5 s/item; batch 24: ~1,7-6,5 s/item conforme grupo de frames (124f domina). GPU 100% — VAE encode é o gargalo real; batch >24 não deve ajudar.
• TE em paralelo com latents na mesma GPU: FRACASSO (TE 11-12 s/item vs ~1,6 solo; latents +14%). GPU time-slicing serializa com overhead. Regra: estágios de cache SEMPRE seriais em single-GPU.
• Checkpoints do treino ajustados a pedido do usuário: a cada 500 steps (sampling idem); states retidos: últimos 1500 steps.

Fase 2 — config pronta (10/08 ~12:20)

• assign_buckets_phase2.py: loopcut 19.746 → v288 10.862 / v384 5.528 / v480 3.356; views de duração (≥124f: 70% f124 / 20% f90 / 10% f73): 9 sub-datasets em train_full/
• dataset_full_train.toml: 12 datasets (3 mega reutilizando cache/quick + 9 loopcut → cache/full)
• train_full.sh (minih33_full, 1 época default — revisar com resultados do quick), cache_full.sh

Treino quick — lançado (2026-08-10 12:12 UTC)

• Cache final: v288 13 GB + v384 9,7 GB + v480 9,0 GB = 31,7 GB (3.885 itens, latents+TE i2va+guidance)
• Duração total do caching (batch 24, serial): ~6h (latents ~4,5h + TE ~1,5h)
• Treino: 2 épocas = 7.770 steps; checkpoint+sampling a cada 500; disco a 49% no início
• Monitores: watchdog stall 15min, checkpoints/samples/erros, marcos do pipeline

Treino quick — ENCERRADO pelo usuário no step 2.500 (10/08 ~21:20 UTC)

• Rodou 2.564 steps a 12,8 s/it; loss 0.129→0.088; 5 checkpoints (500..2500) + samples no HF
• Usuário avaliou samples: "está aprendendo bem"; decidiu parar e ir para fase 2 maior
• Checkpoint 2500 convertido p/ ComfyUI (convert_lora.py --target other, chaves diffusion_model.*) → checkpoints/comfy/minih33_quick-step00002500_comfy.safetensors no repo

BUG da base preservation em c4b84fa (descoberto pelo canal em 10/08)

• Ada: preservation comparava contra o modelo COM a LoRA ativa → efeito nulo/parcial
• Fix: 5d06e34 "disable training LoRA for base preservation" (verificado no diff: toggle enabled no LoRAModule + teste); head atualizado para f175417
• Implicação: o quick run rodou na prática como "guidance 4 + jitter" — checkpoint VÁLIDO (guidance segura runs curtos), mas diz pouco sobre preservation em run longo
• Caches NÃO afetados (fix é na loss; chancelor retomou sem recache; diff não toca fingerprint)
• Validação externa: mamad8 24h+ em 8x4090 com a receita guidance4+prsv0.02+jitter SEM degradação

Fase 2 — revisão pós-relatório do outro agente (10/08 ~21:30)

• Fork: f175417 (fix preservation); re-smoke em execução
• Durações rebalanceadas 35/30/35 (f124/f90/f73) — corta step médio de ~12 p/ ~8-9 s/it
• Duas etapas: STAGE A main (v288+v384, mega+loopcut, 1 época ≈ 20,2k steps) → STAGE B polish (v480, 3.000 steps, --network_weights do LoRA final da A)
• --h3_fused_qk_norm_rope habilitado (recomendação Ada; validando no smoke)
• LR 1e-4 nas duas etapas — decisão explícita do usuário (recusou 5e-5)
• Block swap 24 mantido (benchmark Ada: 0 vs 48 blocos = 0,03 s/it — swap é grátis)
• Pipeline: launch_full_pipeline.sh (cache 12 datasets → stage A → stage B, tmux)

FASE 3 (composição nova definida pelo usuário, 10/08 ~21:30)

Substitui o plano "fase 2 completa". Dataset: mega_curated 3.889 (caches quick reutilizados) + loopcut 2.000 (seleção seeded estratificada por bucket/duração; não-selecionados deletados p/ liberar 38 GB) + looper_v4 10.000 → ~15,9k itens, ~2 épocas (31,8k steps), LR 1e-4 (usuário).

• looper_v4 (AdwolfCzar/looper_v4_dataset_captioned): 3 zips ~50 GB, 26,5k mp4, TUDO ~30fps SAR 1:1, resoluções web modernas (1080p/720p/4K + retrato/quadrado), 79% vira 107f em 24fps; 25.724 com captions; 1.222 curtos demais excluídos
• Prep looper: seleção seeded 10k → normalize 24fps + DOWNSCALE cap 0,61 MP (fonte 4K não serve p/ buckets ≤0,4MP) → SEM extensão de loop (107f natural já no regime; diversidade via views)
• Views compartilhadas train_p3/{bucket}_{dur} (loopcut2k + looper10k juntos), caches cache/p3/*
• Smoke f175417 completo: leg1 10 steps + resume leg (loss 0.185→0.066) com fused_qk_norm_rope
• Limpezas autorizadas executadas: extract_tmp, zips (todos), mega_curated raw, loopcut não-selecionado, states antigos — pico de 443 GB livres
• Entregas ao repo: guia_comfyui.md (resoluções/durações/uso), exemplo_de_captions.txt (100 aleatórias), checkpoint 2500 convertido p/ ComfyUI (convert_lora.py --target other)
• Armadilha nova p/ o runbook: NUNCA usar until pgrep -f <padrão> em background quando o próprio comando contém o padrão — o wrapper se auto-detecta e trava para sempre
• Armadilha (11/08, CAUSA REAL corrigida): vídeos com metadata não-UTF8 (tags latin-1) quebram o PyAV do musubi (av.open → avdict_to_dict → UnicodeDecodeError) — o ffprobe tolera, o PyAV não, e o ffmpeg PRESERVA metadata da fonte por default. Fix: remux lossless -c copy -map_metadata -1 nos 10k do looper (validação PyAV 10000/10000 ok) + -map_metadata -1 adicionado aos scripts de normalização. (Primeira hipótese "race de symlinks" estava errada.)

FASE 3 — treino LANÇADO e saudável (2026-08-11 16:48 UTC)

• Cache p3 completo: 100 GB (12k itens novos: loopcut-2k + looper-10k; mega reutilizou cache/quick) Latents ~14h + TE ~5h no total (incluindo os reruns dos incidentes de metadata)
• Treino minih33_v2: 2 épocas × 15.885 itens = 31.770 steps Medido no step 500: 10,15 s/it (rebalance de durações 35/30/35 + fused_qk_norm_rope entregaram: era 12,8 no quick), loss 0.116 caindo, VRAM 17,4 GB
• Config: f175417 (preservation FUNCIONAL), guidance 4/sigma/normalized, prsv 0.02, jitter 0.2, LR 1e-4 (decisão do usuário), rank 32, swap 24, checkpoint+sampling a cada 500 + upload HF
• Samples step 0 e step 500 (3/3 cada) no repo; primeiro checkpoint 500 salvo
• Projeção aritmética (não promessa): ~3,7 dias para as 2 épocas; checkpoints utilizáveis desde já (quick mostrou sinal bom em ~2,5k steps)
• Disco: 333 GB livres após tudo | Watchdog stall + monitores de erro ativos

RUN v3 (12/08 ~04:1x UTC) — decisões do usuário após avaliação dos samples v2

Contexto: samples do v2 a 3,5k steps considerados fracos pelo usuário. Diagnóstico: (1) f175417 NÃO tem o fix 365d980 (amostragem da preservation + propagação do jitter + alinhamento sigma-guidance) — receita parcialmente torta pela 3ª vez; (2) doutrina do canal virou em 11/08: LR 1e-4 é alto para H3 destilado (rank 32 → 2-5e-5); (3) preservation freia 2x por design. Decisões (usuário): fork f8561f6c; LR 5e-5; SEM preservation (vai parar cedo por checkpoint- picking, prioriza aprendizado rápido; guidance 4 + jitter 0.2 ficam); max 2 épocas (31,8k steps) mas parada manual a qualquer momento; restart DO ZERO (10h de GPU descartadas por baseline limpo); output_v3/ + repo novo AdwolfCzar/minih33-loop-i2v-v3 (gated manual) com uploader próprio. v2 encerrado no step ~3.5k (checkpoints 500-3500 + samples preservados no repo original). Novidade do f8561f6c: checkpoint sob demanda por arquivo-gatilho (parada graciosa a qualquer momento — casa exatamente com o plano de parada manual do usuário).

Incidente v3: OOM no step ~4.502 (12/08 15:1x UTC) — RECUPERADO

• CUDA OOM (alocação de 1,12 GiB com 30,08 GiB já alocados) após 11h de run — batch pesado no pior bucket; expandable_segments estava ativo (fragmentação não era a causa; VRAM cheia real)
• Fix: blocks_to_swap 24→32 (~3 GiB a mais de folga; custo ~zero, H3 é compute-bound) + autoresume do state 4500. Checkpoints 500-4500 + samples intactos no repo v3
• Lição p/ runbook: em runs >10h na 5090, swap 32 desde o início; monitores com tail -n 0 (log em append guarda Tracebacks antigos → falso alarme no relançamento)

FASE 4 — dois treinos separados (decisão do usuário, 14/08)

v3 encerrado no step 17.500 (usuário: "já tá bom o suficiente"). Caches antigos apagados (449 GB livres). Agora: um treino por dataset, um de cada vez — smoothloop primeiro, jiggle depois; 10 épocas cada (parada manual quando estiver bom).

SMOOTHLOOP (966 clipes)

• Fontes: 2 pastas mega.nz + 1 arquivo mega (zip 5 GB) + zip do HF smoothloop_dataset_base_v2
• Dedup real (o palpite do usuário estava certo): 1.863 mp4 → 966 únicos 444 duplicatas exatas (md5 do conteúdo) + 444 mesmo-ID re-encodado em outra fonte
• Captions casadas por stem entre fontes (o zip do mega3 tinha 1.580 captions p/ 505 vídeos — as fontes se complementam; matching por sibling .txt teria perdido a maioria)
• Normalização p4: 24fps CFR + SAR + cap 0,61 MP + -map_metadata -1; 966/966 ok, mediana 236f (78% já ≥124f → sem tiling de loop)
• Views: v288 532 / v384 270 / v480 164 × f124/f90/f73; cache 11 GB (966 latents + 966 TE)
• Config: idêntica ao minih33_v3 (verificado por diff), só muda dataset/output/samples/épocas
• Repo: AdwolfCzar/minih33-smoothloop (gated) + uploader + conversor ComfyUI automático

JIGGLE (1.232 clipes) — preparado, aguardando o fim do smoothloop

• bouncing_body_jiggle_captioned_30-07; cap 800 por nível (medium 866→800, low 225, intense 272)
• Triggers por nível aplicados na caption conforme README do dataset: "bouncing body, " → "bouncing body with {low,medium,intense} jiggle and bouncing, "
• Normalizado: 1.232 ok, 65 curtos demais descartados

Armadilha nova (14/08)

--max_train_steps N NÃO limita quando o script já passa --max_train_epochs M — o smoke de 8 steps virou treino real de 230 steps antes de eu notar. Para smoke com esses scripts, sobrescreva TAMBÉM as épocas (ou use um script dedicado).

Publicação HF (resolvido 10/08)

Repo AdwolfCzar/minih33-loop-i2v — público (sem custo de cota privada) + gated manual (arquivos só baixáveis com aprovação do dono). Regra do usuário: nunca mencionar "minimax" no nome/card público; identificador: minih33. Uploader: scripts/hf_uploader.py (watch em output/).