Soup unifica fine-tuning de LLMs em um único arquivo YAML

O que é o Soup

Soup é uma ferramenta de linha de comando de código aberto (licença Apache-2.0) que promete simplificar o fine-tuning e o pós-treino de LLMs em um único comando, com toda a configuração em um único arquivo YAML - sem SSH nem múltiplos arquivos de configuração. A instalação é feita via pip install "soup-cli[train]", seguida de soup init --template chat e soup train. O projeto mantém repositório no GitHub com 6,8 mil estrelas e 1,1 mil forks, com 1.335 commits.

A proposta ataca um gargalo apontado pelo próprio projeto: segundo o README, equipes experientes gastam de 30% a 50% do tempo combatendo infraestrutura em vez de melhorar modelos. O Soup automatiza batch size, detecção de GPU e quantização, funciona localmente com QLoRA sem exigir nuvem e oferece uma interface web local (soup ui) para acompanhar métricas, explorar datasets e conversar com o modelo treinado.

Layer streaming: 8B em uma GPU de 4 GB

O recurso de destaque é o layer streaming: o modelo base congelado fica fora da VRAM e é alimentado à GPU um decoder layer por vez. Medido em uma RTX 3050 Laptop de 4 GB, o Llama-3.1-8B-Instruct com quantização NF4 atingiu 119,6 tok/s com pico de 3,32 GB - bit-exato contra uma execução normal com o modelo residente, e reproduzido de forma independente em uma H100 a 113,00 tok/s no mesmo pico de memória. O recurso é opt-in (stream_layers: true) e ainda está em beta. Os autores ressalvam que o número de tok/s foi medido na v0.72.2, antes de um reparo de correção da v0.73.0 que custou −4,8% no teste em 32B, e não foi refeito em placa de 4 GB desde então.

A técnica é descrita em um preprint no Zenodo (versão 3, de 13 de agosto de 2026). A v3 retrai uma explicação publicada antes - a de que o streaming era limitado pela transferência host-device - após medições em 11 de agosto mostrarem que remover toda transferência host-to-device compra apenas 1,4% e o maior custo específico do streaming é a dequantização NF4 por camada (9,8%). A mesma versão documentou um defeito silencioso de gradiente errado no NF4 acima de ~165 MiB por camada, com causa nomeada na biblioteca upstream e reparo validado contra controles em modelos reais de 32B e 72B.

Novidades da v0.75.0

A v0.75.0 corrigiu um problema grave: o mesmo soup.yaml treinava uma receita diferente no backend MLX do que no transformers, silenciosamente. Seis opções de treino eram validadas e documentadas, mas nenhum código do backend MLX as lia. O release faz com que o MLX respeite a configuração aceita (train_on_responses_only, warmup_ratio, scheduler, weight_decay, optimizer, max_grad_norm, gradient_accumulation_steps, gradient_checkpointing); dos 32 nomes de otimizador, apenas 8 têm equivalente em MLX e os outros 24 agora são recusados pelo nome em vez de virar AdamW silenciosamente. Também foi corrigida a perda de validação, que era calculada em todos os backends e descartada sem registro.

Mudanças significativas (breaking): chaves de configuração desconhecidas agora recusam o carregamento (um erro de digitação como quantizaton antes era descartado, e o treino seguia com a configuração não aplicada); grpo_variant: gspo passou a ser o objetivo de nível de sequência publicado (arXiv:2507.18071), substituindo uma heurística de centralização por coluna, e configurações gspo existentes não reproduzirão execuções anteriores. A v0.75 também endureceu a segurança da Web UI (autenticação nos endpoints de leitura e SSE, tickets de uso único), resolveu incompatibilidade com torch>=2.6.0 que deixava treinadores de preferência inoperantes e corrigindo crashes com loraplus_lr_ratio e packing: true. Suporte limitado a Python 3.10–3.12, pois no 3.13+ o pip resolve rodas de PyTorch não testadas que travam antes de o Soup rodar.

Todas as 60 pull requests desse release vieram de fora do mantenedor, por 22 pessoas.

Ecossistema e requisitos

O Soup cobre SFT, DPO, GRPO, PPO, KTO, ORPO, SimPO, IPO, BCO, tool-calling, destilação, classificação, visão, áudio, TTS e unlearning, com mais de 100 receitas prontas para famílias como Llama 3.x/4, Qwen 2.5/3, Gemma 3, Mistral, DeepSeek e Phi-4. Funciona com qualquer modelo de geração de texto do HuggingFace Hub que carregue via AutoModelForCausalLM. Exporta para GGUF (Ollama/llama.cpp), ONNX, TensorRT, AWQ, GPTQ e BitNet. Com QLoRA 4-bit, o guia de VRAM indica ~7B em 8 GB, ~14B em 16 GB, ~34B em 24 GB e ~70B em 48 GB. Há imagem Docker publicada no GHCR e o projeto afirma que é mantido abertamente em um único laptop de 4 GB, com números de performance medidos em vez de apenas afirmados; doações são direcionadas a comprar tempo de GPU para trabalho bloqueado por hardware.