1. 将程序、其参数与商业跟踪分离
代码描述程序的行为。配置则明确负载：模型、数据、批次、精度和目标。密钥用于访问所需资源。请将这些要素分开，以便在更改试验时无需重写代码或将令牌复制到共享文件中。
Kernodeck 命令参考可让您在账户中找回租赁的上下文。试验标识用于区分该时间段内您程序的各次执行。如有帮助，可在笔记中将二者关联，但不要要求您的脚本从支付状态推断计算状态。
假设有一个文档排序项目，需要在同一样本上多次启动。程序合约描述了输入文件、可接受的参数、输出目录以及呈现错误的方式。关于数据的指南说明了内容验证；这里，我们组织连接这些步骤的接口。
2. 编写明确且带版本的输入契约
记录必填字段和可接受的值。对于会改变结果的决策，如模型或设备，请避免静默的默认值。架构编号区分配置的形式与代码版本，它不能替代代码版本。
在这个教学示例中，JSON 文件包含一个架构、一个输入路径、一个批次以及所请求的设备。相对路径从配置文件夹读取。此示例所选的规则避免了依赖同事运行命令时所在的目录。
读取 JSON 仅验证其语法。您的程序随后必须检查类型、字段以及项目约束。一旦出错，它应在加载昂贵资源之前停止，并给出指明需修正参数的消息。
{
"schema_version": 1,
"input": "../data/pilote.jsonl",
"batch_size": 4,
"device": "cuda"
}3. 准备一个能拒绝简单错误的入口点
argparse 可用于声明选项并为您的命令生成帮助。以下示例仅作为预检查：它读取配置、检查其字段，并识别已被使用的输出文件夹。它不会将模型或数据加载到内存中，也不会测试 GPU 的可用性。
如果您想调整，请将此教学代码保存到 prepare_run.py。它未经实际执行验证。随后请将您的业务校验添加到应用中，而不是把最终消息当作计算结果。设备 cuda 只是一个请求；PyTorch 在 ROCm 下也使用这个名称。
拒绝已存在的输出目录在这里是一种防止试验相互混淆的保护约定。真正的恢复命令必须接收一个选项和独立的检查。不要因为存在某些文件就把全新启动变成隐式恢复。
import argparse
import json
from pathlib import Path
parser = argparse.ArgumentParser(description="验证一次项目启动")
parser.add_argument("--config", type=Path, required=True)
parser.add_argument("--run-dir", type=Path, required=True)
args = parser.parse_args()
try:
config_path = args.config.resolve()
config = json.loads(config_path.read_text(encoding="utf-8"))
except (OSError, UnicodeError, json.JSONDecodeError) as exc:
parser.error(f"配置无法读取：{exc}")
expected = {"schema_version", "input", "batch_size", "device"}
if not isinstance(config, dict) or set(config) != expected:
parser.error("需要以下字段：schema_version, input, batch_size, device")
if type(config["schema_version"]) is not int or config["schema_version"] != 1:
parser.error("schema_version 必须为 1")
if type(config["batch_size"]) is not int or config["batch_size"] < 1:
parser.error("batch_size 必须为正整数")
if config["device"] not in ("cpu", "cuda"):
parser.error("device 必须为 cpu 或 cuda")
if not isinstance(config["input"], str) or not config["input"]:
parser.error("input 必须为非空路径")
input_path = (config_path.parent / config["input"]).resolve()
run_dir = args.run_dir.resolve()
if not input_path.is_file():
parser.error("输入文件不存在")
if run_dir.exists():
parser.error("请选择一个新的输出文件夹")
print(json.dumps({
"status": "configuration_validated",
"input": str(input_path),
"run_dir": str(run_dir),
"device_requested": config["device"],
"batch_size": config["batch_size"]
}, ensure_ascii=False))python prepare_run.py --config config/pilote.json --run-dir runs/pilote-0014. 为执行及其结果赋予身份
将每次启动关联到一个在你整个实验活动中唯一的短标识符。记录代码修订、schema 和实际使用的参数，然后记录数据与模型的引用。将这些值与输出一起保存，这样结果就不会依赖于之后被修改的配置文件。
要比较两种 batch 大小，请创建两组试验和两个目录。保持相同的样本，并标明有意的差异。pilote-001 和 pilote-002 这些名称本身无法说明改动了什么：manifest 将名称与参数关联起来。
为你的工具预留一种可读的汇总格式。它可以区分已接收、成功、被拒绝和待处理的条目。选择一套完整成功的判定规则，不要在写出第一个结果时就把试验标记为完成。程序的返回码必须与该结论保持一致。
左右滚动表格即可查看所有列。| 文件或状态 | 角色 | 预期校验 |
|---|---|---|
| manifest.json | 代码、数据与参数的身份 | 实际使用的值，不含密钥。 |
| results.jsonl | 每个被接受的条目对应一个输出 | 已知标识符且格式合规。 |
| errors.jsonl | 被拒绝的条目及有用的原因 | 不得静默消失，也不得有无用的敏感内容。 |
| summary.json | 试验结论与计数器 | 总和一致，在给出最终状态前重新读取文件。 |
5. 向你的工具暴露有用的事件
让几个转换过程可见：配置已接受、数据可访问、模型已加载、第一个输出已写出以及处理结束。一条追踪记录应能在不复制文档或 prompt 的情况下回答“这次启动进行到哪一步了？”。将阶段与试验标识符关联到消息中。
Python 的 logging 模块可以按级别和目的地组织消息。然后选择你自己的事件约定并记录下来。一个先写出错误、最后却以成功结束的应用程序会让自动化产生误判；反过来，每条警告并不意味着结果不可用。
不要把已发出的事件与持久结果混为一谈：一条“开始保存”的消息并不能证明文件已被重新读取。对于长时间运行，专门指南解释了进程与会话之间的关系。你的界面最重要的是在交互式连接结束后仍保留一个可访问的结论。
6. 定义失败、恢复与最终校验
对失败进行有效分类：配置无效、资源缺失、计算错误和结果不符合要求。为每一类给出下一步操作。不要在未确定哪些效果可以重复之前就安装自动重试：重写已接受的输出与恢复检查点需要不同的规则。
你的最终流程应说明如何启动、观察、停止、恢复和导出。对于文档处理，保留已完成和待重处理的标识符列表。对于训练，使用能在新进程中验证已保存状态的协议。非空目录并不能证明恢复正确。
最后，用一次新的调用、已知配置和不同的目标位置来验证项目。检查预期的拒绝情况，然后跑一遍小型完整流程。本页的预检不覆盖并发访问、服务的公开暴露或存储权限：这些主题需要各自的设计。