背景概述

在大规模语言模型（LLM）训练过程中，高质量数据集的获取与高效加载是影响训练效果和效率的关键环节。C4（Colossal Clean Crawled Corpus）作为业界广泛使用的预训练数据集，包含超过 3.6 亿条英文文本样本，是众多主流模型（如 T5、Qwen 等）的基础训练语料。

torchtitan 是 PyTorch 官方推出的原生大规模模型训练库，以模块化设计和易用性著称，支持 1D/2D/3D 并行策略，能够帮助开发者快速搭建分布式训练任务。然而，在实际部署中，开发者常面临以下挑战：

• 数据集下载困难：C4 数据集体积庞大（压缩后约 310GB），且 Hugging Face 官方源在国内访问不稳定；
• 环境适配复杂：在 Atlas 800I A2 NPU 上运行 torchtitan 需要额外的环境配置与参数调整；
• 训练启动效率低：多卡并行时数据集缓存转换存在锁竞争问题，可能导致训练长时间无响应。

本文基于实际项目经验，系统性地梳理了从数据集下载、环境配置到训练启动的完整流程，并针对昇腾 NPU 硬件特性提供了专项优化方案，帮助开发者快速上手并规避常见问题。

---

目录

1. 前置准备
2. C4 数据集下载
   • 2.1 方法一：hf 命令行工具
   • 2.2 方法二：wget 直接下载（推荐）
   • 2.3 两种方法对比
3. 下载后数据组织
4. torchtitan 0.2.2 配置与训练
   • 4.1 背景说明
   • 4.2 挑选部分分片（小规模训练）
   • 4.3 指定数据集路径
   • 4.4 预生成缓存（关键步骤）
   • 4.5 启动训练
5. 常见问题与排查
   • 5.1 启动后长时间无日志
   • 5.2 需要清理缓存重来
   • 5.3 磁盘空间管理
6. 数据量与训练消耗估算
7. 附录：完整命令速查

---

1. 前置准备

1.1 Atlas 800I A2 NPU 环境确认

本节针对昇腾硬件补充必要检查，确保后续训练可正确调用 NPU 资源。

• 驱动与固件：确认 npu-smi info 可正常输出，显示 Atlas 800I A2 芯片信息。
• CANN 工具包：已安装与驱动匹配的 CANN 版本（如 8.0.RC1），并确保 source /usr/local/Ascend/ascend-toolkit/set_env.sh 已生效。
• PyTorch 与 torch_npu：已安装适配昇腾的 PyTorch 和 torch_npu（例如 torch==2.1.0 + torch_npu==2.1.0.post6），可通过以下命令验证：

import torch, torch_npu
print(torch.__version__, torch_npu.__version__)
print(torch.npu.is_available())   # 应返回 True

• 分布式通信：昇腾使用 HCCL 作为集合通信后端，需确保 hccl 库可用，且各卡之间网络连通。

1.2 设置镜像端点

export HF_ENDPOINT=https://hf-mirror.com

建议写入 ~/.bashrc 持久化：

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc

1.3 验证镜像连通性

curl -I https://hf-mirror.com

返回 HTTP/2 200 即表示镜像可用。

1.4 数据集基本信息

项目	说明
Hugging Face 仓库	allenai/c4
英文训练集	1024 个分片，文件名 en/c4-train.00000-of-01024.json.gz 至 en/c4-train.01023-of-01024.json.gz
英文验证集	8 个分片，文件名 en/c4-validation.00000-of-00008.json.gz 至 en/c4-validation.00007-of-00008.json.gz
单个训练分片大小	约 300 MB（压缩后）
全量训练集大小	约 310 GB（压缩后）

---

2. C4 数据集下载

2.1 方法一：hf 命令行工具

安装工具

pip install -U huggingface_hub

下载英文训练集到指定路径

export HF_ENDPOINT=https://hf-mirror.com

hf download allenai/c4 \
  --repo-type dataset \
  --include "en/*" \
  --local-dir /data/c4

参数说明：

参数	作用
--repo-type dataset	指定仓库类型为数据集
--include "en/*"	只下载 en 子目录（英文子集）
--local-dir /data/c4	指定下载保存路径（按需修改）

只下载部分分片（测试用）

hf download allenai/c4 \
  --repo-type dataset \
  --include "en/c4-train.00000-of-01024.json.gz" \
  --local-dir /data/c4

断点续传

中断后直接重新执行同一命令即可自动续传。

注意：新版 huggingface_hub 已废弃 huggingface-cli 和 HF_HUB_ENABLE_HF_TRANSFER，请直接使用 hf 命令。不建议开启 HF_XET_HIGH_PERFORMANCE，Xet 加速通道不经由镜像站代理，可能导致连接失败。

---

2.2 方法二：wget 直接下载（推荐）

C4 分片文件名有固定规律，可绕过文件列表接口，直接拼接 URL 逐个下载，兼容性最好。

单文件测试

mkdir -p /data/c4/en

wget -c "https://hf-mirror.com/datasets/allenai/c4/resolve/main/en/c4-train.00000-of-01024.json.gz" -P /data/c4/en

确认速度正常后再批量下载。

批量下载训练集（1024 个分片）

cd /data/c4/en

for i in $(seq -f "%05.0f" 0 1023); do
  wget -c --no-check-certificate "https://hf-mirror.com/datasets/allenai/c4/resolve/main/en/c4-train.$i-of-01024.json.gz"
done

批量下载验证集（8 个分片）

cd /data/c4/en

for i in $(seq -f "%05.0f" 0 7); do
  wget -c "https://hf-mirror.com/datasets/allenai/c4/resolve/main/en/c4-validation.$i-of-00008.json.gz"
done

只下载部分分片

按需修改循环范围即可，例如只下载前 100 个训练分片（约 30 GB）：

for i in $(seq -f "%05.0f" 0 99); do
  wget -c "https://hf-mirror.com/datasets/allenai/c4/resolve/main/en/c4-train.$i-of-01024.json.gz" -P /data/c4/en
done

并行加速下载（可选）

使用 xargs 开启 4 路并发：

seq -f "%05.0f" 0 1023 | xargs -P 4 -I {} \
  wget -c "https://hf-mirror.com/datasets/allenai/c4/resolve/main/en/c4-train.{}-of-01024.json.gz" -P /data/c4/en

镜像站不建议开过多并发，4 路左右比较稳妥。

断点续传

wget -c 参数支持断点续传：已下载完成的文件会自动跳过，未完成的文件继续下载。中断后直接重跑同一命令即可。

---

2.3 两种方法对比

对比项	hf 命令行	wget
安装依赖	需要 huggingface_hub	系统自带
文件列表	走 API 接口自动列出	按文件名规律拼接，无需列表
大仓库兼容性	分页机制可能受镜像限制	无此问题，兼容性最好
断点续传	支持	支持（-c 参数）
适用场景	通用下载、小仓库	C4 这类分片命名规律的大数据集

---

3. 下载后数据组织

下载完成后，数据目录结构如下：

/data/c4/
└── en/
    ├── c4-train.00000-of-01024.json.gz
    ├── c4-train.00001-of-01024.json.gz
    ├── ...
    ├── c4-train.01023-of-01024.json.gz
    ├── c4-validation.00000-of-00008.json.gz
    ├── ...
    └── c4-validation.00007-of-00008.json.gz

如需将缓存放到大容量盘，设置环境变量：

export HF_DATASETS_CACHE=/data/hf_cache

---

4. torchtitan 0.2.2 配置与训练

4.1 背景说明

torchtitan 0.2.2 中 [training] 配置有两个相关字段：

字段	作用
dataset	指定数据加载器（c4_test 对应 C4 的加载逻辑，调用 load_dataset(path, split="train")）
dataset_path	指定数据路径（默认 None，即 HF 仓库名 allenai/c4）

注意 dataset_path 传的是 load_dataset 的第一个参数：

• 传 HF 仓库名（或仓库目录）会走 builder 路径，需要 config（en），torchtitan 未传 config，会报 ValueError: Config name is missing；
• 传一个直接包含数据文件（json.gz / parquet）的本地目录，HF datasets 会自动推断格式并归入 train split，无需 config。这是本文方案的基础。

---

4.2 挑选部分分片（小规模训练）

全量 1024 个分片约 3.6 亿条样本，小规模训练（如 steps = 1000）完全用不上。按需复制一部分即可，例如前 50 个分片（约 1800 万条）：

mkdir -p /data/c4_small/en
cp /data/c4/en/c4-train.000{00..49}-of-01024.json.gz /data/c4_small/en/

后缀以实际文件为准（ls /data/c4/en/ | head 确认，json.gz / json / parquet 均可被自动识别）。

---

4.3 指定数据集路径

方式一：命令行（推荐，不改配置）

--training.dataset_path /data/c4_small/en

方式二：TOML 配置

[training]
dataset = "c4_test"
dataset_path = "/data/c4_small/en"

命令行参数优先级高于 TOML，两者二选一。

---

4.4 预生成缓存（关键步骤）

8 卡同时启动时，所有 rank 会竞争同一份 HF datasets 缓存的文件锁：一个 rank 转换，其余静默等待，容易卡死或长时间无日志。先用单进程预生成：

python -c "
from datasets import load_dataset
ds = load_dataset('/data/c4_small/en', split='train')
print('rows:', len(ds))
"

• 终端可看到实时进度条，50 个分片约 20–40 分钟；
• 打印 rows: ... 即成功，缓存默认在 ~/.cache/huggingface/datasets/；
• 如需放到大盘：export HF_DATASETS_CACHE=/data/hf_cache（训练启动时必须设置同一个值）。

昇腾环境下，此步骤在 CPU 上运行即可，不占用 NPU，但请确保 Python 环境已安装 datasets 等依赖。

---

4.5 启动训练

NCCL_DETERMINISTIC=true \
NGPU=8 MODULE=qwen3 CONFIG=qwen3_14b ./run_train.sh \
  --debug.deterministic \
  --debug.seed 42 \
  --training.dataset_path /data/c4_small/en

缓存已存在时，所有 rank 直接读取，数据集准备阶段秒过。

昇腾补充说明：

• 若 run_train.sh 未自动识别 NPU，需在命令中显式指定设备类型，例如添加 --training.device npu（具体参数名以 torchtitan 0.2.2 实际配置为准）。
• 分布式训练默认使用 HCCL 后端，建议保持默认环境变量，无需额外设置 NCCL_*。
• 可通过 npu-smi info 实时监控 NPU 利用率，确认训练正常运行。

---

5. 常见问题与排查

5.1 启动后长时间无日志（疑似卡住）

通常不是卡死，原因是：

• run_train.sh 中 torchrun 带了 --local-ranks-filter 0，只有 rank 0 的输出可见；
• 缓存转换由抢到文件锁的 rank 执行，若该 rank 不是 rank 0，其进度条被过滤，rank 0 等锁期间无任何输出。

验证方法（另开终端）：

top -b -n 1 | head -15                        # 有 python 进程 CPU 拉满 = 正在转换
du -sh ~/.cache/huggingface/datasets/         # 缓存持续增长 = 正常

根治方法：按 4.4 预生成缓存 单进程预生成缓存。

---

5.2 需要清理缓存重来

pkill -f torchtitan.train
rm -rf ~/.cache/huggingface/datasets/c4_test
find ~/.cache/huggingface -name "*.lock" -delete
find ~/.cache/huggingface -name "*.incomplete" -exec rm -rf {} +

然后重新执行 4.4 预生成缓存 和 4.5 启动训练。

---

5.3 磁盘空间管理

• json.gz 转换为 Arrow 缓存后体积相当甚至更大，注意 ~/.cache 所在盘的剩余空间（df -h）；
• 空间紧张时用 HF_DATASETS_CACHE 指到大容量盘。

---

5.4 昇腾环境特定问题（补充）

• HCCL 相关报错的常见排查：检查 hccl_tools 生成的 rank_table 文件是否正确，或使用 npu-smi info 确认所有 NPU 状态正常。
• 训练速度慢或 NPU 利用率偏低的排查：确认数据加载不是瓶颈（可增加 num_workers），并检查 torch_npu 版本与 CANN 匹配。
• 如何确认训练运行在 NPU 上：执行 npu-smi info，观察 aicore 利用率；或在训练脚本中打印 torch.npu.get_device_name(0) 应输出 Atlas 800I A2 对应的 NPU 设备名。

---

6. 数据量与训练消耗估算

分片数量与样本数

分片数	样本数（约）	原始压缩大小（约）	缓存转换时间（约）
10	360 万	3 GB	5 分钟
50	1800 万	15 GB	20–40 分钟
100	3600 万	30 GB	1–1.5 小时
1024（全量）	3.6 亿	310 GB	数小时

训练 token 消耗估算

total_tokens = steps × local_batch_size × NGPU × seq_len

例如：1000 步 × 2 × 8 × 4096 ≈ 6500 万 token

50 个分片（每条平均数百 token）足够覆盖小规模训练。

---

---

总结

本文面向在 Atlas 800I A2 NPU 上使用 torchtitan 0.2.2 进行 C4 数据集训练的场景，给出了从数据集下载、数据组织到训练启动的完整流程：推荐使用 wget 按分片规律批量下载并配合断点续传，训练前先单进程预生成 HF datasets 缓存以规避多卡文件锁竞争，小规模训练时按需挑选部分分片以节省磁盘与转换时间。按上述步骤操作，即可快速复现 C4 预训练数据的本地化部署与训练启动，后续可在此基础上扩展至更大规模数据集与更长训练周期。

7. 附录：完整命令速查

环境设置

export HF_ENDPOINT=https://hf-mirror.com
export HF_DATASETS_CACHE=/data/hf_cache
# 昇腾环境（如未自动加载）
source /usr/local/Ascend/ascend-toolkit/set_env.sh

下载 C4（wget，前 50 个分片）

mkdir -p /data/c4/en
for i in $(seq -f "%05.0f" 0 49); do
  wget -c "https://hf-mirror.com/datasets/allenai/c4/resolve/main/en/c4-train.$i-of-01024.json.gz" -P /data/c4/en
done

复制部分分片到训练目录

mkdir -p /data/c4_small/en
cp /data/c4/en/c4-train.000{00..49}-of-01024.json.gz /data/c4_small/en/

预生成缓存

python -c "
from datasets import load_dataset
ds = load_dataset('/data/c4_small/en', split='train')
print('rows:', len(ds))
"

启动训练（昇腾 NPU）

NCCL_DETERMINISTIC=true \
NGPU=8 MODULE=qwen3 CONFIG=qwen3_14b ./run_train.sh \
  --debug.deterministic \
  --debug.seed 42 \
  --training.dataset_path /data/c4_small/en
# 若需显式指定设备类型，添加：--training.device npu

清理缓存

rm -rf ~/.cache/huggingface/datasets/c4_test
find ~/.cache/huggingface -name "*.lock" -delete
find ~/.cache/huggingface -name "*.incomplete" -exec rm -rf {} +

Python 加载本地数据（独立使用）

from datasets import load_dataset

ds = load_dataset(
    "json",
    data_files="/data/c4/en/c4-train.*.json.gz",
    split="train",
)