Chapter 02
安装与依赖：nightly PyTorch
📌 commit af33f76跟最新 PyTorch 跑
TorchTitan 主打"PyTorch 原生"，依赖很少：PyTorch 主分支 + 几个数据集 / 日志库。但因为大量用 PyTorch 新 API（DTensor、CP、async TP），通常要 nightly PyTorch。
2.1三条安装路径
| 方式 | 命令 | 场景 |
|---|
| 稳定版（不一定全 feature） | pip install torchtitan | 跑跑看 |
| 跟最新 + nightly torch | pip install --pre torch torchvision --index-url https://download.pytorch.org/whl/nightly/cu124 && pip install torchtitan | ★ 推荐 |
| 源码 | git clone … && pip install -e . | commit af33f76 |
2.2依赖矩阵
| 包 | 版本 | 角色 |
|---|
| torch | nightly >= 2.6（CP/PP API） | 底座 |
| torchao | >= 0.5 | FP8 / 量化训练 |
| tomli / tomllib | — | 读 toml 配置 |
| datasets | >= 2.20 | 数据加载 |
| tiktoken / sentencepiece | — | tokenizer |
| tensorboard | — | 日志 |
2.3源码安装步骤
git clone https://github.com/pytorch/torchtitan
cd torchtitan
git checkout af33f76
# 装 nightly torch
pip install --pre torch torchvision torchao \
--index-url https://download.pytorch.org/whl/nightly/cu124
# 装 torchtitan
pip install -e .
# 验证
python -c "import torchtitan; print(torchtitan.__version__)"
2.4仓库结构
torchtitan/ https://github.com/pytorch/torchtitan
├── torchtitan/
│ ├── train.py ★ 主训练脚本
│ ├── components/ 模型 / parallelize / optimizer
│ │ ├── lr_scheduler.py
│ │ ├── optimizer.py
│ │ ├── tokenizer/
│ │ └── ...
│ ├── distributed/ 分布式工具
│ ├── experiments/ 实验性模型 (DeepSeek-v3 / Mixtral / ...)
│ ├── models/ Llama 3 等主线模型
│ ├── datasets/ hf_datasets / wrappers
│ └── utils/
├── docs/ 架构 / FSDP2 / TP 说明
├── train_configs/ ★ toml 配置（每模型一份）
├── benchmarks/
└── tests/
2.5常见装机问题
| 现象 | 处理 |
|---|
| "DTensor not found" | torch < 2.4；升 nightly |
| "AttributeError: ContextParallel" | torch nightly 不够新；用 2.6+ |
| torchao import 失败 | pip install --pre torchao --index-url ... |
| flash-attn 必须吗 | 不必须，torch 2.5+ 的 SDPA 已包含 flash 实现 |
2.6这章你需要带走的
- TorchTitan 几乎只依赖 torch + torchao；
- 需要 nightly torch >= 2.6 才能用 CP / async TP；
- 仓库结构清爽：train.py 是主流程，配置在 train_configs/；
- 不需要 Apex / flash-attn / TransformerEngine。