从入门到分布式 · 一文读懂 PyTorch 官方 Examples
学深度学习框架，最好的教材是官方示例，文档反而排在后面。PyTorch 的 examples 目录就是一部活的教程库，60 行代码就能跑通的回归入门，和支撑 ImageNet 训练的工业级分布式脚本，全塞在里面。
我按学习路径把仓库里 20 多个示例串了一遍，分成几大块逐个讲。每个示例在解决什么问题、思路是什么、该在哪个阶段入手，下面都会说清楚。说实话这些代码我没有逐行啃完，但每个示例的定位，从 README 和目录结构里看得很明白。
一、入门 · 自动求导到图像分类
regression，60 行读懂 autograd
整个示例集里最精简的就是它，用单个 nn.Linear 拟合一个随机的四次多项式。
它的妙处在手动执行梯度下降，不套任何现成优化器，直接对参数跑 param.data.add_(-0.1 * param.grad)。前向传播、损失计算、反向传播、参数更新，这四步你能一行行看清楚。loss 掉到 1e-3 以下就自动停，再把学出来的多项式系数和真实系数摆在一起对比。
适合刚接触 PyTorch、想弄懂 autograd 机制的开发者。
mnist 系列，一个任务的四种写法
MNIST 手写数字识别是深度学习的 Hello World，官方仓库给它准备了 4 个变体，正好对应四种训练方式。
| 目录 | 技术点 | 并行方式 |
|---|---|---|
mnist |
标准 CNN + 反向传播 | 单进程 |
mnist_forward_forward |
逐层局部学习，无反向传播 | 单进程 |
mnist_hogwild |
多进程共享内存异步 SGD | 多进程无锁更新 |
mnist_rnn |
LSTM 序列建模图像 | 单进程 |
- mnist 是两层卷积加两层全连接的经典 CNN，配 Adadelta 优化器和 StepLR 学习率衰减，后面很多示例都是照着它的骨架改的。
- mnist_forward_forward 复现 Hinton 2022 年的 Forward-Forward 算法。最大亮点是没有反向传播，每层各配一个 Adam 优化器，靠比较正样本（真实标签叠在图片上）和负样本（错误标签叠上去）的激活 goodness 逐层局部训练。想找反向传播的替代方案，这是最直观的一份实现。
- mnist_hogwild 演示 Hogwild! 异步 SGD。用
model.share_memory()把模型塞进共享内存，再起多个进程对同一个模型无锁并发更新，算是多进程并行训练最原始的形态。 - mnist_rnn 把 28×28 图像当成长度 28 的序列，每一行像素算一个时间步，用 LSTM 建模。训练流程和 CNN 版一模一样，方便你直接对比两种架构的差距。
siamese_network，度量学习入门
孪生网络用两个共享权重的 ResNet-18 分别提取两张图的特征，拼起来过全连接层加 Sigmoid 输出相似度，用 BCELoss 训练。数据集构造有个巧思，按奇偶索引交替生成正样本对（同类不同图）和负样本对（不同类），绕开了"两张完全一样的图"这种没意思的样本。想搞人脸识别、图像检索，从这里入手挺顺。
二、生成模型 · 让网络学会创造
vae，变分自编码器
MLP 版的 VAE，结构极简但概念是完整的。编码器输出均值 μ 和对数方差 log σ²，靠重参数化技巧（z = μ + ε·σ，ε ~ N(0,1)）做出可导的随机采样，解码器再重建图像。损失就是重建误差（BCE）加 KL 散度。每个 epoch 会把重建图和随机采样图存进 results/ 目录，训成什么样，翻翻这个目录就知道。
dcgan，生成对抗网络
DCGAN 把生成器和判别器的完整对抗训练循环写全了，数据源支持 CIFAR-10、LSUN、MNIST、ImageNet，也能喂自定义文件夹，还能从 checkpoint 续训，用 --dry-run 快速验证。训练时每个 epoch 都存一张生成样本的网格图，生成质量怎么一点点变好，看得见。
fast_neural_style，实时风格迁移
基于 Johnson 那篇《Perceptual Losses for Real-Time Style Transfer》和 Instance Normalization 实现。两种玩法。第一种，用 COCO 数据集加一张风格图，训练自己的风格迁移模型。第二种，直接拿官方给的预训练模型（mosaic、candy 这些风格）给任意照片上色，笔记本 CPU 就能流畅跑。
三、图神经网络 · 处理非欧几里得数据
gcn 和 gat 是一对姊妹示例，都在 Cora 引文数据集上做半监督节点分类，这个数据集有 2708 个论文节点、7 类主题。
- gcn 实现 Kipf & Welling 的图卷积层
H' = f(D^(-1/2)AD^(-1/2)HW)，重点看度矩阵归一化这个技巧和稀疏矩阵乘法torch.spmm。 - gat 实现图注意力机制，给每条边算注意力系数 α_ij（LeakyReLU 加掩码 softmax），支持多头注意力，最后把各头的输出取平均或者拼起来。
两个对着读，就能分清"固定权重聚合邻居"和"注意力加权聚合邻居"到底差在哪。
四、自然语言处理
word_language_model，词级语言模型
基于 Penn Treebank 数据集的 RNN/LSTM/GRU 语言模型。有几个亮点。一个 RNNModel 容器类统一支持 4 种循环网络。支持权重绑定，让 embedding 和输出层共享权重，这是《Using the Output Embedding to Improve Language Models》里的经典技巧。generate.py 能用训好的模型从任意起始词逐词生成文本。
language_translation，Transformer 机器翻译
基于《Attention is All You Need》的翻译示例，默认德译英，靠 spacy 分词器能切到任意语言对，比如 --src en --tgt fr 就是英译法。训完还给一个交互式推理界面，随便输入一句就能拿到翻译。想学 Transformer 的编码器-解码器结构和贪心解码，这份材料很实用。
五、强化学习 · reinforcement_learning
在经典的 CartPole-v1 环境上实现了两种策略梯度算法。
- reinforce.py 是 REINFORCE（蒙特卡洛策略梯度），等一个完整回合结束后按折扣回报更新策略网络，保存动作 log-prob 的那个列表机制值得细读。
- actor_critic.py 是单模型双头的 Actor-Critic，一个网络同时输出动作概率（actor 头）和状态价值（critic 头），用优势函数 A = R - V 压低梯度方差。
两个脚本加起来不到 200 行，是策略梯度算法最小可行的实现。
六、序列建模与视觉前沿
time_sequence_prediction，手写循环的 LSTM
mnist_rnn 用的是现成的 nn.LSTM，这个示例反过来，用两个 LSTMCell 手写时间步循环，LSTM 内部 hidden state 怎么一层层传，一眼看穿。另一个特色是用 LBFGS 优化器（因为能全量数据训练），还支持对正弦波做 1000 步外推，把预测曲线画出来。
super_resolution，超分辨率
实现 ESPCN 模型，4 层卷积后面接 nn.PixelShuffle 做亚像素级上采样，把低分辨率图放大。代码拆得很干净，model.py 管网络定义，data.py/dataset.py 管数据处理，main.py 管训练，super_resolve.py 管推理，是工程组织的规范样本。
vision_transformer，手写 ViT
不引第三方库，从零实现 Vision Transformer。用 Tensor.unfold 做 Patch 切分，线性投影加 class token 加位置编码，再手写多头自注意力的 Encoder Block（LayerNorm → MultiheadAttention → MLP，带两处残差连接）。仓库还附了训练好的 best-weights.pt，能直接加载验证。
七、进阶 · 工业级训练与分布式
imagenet，真实世界的训练脚本
整个示例集里工程价值最高的单文件脚本就是它。torchvision 的全部图像模型架构，一行 -a 参数就能切。DDP 分布式训练（--multiprocessing-distributed）和混合精度 AMP 都配好了，checkpoint 保存、断点恢复、--evaluate 评估模式一个不少，还有 --dummy 假数据能快速测速。想做大规模训练，先把这个脚本读透。
distributed，分布式训练全家桶
下面这些子目录，基本把 PyTorch 分布式的所有形态都盖到了。
| 子目录 | 内容 |
|---|---|
ddp/ |
DistributedDataParallel 基础（MNIST 多进程训练） |
ddp-tutorial-series/ |
DDP 进阶教程，含单机与多节点（multi_node）版本 |
FSDP/ |
全分片数据并行（Fully Sharded Data Parallel），含微调与绘图工具 |
FSDP2/ |
新一代 per-parameter DTensor FSDP API 示例 |
rpc/ |
RPC 框架系列，含参数服务器、RPC+DDP 组合、模型流水线、批量推理、分布式 RL、分布式 RNN |
tensor_parallelism/ |
张量并行 |
minGPT-ddp/ |
基于 minGPT 的大语言模型 DDP 训练（含 YAML 配置） |
fx，模型变换的瑞士军刀
torch.fx 示例集有 11 个独立脚本，演示符号追踪、自定义 Tracer、子图替换（subgraph rewriter）、算子替换、动态输出包装、性能分析这些。做模型量化、算子融合、编译优化之前，建议先在这里把 FX 的编程模型摸一遍。
八、其他与遗留
legacy/snli 是基于 SNLI 数据集的文本蕴含分类，用 LSTM 编码前提和假设两句话，已经归档不再维护，当参考看就行。
总结 · 推荐学习路径
把这些示例串起来，能理出这么一条学习路径。
regression（自动求导）
→ mnist 四部曲（分类/优化器/并行初探）
→ vae / dcgan（生成模型）
→ gcn / gat（图学习）
→ word_language_model / language_translation（NLP）
→ reinforcement_learning（RL）
→ imagenet / distributed（工业级训练）
最后几条建议，都挺实在。
第一，多用 --dry-run。绝大多数示例都支持这个参数，跑通一个 batch 就退出，适合快速验证环境。
第二，用一键脚本。仓库顶层的 run_python_examples.sh 能批量把全部 Python 示例跑一遍。
第三，对比着读。mnist 对 mnist_rnn 是架构对比，gcn 对 gat 是聚合方式对比，mnist 对 mnist_hogwild 是并行对比，成对读收获翻倍。
第四，别忘了 C++ 版。cpp/mnist 是 CNN 示例的 libtorch 移植，想了解 PyTorch C++ 前端就从它看。