Projeto leva inferência nativa do MiniMax-H3 ao Apple Silicon

Projeto h3.c: inferência nativa do MiniMax-H3 no Apple Silicon

O repositório antirez/h3.c implementa um motor de inferência nativa do modelo MiniMax-H3 para Macs com Apple Silicon. O desenvolvimento segue "fatias verticais" funcionais: metadata determinística do modelo, paridade de blocos Metal, codificação de prompt e geração de vídeo/áudio com condicionamento por primeiro/último frame e referências ordenadas (Ref2VA). Prompt-to-video/audio, first/last-frame conditioning e referências ordenadas já funcionam de ponta a ponta; o foco atual é otimização incremental de performance e memória em M3 Max e M5 Max.

Uso e presets de velocidade

O build é feito com make -j8 e a CLI oferece um modo interativo estilo Iris, mantendo o condicionamento BF16, o DiT preparado e o decoder de vídeo em memória para evitar recarregamentos. Comandos como !first, !last, !ref-image e !refs permitem controlar o condicionamento.

Há presets independentes de velocidade/qualidade: número de passos de denoising (--steps), reuso do denoiser (--reuse), blocos ativos do transformer (--layers), reuso de core (--core-reuse), redução de tokens (--token-reduction) e canvas interno menor com upscale via vImage (--render-width/--render-height).

Números-chave citados:

• O modo de 4 passos levou ~3,5 s no M5 Max, contra 26,4 s da referência de 29 passos, com SSIM de vídeo completo de 0,556.
• --ssd-streaming reduz o armazenamento rastreado do DiT de ~36,5 GiB para ~2,0 GiB em 512x512, tornando a passagem 50-blocos 84% mais lenta nesse caso (1,35 s vs 2,49 s), mas byte-idêntica.
• Token reduction cortou o perfil 45 layers + reuse 2 de 16,69 s para 12,60 s no M5 Max.
• O MLP int8 nativo no M5 reduziu um render fixo de 36,30 s (BF16 MPS) para 25,80 s, e o pico de armazenamento de tensores cai de 36,4 GiB para 25,9 GiB.

Resoluções e durações

Largura e altura devem ser múltiplos de 32 (mínimo 32), com produto máximo de 768 * 1344 pixels. O H3-Base é um modelo 768p. Tamanhos validados incluem 512x512 (mais seguro para desenvolvimento), 768x768, 1344x768 e 1024x768, além de canvases internos de 384x384 e 320x320 para upscale. Em 256x256 nativo, o modelo adapta coordenadas RoPE espaciais pela metade; 128x128 não é suportado.

O output é a 24 fps e os frames são alinhados para cima na forma 5 + 17*n. Exemplos: 22 frames (~0,92 s), 39 (~1,63 s), 107 (~4,46 s), 243 (~10,13 s) e 362 (~15,08 s). --seconds N aceita frações e converte para o formato temporal válido.

Prompt e referências multimodais

O sistema espera descrições no estilo Context-IR, cobrindo cena, ação, câmera, aparência e áudio. --seed controla o RNG (default 42). Para condicionamento, há caminhos distintos: FL2VA para primeiro/último frame (--first-frame, --last-frame) e Ref2VA para referências ordenadas (--ref-image, --ref-silent-video, --ref-video, --ref-video-audio, --ref-audio). Áudio de referência deve ter 2–15 segundos, com no máximo três entradas e duração total decodificada limitada a 15 s.

Implementação e performance

O texto detalha várias otimizações Metal: fusões exatas de AdaLN e residual gate, token reduction com bypass de estado full-resolution, mapeamento direto de pesos safetensors em GPUs M5, prefetch do text encoder Qwen com workers de I/O, streaming de SSD para o DiT, uso de Metal 4/TensorOps no M5 para projeções QKV e atenção, kernels especializados de patch e heads de saída, divisão do DiT em dois command buffers para sobrepor execução GPU e codificação CPU, aliasing de buffers de ativação e caching de wrappers MPSGraph.

O pipeline gera H.264 + AAC estéreo 32 kHz, decodificando o latente de áudio com BigVGAN/AudioVAE nativo. Testes (make test, make parity) comparam blocos Metal contra saídas MLX nomeadas, e o texto menciona correções relevantes na paridade de áudio estéreo e no layout interleaved de QKV do checkpoint.