O percurso de diagnóstico em quatro decisões
O objetivo é encontrar a primeira camada que falha, não tentar várias instalações em sequência. Guarde o comando executado, a primeira mensagem de erro e o resultado de cada controle. Se você mudar ao mesmo tempo o Python, o pacote PyTorch e o tamanho do batch, não saberá mais qual alteração resolveu o problema.
O script para download aplica essa progressão e gera um relatório técnico limitado. Ele não inicia o seu modelo e não modifica a sua instalação. Use-o no mesmo ambiente do seu projeto, caso contrário você verificará um interpretador diferente do programa que está falhando.
Role a tabela para ler todas as colunas.| Controle | Se o controle falhar | O que o sucesso dele permite fazer |
|---|---|---|
| 1. Interpretador e import | Corrigir o Python usado ou a sua instalação do PyTorch. | Ler a versão e o backend do pacote realmente importado. |
| 2. Backend e dispositivo | Examinar o pacote, o driver, a exposição da GPU e as permissões. | Solicitar uma alocação na GPU desejada. |
| 3. Pequeno cálculo na GPU | Guardar o erro de alocação, de cálculo ou de sincronização. | Passar para uma entrada reduzida da aplicação. |
| 4. Aplicação representativa | Isolar pesos, extensão, formato, memória ou saída incorreta. | Aumentar progressivamente o trabalho real. |
1. Identificar o Python realmente executado
Um terminal, um notebook e um serviço podem usar interpretadores diferentes. Exiba sys.executable no contexto que inicia o projeto e depois verifique a versão. O caminho permite identificar um ambiente virtual esquecido ou um notebook que ficou em outro kernel. Examine-o na sua máquina; não é necessário publicar sua árvore de diretórios pessoal em um relatório.
Em seguida, use esse mesmo interpretador para consultar os pacotes. O comando python -m pip show torch fornece as informações do PyTorch associado a esse Python. Se import torch falhar, a etapa seguinte consiste em corrigir essa instalação: reduzir o batch ou mudar os pesos do modelo não resolverá um módulo ausente.
python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip show torch2. Distinguir CUDA, ROCm e um pacote sem aceleração de GPU
Anote separadamente torch.__version__, torch.version.cuda e torch.version.hip. Não conclua "pacote CPU" a partir apenas do valor None de torch.version.cuda: o PyTorch para ROCm usa HIP, reutiliza torch.cuda e também espera um dispositivo chamado cuda. Substituir esse nome por rocm ou hip não é a correção a aplicar.
Em seguida, verifique torch.cuda.is_available() e torch.cuda.device_count(). Esses resultados descrevem o que esse ambiente Python pode usar naquele momento. Eles não substituem o cálculo mínimo. Uma ferramenta de sistema pode enxergar uma placa, enquanto o pacote, o driver acessível ao processo ou seu ambiente impedem o PyTorch de usá-la.
python -c "import torch; print(torch.__version__); print(torch.version.cuda); print(torch.version.hip); print(torch.cuda.is_available()); print(torch.cuda.device_count())"3. Gerar o relatório com o script Kernodeck
Depois de baixar o arquivo, coloque-o em uma pasta de trabalho e execute-o com o Python do projeto. Por padrão, ele exige uma GPU. O modo CPU precisa ser solicitado explicitamente: seu sucesso valida o ramo CPU do diagnóstico e nunca transforma uma GPU indisponível em GPU validada. O relatório é escrito no terminal e, com --output, em um novo arquivo JSON. Um arquivo existente nunca é sobrescrito: escolha outro nome para a próxima tentativa.
O script aloca duas matrizes 2 × 2 em float32, verifica seu produto e depois um gradiente, e sincroniza o dispositivo GPU. A perda esperada é 196 para esse cálculo fixo. Essa verificação muito curta não carrega nenhum peso de modelo e não mede nenhuma taxa de transferência. Ela exige um pequeno cálculo real do backend, além de uma simples detecção de dispositivo.
A verificação de sistema opcional usa nvidia-smi quando ele está presente. Ela reporta apenas a versão do driver NVIDIA e a memória total visível por essa ferramenta; não constitui uma verificação de sistema equivalente para ROCm. O tempo limite do cálculo é de 30 segundos por padrão e pode variar de 5 a 120 segundos. A verificação de sistema tem seu próprio tempo limite máximo de 3 segundos.
python kernodeck-diagnostic-v1.py --device-index 0 --timeout 30 --output diagnostic-gpu.jsonpython kernodeck-diagnostic-v1.py --device cpu --output diagnostic-cpu.jsonpython kernodeck-diagnostic-v1.py --host-check --output diagnostic-gpu-systeme.json4. Ler o relatório e escolher a próxima ação
Comece por status, code, exit_code e stage. O bloco runtime identifica a versão do Python e a família do sistema. O bloco pytorch distingue o pacote importado, suas versões de compilação CUDA/HIP, o backend declarado e os dispositivos visíveis. O bloco execution indica onde o cálculo realmente ocorreu e se o produto e o gradiente foram verificados.
No modo CPU, gpu_available e visible_device_count permanecem como null: o script não consulta o estado do driver GPU. Isso não é nem um zero nem uma falha. Observe também execution.device: um pacote compilado para CUDA pode muito bem executar essa verificação na CPU quando solicitado explicitamente.
O relatório contém uma seleção de dados técnicos. Ele não inclui variáveis de ambiente, caminhos da máquina, identificadores de sessão, uma lista completa de pacotes ou o trace bruto de uma exceção. O script não envia nenhum relatório à Kernodeck. Para um erro detalhado da sua aplicação, mantenha o trace no seu espaço de trabalho e remova os segredos antes de compartilhá-lo.
Role a tabela para ler todas as colunas.| Resultado | Sentido | Próxima ação |
|---|---|---|
| GPU_CHECK_PASSED · 0 | Produto e gradiente verificados na GPU escolhida. | Passar para uma pequena entrada da sua aplicação. |
| CPU_CHECK_PASSED · 0 | Produto e gradiente verificados somente na CPU. | Não concluir sobre CUDA ou ROCm. |
| TORCH_MISSING · 3 / TORCH_IMPORT_FAILED · 4 | PyTorch ausente nesse Python, ou importação com falha. | Verificar o interpretador, o pacote e suas dependências. |
| GPU_BACKEND_ABSENT · 5 | O pacote não declara nem CUDA nem HIP. | Instalar o pacote adequado ao seu ambiente. |
| GPU_UNAVAILABLE · 6 / DEVICE_INDEX_INVALID · 7 | GPU inutilizável nesse processo, ou índice fora dos dispositivos visíveis. | Verificar a exposição das placas, o driver e o índice solicitado. |
| CHECK_FAILED · 8 / OUT_OF_MEMORY ou RUNTIME_ERROR · 9 | Falha no cálculo fixo, na alocação ou em uma operação do backend. | Ler a etapa sinalizada antes de executar o modelo completo. |
| TIMEOUT · 10 / WORKER_FAILED · 11 | Verificação interrompida pelo tempo limite, ou sem relatório utilizável. | Tratar o controle como uma falha; examinar o ambiente. |
| OUTPUT_WRITE_FAILED · 12 | O relatório não foi salvo no destino solicitado. | Usar um novo nome de arquivo acessível. |
5. Passar do pequeno cálculo para a sua aplicação
Antes do lançamento, tenha à disposição um comando reprodutível, um modelo identificado, um pequeno conjunto de dados e um diretório de saída acessível. Escolha uma entrada que conserve as características importantes do trabalho final: comprimento do texto, dimensões da imagem, formato de áudio ou campos obrigatórios. Uma entrada artificialmente curta pode mascarar o problema que você busca observar.
Escreva um critério de sucesso concreto. Para um cálculo de embeddings, cada identificador de entrada deve corresponder a um vetor da dimensão esperada, com valores finitos. Para um treinamento, uma etapa deve produzir uma perda utilizável, atualizar os parâmetros previstos e permitir um salvamento. O código de saída do processo complementa esses controles; não os substitui.
Adicione marcadores antes e depois da leitura dos parâmetros, da importação das bibliotecas, do carregamento dos pesos, da preparação dos dados, da transferência deles, do cálculo e da escrita. Dê a cada tentativa um identificador e mantenha os parâmetros associados. Uma mensagem “modelo carregado” deve corresponder a um evento concluído, não apenas a uma intenção de carregamento.
Registre em log as formas, os tipos e os dispositivos dos tensores úteis sem copiar todo o conjunto de dados. Um resumo como “entrada: 8 sequências, comprimento máximo 512, dispositivo cuda:0” ajuda a comparar duas tentativas. Esses números descrevem aqui um exemplo de log, não uma configuração universal. Evite colocar tokens de acesso ou o conteúdo sensível das entradas nessas mensagens.
6. Corrigir o erro na camada certa
Se o pequeno cálculo passa, mas os pesos não são encontrados, verifique o caminho, o formato e as permissões de acesso. Se uma extensão falha na importação, verifique sua compatibilidade com o pacote PyTorch e o backend do projeto. Um diagnóstico bem-sucedido não qualifica todas as extensões da aplicação. Retome a primeira etapa que falha em vez de mudar várias dependências ao mesmo tempo.
Um erro de dispositivo pode vir de uma entrada que permaneceu na CPU enquanto o modelo está na GPU. Um erro de tipo pode vir de uma conversão parcial ou de um operador incompatível com a precisão escolhida. Guarde a primeira mensagem completa e seu rastreamento. Modifique uma única hipótese por vez e depois execute novamente a entrada mínima antes de reintroduzir o volume final.
7. Se o modelo inicia e depois estoura a memória
Identifique se o estouro ocorre no carregamento dos pesos, no primeiro cálculo ou após várias iterações. Esses momentos apontam para causas diferentes: modelo grande demais, ativações ou cache de geração extensos, acúmulo de tensores mantidos. Registre torch.cuda.memory_allocated() e torch.cuda.memory_reserved() nas mesmas etapas. O primeiro acompanha as alocações dos tensores; o segundo cobre a memória gerenciada pelo alocador.
torch.cuda.empty_cache() pode devolver cache não utilizado, mas não remove os tensores ainda referenciados. Inspecione, portanto, as listas de saídas, os históricos de perda e os objetos que mantêm um grafo de cálculo. Depois, diminua o batch ou o comprimento da entrada para isolar o fator determinante. Trocar de placa se torna uma decisão informada quando você conhece a fase que estoura e a margem realmente necessária.
8. Medir o cálculo sem esquecer o assincronismo
As operações de GPU podem ser assíncronas em relação ao programa Python. Um cronômetro colocado em torno de uma chamada pode, portanto, medir principalmente o envio do trabalho. Para uma medição de diagnóstico, sincronize a GPU nos limites do segmento observado ou use eventos adequados. Essa sincronização altera o desenrolar: mantenha essa instrumentação separada do funcionamento normal da sua aplicação.
Monte um exemplo simples com três segmentos: preparação da entrada, cálculo, escrita da saída. Para o segmento GPU, chame torch.cuda.synchronize(), capture time.perf_counter(), execute o cálculo, sincronize novamente e calcule a diferença. Mantenha separadamente a primeira passagem e as seguintes. Um carregamento ou uma inicialização não deve desaparecer em uma média apresentada como o tempo de resposta completo.
9. Controlar as saídas e manter um diagnóstico reutilizável
Para uma inferência clássica, model.eval() define o comportamento dos módulos envolvidos, enquanto torch.inference_mode() desativa o rastreamento necessário aos gradientes. Esses dois ajustes têm funções diferentes. Use o segundo quando os tensores produzidos não devem participar depois de um cálculo com gradientes. Uma avaliação de modelo durante o treinamento exige restaurar explicitamente o modo correto antes de retomar.
Compare agora as saídas com o contrato preparado: número de resultados, correspondência dos identificadores, dimensões, valores finitos e métrica de negócio apropriada. Se você aumentar o batch, verifique novamente essa correspondência. Se você adicionar GPUs, controle a distribuição das entradas e a coleta das saídas. Os lotes de locação designam placas contratadas; o batch designa exemplos processados juntos pelo seu programa.
O resultado desse método é uma pequena pasta: comando, versões, parâmetros, entrada mínima, última etapa bem-sucedida, primeiro erro, observações de memória e saída obtida. Se a execução funcionar, guarde essa pasta como ponto de comparação antes de aumentar a carga. Se a execução falhar, ela permite reproduzir o problema sem refazer toda a investigação.
Antes de um processamento longo, faça também uma parada limpa e uma retomada nesse pequeno conjunto de entradas. Verifique que as saídas já gravadas não sejam perdidas nem contadas duas vezes. Depois desses controles, aumente progressivamente um único eixo — batch, comprimento, concorrência ou número de processos — e registre o limite observado. Você obtém uma faixa de operação medida para a sua aplicação, em vez de uma suposição ligada ao nome da GPU.
A prova fornecida e seus limites
Os exemplos para download vêm de controles reais realizados em 24 de setembro de 2026. As duas execuções com PyTorch usam Windows, Python 3.14.6 e PyTorch 2.11.0+cu128. O controle de GPU usa CUDA, em uma NVIDIA GeForce RTX 5070; o controle de CPU solicita explicitamente a CPU. Esse hardware de controle não é apresentado como uma oferta Kernodeck. Nenhum cálculo ROCm foi executado para essa prova.
Um pequeno cálculo bem-sucedido mostra que um caminho de alocação e cálculo funciona no dispositivo escolhido. Ele não mede a velocidade do seu modelo, nem a memória necessária para suas maiores entradas, nem sua compatibilidade com uma extensão específica. O relatório também não certifica uma topologia multicartão. Passe ao teste representativo antes de decidir aumentar a carga ou a locação.
Para uma aplicação CUDA, compare uma ficha NVIDIA com suas necessidades de memória e de biblioteca; para uma cadeia ROCm, examine as condições do MI300X. As fichas vinculadas são opções a qualificar para o seu projeto, não a lista do hardware usado na prova. Mantenha o tempo de controle inicial e de exportação dentro do seu período de 3, 7 ou 30 dias.
Role a tabela para ler todas as colunas.| Controle real | Resultado observado | Escopo |
|---|---|---|
| CPU explícita · Python 3.14.6 / PyTorch 2.11.0+cu128 | CPU_CHECK_PASSED; produto e gradiente exatos; perda 196. | O cálculo fixo funciona na CPU. |
| CUDA · RTX 5070 / pacote CUDA 12.8 | GPU_CHECK_PASSED; produto e gradiente exatos; perda 196. | O cálculo fixo funciona nessa placa nesse ambiente. |
| PyTorch ausente · Python 3.12.14 | TORCH_MISSING; código de saída 3. | A ausência do módulo produz uma falha explícita. |
| GPU tornada invisível ao processo de controle | GPU_UNAVAILABLE; código de saída 6. | O script não substitui silenciosamente a GPU pela CPU. |