当前位置：首页 > news >正文

OLMo 3源码深度解析：从安装、准备到可调试训练架构

news 2026/7/8 18:38:56

1. 项目概述：这不是一次普通安装，而是一次对现代开源大模型工程体系的深度解剖

OLMo 3 这个名字最近在开源大模型圈子里出现的频率越来越高，但很多人点开 GitHub 仓库后第一反应是——这代码结构怎么跟 LLaMA、Qwen 或者 Phi 系列完全不是一个路子？没有显眼的modeling_*.py，没有trainer.py的封装入口，甚至找不到一个叫main.py的启动脚本。我第一次 clone 下来时也愣了三秒：这到底是个训练框架，还是个研究实验平台？后来花了整整两天时间，把olmo/目录下每个.py文件的 import 链、类继承关系和 CLI 入口全画在白板上，才真正明白 OLMo 3 的设计哲学——它不是“让你快速跑起来”，而是“逼你搞懂每一层为什么这样写”。标题里写的“读代码1”，绝不是谦虚的说法，它就是一份带注释的源码阅读指南。核心关键词 OLMO、安装、准备、项目架构，四个词其实是一个闭环：安装不是目的，而是进入架构的钥匙；准备不是铺垫，而是理解设计意图的必经路径；架构不是静态结构，而是所有安装与准备动作背后的逻辑总纲。这篇文章适合三类人：想把 OLMo 3 当作基座模型微调的工程师，需要吃透其数据加载与分布式训练机制；正在选型大模型训练框架的研究者，想对比它和 DeepSpeed、Lightning 的抽象层级差异；还有刚从 Hugging Face 生态转过来、对“无 Trainer 封装”感到不适的开发者——你会在这里看到一种更底层、更透明、但也更需要动手能力的工程范式。它不提供开箱即用的pipeline()，但每行代码都在告诉你“数据从哪来、梯度怎么反传、检查点如何序列化”。这种风格，恰恰是当前大模型工程走向可复现、可审计、可协作的关键一步。

2. 内容整体设计与思路拆解：为什么 OLMo 3 要放弃“一键训练”的幻觉？

2.1 架构分层逻辑：从“黑盒训练器”到“白盒组件链”

绝大多数主流大模型训练框架（比如 Hugging Face Transformers + Trainer）采用的是“封装式”设计：用户定义model、dataset、training_args，然后调用Trainer.train()，中间所有细节——数据采样策略、梯度累积步数、混合精度开关、检查点保存逻辑——都被封装在Trainer类内部。OLMo 3 则彻底反其道而行之，它的核心目录结构是olmo/core/、olmo/data/、olmo/train/、olmo/eval/四个平行模块，没有任何一个“上帝类”统领全局。这种设计不是偷懒，而是基于三个明确判断：

第一，训练流程的不可压缩性。当你在做长上下文训练、多阶段课程学习、或自定义 token loss masking 时，“统一 Trainer”反而成了障碍。OLMo 3 把训练循环拆成Trainer（主循环）、TrainLoop（状态管理）、StepScheduler（学习率/批次大小动态调整）三个独立类，每个类只负责一件事。比如StepScheduler里有一个update_batch_size()方法，它不关心模型参数更新，只根据当前 global step 和预设的 schedule config 修改train_config.batch_size。这种解耦让调试变得极其直观：你想看 batch size 是怎么变的？直接断点进StepScheduler.update_batch_size()；你想改梯度裁剪逻辑？只动Trainer.clip_grads()一行，不影响其他任何模块。

第二，数据流的显式声明。在olmo/data/下，你找不到Dataset的抽象基类，取而代之的是DataLoader（继承自 PyTorch）、ShardLoader（处理单个数据分片）、SampleIterator（生成单个样本）。关键在于ShardLoader的__iter__方法里，有一段硬编码的yield from self._process_shard(shard_path)，而_process_shard会调用self.tokenizer.encode()并施加max_length截断。这意味着：数据预处理不是在 Dataset 的__getitem__里隐式发生的，而是在 DataLoader 迭代时显式、同步、可追踪地执行的。这对调试数据质量至关重要——当 loss 突然飙升，你可以立刻在ShardLoader._process_shard里加日志，看到具体是哪个 shard 的第几个样本触发了异常 tokenization。

第三，配置驱动的架构粘合。OLMo 3 没有config.json，只有olmo/config/下的 Python 配置类，比如TrainConfig、ModelConfig、DataConfig。这些类不是简单的字典封装，而是带有完整类型注解和默认值校验的 dataclass。更重要的是，它们之间存在强依赖关系：TrainConfig的model_config: ModelConfig字段强制要求你必须传入一个ModelConfig实例，而ModelConfig的vocab_size: int又必须与DataConfig的tokenizer.vocab_size一致。这种设计杜绝了“配置错位”——你不可能在train_config.yaml里把vocab_size设为 50257，却在data_config.yaml里用llama-tokenizer，因为代码层面就编译不过。我实测过，如果强行绕过类型检查传入不匹配的 config，程序会在Trainer.__init__的self._validate_configs()方法里抛出清晰的ValueError：“Model vocab_size (50257) does not match tokenizer vocab_size (32000)”。

2.2 安装策略选择：为什么坚持纯 pip install + git submodule，而非 Docker 一键包？

网络热词里反复出现 “docker安装”、“vmware虚拟机安装教程”，但 OLMo 3 的官方 README 明确写着：“We recommend installing from source”。这不是故作高深，而是由它的架构特性决定的。OLMo 3 的核心依赖有两个特殊点：一是它深度绑定了flash-attn的特定 commit（不是 PyPI 上的最新版），二是它使用了xformers的一个未合并进主干的分支功能（用于优化 rotary embedding 的内存布局）。如果你用pip install olmo，PyPI 包会拉取固定版本的flash-attn，但那个版本可能不兼容你 GPU 的 compute capability（比如 A100 的 8.0 vs RTX 4090 的 8.9）。而 Docker 镜像则更麻烦——镜像里预装的 CUDA 版本、NCCL 版本、甚至glibc版本，都可能和你的宿主机环境冲突。我踩过一次坑：用官方 Docker 镜像在 WSL2 上跑，结果torch.distributed.init_process_group()一直卡在ncclCommInitRank，最后发现是镜像里的 NCCL 2.12 不支持 WSL2 的 IPC 机制。

所以 OLMo 3 的安装流程本质是一次“环境适配”：先git clone --recursive拉下主仓库和所有 submodule（注意--recursive，因为olmo/data/下的tokenizers是 submodule），然后手动编译flash-attn。编译命令是cd flash-attn && make install，但它背后做了三件事：自动检测你的 GPU 架构（通过nvidia-smi -q | grep "Product Name"），下载对应 compute capability 的 cuBLAS 库，再用nvcc编译时加上-gencode arch=compute_80,code=sm_80这样的 flag。这个过程无法被 Docker 预先打包，因为你的 GPU 型号是运行时才知道的。同理，xformers的安装也要求你先git checkout到指定分支，再python setup.py develop。这种“繁琐”恰恰是稳定性的来源——每一行编译日志都在告诉你“此刻正在为你的硬件定制什么”。

2.3 准备工作的本质：不是拷贝文件，而是建立“可验证的数据契约”

标题里的“准备”，在网络热词中常被理解为“下载数据集、解压、放对路径”。但在 OLMo 3 语境下，“准备”是一个严格的验证过程。它的olmo/data/目录下有一个prepare_data.py脚本，但它不是用来下载数据的，而是用来生成并校验数据分片（shard）的元信息。当你运行python -m olmo.data.prepare_data --data_dir /path/to/raw --shard_dir /path/to/shards --tokenizer_name gpt2，脚本会做四件事：

扫描原始文件：递归遍历/path/to/raw，收集所有.jsonl或.txt文件，按文件大小排序（确保大文件优先处理，避免小文件碎片化）；
分片切分：不是简单按行数切，而是按 token 数量切。它会用tokenizer对每个文件逐行 encode，累计 token count，当达到shard_size=100_000_000（一亿 tokens）时，关闭当前 shard 文件，开启下一个。这个shard_size是硬编码在prepare_data.py里的，不能通过命令行修改；
元信息生成：为每个生成的shard-00001.bin创建对应的shard-00001.json，里面记录num_tokens: 99876543、num_sequences: 1234567、avg_seq_len: 80.9三个关键指标；
一致性校验：最后一步，它会重新打开所有.bin文件，用mmap方式读取前 1024 个 bytes，验证它们是否都是合法的np.uint16序列（OLMo 3 强制使用 uint16 存储 token ids，因为 vocab_size < 65536），并检查总 token 数是否等于所有shard-*.json中num_tokens的 sum。

这个过程耗时很长（我处理 1TB 的 The Pile 数据集用了 17 小时），但好处是：一旦prepare_data.py成功退出，你就拥有了一个数学上可证明的数据契约——你知道每个 shard 精确包含多少 tokens，且所有 tokens 都在合法范围内。后续训练中如果出现IndexError: index 65536 is out of bounds for dimension 0 with size 65536，问题一定不在数据，而在模型vocab_size配置错了。这种确定性，在分布式训练中价值千金。

3. 核心细节解析与实操要点：从零开始搭建可调试的 OLMo 3 环境

3.1 环境初始化：conda 与 system python 的生死线

OLMo 3 的setup.py明确要求 Python >= 3.10，但很多系统自带的 Python 是 3.9 或更低。新手常犯的错误是直接sudo apt install python3.10，然后python3.10 -m pip install ...。这会导致灾难性后果：Ubuntu 系统的apt包管理器严重依赖/usr/bin/python3，如果你升级了 system python，apt update可能直接报错。正确做法是用 conda 创建隔离环境。但这里有个隐藏陷阱：conda-forge 的pytorch包默认链接的是libstdc++的旧版本，而 OLMo 3 编译flash-attn时需要libstdc++ > 3.4.29。我试过conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia，结果import torch时报GLIBCXX_3.4.29 not found。

解决方案是：先创建 conda 环境，再用 pip 安装 PyTorch。命令序列如下：

conda create -n olmo3 python=3.10 conda activate olmo3 # 关键：用 pip 而非 conda 安装 torch，因为它会自动选择匹配系统 libstdc++ 的 wheel pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

验证是否成功：运行python -c "import torch; print(torch.__version__, torch.cuda.is_available())"，输出应为2.3.0+cu121 True。如果cuda.is_available()是 False，别急着重装，先检查nvidia-smi是否能看到 GPU，再运行python -c "import torch; print(torch._C._cuda_getCurrentRawStream(None))"—— 如果这里报错，说明 CUDA driver 和 runtime 版本不匹配，需要升级 NVIDIA driver（>=535.104.05）。

提示：不要用pip install --upgrade pip升级 pip 到最新版。OLMo 3 的setup.py依赖setuptools<68.0.0，而新版 pip 会强制升级 setuptools，导致pip install -e .失败。保持 pip 在 23.x 版本即可（pip install pip==23.3.2）。

3.2 项目架构导航：一张图看懂`olmo/`目录下的权力地图

olmo/目录不是扁平的，而是一个三层权力结构。最顶层是olmo/__init__.py，它只做一件事：暴露olmo.train.Trainer和olmo.eval.Evaluator两个核心类。第二层是olmo/train/和olmo/eval/，它们是“作战指挥部”，定义了Trainer.run()和Evaluator.run()这两个终极入口函数。第三层才是真正的“兵工厂”，包括olmo/core/（模型、优化器、调度器）、olmo/data/（数据加载）、olmo/utils/（日志、检查点、分布式工具）。这种分层意味着：你永远不应该直接import olmo.core.model，而应该通过Trainer的self.model属性来访问模型实例。因为Trainer.__init__里有一段关键逻辑：

# olmo/train/trainer.py line 127 self.model = self.model_config.build_model() # 调用 ModelConfig.build_model() self.model = self._wrap_model(self.model) # 应用 DDP/FSDP 包装 self.optimizer = self._build_optimizer() # 根据 TrainConfig 构建 optimizer

_wrap_model方法会根据train_config.distributed_strategy（ddp,fsdp,deepspeed）自动选择包装方式。如果你跳过Trainer，自己from olmo.core.model import OlmoModel，那么你得到的只是一个裸模型，没有 FSDP 的shard_module，也没有 DDP 的register_comm_hook，训练时必然崩溃。我见过太多人卡在这一步，花三天时间 debugRuntimeError: Expected all tensors to be on the same device，最后发现只是因为手动 import 了模型。

3.3 安装实操：`flash-attn`编译失败的七种死法与解法

flash-attn是 OLMo 3 的性能心脏，但也是安装雷区。根据我处理 23 个不同 GPU 环境的经验，编译失败主要分七类：

失败类型	错误日志关键词	根本原因	解决方案
CUDA 架构不匹配	`nvcc: error: 'sm_90' is not a valid value for '--gpu-architecture'`	你的 GPU 是 H100（sm_90），但 nvcc 版本太低（<12.2）	升级 CUDA Toolkit 到 12.2+，或手动修改`flash-attn/setup.py`中的`arch_list`，删掉`sm_90`
cuBLAS 版本冲突	`undefined reference to 'cublasLtMatmulHeuristicResult_t'`	系统 cuBLAS 库版本（如 11.6）与 flash-attn 编译时链接的版本（12.1）不兼容	设置`export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH`，然后重编译
PyTorch 头文件缺失	`fatal error: ATen/ATen.h: No such file or directory`	`torch`没有正确安装，或`TORCH_HOME`环境变量指向错误路径	运行`python -c "import torch; print(torch.__file__)`，确认`torch/include`目录存在，然后`export TORCH_INCLUDE_DIR=$(python -c "import torch; print(torch.__file__.replace('/__init__.py', '/include'))")`
GCC 版本过高	`error: ‘__int128’ was not declared in this scope`	GCC 12+ 默认启用`__int128`，但某些 CUDA 版本不支持	降级 GCC 到 11：`sudo apt install gcc-11 g++-11`，然后`sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100`
内存不足	`gcc: fatal error: Killed signal terminated program cc1plus`	编译`flash-attn`需要 16GB+ RAM，WSL2 默认只有 4GB	在 WSL2 的`.wslconfig`中添加`memory=16GB`，重启 WSL
权限问题	`Permission denied: '/usr/local/lib/python3.10/site-packages/flash_attn'`	用`sudo pip install`导致权限混乱	彻底删除`sudo pip uninstall flash-attn`，然后用`pip install --user`或 conda 环境安装
NCCL 通信失败	`NCCL version 2.14.3+cuda12.1`后面跟着`all_reduce failed`	NCCL 的`NCCL_SOCKET_NTHREADS`设置过小	设置`export NCCL_SOCKET_NTHREADS=8`，`export NCCL_NSOCKS_PERTHREAD=4`

最稳妥的编译命令是：

cd flash-attn # 清理上次编译残留 make clean # 显式指定 CUDA 和 PyTorch 路径 CUDA_HOME=/usr/local/cuda \ TORCH_CUDA_ARCH_LIST="8.0;8.6;8.9" \ pip install -v --disable-pip-version-check --no-cache-dir --no-build-isolation --config-settings editable-verbose=true .

TORCH_CUDA_ARCH_LIST必须包含你的 GPU 架构（A100=8.0, RTX4090=8.9, V100=7.0），多个用分号隔开。-v参数会输出详细日志，失败时能精准定位到哪一行nvcc命令出错。

3.4 数据准备实操：如何用`prepare_data.py`生成可审计的分片

假设你已经下载了The Pile的train分卷（pile_train_00.tar.gz到pile_train_49.tar.gz），解压到/data/pile-raw/。现在要生成 OLMo 3 兼容的分片。关键不是“怎么运行命令”，而是“如何验证结果可信”。

第一步，创建目标分片目录并设置权限：

mkdir -p /data/pile-shards # OLMo 3 的 ShardLoader 使用 mmap，需要文件系统支持 large pages sudo sysctl vm.nr_hugepages=1024 # 确保目录在 XFS 或 ext4 上，且有足够空间（1TB+） df -h /data

第二步，运行准备脚本，但必须加上--dry-run和--verbose：

python -m olmo.data.prepare_data \ --data_dir /data/pile-raw \ --shard_dir /data/pile-shards \ --tokenizer_name gpt2 \ --shard_size 100000000 \ --dry-run \ --verbose

--dry-run会模拟整个流程但不写文件，--verbose会打印每个文件的 token count。观察输出：如果某个.jsonl文件报告tokens: 0，说明它可能为空或格式错误（比如 JSON 解析失败），需要手动检查。

第三步，正式运行，并实时监控：

# 用 ts 命令（需 apt install moreutils）给每行日志加时间戳 python -m olmo.data.prepare_data \ --data_dir /data/pile-raw \ --shard_dir /data/pile-shards \ --tokenizer_name gpt2 \ --shard_size 100000000 2>&1 | ts '%Y-%m-%d %H:%M:%S'

你会看到类似这样的日志：

[2024-05-20 14:23:15] Processing /data/pile-raw/00.jsonl... tokens: 12456789 [2024-05-20 14:25:42] Created shard-00001.bin (100000000 tokens) [2024-05-20 14:26:01] Processing /data/pile-raw/01.jsonl... tokens: 9876543

注意Created shard-*.bin行，它表示一个分片已满并关闭。如果某次运行后，/data/pile-shards/下只有shard-00001.bin而没有shard-00001.json，说明脚本在写元信息时崩溃了，需要检查磁盘空间或权限。

第四步，终极验证：用olmo/data/validate_shards.py脚本校验：

python -m olmo.data.validate_shards --shard_dir /data/pile-shards

它会输出：

Validating 50 shards... shard-00001.bin: OK (100000000 tokens, vocab_max=50256) shard-00002.bin: OK (100000000 tokens, vocab_max=50256) ... Total tokens: 5000000000, Total shards: 50

vocab_max=50256是关键——它确认所有 token id 都小于gpt2的 vocab size（50257），没有越界。如果出现vocab_max=65536，说明 tokenizer 配置错了，必须重新 prepare。

4. 实操过程与核心环节实现：从启动训练到第一个检查点

4.1 配置文件编写：YAML 不是万能的，Python Config 才是灵魂

OLMo 3 不接受train_config.yaml，它只认olmo/config/train.py里的TrainConfig类。但你可以用 YAML 来初始化它，这是官方推荐的“混合模式”。创建my_train_config.py：

from olmo.config import TrainConfig, ModelConfig, DataConfig, OptimizerConfig from olmo.data import DataConfig from olmo.train import Trainer # 1. 定义模型 model_config = ModelConfig( name="olmo-1b", # 必须是 olmo/config/models.py 中预定义的名字 vocab_size=50257, hidden_size=2048, num_layers=24, num_heads=16, ) # 2. 定义数据 data_config = DataConfig( train_shard_dir="/data/pile-shards", val_shard_dir="/data/pile-val-shards", # 验证集分片 tokenizer_name="gpt2", seq_len=2048, ) # 3. 定义优化器 optim_config = OptimizerConfig( name="adamw", lr=3e-4, weight_decay=0.1, betas=(0.9, 0.999), ) # 4. 主训练配置 train_config = TrainConfig( model_config=model_config, data_config=data_config, optim_config=optim_config, batch_size=1024, # global batch size grad_accumulation_steps=8, # per-GPU accumulation save_interval=1000, # 保存检查点的 global step 间隔 log_interval=10, # 日志打印间隔 wandb_project="olmo-1b-finetune", # Weights & Biases 项目名 )

这个文件的价值在于：所有配置项都有类型提示和默认值，IDE（如 PyCharm）能实时提示可用参数，且train_config.validate()会在运行前做完整性检查。比如，如果你忘了设train_config.save_interval，Trainer.__init__会报错：“save_intervalmust be a positive integer”。

4.2 启动训练：`Trainer.run()`背后的十二个隐式步骤

运行python -m olmo.train --config my_train_config.py后，Trainer.run()会依次执行以下步骤（我在olmo/train/trainer.py里加了 12 个print(f"[STEP {i}] ...")日志）：

环境探测：self._detect_environment()读取CUDA_VISIBLE_DEVICES，计算world_size=4（如果你有 4 张 GPU），设置rank=0（主进程）；
配置验证：self.train_config.validate()检查batch_size % (num_gpus * grad_accumulation_steps) == 0，确保能整除；
模型构建：self.model_config.build_model()实例化OlmoModel，此时model.num_parameters()返回 1.2B；
数据加载器构建：self._build_dataloaders()创建ShardLoader，它会扫描/data/pile-shards/下所有shard-*.bin，按shard_id排序，并为每个 GPU 分配连续的 shard range（GPU0: shard-00001~00012, GPU1: 00013~00024...）；
优化器构建：self._build_optimizer()根据OptimConfig创建torch.optim.AdamW，但关键在self._setup_fsdp()（如果启用了 FSDP）；
FSDP 初始化：self._setup_fsdp()调用FullyShardedDataParallel(model, ...)，并传入auto_wrap_policy，该策略会递归包装所有nn.TransformerEncoderLayer；
检查点加载：self._load_checkpoint()查找checkpoints/latest.pth，如果存在，恢复model.state_dict()、optimizer.state_dict()和self.step；
日志系统初始化：self._setup_logging()启动wandb.init()，并注册self._log_metrics()回调；
主循环启动：进入for self.step in range(self.start_step, self.train_config.max_steps):；
数据采样：batch = next(self.train_loader)，此时ShardLoader.__next__()从当前 shard 读取batch_size // world_size个序列；
前向传播：loss = self.model(batch["input_ids"], batch["attention_mask"])，FSDP 自动处理梯度分片；
梯度同步：self._step()调用self.optimizer.step()，FSDP 的post_backward_callback触发all_reduce。

这个过程之所以可控，是因为每一步都是一个可重写的self._xxx()方法。如果你想自定义梯度裁剪，只需重写Trainer.clip_grads()；如果你想换数据采样策略，重写Trainer._build_dataloaders()即可。没有魔法，只有清晰的钩子。

4.3 第一个检查点分析：解剖`checkpoints/step-00001000/`里的秘密

当训练跑到step=1000，OLMo 3 会生成checkpoints/step-00001000/目录，里面包含：

model.pth: 模型权重（如果是 FSDP，这是shard_00000.pth到shard_00003.pth的集合）
optimizer.pth: 优化器状态（包括param_groups、state字典）
train_state.json: 记录step: 1000,epoch: 0,lr: 3e-4,loss: 4.2187
config.json: 当前TrainConfig的 JSON 序列化（用于复现实验）

最关键的不是model.pth，而是train_state.json。它里面有一个rng_states字段，存储了torch.random.get_rng_state()、numpy.random.get_state()、random.getstate()三个随机状态。这意味着：如果你用完全相同的train_state.json和model.pth重启训练，从step=1000开始，每一个 batch 的数据顺序、dropout mask、weight initialization 都会和第一次完全一致。这是 OLMo 3 对“可复现性”的终极承诺。我验证过：在step=1000保存检查点，然后修改train_config.lr=1e-4，重启后step=1001的 loss 和第一次step=1001的 loss 差异在1e-6以内。

注意：train_state.json里的timestamp是 ISO 格式字符串（"2024-05-20T14:23:15.123456"），不是 Unix 时间戳。如果你要用脚本批量分析检查点，别用int(time.time())去比对，要用datetime.fromisoformat()解析。

5. 常见问题与排查技巧实录：那些文档里不会写的血泪教训

5.1 问题速查表：高频崩溃场景与一招毙命解法

问题现象	根本原因	一招毙命解法	为什么有效
`RuntimeError: Expected all tensors to be on the same device`	`ShardLoader`加载的`input_ids`在 CPU，而`model`在 GPU	在`ShardLoader.__next__()`末尾加`batch = {k: v.cuda() for k, v in batch.items()}`	`ShardLoader`默认不移动设备，它假设你用`DistributedSampler`，但 OLMo 3 的`ShardLoader`是自研的，必须手动`cuda()`
`OSError: [Errno 24] Too many open files`	`ShardLoader`同时打开 50+ 个`.bin`文件，超过系统 limit	运行`ulimit -n 65536`，然后重启训练进程	Linux 默认`ulimit -n`是 1024，而 OLMo 3 的`ShardLoader`会预加载多个 shard 的 header，需要大量 file descriptor
`ValueError: Expected input batch_size (1024) to match target batch_size (512)`	`ShardLoader`的`batch_size`和`Trainer`的`batch_size`单位不一致（前者是 per-GPU，后者是 global）	在`my_train_config.py`中，设`train_config.batch_size = 4096`（4 GPUs × 1024）	`Trainer`的`batch_size`是 global 总量，`ShardLoader`的`batch_size`是每个 loader 的输出量，必须`global_batch_size % world_size == 0`
`CUDA out of memory`在`step=0`	`FSDP`的`reshard_after_forward=True`导致峰值内存翻倍	在`TrainConfig`中添加`fsdp_config={"reshard_after_forward": False}`	`reshard_after_forward=False`会让 FSDP 保持所有参数分片在 GPU 上，不 re-shard，内存占用更平稳，牺牲一点通信带宽
`wandb`日志卡住，CPU 占用 100%	`wandb`的`thread_count`默认为`os.cpu_count()`，在容器里可能错误识别为 64	设置`os.environ["WANDB_START_METHOD"] = "thread"`，并在`train_config.wandb_config`中加`"thread_count": 4`	强制`wandb`用单线程，避免在高核数机器上创建过多线程争抢 GIL

5.2 独家避坑技巧：来自生产环境的三条铁律

铁律一：永远不要信任pip list | grep olmo
OLMo 3 的setup.py使用find_packages()，但如果你在olmo/目录外运行pip install -e .，它会把当前目录也当作一个包安装，导致import olmo时导入的是空目录。正确姿势是：必须在olmo/目录内运行pip install -e .。验证方法：python -c "import olmo; print(olmo.__file__)"，输出必须是/path/to/olmo/olmo/__init__.py，而不是/path/to/olmo/__init__.py。