Como corrigir “RuntimeError: Erro CUDA: declaração do lado do dispositivo acionada”

Publicados: 2025-10-14

Se você estiver trabalhando com modelos de aprendizado profundo no PyTorch, é provável que tenha se deparado com uma mensagem de erro intrigante como:

 RuntimeError: CUDA error: device-side assert triggered

Esse erro pode ser extremamente frustrante, especialmente quando você não tem certeza do que está causando isso. Ao contrário de muitos erros de programação que fornecem um rastreamento de pilha útil apontando para o problema, este pode parecer mais como se sua GPU estivesse levantando as sobrancelhas e indo embora silenciosamente. Mas não se preocupe – ao final deste guia, você não apenas entenderá por que isso acontece, mas também como corrigi-lo metodicamente.

O que esse erro realmente significa?

Este erro ocorre quando um kernel CUDA em execução na sua GPU encontra uma falha de asserção. Isso geralmente ocorre devido a uma entrada inválida ou a um comportamento inesperado que você pode não detectar no modo CPU. Por ser um problema no nível da GPU, ele tende a travar sem as mensagens de depuração detalhadas que estamos acostumados a ver nas exceções do Python.

As causas comuns incluem:

  • Erros de indexação (por exemplo, tentar usar um índice de classe que não existe)
  • Formas de tensor inválidas
  • Uso incorreto da função de perda
  • Dados que quebram expectativas (como tensores vazios)

Felizmente, com a abordagem certa, você pode rastrear e corrigir esse problema – vamos ver como.

Processo passo a passo para diagnosticar e corrigir

1.Execute seu modelo na CPU

A primeira etapa do diagnóstico é desabilitar o CUDA e executar tudo na CPU. Freqüentemente, ao ser executado na CPU, o PyTorch fornece mensagens de erro mais claras porque as declarações do lado do dispositivo agora são lançadas como exceções Python com contexto completo.

Para mudar para o modo CPU, modifique seu código da seguinte maneira:

 device = torch.device("cpu") model.to(device)

Se uma asserção falhar, você deverá obter um rastreamento de pilha muito mais informativo.

2. Verifique seus rótulos de destino

Uma das causas mais frequentes desse erro são rótulos de classe inadequados — especialmente ao usar nn.CrossEntropyLoss . Esta função de perda espera que seu tensor alvo inclua índices de classe entre 0 e num_classes - 1 . Portanto, se o seu modelo gerar 10 classes, os alvos deverão ser números inteiros de 0 a 9.

Erro comum:

 # Target contains 10 instead of 0–9 range target = torch.tensor([10])

Se esses índices estiverem fora dos limites, você encontrará uma afirmação na GPU. Para validar isso, use:

 assert target.max().item() < num_classes

Se você estiver classificando imagens, certifique-se também de que o formato do seu alvo seja apropriado. Para CrossEntropyLoss , deve ter o formato [batch_size] , não codificado one-hot!

 # Incorrect (for CrossEntropyLoss) target = torch.tensor([[0, 0, 1], [1, 0, 0]]) # Correct target = torch.tensor([2, 0])

3. Inspecione o DataLoader em busca de erros

Às vezes, o erro vem do seu conjunto de dados ou DataLoader, especialmente quando usado no treinamento em lote. Se alguns rótulos estiverem corrompidos ou inconsistentes, eles poderão quebrar seu modelo na GPU.

Verifique seu conjunto de dados assim:

 for i, (x, y) in enumerate(loader): assert y.dtype == torch.long assert y.max().item() < num_classes assert x.shape[0] == y.shape[0]

Isso é particularmente útil se o seu conjunto de dados for construído a partir de um arquivo CSV ou de uma lógica de processamento personalizada que possa introduzir silenciosamente rótulos inválidos.

desenvolvedor introspectivo, inspecionando código, laptop, depuração

Outras armadilhas comuns

4. Tamanhos de lote incompatíveis

Às vezes, o modelo ou função de perda espera que as entradas tenham determinados formatos. As incompatibilidades podem levar a problemas sutis. Certifique-se de que o tamanho do lote nas entradas e nos alvos esteja alinhado:

 # torchvision models usually expect [N, 3, 224, 224] assert inputs.shape[1:] == (3, 224, 224)

Isso é especialmente importante ao usar o DataLoader com drop_last=False — o último lote pode ser menor dependendo do tamanho do seu conjunto de dados. Seu modelo ou operações como BatchNorm devem lidar com isso de maneira adequada ou verificar explicitamente lotes menores.

5. Tensores acidentais em diferentes dispositivos

Certifique-se de que os recursos de entrada e o modelo estejam no mesmo dispositivo. Se você enviar seu modelo para CUDA, mas deixar suas entradas na CPU, as coisas falharão inesperadamente, muitas vezes sem erros úteis.

Sempre verifique com:

 assert inputs.device == model.device

Dica avançada: ative o relatório completo de erros

Se a execução na CPU não ajudar ou se você estiver trabalhando em uma configuração mista de CPU/GPU e ainda não obtiver erros úteis, tente configurar:

 CUDA_LAUNCH_BLOCKING=1 python my_script.py

Isso diz ao PyTorch para executar o código GPU de forma síncrona, para que ele trave no ponto exato da falha. Isso pode retardar um pouco a execução, mas fornece um rastreamento muito mais claro.

Somente em Python, sem modificar o shell:

 import os os.environ["CUDA_LAUNCH_BLOCKING"] = "1"

Agora o tempo de execução deve oferecer informações mais específicas sobre onde ocorreu a afirmação CUDA.

Correção por exemplo

Vejamos um exemplo prático. Suponha que você esteja construindo um modelo para classificação de dígitos no MNIST e defina sua camada de modelo final da seguinte forma:

 self.fc = nn.Linear(128, 10)

No ciclo de treinamento, você tem:

 criterion = nn.CrossEntropyLoss() output = model(images) # Output shape: [batch_size, 10] loss = criterion(output, labels)

Mas seus rótulos são como:

 labels = torch.tensor([[0], [1], [2]])

Esta forma está incorreta. CrossEntropyLoss espera rótulos como um vetor 1D de índices de classe:

 labels = torch.tensor([0, 1, 2])

Corrigir esta forma por si só poderia resolver o problema.

modelo pytorch, função de perda, erro de GPU, correção

Resumo: Lista de verificação para corrigir o erro

Antes de começar a arrancar o cabelo, siga esta lista de verificação:

  1. Mude para o modo CPUe tente novamente – a mensagem de erro pode ser mais descritiva.
  2. Verifique os rótulos das classes:certifique-se de que estejam dentro do intervalo válido e no formato correto.
  3. Inspecione os dados provenientes do DataLoader— itere em lotes e verifique se há anomalias.
  4. Garanta formatos e dimensões de tensor adequados, especialmente para saídas e alvos.
  5. Use CUDA_LAUNCH_BLOCKING=1para obter um rastreamento síncrono e detalhado do CUDA.

Conclusão

Embora o erro acionado por declaração do lado do dispositivopossa parecer vago e opaco no início, é, em última análise, a maneira do seu modelo ou dados apontarem uma bandeira vermelha para você. Ao verificar sistematicamente seus rótulos, formatos de dados e usar o modo CPU e o bloqueio de inicialização, você quase sempre pode isolar o problema.

Da próxima vez, em vez de reagir confuso, você estará munido de conhecimento e de um kit de ferramentas de diagnóstico. Boa depuração!