54-复现实验清单 Template v1.0 | 第4章 环境锁定与依赖（硬件/容器/驱动）

目录 ／ 文档-技术白皮书 ／ 54-复现实验清单 Template v1.0

第4章 环境锁定与依赖（硬件/容器/驱动）

I. 目标与范围（Purpose & Scope）

• 规定硬件/OS/驱动/容器/框架/编译器/时钟源的锁定方法与验证流程，输出机读清单，确保任意环境下等价执行、可审计、可回滚。
• 凡涉及路径量（到达时/相位），正文显式 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；所有表达括号化，发布要求 p_dim = 1.0 并随附 check_dim_report.json。

II. 输入与依赖（Inputs & Dependencies）

• 对齐：《数据集卡》Ch.3/Ch.4/Ch.6/Ch.7/Ch.10、《模型卡》Ch.6/Ch.10/Ch.11/Ch.12、《误差预算卡》Ch.8/Ch.9、《管线卡》Ch.5/Ch.12、《参数注册卡》Ch.6。
• 引用统一“卷名 + 版本 + 锚点（P/S/M/I）”，锚点直指率 ≥ 90%；对外仅 v1.*。

III. 硬件锁定（Hardware Lock）

• 必填字段：CPU 型号与核心数、指令集；GPU/加速卡型号与数量、SM/VRAM；内存/存储类型与容量；电源/机架电源域（如有）；时钟源。
• 时钟与同步：clock_state="locked"，记录 δt_abs、Δτ_ch、σ_y(τ) 的目标与实测。
• 功耗记录（如涉及）：P_avg、Energy/req 的采样窗口与采样频率。

示例 — env_lock.json:hardware（节选）

{

"hardware": {

"cpu": { "model": "Intel Xeon 8368", "sockets": 2, "cores_per_socket": 38, "isa": "AVX512" },

"gpu": [{ "model": "NVIDIA A100 80GB", "count": 8, "sm": 108, "vram_gb": 80 }],

"memory": { "ram_gb": 1024, "type": "DDR4" },

"storage": { "type": "NVMe", "size_tb": 8, "raid": "none" },

"power": { "pdu_domain": "rackA", "p_avg_w": 1650 },

"clock": { "state": "locked", "source": "GNSS_PPS", "allan_1s": 1.0e-11 }

}

}

IV. OS/驱动/框架锁定（OS/Drivers/Frameworks）

• OS/内核：发行版与版本、内核版本、glibc。
• 驱动：GPU/加速器驱动与固件，PTP/NTP 服务版本与配置。
• 框架与编译器：深度学习框架、编译器/链接器、数学库（MKL/cuBLAS/cuDNN/FFT）。
• 包锁文件：requirements.lock / conda-lock.yml / pip-compile.txt 等。

示例 — env_lock.json:software（节选）

{

"software": {

"os": { "name": "Ubuntu", "version": "22.04", "kernel": "5.15.0-106" },

"drivers": { "nvidia": "535.146.02", "cuda": "12.2", "cudnn": "9.1.0" },

"frameworks": { "torch": "2.2.2+cu122", "triton": "2.2.0", "numpy": "1.26.4" },

"toolchain": { "gcc": "11.4.0", "cmake": "3.26.4" },

"time": { "ptp": "phc2sys 4.1", "ntp": "chrony 4.3" }

}

}

V. 容器与镜像（Containers & Images）

• 镜像来源：注册表、镜像名、标签/摘要（digest 必填），基础镜像链。
• 运行参数：ulimits、设备映射、挂载、环境变量、入口点。
• 可移植性：声明 cgroup/namespace 要求、容器运行时（docker/podman/containerd）。

示例 — container_spec.yaml

version: "1.0.0"

image:

name: "registry.example.com/ml/ptn-repro"

tag: "1.2.0"

digest: "sha256:abcdef..."

runtime:

driver: "nvidia"

gpus: "all"

shm_size: "64g"

ulimits: { memlock: -1, stack: 67108864 }

mounts:

- { src: "/data", dst: "/mnt/data", mode: "ro" }

env:

- { name: "OMP_NUM_THREADS", value: "8" }

- { name: "HF_HOME", value: "/opt/.cache/hf" }

entrypoint: ["bash","-lc"]

cmd: ["./reproduce.sh"]

VI. 决定性与随机性（Determinism & RNG）

• 随机源：统一 seed，固定数据打乱/初始化/算子随机性；关闭非确定性内核或替换为确定实现。
• 库级设置：torch.use_deterministic_algorithms(True)、cudnn.deterministic=True、cublasLt 重排关闭等。
• 时间/并发：禁用依赖 wall-clock 的非确定逻辑；并发度与线程/流数固定。

示例 — seed_policy.yaml

seed: 20250924

deterministic: true

torch:

deterministic_algorithms: true

cudnn: { deterministic: true, benchmark: false }

numpy: { seed: 20250924 }

random: { seed: 20250924 }

VII. 运行前自检（Preflight Checks）

• 硬件探测：设备数/型号匹配；VRAM/PCIe 拓扑一致。
• 驱动与库：版本/ABI 校验；CUDA capability 与已编译算子匹配。
• 时间锁定：clock_state=="locked" 且 δt_abs/Δτ_ch/σ_y(τ) 在阈值内。
• 包一致性：锁文件哈希匹配；不可替换包黑名单通过。

示例 — preflight_report.json（节选）

{

"hardware_ok": true,

"drivers_ok": true,

"timebase_ok": true,

"packages_ok": true,

"notes": []

}

VIII. 路径量统一口径（Normative Path Forms）

• 到达时（两式等价）：
  T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
  T_arr = ( ∫ ( n_eff / c_ref ) d ell )
• 相位累计：
  Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell )

执行与核验前按“时间→路径→相位”顺序对齐；数组满足 len(gamma_ell)=len(d_ell)=len(n_eff)≥2；数据侧记录 delta_form；全程 I70-dim_check，要求 p_dim = 1.0。

IX. 质量门映射（Gate Mapping）

• G1 Schema 完整：env_lock.json / container_spec.yaml / preflight_report.json 齐备；
• G2 引用合规：清单 see[]/version 锚点直指率 ≥ 90%；
• G3 路径规范：路径块与步长/对齐约束在相关清单中可机读；
• G4 量纲闭合：check_dim_report.json 通过；
• G5 新鲜度：时钟锁定与 τ_calib 合规；
• G6 覆盖一致：本章不改动覆盖模式；
• G7 协方差一致：不引入与误差卷冲突的数值库或随机性；
• G8 唯一性与无环：制品具 checksum/signature，引用 lineage 无环。
• 触发 S1–S5（量纲/新鲜度/路径/协方差/引用）即拒绝验收或标注 [Restricted]。

X. 反例与修正（Anti-Patterns & Fixes）

• 反例：容器仅给 tag 未给 digest → 修正：补充 digest 并在清单锁定。
• 反例：T_arr = ∫ n_eff / c_ref d ell（无括号） → 修正：括号化统一口径。
• 反例：clock_state!="locked" 或 δt_abs 超阈仍执行 → 修正：阻断并告警。
• 反例：未固定随机源/使用非确定性内核 → 修正：固定 seed 与确定性开关或替换实现。
• 反例：锁文件与现场包版本不一致 → 修正：以锁文件为准重建环境并校验 ABI。

XI. 机读清单（Machine-Readable Artifacts）

• env_lock.json：硬件/OS/驱动/框架/时钟。
• container_spec.yaml：镜像与运行参数。
• seed_policy.yaml：随机性与确定性策略。
• preflight_report.json：运行前自检结果。
• report_manifest.yaml/checksums.txt/SIGNATURE.asc：清单与签名。

XII. 交叉引用（Cross-References）

• 《模型卡》Ch.11（资源与性能）、Ch.10（部署接口）；
• 《管线卡》Ch.5（时基/同步/缓冲）、Ch.12（产出与发布）；
• 《数据集卡》Ch.10（API/访问）；
• 《误差预算卡》Ch.8（区间与协方差口径）；
• 《参数注册卡》Ch.6（版本与新鲜度）。

XIII. 勾选清单（Checklist）

• env_lock.json / container_spec.yaml / seed_policy.yaml / preflight_report.json 完整且已入库。
• 时钟锁定且 δt_abs/Δτ_ch/σ_y(τ) 在阈值内；路径块显式 gamma/measure/delta_form；p_dim = 1.0。
• 容器以 digest 锁定，驱动/框架版本与锁文件一致；随机源与确定性开关完成配置。
• 清单具 checksum/signature；引用锚点直指率 ≥ 90%；不合规项按 [Restricted] 标注与处置。