1. 定义参照与预期结果
首先明确您想要复现的内容：产出相同的类别、获得接近的数值，或复现一条训练轨迹。保留一组能贯穿关键步骤的小型输入，以及一个有效输出的示例。一次无报错完成的安装还不能回答这个问题。
举一个教学案例：你的应用为某个已识别的样本生成嵌入。在参考环境中，你需要记录输出的形状、类型、是否存在非有限值以及有用的业务判据。如果要比较数值，请选择由你的使用场景所证明合理的容差。这里不提供任何通用的数值阈值。
为代码、数据和权重指定一个修订版本。像“dernier-modele”（最新模型）这样的名称可能在程序毫无察觉的情况下发生变化。还要把参数和预处理与参考版本关联起来。这套记录可以让你知道某个差异究竟来自软件、输入还是运行条件。
左右滚动表格即可查看所有列。| 元素 | 需保留的内容 | 重建后的检查 |
|---|---|---|
| 代码与参数 | 修订版本、可能的修改、配置 | 相同的入口点和相同的选项。 |
| 数据与权重 | 版本或指纹、来源与访问权限 | 相同的样本和相同的预期内容。 |
| Python 与软件包 | 版本、安装流程与来源 | 正确的解释器和一致的依赖项。 |
| 系统与后端 | 操作系统、架构、驱动、CUDA 或 ROCm | 可见的设备以及最小计算成功完成。 |
| 结果 | 格式与验收标准 | 先看结构，再看质量或预期容差。 |
2. 将系统链路与 Python 软件包分开
请将显卡、系统、驱动、Python 和各库放在一起检查。虚拟环境负责组织 Python 软件包，但它不能替代系统驱动。同样，镜像的参考标识也不足以描述从宿主机实际访问 GPU 的情况。对于编译型扩展，请记录所需的编译工具和库。
请根据项目的计算平台选择 PyTorch 发行版。在 ROCm 上，PyTorch 复用 torch.cuda 调用以及名为 cuda 的设备：接口的名称并不能用来识别 NVIDIA。请分别记录 torch.version.cuda 和 torch.version.hip。为某一链路编写的扩展值得单独进行验证。
请保留下真正让安装得以完成的流程，并记录软件包的来源。避免把网上找到的新命令与旧的依赖文件混用而不检查兼容性。你查阅的文档可能会变化；请在使用时把所用版本记入你自己的记录中。
3. 编写重建流程，而不是复制已安装的目录
用选定的 Python 创建一个新环境。然后显式使用它的解释器来安装和启动项目。在 Linux 上，例如 .venv-rebuild/bin/python；在 Windows 上，则是 .venv-rebuild\Scripts\python.exe。你无需依赖此前的激活操作。Python 文档明确指出，虚拟环境一旦改变位置就必须重新创建。
pip freeze 提供的是已安装软件包的清单，而不是经过计算的锁定文件。请把它作为观察记录保留下来。重建文件还应明确说明你的 PyTorch 变体所需的索引或文件，以及兼容的版本。在分享之前，请重新检查清单中可能包含的路径或 URL。
下面的命令演示了一次需要按需调整的 Linux 重建；它们并不构成对你项目的实际执行测试。requirements-rebuild.txt 文件应当已经描述了你的环境，包括对 PyTorch 的正确选择。不要用一份假定通用的版本列表来替代它。
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. 在计算前检查依赖项的契约
用正确的解释器运行 python -m pip check，会根据元数据查找已安装但缺失或不兼容的依赖项。没有冲突的结果并不代表驱动、原生扩展或应用质量通过了验证。因此请让这一步保持简短，然后继续做一次计算检查。
为了让重建更加严格，你可以固定版本并保留已授权发行版的指纹。这一决定要求你维护一份与自身平台相对应的完整清单。编译 wheel 的归档可能取决于操作系统和架构；它并不保证在两台不同机器之间具有可移植性。
在我们这个 embeddings 示例中，请在修改模型或其参数之前，将重建出的清单与参考进行对比。如果某处差异是有意为之，请记录下来，并将新的运行视为一个变体。否则，请修正重建；同时改动多个层会降低诊断的精确度。
5. 从最小检查过渡到应用
在项目的解释器中，记录 Python、PyTorch 和后端，然后检查设备并做一次小计算。如果预期的 GPU 不可访问，请停止此步骤；回退到 CPU 执行会干扰对比。Kernodeck 诊断会提供一份可解读的报告，并区分实际已完成的步骤。
一旦这项检查通过，就使用你的小型应用样本。对于 embeddings，请检查输出的数量、它们的维度、它们与标识符的对应关系，以及所选定的判据。从输出文件夹重新加载文件。一次成功的矩阵计算并不能证明预处理或项目的某个扩展也能正常工作。
如果试运行在读取数据、传输或执行某个特定操作时崩溃，请保留该步骤和第一个错误。整体重建可能是正确的；卡点可能属于数据加载器或某个特定的算子。此时应将诊断方向转向那一层。
6. 区分重建与数值一致性
找回相同的依赖并不能保证在不同硬件、平台或 PyTorch 版本之间得到相同的结果。固定随机种子并不能覆盖所有变异来源。请记录所使用的生成器、数据变换，以及相关的精度或确定性设置。
在查看差异之前，先定义比较判据：精确结构、数值容差或某项指标的稳定性。某些确定性设置可能会拒绝某些操作，或改变计算开销。所追求的结果是在已声明的条件下得出一个可理解的结论，而不是承诺在任意机器上都完全一致。
对于训练恢复来说，仅有版本是不够的：还需要恢复计算状态和进度。恢复文件夹会单独检查这一问题。它的 CPU 演练和容差不会自动成为您模型的条件。
7. 以一份可供他人再次启动使用的文件夹收尾
最终文件夹汇集了流程、观察到的清单、配置、数据引用以及检查结果。请补充确切的顺序：重建、诊断、运行样本、回读输出。将访问凭据单独保存，并仅说明如何提供它们。
在认为环境可传递之前，请在一个干净的文件夹中重跑这一顺序。检查必须在无需从旧 notebook 中取用变量、也无需寻找被遗忘的文件的情况下通过。如果必须做出改动，请修正流程，并给参考赋予新的标识。你就得到了一个可用于下一段计算周期的基础。