Programmer.ie 图书 Published

PyTorch From First Principles

从第一性原理理解 PyTorch——从张量几何与 autograd,到模型结构、变换、注意力、调试、性能、编译、可复现性,以及从零构建的 GPT 风格模型。

PyTorch 上手很容易,理解却没那么容易。

你可以创建一个张量,复制一段模型结构,调用 loss.backward(),构造一个优化器,几分钟内就能让训练循环跑起来。

这正是 PyTorch 的优点之一。

麻烦也从这里开始。

一段程序可以在广播(broadcasting)了错误的维度的情况下依然运行。一个参数可以有梯度,却永远得不到更新。一个模型可以在吃着数值含义完全错误的输入的情况下“训练成功”。GPU 看似利用率很低,但增加 worker 反而让程序更慢。检查点(checkpoint)可以毫无报错地加载,而模型行为却变了,只因为预处理变了。torch.compile 看似生效了,却悄悄产生了比预期多得多的图(graph)。

这些问题都不是靠“再多知道一个 API”能解决的。

解决它们需要知道 PyTorch 实际在执行什么计算。

这本书讲的就是这件事。

在猜测之前,先让隐藏的结构可见。

我们将从 PyTorch 最小的机制自底向上构建,并反复追问同一类问题:

PyTorch 以为这里发生了什么?实际发生了什么?什么样的证据能区分这两者?

目标不是背下 PyTorch。

目标是让没见过的 PyTorch 代码变得可检查。


我们要构建的系统

本书从几乎一无所有开始:

一个值
    ↓
一个参数
    ↓
一次预测
    ↓
一个损失
    ↓
一个梯度
    ↓
一次更新

到最后,同样的机制会扩展成一个小型的 GPT 风格语言模型:

原始数据
    ↓
Dataset / transforms / DataLoader
    ↓
词元张量
    ↓
嵌入(embeddings)
    ↓
注意力(attention)
    ↓
残差块(residual blocks)
    ↓
logits
    ↓
交叉熵(cross entropy)
    ↓
autograd
    ↓
优化器(optimizer)
    ↓
更新后的参数
    ↓
检查点 / 生成 / 评估

而围绕这个模型,还有另一套系统:

CPU 工作
GPU 工作
内存
性能分析(profiling)
编译(compilation)
可复现性
测量
回归测试

这些不是彼此独立的主题。

它们是同一个运行中程序的不同视图。

本书会把这个程序从第一性原理构建到足够完整的程度,让你在出问题时,能判断该去盘问系统的哪一部分。


反复出现的调试动作

很多 PyTorch 调试开始得太晚。

某个张量以错误的形状到达某个算子,于是我们不断 reshape,直到异常消失。

某个参数的 grad=None,于是我们加上 requires_grad=True。

GPU 利用率低,于是我们增大 num_workers。

训练不稳定,于是我们调小学习率。

编译很慢,于是我们关掉 torch.compile。

这些改动有时确实“管用”。

但一个管用的改动不自动等于一次诊断。

本书使用另一种模式:

预测
    ↓
观察
    ↓
找到第一个分歧点
    ↓
确认背后的机制
    ↓
只改一处
    ↓
验证修复

各章会把这个模式逐渐变成一套具体的诊断技术。

对于张量:

找到张量第一次变错的位置,而不只是它最终变得不合法的位置。

对于 autograd:

找到梯度通路第一次不再存在的位置。

对于模块和参数:

检查 PyTorch 所看到的结构,而不是从源代码去推测。

对于输入流水线:

找到生产者与消费者之间有用功停止流动的位置。

对于变换(transforms):

找到样本第一次不再满足模型所期望表示的边界。

具体的机制一直在变。

调查问题的方式不变。


PyTorch 里叠着好几套结构

PyTorch 容易让人困惑的原因之一,是同一个 Python 程序里住着好几套不同的系统。

考虑一个带有几个张量和子模块的模型。

这里有普通的 Python 对象结构:

model
  ├── encoder
  ├── blocks
  └── head

这里有 PyTorch 已经注册(registered)的结构:

_modules
_parameters
_buffers

这里有当前前向传播中执行过的算子所创建的计算图(computation graph):

parameter
    ↓
operation
    ↓
intermediate
    ↓
loss

这里有优化器参数组:

optimizer
    ↓
具体的参数对象

这里有输入流水线:

source
  ↓
Dataset
  ↓
transforms
  ↓
collation
  ↓
DataLoader workers
  ↓
batch

而在所有这些之下,还有执行系统:

Python
CPU threads
worker processes
host memory
CUDA
GPU memory
compiled graphs

一个张量可以属于其中一套系统,而不属于另一套。

一个参数可以参与 autograd,却没有注册进模型。

一个已注册的参数可以存在,却不属于你早先创建的那个优化器。

一个变换可以返回形状和 dtype 都正确的张量,同时改变其数值的含义。

一个批次可以到达得很快,但仍然是错的。

GPU 可以很忙,而整个程序几乎没有实质进展。

一旦不再把这些结构当成同一个东西,很多 PyTorch 调试会变容易。


本书要教什么

本书从小机制走向完整系统。

你将学会推理:

  • 张量几何——形状、dtype、设备(device)、步长(stride)、广播、连续性(contiguity)、布局,以及每个轴所承载的含义;
  • autograd——PyTorch 记录了什么,叶张量与中间张量,grad_fn,梯度累积,断裂的通路,被保留的梯度,以及图的生命周期;
  • 从原始张量出发的神经网络——在 nn.Module 把记账工作藏起来之前,先讲参数、矩阵乘法、非线性、logits、损失、梯度与手工更新;
  • 已注册的模型结构——模块、参数、缓冲(buffers)、递归组合、state_dict()、设备移动、train/eval 行为、优化器成员关系,以及这些结构可能互相不一致的位置;
  • 输入供给——数据集、批整理(collation)、多进程、worker、预取、持久状态、主机到设备的传输,以及“流水线在等待”与“只是把瓶颈挪了个地方”的区别;
  • 输入表示——变换、缩放、归一化、增强、目标语义、预训练的预处理契约,以及合法张量与有意义张量的区别;
  • 空间模型——通道、高、宽、卷积、感受野几何,以及推导 CNN 形状而不是猜形状;
  • 更高维的表示——特征、嵌入、注意力、注意力头、掩码、logits,以及 Transformer 风格的张量几何;
  • 训练失败——数据、目标、损失、梯度、优化器、参数移动、数值不稳定,以及能跑却拒绝学习的模型;
  • 执行与性能——CUDA 计时、内存、性能分析、瓶颈、编译、图断裂(graph breaks)、守卫(guards)、重编译与动态行为;
  • 实验——基线、可复现性、可比的运行、回归、基准有效性,以及把发现的失败变成测试;以及
  • 集成——把这些机制组装成一个小型的 GPT 风格语言模型,其行为可以从输入一路检查到生成。

重要的不是这张表有多长。

重要的是这些主题是累积的。

后面的章节应该是你已经理解的结构在更大系统上的应用。


一个逐步构建的系统

这个顺序是刻意的。

我们从训练循环开始,因为 PyTorch 里几乎一切最终都要挂到它上面。

然后揭开流经这个循环的张量。

然后揭开连接这些张量算子的图。

然后在没有常用组织机制的情况下构建一个神经网络。

只有当这些部分都可见之后,我们才引入 nn.Module,追问 PyTorch 认为哪些状态属于模型。

然后走出模型。

追问下一个批次是怎么到达的。

再追问这个批次实际意味着什么。

只有当输入契约可信之后,我们才开始用卷积利用空间结构,并使用越来越复杂的模型结构。

再往后,当所有部件都齐了,本书会变得更像法医工作。

我们会问这样的问题:

为什么这个模型能跑却学不会?

GPU 内存到底去哪了?

为什么 GPU 在等?

这个算子的哪一部分是异步的?

为什么这个编译过的函数又产生了一个图?

是输入的哪个性质产生了那个守卫(guard)?

这次优化真的提高了吞吐量,
还是测量位置变了而已?

这个新结果真的更差,
还是两次实验根本不可比?

最后我们把部件组装起来。

到那时,收尾的模型不应该像二十个互不相干的 PyTorch 技巧拼成的 Transformer。

每个机制都应该已经有地方可以挂靠。


合法不等于正确

这个区分会贯穿全书反复出现。

PyTorch 很擅长拒绝不可能的计算。

它拒绝不了每一个无意义的计算。

一次广播可能是合法的,却配错了轴。

一张浮点图像可以完全合法,却在模型期望 0..1 时表示着 0..255 的数值。

一次水平翻转可以完美执行,却改变了标签的真假。

一个参数可以收到梯度,却一直在优化器之外。

一个检查点可以在每个键都匹配的情况下加载成功,而推理预处理早已与训练不一致。

一次基准测试可以在比较着两个不同工作负载的情况下正确运行。

所以我们会反复区分:

PYTORCH 能执行它吗?

与

这是否是我们想要的计算?

报错信息能回答第一个问题。

本书主要是学会回答第二个问题。


先观察,再解释

另一条规则自然跟上:

先检查发生了什么,再解释为什么发生。

诊断张量问题之前,先打印张量。

诊断梯度问题之前,先检查图和梯度。

诊断优化器问题之前,先确认参数对象是否真的在优化器里,以及它是否移动了。

诊断输入问题之前,先跟踪一个已知样本穿过变换的全过程。

诊断 DataLoader 性能之前,先分别测量批次等待与消费者工作。

诊断 CUDA 性能之前,先区分主机时间与设备时间。

诊断编译问题之前,先检查真实的图断裂和重编译原因。

诊断回归问题之前,先确认两次运行是可比的。

先于证据到达的解释,只是假设。

把它当假设对待。


使用 AI,但不把理解外包出去

现代 PyTorch 开发越来越多涉及 AI 生成的代码。

这不是本书要回避的问题。

这正是本书重要的原因之一。

助手常常能比你手写更快地给出可用的训练循环、自定义数据集、注意力块、性能分析脚本或 torch.compile 配置。

问题是当生成的程序行为怪异时,会发生什么。

如果你唯一会做的事是再要一份实现,那么每次失败都会变成另一个生成问题。

如果你理解底层机制,你能问出好得多的问题:

给我看每个算子之后的张量形状。

是哪条边把这个参数与损失断开了?

哪些已注册的参数不在优化器里?

这个变换假定输入范围是什么?

DataLoader 消费者到底在哪里等待?

是哪个图断裂导致这个函数重编译了?

什么样的观察能区分这两种解释?

AI 可以生成实现。

当实现不再合理时,你仍然需要足够的理解,知道该索取什么证据。

这就是本书假定的与 AI 的关系。


读完之后你应该能做什么

目标不是记住各章用过的每个 PyTorch API。

目标是让没见过的 PyTorch 程序变得可读。

你应该能打开一段程序并问出:

这个张量表示什么?

它的形状应该是什么?

每个维度是什么意思?

这个张量在哪里创建的?

哪些算子产生了这个值?

损失是否依赖这个参数?

依赖第一次消失在哪里?

PyTorch 把哪些张量看作参数?

哪些状态被注册了?

优化器到底拥有哪几个参数对象?

step 之后那些对象移动了吗?

这个样本在到达模型之前经历了什么?

变换后的样本是否还符合其目标所说的含义?

下一个批次把时间花在哪里了?

CPU 是在等待、计算,还是在争用?

这次 CUDA 计时测的是提交还是已完成的工作?

内存分配在哪里?

为什么编译又产生了一个图?

是哪个假设产生了那个守卫?

这次干预真的提高了吞吐量或精度吗?

这两次实验可比吗?

这些问题比知道某个方法在文档的哪一页有用得多。

它们告诉你如何调查。


你也会学到何时不该用更多 PyTorch

不是每个问题都需要另一个抽象。

你并不总是需要:

  • 更复杂的模型;
  • 另一层;
  • 混合精度;
  • 更多的 worker;
  • 锁页内存(pinned memory);
  • 编译;
  • 自定义 CUDA 核函数;
  • 更精巧的优化器;
  • 另一种增强;
  • 另一个包在 PyTorch 外面的框架。

有时张量就是错的。

有时参数就是不在优化器里。

有时数据集就是重复了。

有时验证流水线就是与训练契约不一致。

有时 GPU 根本不是瓶颈。

有时朴素的 eager 实现已经够快。

所以本书会努力“挣得”复杂度。

只有当更简单的系统暴露出新机制确实能解决的局限时,我们才加入新机器。


本书面向谁

你应该熟悉基本的 Python:

变量
函数
循环
类
列表
字典
运行脚本

你不需要已有的 PyTorch 经验。

你不需要在开始之前懂 Transformer 内部结构。

你不需要带着一套完整的神经网络数学处理入场。

你需要愿意运行小实验。

很多章节会故意弄坏能跑的代码。

那不是对课程的打断。

那就是课程本身。

本书写给想拥有调查 PyTorch 能力的人,而不是只想在一切顺利时操作 PyTorch 的人。


本书不打算覆盖什么

这不是 PyTorch API 的百科全书。

它也不打算把每个专门方向都变成胜任力的前提。

比如这些主题:

  • 大规模分布式训练;
  • 多节点基础设施;
  • 自定义 CUDA 核函数;
  • 量化;
  • 生产 serving;
  • LoRA 等参数高效微调系统;
  • 混合专家架构;
  • 每一种现行 Transformer 变体;
  • 每一种视觉架构;
  • 每一种编译器后端;

都很重要。

但它们不是地基。

本书的目的是给这些主题一个可以挂靠的地方。

如果张量、计算图、已注册状态、输入契约、优化、执行、测量与调试都是清楚的,不熟悉的特性就不再是一条条孤立的咒语。

它们会变成你已理解系统上的扩展。


约定

读完 PyTorch From First Principles,当你遇到没见过的 PyTorch 代码,应该能弄清:

张量是什么意思,它们怎么产生的,PyTorch 记录了关于它们的什么,哪些状态属于模型,优化器实际能改什么,什么表示到达了模型,执行时间与内存去了哪里,以及什么样的证据能区分真正的修复与看似合理的改动。

更紧凑地说:

让隐藏的结构可见。找到第一个分歧点。修复造成它的机制。验证系统真的变好了。

这就是全书所围绕的标准。

最后的 GPT 风格模型很重要。

但它不是真正的终点。

真正的终点是:当模型做出你没预料到的事时,你知道如何查出原因。

目录

章节

01

我们到底在做什么?

从一个标量参数构建最小的 PyTorch 训练循环,手算梯度,区分前向、反向与更新,然后破坏梯度清零与参数同一性,学会从证据而不是损失曲线诊断训练。

02

张量:循环里真正流动的是什么?

让张量行为可检查:运行前先推导形状,说清每个轴的语义,跟踪广播、归约、重塑、步长、dtype 与设备,找到观测结构第一次偏离契约的张量。

04

网络:没有 nn.Module 时它是什么?

完全用张量构建双层神经网络——权重、非线性、logits、交叉熵、初始化、梯度与手工更新,再用六断言审计区分表示、计算、目标、微分、更新与评估失败。

05

nn.Module:PyTorch 认为哪些属于你的模型?

揭开 nn.Module 如何组织已注册参数、缓冲、子模块、state_dict()、设备移动与优化器成员,当模型状态悄悄分歧时,对齐 Python 对象图、已注册树、autograd 图与优化器组。

06

DataLoader:训练循环到底在等哪里?

把 DataLoader 建模成生产者-消费者系统,分别测量批次等待与训练工作,用受控的 worker、预取、持久化与争用实验找到真正限制输入吞吐的资源。

07

变换:模型实际看到的是什么?

跟踪一个已知样本穿过预处理,验证结构、数值解释、语义、关系与来源,在第一个坏掉的表示边界诊断合法但错误的变换、缩放、归一化、增强与目标对齐。

09

特征空间:线性模型实际看到了什么?

弄清特征空间里向量表示什么:分开张量秩与表示维度,推导点积、余弦相似度、距离与线性分数,测试不变性,用简单线性模型恢复埋下的可分方向。

10

注意力:哪个位置在和哪个位置比?

从张量几何构建多头注意力,说清每个 query、key、head、位置轴,验证掩码、softmax、缩放与头往返,用从形状到行为干预的四层证据定位第一次语义失败。

11

训练:学习链哪环断了?

诊断能跑但学不会的模型:沿 TASK → OBJECTIVE → DEPENDENCY → GRADIENT → OPTIMIZER OWNERSHIP → PARAMETER UPDATE → CAPABILITY 走,用固定 batch、精确参数同一性、受控 SGD、小 batch 过拟合找到学习第一个缺席的后果。

12

性能:机器在等什么?

把 PyTorch 性能变成可测的比较:定义 workload 与指标,纠正 CUDA 计时,分离训练阶段,跟踪已分配与保留内存,分析瓶颈,把 AMP、检查点、SDPA、torch.compile 当有证据的干预来测。

13

编译:哪个假设不再成立?

把 torch.compile 当运行时契约:区分正确与捕获、稳定、价值,检查图断裂、守卫、缓存变体、动态形状、重编译、冷热代价,找到编译器第一个不再成立的假设。

14

回归:模型变了,还是测量变了?

解释前先确立回归是否存在:测基线 variation,valid 时用配对比较,给评估路径 fingerprint,控随机与确定性,二分交互变化,记录 run,把模型变化与测量变化分开。

15

组装:可盘问的语言模型

组装小 GPT 风格语言模型,用全书诊断栈盘问它——分词器与目标契约、注意力干预、参数核算、学习性能台账、编译、生成、配对评估——让成品保持可检查而不是魔法。

16

附录 A:PyTorch 诊断野战指南

把真实 PyTorch 症状路由到能解决它的最小诊断仪器:野战表、证据包、事故工作单、AI prompt、升级规则,以及从张量跟踪到回归、编译执行的完整栈。