1. Definir la referencia y el resultado esperado
Empieza por lo que quieres reproducir: producir las mismas categorías, obtener valores cercanos o retomar una trayectoria de entrenamiento. Guarda un pequeño conjunto de entradas que recorra las etapas importantes y un ejemplo de salida válida. Una instalación que termina sin errores todavía no responde a esta pregunta.
Tomemos un caso pedagógico: tu aplicación produce embeddings para una muestra identificada. En el entorno de referencia, debes registrar la forma de las salidas, su tipo, la ausencia de valores no finitos y el criterio de negocio útil. Si comparas valores, elige una tolerancia justificada por tu uso. Aquí no se proporciona ningún umbral numérico universal.
Asigna una revisión al código, a los datos y a los pesos. Un nombre como «último-modelo» puede cambiar sin que el programa lo muestre. Asocia también los parámetros y el preprocesamiento a la referencia. Este expediente permite saber si una diferencia proviene del software, de las entradas o de las condiciones de ejecución.
Desplaza la tabla para leer todas las columnas.| Elemento | Qué conservar | Control tras la reconstrucción |
|---|---|---|
| Código y parámetros | Revisión, posibles modificaciones, configuración | Mismo punto de entrada y mismas opciones. |
| Datos y pesos | Versión o huella, procedencia y derechos de acceso | Misma muestra y mismo contenido esperado. |
| Python y paquetes | Versiones, procedimiento y fuentes de instalación | Intérprete correcto y dependencias coherentes. |
| Sistema y backend | SO, arquitectura, controlador, CUDA o ROCm | Dispositivo visible y cálculo mínimo superado. |
| Resultado | Formato y criterios de aceptación | Estructura y luego calidad o tolerancia prevista. |
2. Separar la cadena del sistema de los paquetes de Python
Verifica en conjunto la tarjeta, el sistema, el controlador, Python y las bibliotecas. Un entorno virtual organiza los paquetes de Python; no sustituye al controlador del sistema. Del mismo modo, la referencia de una imagen no basta para describir el acceso real a la GPU desde su host. Para una extensión compilada, anota las herramientas y bibliotecas de compilación necesarias.
Elige la distribución de PyTorch a partir de la plataforma de cálculo de tu proyecto. En ROCm, PyTorch reutiliza las llamadas torch.cuda y los dispositivos nombrados cuda: el nombre de la interfaz no permite identificar NVIDIA. Registra por separado torch.version.cuda y torch.version.hip. Una extensión escrita para una cadena concreta merece su propia comprobación.
Conserva el procedimiento que realmente permitió la instalación, con el origen de los paquetes. Evita mezclar un comando reciente encontrado en línea con un archivo de dependencias antiguo sin examinar su compatibilidad. La documentación consultada puede cambiar; anota las versiones utilizadas en tu propio expediente.
3. Escribir una reconstrucción en lugar de copiar la carpeta instalada
Crea un entorno nuevo con el Python elegido. Usa después explícitamente su intérprete para instalar y ejecutar el proyecto. En Linux, será por ejemplo .venv-rebuild/bin/python; en Windows, .venv-rebuild\Scripts\python.exe. No necesitas depender de una activación previa. La documentación de Python precisa que un entorno virtual debe recrearse cuando cambia de ubicación.
pip freeze proporciona un inventario de los paquetes instalados, no un archivo de bloqueo calculado. Consérvalo como observación. El archivo de reconstrucción también debe explicitar los índices o archivos necesarios para tu variante de PyTorch y las versiones compatibles. Revisa las rutas o URL que un inventario pueda contener antes de compartirlo.
Los comandos siguientes ilustran una reconstrucción en Linux que debes adaptar; no constituyen una prueba ejecutada de tu proyecto. El archivo requirements-rebuild.txt ya debe describir tu entorno, incluida la elección correcta de PyTorch. No lo sustituyas por una lista de versiones supuestamente universales.
python -m venv .venv-rebuild
.venv-rebuild/bin/python -m pip --version
.venv-rebuild/bin/python -m pip install -r requirements-rebuild.txt
.venv-rebuild/bin/python -m pip check
.venv-rebuild/bin/python -m pip freeze --all > installed-after.txt4. Verificar el contrato de las dependencias antes del cálculo
python -m pip check, ejecutado con el intérprete correcto, busca dependencias instaladas ausentes o incompatibles según sus metadatos. Un resultado sin conflictos no es una validación del controlador, de las extensiones nativas o de la calidad de la aplicación. Mantén, pues, este paso breve y continúa hacia una comprobación de cálculo.
Para que la reconstrucción sea más estricta, puedes fijar las versiones y conservar las huellas de las distribuciones autorizadas. Esta decisión exige mantener la lista completa que corresponde a tu plataforma. Un archivo de ruedas compiladas puede depender del SO y de la arquitectura; no es una garantía de portabilidad entre dos máquinas distintas.
En nuestro ejemplo de embeddings, compara el inventario reconstruido con la referencia antes de modificar el modelo o sus parámetros. Si una diferencia es intencional, anótala y trata la nueva ejecución como una variante. Si no, corrige la reconstrucción; cambiar varias capas a la vez hará que el diagnóstico sea menos preciso.
5. Pasar del control mínimo a la aplicación
En el intérprete del proyecto, registra Python, PyTorch y el backend, y luego verifica el dispositivo y un pequeño cálculo. Detén este paso si la GPU esperada no es accesible; una ejecución de respaldo en CPU enturbiaría la comparación. El diagnóstico de Kernodeck proporciona un informe interpretable y distingue los pasos realmente superados.
Una vez superado este control, utiliza tu pequeña muestra de la aplicación. Para los embeddings, verifica el número de salidas, sus dimensiones, su correspondencia con los identificadores y el criterio elegido. Vuelve a cargar los archivos desde la carpeta de salida. Un cálculo matricial correcto no demuestra que el preprocesamiento o una extensión del proyecto funcione.
Si la prueba falla al leer los datos, en la transferencia o durante una operación específica, conserva el paso y el primer error. La reconstrucción general puede ser correcta; el bloqueo puede pertenecer al cargador de datos o a un operador concreto. Orienta entonces el diagnóstico hacia esa capa.
6. Distinguir reconstrucción e identidad numérica
Recuperar las mismas dependencias no garantiza resultados idénticos entre hardware, plataformas o versiones de PyTorch. Fijar una semilla no cubre todas las fuentes de variación. Documenta los generadores utilizados, las transformaciones de los datos y los ajustes de precisión o de determinismo pertinentes.
Define el criterio de comparación antes de mirar la diferencia: estructura exacta, tolerancia numérica o estabilidad de una métrica. Algunos ajustes deterministas pueden rechazar operaciones o modificar el coste de cálculo. El resultado buscado es una conclusión comprensible en las condiciones anunciadas, no una promesa de identidad en cualquier máquina.
Para reanudar un entrenamiento, las versiones no bastan: también hay que restaurar el estado de cálculo y la progresión. La carpeta de reanudación verifica esta cuestión por separado. Su ejercicio en CPU y su tolerancia no se convierten automáticamente en las condiciones de tu modelo.
7. Terminar con una carpeta que otro lanzamiento pueda usar
La carpeta final reúne el procedimiento, el inventario observado, la configuración, las referencias de los datos y los resultados del control. Añade la secuencia exacta: reconstruir, diagnosticar, ejecutar la muestra, releer la salida. Conserva los accesos aparte y precisa únicamente cómo proporcionarlos.
Repite esta secuencia en una carpeta limpia antes de considerar el entorno como transmisible. El control debe superarse sin recuperar una variable de un notebook antiguo ni buscar un archivo olvidado. Si es necesario un cambio, corrige el procedimiento y da una nueva identidad a la referencia. Obtienes una base utilizable para tu próximo periodo de cálculo.