机器学习与深度学习 / 知识点
PyTorch API 函数速查
张量基础操作
torch.tensor(data, *, dtype=None, device=None, requires_grad=False, pin_memory=False)从 Python 数据或数组创建张量,可指定类型、设备和梯度属性;适合初始化输入数据、小规模参数和测试样例。
创建张量
查找 torch.tensor 时,用于确认如何把 Python 数据转换为 PyTorch 张量,并设置数据类型、设备和梯度跟踪属性。
签名
torch.tensor(data, *, dtype=None, device=None, requires_grad=False, pin_memory=False)参数
data:可转换为张量的数据,例如列表、元组或支持数组协议的对象。dtype:可选,指定张量元素类型,例如torch.float32或torch.int64。device:可选,指定存储设备,例如cpu或cuda。requires_grad:是否记录梯度计算,默认False。pin_memory:是否使用锁页内存,主要用于 CPU 张量向 CUDA 传输优化。
返回与边界
成功时返回新的 torch.Tensor。输入数据会被复制为新的张量存储,不会像 torch.as_tensor 一样优先共享已有内存。
完整示例
import torch
values = [1, 2, 3]
tensor = torch.tensor(values, dtype=torch.float32)
print(tensor)
print(tensor.dtype)预期输出
tensor([1., 2., 3.])
torch.float32常见误用
requires_grad=True 适合需要参与自动求导的张量;普通输入数据通常保持默认值,避免产生不必要的计算图开销。
不同 PyTorch 版本支持的输入类型可能存在差异,实际使用时应以当前版本文档为准。
torch.zeros(*size, *, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False)创建指定形状且元素全为零的张量;常用于初始化缓存、状态变量和模型输入占位数据。
生成零张量
查找 torch.zeros 时,用于快速创建指定形状的全零张量,并确认尺寸、类型和设备设置方式。
签名
torch.zeros(*size, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False)参数
size:必填,定义张量形状,可以使用多个整数参数,例如2, 3表示二维张量。out:可选,将结果写入已有张量。dtype:可选,指定元素数据类型。layout:可选,指定存储布局,默认使用稠密布局torch.strided。device:可选,指定张量所在设备。requires_grad:是否开启自动求导记录,默认False。
返回与边界
成功时返回指定形状且元素均为零的 torch.Tensor。形状参数必须为非负整数;需要 GPU 张量时应显式指定 device 或在创建后迁移。
完整示例
import torch
zeros = torch.zeros(2, 3, dtype=torch.float32)
print(zeros)
print(zeros.shape)预期输出
tensor([[0., 0., 0.],
[0., 0., 0.]])
torch.Size([2, 3])常见误用
torch.zeros 创建的是全新初始化张量。如果需要根据已有数据创建并保留数据内容,应使用其他张量构造 API,而不是零初始化函数。
torch.reshape(input, shape)返回具有新形状的张量视图或副本;适合调整批次、通道和序列维度,需保证元素数量一致。
改变张量形状
调用 torch.reshape 时,用于在不改变元素总数的前提下重新组织张量维度。查到该接口后可以快速完成批次、通道或序列长度调整。
签名
torch.reshape(input, shape)参数
input:torch.Tensor,需要调整形状的输入张量。shape:目标形状,可以是整数、整数元组或列表;新形状所有维度乘积必须等于输入元素数量。
返回与边界
返回具有目标形状的张量。如果底层存储连续且布局允许,PyTorch 会返回视图;否则可能创建数据副本。返回张量与输入共享数据时,修改其中一个可能影响另一个。
元素数量不一致时会报错,不能通过 reshape 增加或删除数据。
完整示例
import torch
x = torch.tensor([1, 2, 3, 4])
y = torch.reshape(x, (2, 2))
print(y)
print(y.shape)预期结果
tensor([[1, 2],
[3, 4]])
torch.Size([2, 2])边界与兼容性
需要强制复制数据时使用 clone();只需要改变维度排列时不要使用 reshape,应使用 permute。不同 PyTorch 版本均支持该基础张量操作,但具体返回是否共享存储取决于输入布局。
torch.permute(input, dims)重新排列张量维度顺序,不改变数据内容;常用于图像、序列模型中的维度格式转换。
调整维度顺序
调用 torch.permute 时,用于改变张量维度排列方式而不修改数据值。查到该接口后可以完成图像、序列和批处理数据格式转换。
签名
torch.permute(input, dims)参数
input:torch.Tensor,需要重新排列维度的输入张量。dims:整数元组,指定新的维度顺序。长度必须等于输入张量的维度数量,每个维度编号只能出现一次。
返回与边界
返回输入张量的视图,并根据新的维度顺序解释同一份数据存储。permute 不会复制数据,但返回张量通常可能变为非连续布局。
需要连续内存时,可在后续调用 contiguous() 创建连续副本。
完整示例
import torch
x = torch.randn(2, 3, 4)
y = torch.permute(x, (0, 2, 1))
print(x.shape)
print(y.shape)预期结果
torch.Size([2, 3, 4])
torch.Size([2, 4, 3])边界与兼容性
permute 只改变维度解释顺序,不改变元素排列内容。常见误用是把它当作数据复制或数值转换接口;需要交换两个维度时也可以考虑 transpose,但 transpose 主要用于两个维度交换场景。
torch.Tensor.to(device=None, dtype=None, non_blocking=False, copy=False, memory_format=torch.preserve_format)将张量移动到指定设备或转换类型;训练和推理阶段常用于 CPU 与 GPU 数据切换。
移动计算设备
需要在 CPU、GPU 或其他计算设备之间迁移张量,或同时转换张量类型时查阅 Tensor.to。调用成功后会返回目标设备上的张量,用于后续计算。
签名
torch.Tensor.to(device=None, dtype=None, non_blocking=False, copy=False, memory_format=torch.preserve_format)参数
device:目标设备,例如"cpu"、"cuda"或torch.device,默认为None。dtype:目标数据类型,例如torch.float32,默认为保持当前类型。non_blocking:是否尝试执行异步拷贝,默认为False,通常需要源数据位于固定内存时才有效。copy:是否强制创建副本,默认为False。memory_format:内存布局策略,默认为torch.preserve_format。
返回与错误
返回移动或转换后的张量。如果目标设备、数据类型或内存格式参数无效,会抛出参数相关异常。原张量不会因设备迁移而被原地修改。
完整示例
import torch
x = torch.tensor([1.0, 2.0])
# 将张量移动到可用设备
x_device = x.to(torch.device("cuda" if torch.cuda.is_available() else "cpu"))
print(x_device.device)预期结果
cpu如果运行环境检测到 CUDA 可用,输出设备会变为 cuda:0。
边界与兼容性
GPU 训练时通常需要同时移动模型和输入数据,否则会出现设备不一致错误。使用 non_blocking=True 前应确认数据加载和内存条件满足异步传输要求。
自动求导
torch.autograd.grad(outputs, inputs, grad_outputs=None, retain_graph=None, create_graph=False)计算输出相对于输入的梯度,支持自定义训练流程和高阶梯度计算;需确保张量参与计算图。
自动求导计算
需要手动获取某个输出相对于输入的梯度,而不是通过优化器更新参数时,查阅 torch.autograd.grad。它返回梯度结果,可用于自定义训练流程、梯度分析和高阶求导。
签名
torch.autograd.grad(outputs, inputs, grad_outputs=None, retain_graph=None, create_graph=False)参数
outputs:需要求导的输出张量或张量序列。inputs:需要计算梯度的输入张量或张量序列,必须参与计算图。grad_outputs:输出梯度权重,默认为None,适用于标量输出或自动推导场景。retain_graph:是否保留计算图,默认为根据求导过程决定;多次反向计算同一图时需要考虑设置。create_graph:是否创建用于高阶梯度计算的新计算图,默认为False。
返回与错误
成功时返回与 inputs 对应的梯度元组。输入没有梯度关系或未参与计算图时,可能抛出运行时错误;需要检查 requires_grad 和计算路径。
完整示例
import torch
x = torch.tensor(3.0, requires_grad=True)
y = x ** 2
grad = torch.autograd.grad(y, x)
print(grad[0])预期结果
tensor(6.)边界与兼容性
默认情况下,grad 不会像 backward() 一样把梯度累积到 .grad 属性,而是直接返回梯度值。需要二阶或更高阶梯度时,应设置 create_graph=True 并注意额外计算图带来的内存开销。
torch.Tensor.backward(gradient=None, retain_graph=None, create_graph=False, inputs=None)沿计算图执行反向传播并累积梯度;通常用于训练循环中更新模型参数前计算损失梯度。
反向传播
Tensor.backward() 用于从当前张量沿计算图反向计算梯度。训练模型时通常对损失张量调用它,让参数的 grad 字段获得梯度值,随后交给优化器更新参数。
签名
torch.Tensor.backward(gradient=None, retain_graph=None, create_graph=False, inputs=None)参数
gradient:可选,传入当前张量相对于目标输出的梯度。标量张量通常不需要传入。retain_graph:可选,是否保留计算图。默认根据create_graph决定,重复反向传播时需要显式设置。create_graph:布尔值,是否创建用于高阶梯度计算的新计算图,默认False。inputs:可选,限制需要计算梯度的叶子张量。
返回与异常
该方法不返回梯度值,而是将梯度累积到参与计算且需要梯度的张量 grad 属性中。若对不支持梯度计算的张量调用,会产生自动求导相关错误。
完整示例
import torch
x = torch.tensor(3.0, requires_grad=True)
y = x * x + 2 * x
# 对标量结果执行反向传播
# 梯度为 dy/dx = 2x + 2,在 x=3 时结果为 8
y.backward()
print(x.grad)预期输出
tensor(8.)边界
梯度默认会累积,而不是覆盖已有值。训练循环中通常需要在每次更新前调用 optimizer.zero_grad() 清空旧梯度。需要多次调用 backward() 时,应确认计算图是否需要保留。
模型构建
torch.nn.Module()所有神经网络组件的基础类;用于封装参数、子模块和前向计算逻辑,是构建模型的核心入口。
定义神经网络模块
torch.nn.Module 是创建 PyTorch 模型组件时继承的基础类。使用它可以自动管理参数、注册子模块,并通过 forward() 描述前向计算逻辑。
签名
class torch.nn.Module(*args, **kwargs)参数
Module 构造函数通常不需要业务参数。模型自定义参数应在子类的 __init__() 中定义,并通过父类初始化完成模块注册。
*args:父类初始化参数,通常保持默认。**kwargs:父类初始化关键字参数,通常保持默认。
返回与行为
实例化后返回一个神经网络模块对象。对象中的 nn.Parameter 会自动加入参数列表,可通过 parameters()、state_dict() 等接口访问。
完整示例
import torch
class LinearModel(torch.nn.Module):
def __init__(self):
super().__init__()
self.layer = torch.nn.Linear(2, 1)
def forward(self, x):
return self.layer(x)
model = LinearModel()
print(len(list(model.parameters())))预期输出
2边界
不要直接把普通 Python 对象赋给模型后期待 PyTorch 自动管理;需要训练的权重应使用 nn.Parameter,子网络应作为 Module 属性注册。自定义模块必须实现与输入输出匹配的 forward() 方法。
torch.nn.Linear(in_features, out_features, bias=True, device=None, dtype=None)创建全连接层并管理权重与偏置参数;常用于分类器、投影层和 Transformer 中的线性变换。
创建线性层
torch.nn.Linear 用于创建全连接层。需要将输入特征映射到新的特征空间时调用它,返回一个带可训练权重和偏置参数的线性变换模块。
签名
torch.nn.Linear(in_features, out_features, bias=True, device=None, dtype=None)参数
| 参数 | 类型 | 含义 | 默认值或约束 |
|---|---|---|---|
in_features |
int | 输入特征数量 | 必填,必须与输入张量最后一维匹配 |
out_features |
int | 输出特征数量 | 必填,决定输出最后一维大小 |
bias |
bool | 是否添加偏置参数 | True |
device |
torch.device | 参数存放设备 | None,使用默认设备 |
dtype |
torch.dtype | 参数数据类型 | None,使用默认类型 |
返回与参数状态
调用后返回 torch.nn.Linear 模块,其中包含可训练参数 weight 和可选参数 bias。输入形状为 (*, in_features) 时,输出形状为 (*, out_features)。
完整示例
import torch
from torch import nn
layer = nn.Linear(10, 2)
inputs = torch.randn(4, 10)
outputs = layer(inputs)
print(outputs.shape)预期输出
torch.Size([4, 2])边界与兼容性
in_features 必须匹配输入张量最后一维,否则前向计算会因矩阵乘法维度不一致失败。训练模型时通常将该层加入 nn.Module 子类,由优化器统一更新参数。
torch.nn.Conv2d(in_channels, out_channels, kernel_size, stride=1, padding=0)创建二维卷积操作层;适用于图像处理任务,需要根据输入通道和空间尺寸选择参数。
创建卷积层
torch.nn.Conv2d 用于创建二维卷积模块。处理图像或二维特征图时,可以通过输入通道、输出通道和卷积核尺寸定义局部特征提取操作。
签名
torch.nn.Conv2d(in_channels, out_channels, kernel_size, stride=1, padding=0)参数
| 参数 | 类型 | 含义 | 默认值或约束 |
|---|---|---|---|
in_channels |
int | 输入特征图通道数 | 必填,需要匹配输入张量通道维 |
out_channels |
int | 输出通道数 | 必填,决定卷积核数量 |
kernel_size |
int 或 tuple | 卷积核尺寸 | 必填,如 3 表示 3×3 卷积 |
stride |
int 或 tuple | 卷积步长 | 1 |
padding |
int 或 tuple | 输入边缘填充大小 | 0 |
返回与形状规则
调用后返回卷积模块,包含可训练卷积核参数。输入通常为 (N, C_in, H, W),输出为 (N, C_out, H_out, W_out),空间尺寸由卷积核、步长和填充共同决定。
完整示例
import torch
from torch import nn
conv = nn.Conv2d(3, 16, 3)
image = torch.randn(1, 3, 32, 32)
feature = conv(image)
print(feature.shape)预期输出
torch.Size([1, 16, 30, 30])边界与兼容性
输入通道数必须与 in_channels 一致,否则前向计算会报维度错误。需要保持空间尺寸时,应根据卷积核大小配置合适的 padding;实际输出尺寸需要结合 stride 和卷积参数计算。
torch.nn.ReLU(inplace=False)提供非线性激活能力并缓解深层网络表达限制;ReLU 是卷积网络和基础深度模型常用组件。
创建 ReLU 激活函数
torch.nn.ReLU 用于在模型中加入非线性变换。调用后返回一个可插入 nn.Module 网络结构的 ReLU 层,将负值压缩为 0,正值保持不变。
签名
torch.nn.ReLU(inplace=False)参数
| 参数 | 类型 | 含义 | 默认值或约束 |
|---|---|---|---|
inplace |
bool |
是否直接修改输入张量,而不是创建新输出 | False |
inplace=True 可以减少部分内存占用,但会改变输入张量,可能影响需要保留梯度或复用输入的计算流程。
返回与边界
该调用返回一个 torch.nn.ReLU 模块实例。前向计算时输入张量中的负数元素变为 0,正数元素保持不变。
完整示例
import torch
from torch import nn
activation = nn.ReLU()
x = torch.tensor([-2.0, 0.0, 3.0])
y = activation(x)
print(y)预期结果:
tensor([0., 0., 3.])常见误用
不要将 ReLU() 与已经完成激活计算的张量混用。模型定义阶段通常保存模块实例,在 forward 中对中间特征调用。
torch.nn.Module.load_state_dict(state_dict, strict=True)将保存的参数字典加载到模型实例;适用于恢复训练、迁移学习和部署前初始化。
加载模型参数
load_state_dict 用于把保存的参数字典写入已有模型实例。查阅该接口可以确认恢复训练、迁移学习或部署初始化时需要提供的数据格式和校验方式。
签名
torch.nn.Module.load_state_dict(state_dict, strict=True)参数
| 参数 | 类型 | 含义 | 默认值或约束 |
|---|---|---|---|
state_dict |
dict |
模型参数字典,通常来自 state_dict() 保存结果 |
必填 |
strict |
bool |
是否要求参数键与模型结构完全匹配 | True |
返回与错误
成功加载后返回加载状态信息对象。使用 strict=True 时,如果缺少参数、存在多余参数或名称不匹配,会报告加载错误;strict=False 可允许部分匹配,适用于迁移学习场景。
完整示例
import torch
from torch import nn
model = nn.Linear(2, 1)
checkpoint = model.state_dict()
result = model.load_state_dict(checkpoint)
print(result)预期结果:
<All keys matched successfully>实际显示形式可能随 PyTorch 版本变化,但应表示所有参数键成功匹配。
边界与兼容性
保存和加载时应保持模型结构与参数名称一致。加载文件前确认来源可信,并根据运行环境检查 PyTorch 版本兼容性,避免序列化对象或参数格式不匹配。
数据加载
torch.utils.data.Dataset()定义数据读取逻辑的抽象接口;用于封装样本访问、标签生成和自定义数据加载流程。
创建数据集
需要封装自定义样本读取逻辑时使用 Dataset,它定义单个样本如何通过索引获取,最终交给 DataLoader 组成训练批次。
签名
class torch.utils.data.Dataset(*args, **kwargs)Dataset 是抽象基类,通常通过继承实现 __len__() 和 __getitem__()。
核心方法
| 方法 | 类型 | 含义 | 约束 |
|---|---|---|---|
__len__ |
方法 | 返回数据集样本数量 | 应返回可确定的整数 |
__getitem__ |
方法 | 根据索引返回一个样本 | 应支持合法索引访问 |
完整示例
from torch.utils.data import Dataset
class NumberDataset(Dataset):
def __init__(self, values):
self.values = values
def __len__(self):
return len(self.values)
def __getitem__(self, index):
# 返回单个样本,DataLoader 会继续组织批次
return self.values[index]
dataset = NumberDataset([10, 20, 30])
print(len(dataset))
print(dataset[1])预期输出
3
20返回与边界
__getitem__() 的返回结构由任务决定,可以是张量、元组、字典等。训练代码和批处理逻辑需要保持返回格式一致。
不要在 __getitem__() 中执行无法接受的慢操作,否则会拖慢数据加载;大规模数据通常结合 DataLoader 的多进程加载能力优化。
torch.utils.data.DataLoader(dataset, batch_size=1, shuffle=False, sampler=None)将数据集封装为批次迭代器,支持打乱、并行加载和批训练;是训练循环的数据入口。
批量加载数据
训练模型需要按批次读取样本时使用 DataLoader,它把 Dataset 转换为可迭代的数据流,并负责批处理、顺序控制和加载优化。
签名
torch.utils.data.DataLoader(dataset, batch_size=1, shuffle=False, sampler=None)参数
| 参数 | 类型 | 含义 | 默认值或约束 |
|---|---|---|---|
dataset |
Dataset |
数据来源对象 | 必填 |
batch_size |
int |
每个批次包含的样本数 | 1 |
shuffle |
bool |
每轮迭代前是否打乱数据 | False |
sampler |
Sampler |
自定义采样策略 | None,与 shuffle 互斥使用 |
返回与错误
返回可迭代的 DataLoader 对象。实际取出的元素由 dataset 返回值和默认或自定义 collate_fn 共同决定。
dataset 不满足索引访问要求、batch_size 为非法值或 sampler 配置冲突时会在创建或迭代阶段报错。
完整示例
from torch.utils.data import Dataset, DataLoader
class NumberDataset(Dataset):
def __init__(self):
self.values = [1, 2, 3, 4]
def __len__(self):
return len(self.values)
def __getitem__(self, index):
return self.values[index]
dataset = NumberDataset()
loader = DataLoader(dataset, batch_size=2)
for batch in loader:
print(batch.tolist())预期输出
[1, 2]
[3, 4]边界与兼容性
训练任务通常设置 shuffle=True,避免模型学习固定顺序带来的偏差;验证和测试阶段一般保持固定顺序。
需要提升读取速度时,可结合 num_workers、pin_memory 等参数调整,但具体效果依赖运行环境、存储速度和数据预处理开销。
训练优化
torch.nn.CrossEntropyLoss(weight=None, size_average=None, ignore_index=-100, reduction='mean')计算分类任务预测结果与目标标签之间的损失;适用于多分类模型训练和概率输出优化。
定义分类损失函数
使用 CrossEntropyLoss 时,用于训练分类模型并计算预测类别与真实标签之间的误差。调用后得到一个损失函数对象,可在前向计算后参与反向传播。
签名
torch.nn.CrossEntropyLoss(weight=None, size_average=None, ignore_index=-100, reduction='mean')参数
| 参数 | 类型 | 含义 | 默认值或约束 |
|---|---|---|---|
weight |
Tensor | 每个类别的权重,用于处理类别不均衡 | None |
size_average |
bool | 旧版平均策略参数,已被 reduction 替代 |
None |
ignore_index |
int | 指定不参与损失计算的目标类别索引 | -100 |
reduction |
str | 损失聚合方式 | mean |
返回与边界
调用 torch.nn.CrossEntropyLoss() 返回一个损失函数模块。输入通常为未经过 Softmax 的模型输出 logits,以及表示类别索引的目标标签。
如果输入类别数量与标签范围不匹配,会在计算时产生错误;不要提前对 logits 使用 Softmax,否则会改变该损失函数期望的输入形式。
完整示例
import torch
import torch.nn as nn
loss_fn = nn.CrossEntropyLoss()
logits = torch.tensor([[2.0, 0.5, -1.0]])
target = torch.tensor([0])
loss = loss_fn(logits, target)
print(loss.item())预期结果:
输出一个表示分类误差的浮点数,例如 0.241311...常见误用
训练多分类模型时,标签应使用类别索引形式,例如 0、1、2,而不是 one-hot 向量。类别数量变化时,需要同步检查输出层维度和目标标签范围。
torch.optim.Adam(params, lr=0.001, betas=(0.9,0.999), eps=1e-08)使用 Adam 算法更新模型参数;适合大多数深度学习训练任务,需要结合梯度清零和损失反向传播。
创建 Adam 优化器
使用 torch.optim.Adam 时,用于根据梯度更新模型参数。创建优化器后,需要在训练循环中配合 zero_grad()、反向传播和 step() 完成一次参数更新。
签名
torch.optim.Adam(params, lr=0.001, betas=(0.9, 0.999), eps=1e-08)参数
| 参数 | 类型 | 含义 | 默认值或约束 |
|---|---|---|---|
params |
iterable | 需要更新的模型参数集合 | 必填 |
lr |
float | 学习率,控制参数更新步长 | 0.001 |
betas |
tuple | 一阶和二阶矩估计衰减系数 | (0.9, 0.999) |
eps |
float | 数值稳定项,避免除零 | 1e-08 |
返回与使用边界
调用后返回 Adam 优化器对象。step() 会根据当前参数梯度更新模型;如果忘记执行 loss.backward(),优化器不会获得有效梯度。
参数列表应来自需要训练的模型参数,例如 model.parameters()。冻结参数不应传入优化器更新范围。
完整示例
import torch
import torch.nn as nn
model = nn.Linear(2, 1)
optimizer = torch.optim.Adam(model.parameters(), lr=0.001)
x = torch.tensor([[1.0, 2.0]])
y = model(x)
loss = y.mean()
optimizer.zero_grad()
loss.backward()
optimizer.step()
print("updated")预期结果:
updated常见误用
调整学习率时优先检查训练曲线和梯度变化,不要只通过增大学习率解决收敛问题。加载已有训练状态时,需要同时保存和恢复优化器状态,否则动量信息会丢失。
torch.optim.Optimizer.zero_grad(set_to_none=True)清除优化器中累积的梯度值;通常放在训练循环开始位置,避免多个 batch 梯度叠加。
清空梯度
optimizer.zero_grad() 用于在开始下一轮参数计算前移除上一轮反向传播留下的梯度,避免不同 batch 的梯度累积到同一组参数上。
签名
torch.optim.Optimizer.zero_grad(set_to_none=True)参数
set_to_none:bool类型,是否将梯度设置为None。默认值取决于调用方式;显式传入True可减少部分内存写入,并让未参与计算的参数梯度保持None。
返回与行为
该方法返回 None。调用后,优化器管理参数的 .grad 会被清理:
set_to_none=True:梯度字段变为None。set_to_none=False:梯度张量被填充为 0。
完整示例
import torch
model = torch.nn.Linear(2, 1)
optimizer = torch.optim.SGD(model.parameters(), lr=0.1)
x = torch.tensor([[1.0, 2.0]])
y = model(x).sum()
y.backward()
# 下一轮训练前清除旧梯度
optimizer.zero_grad(set_to_none=True)
print(model.weight.grad is None)预期结果
True边界
不要在 backward() 之前误删当前轮需要累积的梯度。如果需要梯度累积训练,应按累计步数控制清空时机,而不是每个 batch 都调用。
torch.optim.Optimizer.step(closure=None)根据当前梯度执行一次参数更新;必须在完成反向传播后调用,否则不会产生有效优化。
更新模型参数
optimizer.step() 用于根据当前参数梯度执行一次优化器更新。训练循环中通常在 backward() 完成后调用,让模型参数沿优化方向移动。
签名
torch.optim.Optimizer.step(closure=None)参数
closure:可调用对象,默认值为None。部分需要重新计算损失的优化器会使用该回调,例如某些二阶优化方法。
返回与错误
普通优化器调用后通常返回 None。如果参数没有有效梯度,更新可能不会发生;若优化器状态或参数配置不匹配,可能抛出运行时异常。
完整示例
import torch
model = torch.nn.Linear(2, 1)
optimizer = torch.optim.SGD(model.parameters(), lr=0.1)
x = torch.tensor([[1.0, 2.0]])
loss = model(x).sum()
optimizer.zero_grad()
loss.backward()
optimizer.step()
print(model.weight.detach().shape)预期结果
torch.Size([1, 2])边界
调用顺序通常应保持为 zero_grad() → 前向计算 → backward() → step()。如果跳过反向传播直接调用 step(),参数通常不会获得基于当前 batch 的有效更新。
推理部署
torch.nn.Module.train(mode=True)设置模块进入训练状态,会启用 Dropout 和 BatchNorm 等训练行为;训练阶段通常需要调用。
切换训练模式
train 用于让模块进入训练状态。训练循环开始前调用它,使 Dropout、BatchNorm 等依赖训练状态的层按训练逻辑运行。
签名
torch.nn.Module.train(mode=True)参数
| 参数 | 类型 | 含义 | 默认值 |
|---|---|---|---|
mode |
bool |
是否进入训练模式;True 为训练,False 等价于切换评估行为 |
True |
返回与行为
该方法返回模块自身对象,便于链式调用。调用后会递归修改当前模块及所有子模块的 training 状态,但不会自动计算梯度或启动优化器。
完整示例
import torch
import torch.nn as nn
model = nn.Sequential(
nn.Linear(10, 5),
nn.Dropout(p=0.5),
)
model.train()
print(model.training)
print(model[1].training)预期输出
True
True边界与误用
train() 不等同于开始训练流程。参数更新仍需要优化器和反向传播;如果在验证或推理阶段忘记切换状态,Dropout 随机失活和 BatchNorm 统计更新可能导致结果异常。
torch.nn.Module.eval()设置模块进入评估状态,关闭训练特有行为;模型验证和线上推理前应调用此接口。
切换推理模式
eval 用于将模块切换到评估状态。模型验证、测试和部署推理前调用它,可以关闭 Dropout 等训练专用行为,并让 BatchNorm 使用已有统计量。
签名
torch.nn.Module.eval()参数与返回
该方法没有参数,等价于调用 train(False)。调用后返回模块自身对象,并递归修改当前模块及所有子模块的训练状态。
完整示例
import torch.nn as nn
model = nn.Sequential(
nn.Linear(10, 5),
nn.Dropout(p=0.5),
)
model.eval()
print(model.training)
print(model[1].training)预期输出
False
False边界与兼容性
eval() 只改变模块状态,不会关闭梯度计算。部署推理时通常还需要结合 torch.no_grad() 或推理模式 API 来减少计算开销。
如果验证集结果异常,优先检查是否在评估前调用了 model.eval(),避免模型仍处于训练状态。