Unsloth Docker: treine e rode modelos de IA localmente sem configurar nada

A imagem Docker do Unsloth resolve um dos piores problemas do trabalho com IA local: a configuração do ambiente. Em vez de brigar com versões de CUDA, PyTorch e dezenas de dependências, você baixa um único contêiner e começa a treinar modelos.

A proposta é simples de entender e poderosa na prática. O Unsloth empacota o conjunto inteiro de ferramentas de ajuste fino em uma imagem pronta, com interface gráfica incluída. Este guia explica o que vem dentro, como instalar e o que esperar de desempenho.

O que é o Unsloth Docker

O Unsloth Docker é uma imagem oficial que reúne o stack completo de treinamento e inferência do Unsloth em um contêiner de 9,2 GB. Você não instala bibliotecas uma a uma; você roda um comando e o ambiente aparece pronto.

Quem já tentou treinar LLM localmente com Docker sem uma imagem pronta conhece o ritual. A versão do CUDA precisa bater com a do PyTorch, que precisa bater com o driver. Depois vêm bitsandbytes, xformers, TRL e PEFT, cada um uma nova chance de encher a tela de erro. A resposta do Unsloth é direta: pare de instalar, use o ambiente já montado.

A imagem também marca a parceria com o Docker. O Unsloth agora alimenta a maioria dos modelos GGUF no Docker, e a integração roda modelos com um único comando, sem dependências quebradas.

O que vem dentro da imagem Docker do Unsloth

A lista de componentes é o motivo para usar o contêiner em vez de montar o ambiente à mão.

• PyTorch 2.11 sobre CUDA 12.8.
• Unsloth e unsloth-zoo.
• bitsandbytes, TRL e PEFT.
• xformers, apenas na plataforma Linux/amd64.
• llama.cpp pré-compilado para inferência.
• whisper.cpp na tag mais recente, para transcrição de fala no Studio.
• Unsloth Studio, a interface web gráfica.
• JupyterLab com notebooks de exemplo.

Há duas versões principais da imagem. A tag latest, também chamada studio, traz o pacote completo: interface web do Studio, JupyterLab, notebooks de exemplo e acesso SSH por chave. A tag core traz o stack de treinamento mais o JupyterLab, sem o Studio, e serve para scripts e integração contínua, ou para quem quer uma imagem mais leve.

A imagem ocupa 9,2 GB e já passou de 100 mil downloads acumulados. As tags principais são reconstruídas diariamente e a cada lançamento.

Como instalar o Unsloth com Docker

A instalação tem dois caminhos, e nenhum exige configuração manual de dependências.

Método 1: pelo terminal

1. Instale o Docker, seja o Docker Desktop ou o Docker CE.
2. Verifique se o comando docker responde no terminal.
3. Baixe e rode a imagem com um comando.
4. Acesse o JupyterLab ou o Unsloth Studio pelo navegador.

O comando básico para subir o contêiner com acesso à GPU é:

docker run --gpus all -it unslothai/unsloth

Para rodar um modelo direto, sem treinar, o Docker Model Runner simplifica ainda mais. Um comando carrega o modelo desejado, como o gpt-oss-20B da OpenAI, sem escrever código.

Método 2: pelo Docker Desktop, sem código

1. Abra o Docker Desktop e vá até a aba de modelos.
2. Selecione a opção de adicionar modelos ou abra o Docker Hub.
3. Busque o modelo desejado no catálogo verificado.
4. Baixe e execute pela própria interface.

O catálogo do Docker Hub usa, por padrão, a quantização dinâmica de 4 bits do Unsloth, mas você pode escolher outro nível de quantização ao baixar.

Unsloth Studio: a interface gráfica no navegador

O Unsloth Studio é o que torna a imagem acessível a quem não quer escrever código. É uma interface web que roda dentro do contêiner e permite treinar, ajustar e testar modelos por cliques.

Os dados persistem no volume unsloth-studio. Isso significa que suas contas, conversas e modelos treinados sobrevivem quando você remove o contêiner com docker rm. Cada imagem traz o próprio código do Studio, e um volume criado por uma imagem antiga é migrado no primeiro início, com o código anterior preservado em uma pasta de legado.

A vantagem é não perder trabalho. Quem treina modelos sabe quanto tempo um ajuste fino consome, e ter a garantia de que o modelo sobrevive a uma troca de imagem muda a forma de experimentar.

Requisitos de hardware e desempenho

Antes de baixar qualquer modelo, vale entender a matemática de memória. Afinal, de que adianta ter o ambiente pronto se o modelo não cabe na sua máquina?

Para o melhor desempenho, a soma de VRAM e RAM deve ser igual ou maior que o tamanho do modelo quantizado. Se faltar, o modelo ainda roda, mas fica bem mais lento. Como referência, quando o modelo cabe por pouco na memória, espere algo perto de 5 tokens por segundo, dependendo do tamanho.

Um exemplo ajuda. Se você baixa o gpt-oss-20B em F16, o modelo tem cerca de 13,8 GB. Garanta que o espaço em disco e a soma de RAM com VRAM passem desse valor.

Sobre quantização, há duas regras práticas. Para modelos com menos de 30 bilhões de parâmetros, use pelo menos 4 bits. Para modelos com 70 bilhões de parâmetros ou mais, use no mínimo 2 bits, como a quantização UD_Q2_K_XL.

Onde o Unsloth Docker se destaca

O ajuste fino de LLM local nunca foi fácil, e o Unsloth ficou conhecido por espremer trabalhos de treinamento em menos VRAM. A imagem leva essa vantagem para um pacote reprodutível.

A reprodutibilidade é o ganho silencioso. Como o ambiente é idêntico em qualquer máquina, o problema de "funciona no meu computador" desaparece. Em equipe, isso significa que o modelo treinado por uma pessoa roda igual na máquina de outra.

A portabilidade vem junto. As tags principais são multi-arquitetura, cobrindo Linux/amd64 e Linux/arm64, o que inclui máquinas ARM. Para AMD, existe a imagem unsloth/unsloth-rocm, uma versão ROCm do mesmo stack. Ou seja, o suporte a NVIDIA e AMD está resolvido sem que você monte nada.

Por fim, as tags nightly são mantidas por 60 dias, ao lado das tags com versão fixa. Isso dá a quem precisa de estabilidade a opção de travar uma versão, e a quem quer o mais novo a opção de acompanhar o desenvolvimento.

Limitações do Unsloth Docker

Nem tudo é ganho, e é justo apontar o que exige atenção.

• Tamanho. A imagem tem 9,2 GB, sem contar os modelos, que costumam ser maiores ainda.
• Memória. Modelos grandes exigem VRAM somada à RAM compatível com o tamanho. Faltando memória, o desempenho cai bastante.
• Armazenamento. Treinar modelos consome disco depressa, e o volume do Studio precisa de espaço para guardar contas, conversas e modelos.
• Hardware limitado. Sem GPU adequada, o ajuste fino fica lento a ponto de inviabilizar experimentos maiores, sobretudo quando o modelo passa de dezenas de bilhões de parâmetros e cada etapa de treinamento leva horas em vez de minutos.
• Curva inicial. A interface do Studio reduz a barreira, mas entender quantização e requisitos de memória continua sendo necessário.

Nada disso anula a proposta. Só mostra que a imagem elimina o problema de configuração, não o de hardware.

Como começar com o Unsloth Docker

1. Confirme que sua máquina tem espaço em disco e memória suficientes para o modelo pretendido.
2. Instale o Docker, Desktop ou CE.
3. Baixe a imagem unsloth/unsloth na versão que faz sentido para você.
4. Suba o contêiner com acesso à GPU.
5. Abra o Unsloth Studio no navegador ou o JupyterLab, conforme preferir.
6. Escolha um modelo pequeno para o primeiro teste e aumente depois.

Começar pequeno ajuda a calibrar o que sua máquina aguenta antes de investir horas em um modelo grande que não vai caber na memória. Esta imagem Docker para treinar modelos de IA foi feita justamente para encurtar esse caminho, mas o teste gradual continua sendo a melhor estratégia.

Problemas comuns com o Unsloth Docker

O contêiner não acessa a GPU. Confirme que o Docker tem suporte a GPU habilitado e que você usou a flag de acesso às GPUs ao subir o contêiner.

O modelo roda muito devagar. Provavelmente faltou memória. Verifique se a soma de VRAM e RAM cobre o tamanho do modelo quantizado. Se o modelo cabe por pouco, espere algo perto de 5 tokens por segundo.

Perdi meus modelos ao remover o contêiner. Use o volume unsloth-studio. Ele mantém contas, conversas e modelos treinados entre remoções.

Uso uma placa AMD. Baixe a imagem unsloth/unsloth-rocm, uma versão ROCm do mesmo stack.

A imagem é grande demais para meu ambiente. A tag core traz só o stack de treinamento e o JupyterLab, sem o Studio, e é a opção mais leve.

Depois de configurar o ambiente, mantenha a imagem atualizada e revise as permissões e as configurações de privacidade do contêiner antes de conectar dados sensíveis. Rodar modelos localmente aumenta o controle sobre os dados, mas vale confirmar o que o ambiente acessa e o que fica salvo no disco.

Em resumo

O Unsloth Docker transforma uma das piores tarefas da IA local em um único comando. A imagem reúne o stack completo de treinamento, uma interface gráfica no navegador e notebooks prontos, com suporte a NVIDIA e AMD e opções para arquiteturas distintas. Para quem sempre quis experimentar ajuste fino, mas travou na configuração de ambiente, esse é o caminho mais curto. O critério antes de começar é simples: verifique memória e disco, comece por um modelo pequeno e suba de tamanho conforme a máquina responder. Feito isso, o Unsloth Docker deixa de ser uma imagem grande e vira uma oficina de modelos pronta para uso.