El recorrido de diagnóstico en cuatro decisiones
El objetivo es encontrar la primera capa que falla, no probar varias instalaciones seguidas. Conserva el comando ejecutado, el primer mensaje de error y el resultado de cada control. Si cambias a la vez Python, el paquete PyTorch y el tamaño del batch, ya no sabrás qué modificación resolvió el problema.
El script descargable aplica esta progresión y genera un informe técnico limitado. No lanza tu modelo ni modifica tu instalación. Úsalo en el mismo entorno que tu proyecto; de lo contrario, estarás comprobando un intérprete distinto del que usa el programa que falla.
Desplaza la tabla para leer todas las columnas.| Comprobación | Si la comprobación falla | Qué permite hacer si tiene éxito |
|---|---|---|
| 1. Intérprete e importación | Corregir el Python utilizado o su instalación de PyTorch. | Leer la versión y el backend del paquete realmente importado. |
| 2. Backend y dispositivo | Examinar el paquete, el controlador, la exposición de la GPU y los permisos. | Solicitar una asignación en la GPU objetivo. |
| 3. Pequeño cálculo GPU | Conservar el error de asignación, de cálculo o de sincronización. | Pasar a una entrada reducida de la aplicación. |
| 4. Aplicación representativa | Aislar pesos, extensión, formato, memoria o salida incorrecta. | Aumentar progresivamente el trabajo real. |
1. Identificar el Python que realmente se ejecuta
Un terminal, un notebook y un servicio pueden usar intérpretes distintos. Muestra sys.executable en el contexto que lanza el proyecto y luego comprueba la versión. La ruta permite detectar un entorno virtual olvidado o un notebook que sigue en otro kernel. Examínala en tu máquina; no es necesario publicar tu estructura de directorios personal en un informe.
Después, usa ese mismo intérprete para consultar los paquetes. El comando python -m pip show torch da la información de PyTorch asociado a ese Python. Si import torch falla, el siguiente paso consiste en corregir esa instalación: reducir el batch o cambiar los pesos del modelo no resolverá un módulo ausente.
python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip show torch2. Distinguir CUDA, ROCm y un paquete sin aceleración GPU
Anota por separado torch.__version__, torch.version.cuda y torch.version.hip. No concluyas "paquete CPU" a partir del único valor None de torch.version.cuda: PyTorch para ROCm usa HIP, reutiliza torch.cuda y también espera un dispositivo llamado cuda. Sustituir ese nombre por rocm o hip no es la corrección que hay que aplicar.
A continuación, verifica torch.cuda.is_available() y torch.cuda.device_count(). Estos resultados describen lo que este entorno de Python puede usar en ese momento. No sustituyen al cálculo mínimo. Una herramienta del sistema puede ver una tarjeta mientras que el paquete, el controlador accesible al proceso o su entorno impiden que PyTorch la use.
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. Generar el informe con el script de Kernodeck
Después de descargar el archivo, colócalo en una carpeta de trabajo y ejecútalo con el Python del proyecto. Por defecto, exige una GPU. El modo CPU debe solicitarse explícitamente: su éxito verifica la rama CPU del diagnóstico y nunca convierte una GPU no disponible en una GPU validada. El informe se escribe en el terminal y, con --output, en un nuevo archivo JSON. Nunca se sobrescribe un archivo existente: elige otro nombre para tu siguiente intento.
El script asigna dos matrices de 2 × 2 en float32, verifica su producto y luego un gradiente, y sincroniza el dispositivo GPU. La pérdida esperada es 196 para este cálculo fijo. Esta comprobación tan breve no carga ningún peso de modelo ni mide ningún rendimiento. Solicita un pequeño cálculo real al backend, más allá de una simple detección de dispositivo.
La comprobación opcional del sistema usa nvidia-smi cuando está presente. Solo informa de la versión del controlador NVIDIA y de la memoria total visible por esa herramienta; no constituye una comprobación del sistema equivalente para ROCm. El tiempo de espera del cálculo es de 30 segundos por defecto y puede ir de 5 a 120 segundos. La comprobación del sistema tiene su propio tiempo de espera 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. Leer el informe y elegir la siguiente acción
Empieza por status, code, exit_code y stage. El bloque runtime identifica la versión de Python y la familia del sistema. El bloque pytorch distingue el paquete importado, sus versiones de compilación CUDA/HIP, el backend declarado y los dispositivos visibles. El bloque execution indica dónde se realizó realmente el cálculo y si se verificaron tanto el producto como el gradiente.
En modo CPU, gpu_available y visible_device_count permanecen en null: el script no consulta el estado del controlador de GPU. Esto no es ni un cero ni una avería. Lee también execution.device: un paquete compilado para CUDA puede perfectamente ejecutar esta comprobación en CPU cuando se solicita explícitamente.
El informe contiene una selección de datos técnicos. No incluye las variables de entorno, las rutas del equipo, los identificadores de sesión, una lista completa de paquetes ni el rastro bruto de una excepción. El script no envía ningún informe a Kernodeck. Para un error detallado de tu aplicación, conserva su rastro en tu espacio de trabajo y elimina los secretos antes de compartirlo.
Desplaza la tabla para leer todas las columnas.| Resultado | Significado | Acción siguiente |
|---|---|---|
| GPU_CHECK_PASSED · 0 | Producto y gradiente verificados en la GPU elegida. | Pasa a una entrada pequeña de tu aplicación. |
| CPU_CHECK_PASSED · 0 | Producto y gradiente verificados solo en CPU. | No saques conclusiones sobre CUDA o ROCm. |
| TORCH_MISSING · 3 / TORCH_IMPORT_FAILED · 4 | PyTorch no está en este Python, o la importación falla. | Verifica el intérprete, el paquete y sus dependencias. |
| GPU_BACKEND_ABSENT · 5 | El paquete no declara ni CUDA ni HIP. | Instala el paquete adecuado para tu entorno. |
| GPU_UNAVAILABLE · 6 / DEVICE_INDEX_INVALID · 7 | GPU no utilizable en este proceso, o índice fuera de los dispositivos visibles. | Verifica la exposición de las tarjetas, el controlador y el índice solicitado. |
| CHECK_FAILED · 8 / OUT_OF_MEMORY o RUNTIME_ERROR · 9 | Fallo del cálculo fijo, de la asignación o de una operación del backend. | Lee la etapa señalada antes de lanzar el modelo completo. |
| TIMEOUT · 10 / WORKER_FAILED · 11 | Comprobación detenida por el tiempo de espera, o sin informe aprovechable. | Tratar el control como un fallo; examinar el entorno. |
| OUTPUT_WRITE_FAILED · 12 | El informe no se guardó en el destino solicitado. | Usar un nuevo nombre de archivo accesible. |
5. Pasar del cálculo pequeño a tu aplicación
Antes del lanzamiento, dispón de un comando reproducible, un modelo identificado, un pequeño conjunto de datos y un directorio de salida accesible. Elige una entrada que conserve las características importantes del trabajo final: longitud de texto, dimensiones de imagen, formato de audio o campos obligatorios. Una entrada artificialmente corta puede ocultar el problema que buscas observar.
Escribe un criterio de éxito concreto. Para un cálculo de embeddings, cada identificador de entrada debe recuperar un vector de la dimensión esperada, con valores finitos. Para un entrenamiento, un paso debe producir una pérdida aprovechable, actualizar los parámetros previstos y permitir un guardado. El código de salida del proceso complementa estos controles; no los sustituye.
Añade marcadores antes y después de la lectura de los parámetros, la importación de las bibliotecas, la carga de los pesos, la preparación de los datos, su transferencia, el cálculo y la escritura. Da a cada ensayo un identificador y conserva los parámetros asociados. Un mensaje «modelo cargado» debe corresponder a un evento terminado, no simplemente a una intención de carga.
Registra en el log las formas, los tipos y los dispositivos de los tensores útiles sin copiar todo el conjunto de datos. Un resumen como «entrada: 8 secuencias, longitud máxima 512, dispositivo cuda:0» ayuda a comparar dos ensayos. Estos números describen aquí un ejemplo de log, no una configuración universal. Evita incluir tokens de acceso o el contenido sensible de las entradas en estos mensajes.
6. Corregir el error en la capa correcta
Si el cálculo pequeño pasa pero los pesos no se encuentran, controla su ruta, su formato y los permisos de acceso. Si una extensión falla al importarse, verifica su compatibilidad con el paquete PyTorch y el backend del proyecto. Un diagnóstico exitoso no cualifica todas las extensiones de la aplicación. Retoma el primer paso que falle en lugar de cambiar varias dependencias a la vez.
Un error de dispositivo puede venir de una entrada que se quedó en la CPU mientras el modelo está en la GPU. Un error de tipo puede venir de una conversión parcial o de un operador incompatible con la precisión elegida. Conserva el primer mensaje completo y su traza. Modifica una sola hipótesis a la vez y luego vuelve a lanzar la entrada mínima antes de reintroducir el volumen final.
7. Si el modelo arranca y luego supera la memoria
Detecta si el exceso de memoria se produce al cargar los pesos, en el primer cálculo o después de varias iteraciones. Estos momentos orientan hacia causas distintas: modelo demasiado voluminoso, activaciones o caché de generación importantes, acumulación de tensores conservados. Registra torch.cuda.memory_allocated() y torch.cuda.memory_reserved() en los mismos pasos. El primero sigue las asignaciones de los tensores; el segundo cubre la memoria gestionada por el asignador.
torch.cuda.empty_cache() puede devolver caché no utilizada, pero no elimina los tensores todavía referenciados. Inspecciona por tanto las listas de salidas, los historiales de pérdidas y los objetos que conservan un grafo de cálculo. Reduce después el batch o la longitud de entrada para aislar el factor determinante. Cambiar de tarjeta se convierte en una decisión informada cuando conoces la fase que se excede y el margen realmente necesario.
8. Medir el cálculo sin olvidar el asincronismo
Las operaciones de GPU pueden ser asíncronas respecto al programa Python. Un cronómetro colocado alrededor de una llamada puede por tanto medir sobre todo el envío del trabajo. Para una medición de diagnóstico, sincroniza la GPU en los límites del segmento observado, o utiliza eventos adecuados. Esta sincronización modifica el desarrollo: mantén esta instrumentación separada del funcionamiento normal de tu aplicación.
Construye un ejemplo sencillo con tres segmentos: preparación de la entrada, cálculo, escritura de la salida. Para el segmento de GPU, llama a torch.cuda.synchronize(), registra time.perf_counter(), ejecuta el cálculo, sincroniza de nuevo y calcula la diferencia. Conserva por separado la primera pasada y las siguientes. Una carga o una inicialización no debe desaparecer dentro de un promedio presentado como el tiempo de respuesta completo.
9. Controlar las salidas y conservar un diagnóstico reutilizable
Para una inferencia clásica, model.eval() ajusta el comportamiento de los módulos afectados, mientras que torch.inference_mode() desactiva el seguimiento necesario para los gradientes. Estos dos ajustes cumplen funciones distintas. Usa el segundo cuando los tensores producidos no deban participar después en un cálculo con gradientes. Una evaluación del modelo durante el entrenamiento exige volver a establecer explícitamente el modo correcto antes de reanudar.
Ahora compara las salidas con el contrato preparado: número de resultados, correspondencia de los identificadores, dimensiones, valores finitos y la métrica de negocio adecuada. Si aumentas el batch, verifica de nuevo esa correspondencia. Si añades GPU, controla el reparto de las entradas y la recolección de las salidas. Los lotes de alquiler designan tarjetas pedidas; el batch designa ejemplos procesados juntos por tu programa.
El resultado de este método es una carpeta pequeña: comando, versiones, parámetros, entrada mínima, última etapa exitosa, primer error, observaciones de memoria y salida obtenida. Si el lanzamiento funciona, conserva esa carpeta como punto de comparación antes de aumentar la carga. Si el lanzamiento falla, permite reproducir el problema sin rehacer toda la investigación.
Antes de un procesamiento largo, realiza también una parada limpia y una reanudación sobre ese pequeño conjunto de entradas. Verifica que las salidas ya escritas no se pierdan ni se cuenten dos veces. Una vez superados estos controles, aumenta progresivamente un solo eje —batch, longitud, concurrencia o número de procesos— y registra el límite observado. Obtienes un rango de funcionamiento medido para tu aplicación, en lugar de una suposición ligada al nombre de la GPU.
La prueba aportada y sus límites
Los ejemplos descargables provienen de controles reales efectuados el 24 de septiembre de 2026. Las dos ejecuciones con PyTorch usan Windows, Python 3.14.6 y PyTorch 2.11.0+cu128. El control de GPU emplea CUDA, sobre una NVIDIA GeForce RTX 5070; el control de CPU solicita explícitamente la CPU. Este hardware de control no se presenta como una oferta de Kernodeck. No se ejecutó ningún cálculo ROCm para esta prueba.
Un cálculo pequeño exitoso demuestra que una ruta de asignación y de cálculo funciona en el dispositivo elegido. No mide ni la velocidad de tu modelo, ni la memoria necesaria para sus entradas más grandes, ni su compatibilidad con una extensión concreta. El informe tampoco certifica una topología multicartel. Pasa a la prueba representativa antes de decidir aumentar la carga o el alquiler.
Para una aplicación CUDA, compara una ficha de NVIDIA con tus necesidades de memoria y de biblioteca; para una cadena ROCm, examina las condiciones del MI300X. Las fichas enlazadas son opciones por validar para tu proyecto, no la lista del hardware utilizado en la prueba. Mantén el tiempo de control inicial y de exportación dentro de tu periodo de 3, 7 o 30 días.
Desplaza la tabla para leer todas las columnas.| Control real | Resultado observado | Alcance |
|---|---|---|
| CPU explícita · Python 3.14.6 / PyTorch 2.11.0+cu128 | CPU_CHECK_PASSED; producto y gradiente exactos; pérdida 196. | El cálculo fijo funciona en CPU. |
| CUDA · RTX 5070 / paquete CUDA 12.8 | GPU_CHECK_PASSED; producto y gradiente exactos; pérdida 196. | El cálculo fijo funciona en esta tarjeta en este entorno. |
| PyTorch ausente · Python 3.12.14 | TORCH_MISSING; código de salida 3. | La ausencia del módulo produce un fallo explícito. |
| GPU invisible para el proceso de control | GPU_UNAVAILABLE; código de salida 6. | El script no sustituye silenciosamente la GPU por la CPU. |