Configuração do Ambiente Spark

O DGX Spark vem com um chip GB10 Grace Blackwell: CPU aarch64, GPU SM121, 128GB de memória unificada, CUDA 13. Esta é uma plataforma mais restrita e nova do que uma caixa CUDA 12 x86 padrão, então a seleção de pacotes e a compatibilidade de ABI importam mais do que o usual — o ecossistema de wheels para aarch64 + CUDA 13 ainda está em desenvolvimento.

Quando Usar Esta Skill

• Configurando uma nova caixa Spark para treinamento ou inferência.
• Encontrando um erro de importação mencionando libcudart, um símbolo ausente, ou uma wheel que "foi instalada com sucesso, mas não carrega".
• Uma instalação de framework (PyTorch, Unsloth, TRL, vLLM, xformers) falha, trava ou volta silenciosamente para a CPU.
• Decidindo se deve usar um contêiner NGC ou pip puro.
• Restaurando uma configuração funcional após uma reinstalação do sistema operacional ou uma atualização da imagem base, precisando verificar novamente do zero.

Cada um desses cenários aceita a mesma correção geral: combinar o contêiner/wheel com CUDA 13 e SM121, não lute contra a ABI.

Regra do Contêiner em Primeiro Lugar

Decisão rápida, antes dos detalhes abaixo:

• Trabalho padrão de treinamento/inferência → Contêiner PyTorch NGC.
• Fine-tuning focado em Unsloth → Contêiner Unsloth (ele já vem com a combinação de Triton/xformers/transformers fixada e validada para esse caminho).
• Nenhum dos dois se encaixa (pacote de sistema personalizado, interpretador de IDE local) → pip puro, seguindo a sequência exata mais adiante.

Prefira um contêiner. Use nvcr.io/nvidia/pytorch:25.09-py3 como base para trabalho geral — a tag mais recente confirmada como funcional neste hardware; baixe uma tag mais nova e aprovada se disponível localmente em vez de bloquear em 25.11-py3. A tag do NGC está datada, então executá-la diretamente é bom:

docker run --runtime=nvidia --gpus all -it --rm \
  nvcr.io/nvidia/pytorch:25.09-py3

unsloth/unsloth:dgxspark-latest é uma tag em movimento em contraste — resolva e fixe seu digest antes de executá-la para qualquer coisa reproduzível; a tag pura é apenas uma etapa de descoberta, não a invocação padrão. Sequência completa de pull-inspect-pin e justificativa de flags/montagens de volume para diretórios de execução de finetuning/: references/container-workflow.md. Trate o pip puro como a exceção.

A razão para a abordagem de contêiner em primeiro lugar é a fixação (pinning), não a conveniência. As versões de Triton, xformers e transformers interagem de forma restrita com o alvo SM121 do GB10 e CUDA 13; um contêiner trava todos eles juntos contra uma combinação já validada neste hardware. O pip puro deixa essa resolução para você, um erro de importação de cada vez.

Quando o pip puro for justificado, siga a sequência de instalação do playbook da NVIDIA literalmente e em ordem:

pip install "transformers==5.13.1" "peft==0.19.1" "hf_transfer==0.1.9" "datasets==4.3.0" "trl==1.8.0"
pip install --no-deps "unsloth==2026.7.2" "unsloth_zoo==2026.7.2" "bitsandbytes==0.49.2"
pip install -U "torchao==0.17.0"

O flag --no-deps do segundo comando não é opcional — permitir que o pip resolva novamente a árvore de dependências do Unsloth em aarch64 é uma maneira comum de puxar uma build incompatível de torch ou triton. A terceira linha também não é opcional: a imagem base do NGC empacotada com torchao é muito antiga para o caminho LoRA-attach dos peft atuais (ImportError: ... torchao ... only versions above 0.16.0 are supported) — a hard blocker, not a warning. Every == o pin acima é crucial, retirado da matriz de versão conhecida e funcional datada em references/stack-matrix.md (a data de Last verified governa a obsolescência) — uma instalação sem pin resolve as versões atuais do PyPI bem fora do que esta versão do Unsloth suporta.

Baixe uma tag nova quando um novo lançamento aprovado for anunciado. Reconstrua localmente a partir de uma das duas bases apenas quando um projeto precisar de um pacote de sistema extra — não para "atualizar" um componente que a imagem já fixa. Detalhes sobre ambos os caminhos: references/container-workflow.md.

Mais um pré-voo: playbooks oficiais do DGX Spark já foram lançados com erros. Verifique issues recentes em github.com/NVIDIA/dgx-spark-playbooks (e os outros recursos em references/stack-matrix.md) antes de confiar em uma receita literalmente para uma execução longa.

A Regra da ABI

A falha mais comum no Spark é uma incompatibilidade de ABI CUDA 12/13: uma wheel construída contra libcudart.so.12 carregada em um sistema que só tem libcudart.so.13. A instalação geralmente é bem-sucedida; a falha surge mais tarde como um erro de símbolo ausente ou um segfault que não aponta claramente para CUDA.

Correção: baixe wheels de download.pytorch.org/whl/cu130 (as builds aarch64 com tag cu130), ou use um dos contêineres acima, que já carregam uma build compatível. Antes de perseguir um

…