附录 A　从空电脑到可复现实验环境¶

本附录给出一条不依赖特定云平台的环境路线。版本会变化，因此原则比命令更重要：先确定操作系统、Python、GPU 驱动和框架的兼容关系；每个项目使用隔离环境；安装后做最小健康检查；最后锁定依赖并记录硬件。

A.1 CPU、GPU 与显存分别负责什么¶

CPU 负责 Python 调度、数据解析、tokenization 和大量通用任务；GPU 擅长并行矩阵计算；显存保存权重、激活、梯度、优化器状态和缓存。没有 GPU 可以完成 NumPy、数据处理、API 应用和小模型实验，但本地运行数十亿参数模型会受到内存与速度限制。

粗略估算权重存储时，可用“参数量×每参数字节”。7B 模型仅 FP16 权重约需 14 GB，但真实推理还需要 KV Cache、临时 buffer 和框架开销；训练还需要梯度和优化器状态，不能用权重大小直接判断能否训练。量化文件变小也不保证目标硬件具有加速 kernel。

A.2 创建虚拟环境¶

python -m venv .venv

Windows PowerShell 激活：

.venv\Scripts\Activate.ps1

Linux/macOS 激活：

source .venv/bin/activate

确认 python 和 pip 指向当前环境：

python -c "import sys; print(sys.executable)"
python -m pip --version

始终优先使用 python -m pip，因为它明确调用当前 Python 对应的 pip。若 PowerShell 禁止激活脚本，应先理解组织安全策略；不要从陌生网页复制修改全局执行策略的命令。

A.3 安装 PyTorch 前先核对兼容关系¶

GPU 环境至少包含三层：操作系统驱动、PyTorch 包内或依赖的 CUDA runtime、实际 GPU 架构。nvidia-smi 显示的“CUDA Version”通常表示驱动可支持的最高 CUDA 版本，不等于你安装的 PyTorch build。

安装命令应从 PyTorch 官方选择器获取。安装后运行：

import torch

print("torch:", torch.__version__)
print("torch cuda build:", torch.version.cuda)
print("cuda available:", torch.cuda.is_available())
if torch.cuda.is_available():
    print("device:", torch.cuda.get_device_name(0))
    x = torch.randn(1024, 1024, device="cuda")
    y = x @ x
    print(y.mean().item())

若 cuda available 为 False，按顺序检查：是否安装了 CPU 版 PyTorch；驱动是否可见；当前 Python 是否是刚安装依赖的环境；远程容器是否映射 GPU；系统是否需要重启。不要在原因未明时重复安装多个 CUDA Toolkit，它们可能并不能解决 wheel 与驱动的问题。

A.4 Hugging Face 模型与缓存¶

下载模型前阅读模型卡、许可证、参数量、精度和上下文长度。权重、tokenizer 和配置必须属于同一版本。缓存目录可能占用大量磁盘，团队环境应明确缓存位置、清理策略和离线镜像。

对包含 trust_remote_code=True 的项目要特别谨慎：这意味着模型仓库代码会在本地执行。只有确认来源、固定 revision 并审查代码后才考虑启用。对于 checkpoint，优先使用安全序列化格式；不可信 pickle 可能在加载时执行代码。

A.5 依赖锁定与环境报告¶

最简单的环境快照可以用：

python -m pip freeze > requirements-lock.txt

但 pip freeze 记录的是当前环境的所有包，不一定是最小依赖。成熟项目可使用 pyproject.toml 描述直接依赖，再由锁定工具生成解析后的版本。无论采用什么工具，实验报告都应包含 Python、核心库、操作系统、CPU/GPU、驱动和启动命令。

A.6 常见环境错误清单¶

ModuleNotFoundError：先打印 sys.executable，确认装包和运行使用同一环境。
CUDA OOM：记录实际分配与保留显存，缩小单样本长度；梯度累积不能解决一条样本本身放不下。
DLL/so 加载失败：检查架构、编译版本和依赖搜索路径，不要随意下载未知 DLL 覆盖系统文件。
tokenizer 或模型维度不匹配：核对仓库 revision、词表大小、特殊 token 和 resize 过程。
多进程卡死：记录每个 rank 最后一步，检查样本数量、集合通信顺序和异常进程。
结果不复现：除随机种子外，还要核对数据顺序、非确定 kernel、库版本、精度与硬件。

A.7 一个合格的环境验收¶

环境准备完成的标准不是“安装没有报错”，而是：NumPy 示例可以运行；PyTorch 前向与反向通过；GPU 小矩阵计算通过；保存的模型能在新进程加载；版本报告已写入文件；仓库不包含密钥、缓存和大权重。之后再进入大模型下载和训练，会节省大量排错时间。

附录 A 从空电脑到可复现实验环境¶