Il percorso di diagnostica in quattro decisioni
L'obiettivo è trovare il primo livello che fallisce, non provare più installazioni una dopo l'altra. Conserva il comando eseguito, il primo messaggio di errore e il risultato di ogni controllo. Se cambi contemporaneamente Python, il pacchetto PyTorch e la dimensione del batch, non saprai più quale modifica ha risolto il problema.
Lo script scaricabile applica questa progressione e produce un report tecnico limitato. Non avvia il tuo modello e non modifica la tua installazione. Usalo nello stesso ambiente del tuo progetto, altrimenti controllerai un altro interprete rispetto a quello del programma in errore.
Scorri la tabella per leggere tutte le colonne.| Controllo | Se il controllo fallisce | Cosa permette di fare il suo successo |
|---|---|---|
| 1. Interprete e import | Correggere il Python utilizzato o la sua installazione di PyTorch. | Leggere la versione e il backend del pacchetto effettivamente importato. |
| 2. Backend e dispositivo | Esaminare il pacchetto, il driver, l'esposizione della GPU e i permessi. | Richiedere un'allocazione sulla GPU desiderata. |
| 3. Piccolo calcolo GPU | Conservare l'errore di allocazione, di calcolo o di sincronizzazione. | Passare a un input ridotto dell'applicazione. |
| 4. Applicazione rappresentativa | Isolare pesi, estensione, formato, memoria o output errato. | Aumentare progressivamente il lavoro reale. |
1. Identificare il Python effettivamente eseguito
Un terminale, un notebook e un servizio possono usare interpreti diversi. Mostra sys.executable nel contesto che avvia il progetto, poi controlla la versione. Il percorso permette di individuare un ambiente virtuale dimenticato o un notebook rimasto su un altro kernel. Esaminalo sulla tua macchina; non è necessario pubblicare la tua struttura di cartelle personale in un report.
Usa poi lo stesso interprete per interrogare i pacchetti. Il comando python -m pip show torch fornisce le informazioni di PyTorch associato a quel Python. Se import torch fallisce, il passo successivo consiste nel correggere questa installazione: ridurre il batch o cambiare i pesi del modello non risolverà un modulo assente.
python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip show torch2. Distinguere CUDA, ROCm e un pacchetto senza accelerazione GPU
Rileva separatamente torch.__version__, torch.version.cuda e torch.version.hip. Non concludere "pacchetto CPU" dalla sola valore None di torch.version.cuda: PyTorch per ROCm usa HIP, riutilizza torch.cuda e si aspetta ugualmente un dispositivo chiamato cuda. Sostituire questo nome con rocm o hip non è la correzione da applicare.
Verifica poi torch.cuda.is_available() e torch.cuda.device_count(). Questi risultati descrivono ciò che questo ambiente Python può utilizzare in quel momento. Non sostituiscono il calcolo minimale. Uno strumento di sistema può vedere una scheda mentre il pacchetto, il driver accessibile al processo o il suo ambiente impediscono a PyTorch di utilizzarla.
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. Produrre il report con lo script Kernodeck
Dopo aver scaricato il file, mettilo in una cartella di lavoro e avvialo con il Python del progetto. Per impostazione predefinita richiede una GPU. La modalità CPU deve essere richiesta esplicitamente: il suo successo verifica il ramo CPU della diagnostica e non trasforma mai una GPU non disponibile in una GPU validata. Il report viene scritto nel terminale e, con --output, in un nuovo file JSON. Un file esistente non viene mai sovrascritto: scegli un altro nome per il prossimo tentativo.
Lo script alloca due matrici 2 × 2 in float32, verifica il loro prodotto e poi un gradiente e sincronizza il dispositivo GPU. La perdita attesa vale 196 per questo calcolo fisso. Questo controllo molto breve non carica alcun peso di modello e non misura alcun throughput. Richiede un piccolo calcolo reale al backend, al di là di una semplice rilevazione del dispositivo.
Il controllo di sistema facoltativo utilizza nvidia-smi quando è presente. Riporta unicamente la versione del driver NVIDIA e la memoria totale visibile da questo strumento; non costituisce un controllo di sistema equivalente per ROCm. Il timeout del calcolo vale 30 secondi per impostazione predefinita e può andare da 5 a 120 secondi. Il controllo di sistema ha il proprio timeout massimo di 3 secondi.
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. Leggere il report e scegliere l'azione successiva
Inizia da status, code, exit_code e stage. Il blocco runtime identifica la versione di Python e la famiglia del sistema. Il blocco pytorch distingue il pacchetto importato, le sue versioni di compilazione CUDA/HIP, il backend dichiarato e i dispositivi visibili. Il blocco execution indica dove il calcolo è realmente avvenuto e se il prodotto e il gradiente sono stati verificati.
In modalità CPU, gpu_available e visible_device_count restano a null: lo script non richiede lo stato del driver GPU. Non è né uno zero né un guasto. Leggi anche execution.device: un pacchetto compilato per CUDA può benissimo eseguire questo controllo su CPU quando viene richiesto esplicitamente.
Il report contiene una selezione di dati tecnici. Non include le variabili d'ambiente, i percorsi della macchina, gli identificatori di sessione, un elenco completo dei pacchetti o la traccia grezza di un'eccezione. Lo script non invia alcun report a Kernodeck. Per un errore dettagliato della tua applicazione, conserva la sua traccia nel tuo spazio di lavoro e rimuovi i segreti prima di condividerla.
Scorri la tabella per leggere tutte le colonne.| Risultato | Significato | Azione successiva |
|---|---|---|
| GPU_CHECK_PASSED · 0 | Prodotto e gradiente verificati sulla GPU scelta. | Passare a un piccolo input della tua applicazione. |
| CPU_CHECK_PASSED · 0 | Prodotto e gradiente verificati solo su CPU. | Non trarre conclusioni su CUDA o ROCm. |
| TORCH_MISSING · 3 / TORCH_IMPORT_FAILED · 4 | PyTorch assente da questo Python, o import fallito. | Verificare l'interprete, il pacchetto e le sue dipendenze. |
| GPU_BACKEND_ABSENT · 5 | Il pacchetto non dichiara né CUDA né HIP. | Installare il pacchetto adatto al tuo ambiente. |
| GPU_UNAVAILABLE · 6 / DEVICE_INDEX_INVALID · 7 | GPU inutilizzabile in questo processo, o indice fuori dai dispositivi visibili. | Verificare l'esposizione delle schede, il driver e l'indice richiesto. |
| CHECK_FAILED · 8 / OUT_OF_MEMORY o RUNTIME_ERROR · 9 | Fallimento del calcolo fisso, dell'allocazione o di un'operazione del backend. | Leggere la fase segnalata prima di avviare il modello completo. |
| TIMEOUT · 10 / WORKER_FAILED · 11 | Controllo interrotto per timeout, o senza report utilizzabile. | Trattare il controllo come un fallimento; esaminare l'ambiente. |
| OUTPUT_WRITE_FAILED · 12 | Il report non è stato salvato nella destinazione richiesta. | Usare un nuovo nome di file accessibile. |
5. Passare dal piccolo calcolo alla tua applicazione
Prima del lancio, disponi di un comando riproducibile, di un modello identificato, di un piccolo set di dati e di una directory di output accessibile. Scegli un input che conservi le caratteristiche importanti del lavoro finale: lunghezza del testo, dimensioni dell'immagine, formato audio o campi obbligatori. Un input artificiosamente corto può mascherare il problema che cerchi di osservare.
Scrivi un criterio di successo concreto. Per un calcolo di embeddings, ogni identificatore di input deve restituire un vettore della dimensione attesa, con valori finiti. Per un addestramento, una fase deve produrre una loss utilizzabile, aggiornare i parametri previsti e consentire un salvataggio. Il codice di uscita del processo completa questi controlli; non li sostituisce.
Aggiungi dei marcatori prima e dopo la lettura dei parametri, l'import delle librerie, il caricamento dei pesi, la preparazione dei dati, il loro trasferimento, il calcolo e la scrittura. Assegna a ogni tentativo un identificatore e conserva i parametri associati. Un messaggio "modello caricato" deve corrispondere a un evento concluso, non semplicemente a un'intenzione di caricamento.
Registra nei log forme, tipi e dispositivi dei tensori utili senza copiare l'intero set di dati. Un riepilogo come "input: 8 sequenze, lunghezza massima 512, dispositivo cuda:0" aiuta a confrontare due tentativi. Questi numeri descrivono qui un esempio di log, non una configurazione universale. Evita di inserire token di accesso o il contenuto sensibile degli input in questi messaggi.
6. Correggere l'errore del livello giusto
Se il piccolo calcolo passa ma i pesi sono introvabili, controlla il loro percorso, il loro formato e i permessi di accesso. Se un'estensione fallisce all'import, verifica la sua compatibilità con il pacchetto PyTorch e il backend del progetto. Una diagnosi riuscita non qualifica tutte le estensioni dell'applicazione. Riprendi dalla prima fase che fallisce invece di cambiare più dipendenze contemporaneamente.
Un errore di dispositivo può derivare da un input rimasto sulla CPU mentre il modello è sulla GPU. Un errore di tipo può derivare da una conversione parziale o da un operatore incompatibile con la precisione scelta. Conserva il primo messaggio completo e la sua traccia. Modifica una sola ipotesi alla volta, poi rilancia l'input minimo prima di reintrodurre il volume finale.
7. Se il modello si avvia e poi supera la memoria
Individua se il superamento avviene al caricamento dei pesi, al primo calcolo o dopo diverse iterazioni. Questi momenti orientano verso cause diverse: modello troppo voluminoso, attivazioni o cache di generazione importanti, accumulo di tensori conservati. Rileva torch.cuda.memory_allocated() e torch.cuda.memory_reserved() nelle stesse fasi. Il primo segue le allocazioni dei tensori; il secondo copre la memoria gestita dall'allocatore.
torch.cuda.empty_cache() può restituire cache inutilizzata, ma non elimina i tensori ancora referenziati. Ispeziona quindi le liste di output, gli storici delle loss e gli oggetti che mantengono un grafo di calcolo. Riduci poi il batch o la lunghezza dell'input per isolare il fattore determinante. Cambiare scheda diventa una decisione informata quando conosci la fase che supera il limite e il margine realmente necessario.
8. Misurare il calcolo senza dimenticare l'asincronia
Le operazioni GPU possono essere asincrone rispetto al programma Python. Un cronometro posto attorno a una chiamata può quindi misurare soprattutto l'invio del lavoro. Per una misura di diagnostica, sincronizza la GPU ai limiti del segmento osservato, oppure usa eventi adatti. Questa sincronizzazione modifica lo svolgimento: mantieni questa strumentazione distinta dal funzionamento normale della tua applicazione.
Costruisci un esempio semplice con tre segmenti: preparazione dell'input, calcolo, scrittura dell'output. Per il segmento GPU, chiama torch.cuda.synchronize(), rileva time.perf_counter(), esegui il calcolo, sincronizza di nuovo, poi calcola la differenza. Conserva separatamente la prima esecuzione e quelle successive. Un caricamento o un'inizializzazione non deve sparire in una media presentata come tempo di risposta completo.
9. Controllare gli output e conservare una diagnostica riutilizzabile
Per un'inferenza classica, model.eval() regola il comportamento dei moduli interessati, mentre torch.inference_mode() disattiva il tracciamento necessario ai gradienti. Queste due impostazioni hanno funzioni diverse. Usa la seconda quando i tensori prodotti non devono partecipare successivamente a un calcolo con gradienti. Una valutazione del modello durante l'addestramento richiede di ripristinare esplicitamente la modalità corretta prima di riprendere.
Ora confronta gli output con il contratto preparato: numero di risultati, corrispondenza degli identificatori, dimensioni, valori finiti e metrica di business appropriata. Se aumenti il batch, verifica ancora questa corrispondenza. Se aggiungi GPU, controlla la distribuzione degli input e la raccolta degli output. I lotti di noleggio indicano le schede ordinate; il batch indica gli esempi elaborati insieme dal tuo programma.
Il risultato di questo metodo è una piccola cartella: comando, versioni, parametri, input minimo, ultimo passaggio riuscito, primo errore, osservazioni sulla memoria e output ottenuto. Se l'avvio funziona, conserva questa cartella come punto di confronto prima di aumentare il carico. Se l'avvio fallisce, permette di riprodurre il problema senza ricominciare tutta l'indagine.
Prima di un'elaborazione lunga, esegui anche un arresto pulito e una ripresa su questo piccolo insieme di input. Verifica che gli output già scritti non siano né persi né contati due volte. Una volta superati questi controlli, aumenta progressivamente un solo asse — batch, lunghezza, concorrenza o numero di processi — e annota il limite osservato. Ottieni un intervallo di funzionamento misurato per la tua applicazione, invece di una supposizione legata al nome della GPU.
La prova fornita e i suoi limiti
Gli esempi scaricabili provengono da controlli reali effettuati il 24 settembre 2026. Le due esecuzioni con PyTorch usano Windows, Python 3.14.6 e PyTorch 2.11.0+cu128. Il controllo GPU impiega CUDA, su una NVIDIA GeForce RTX 5070; il controllo CPU richiede esplicitamente la CPU. Questo hardware di controllo non è presentato come un'offerta Kernodeck. Nessun calcolo ROCm è stato eseguito per questa prova.
Un piccolo calcolo riuscito dimostra che un percorso di allocazione e calcolo funziona sul dispositivo scelto. Non misura né la velocità del tuo modello, né la memoria necessaria ai suoi input più grandi, né la sua compatibilità con una particolare estensione. Il rapporto non certifica neppure una topologia multi-scheda. Passa al test rappresentativo prima di decidere di aumentare il carico o il noleggio.
Per un'applicazione CUDA, confronta una scheda NVIDIA con le tue esigenze di memoria e librerie; per una catena ROCm, esamina le condizioni del MI300X. Le schede collegate sono opzioni da qualificare per il tuo progetto, non la lista dell'hardware usato nella prova. Mantieni il tempo di controllo iniziale e di export nel tuo periodo di 3, 7 o 30 giorni.
Scorri la tabella per leggere tutte le colonne.| Controllo reale | Risultato osservato | Ambito |
|---|---|---|
| CPU esplicita · Python 3.14.6 / PyTorch 2.11.0+cu128 | CPU_CHECK_PASSED; prodotto e gradiente esatti; perdita 196. | Il calcolo fisso funziona su CPU. |
| CUDA · RTX 5070 / pacchetto CUDA 12.8 | GPU_CHECK_PASSED; prodotto e gradiente esatti; perdita 196. | Il calcolo fisso funziona su questa scheda in questo ambiente. |
| PyTorch assente · Python 3.12.14 | TORCH_MISSING; codice di uscita 3. | L'assenza del modulo produce un fallimento esplicito. |
| GPU resa invisibile al processo di controllo | GPU_UNAVAILABLE; codice di uscita 6. | Lo script non sostituisce silenziosamente la GPU con la CPU. |