企业官网建设流程全解析

很多人第一次写PyTorch训练循环，八成都被同一个报错拍在墙上：

RuntimeError: Expected all tensors to be on the same device, but found at least two devices, cuda:0 and cpu!

看着这个错，第一反应通常是“我明明写了to(device)啊”，再一看，原来有的地方写了，有的地方漏了。to(device)这个词看起来简单，就一个函数调用，但它的行为细节、底层机制、使用场景，以及围绕它衍生出的一堆坑，绝不是“一行代码”这么简单。这篇东西就把to(device)的来龙去脉、正确姿势、常见翻车现场一次讲透，适合刚入门 PyTorch 的读者，也适合已经写过几个模型但被设备问题来回折磨的开发者。

1. to(device) 到底在解决什么问题：先理解 CPU 和 GPU 之间是“物理隔离”

1.1 PyTorch 为什么默认把所有东西放在 CPU 上

只要你在交互环境里敲过torch.randn(3, 3)，你发现它返回的张量在 CPU 上。PyTorch 之所以这么设计，根源在于 CPU 是唯一一个“不需要任何前提条件就能使用的设备”。CUDA 需要显卡驱动、需要 PyTorch 编译时带上 CUDA 支持、需要torch.cuda.is_available()返回 True，任何一个环节不满足，程序直接崩溃。为了库的通用性和开箱即用，PyTorch 把 CPU 作为默认设备。

问题来了：当你真正要训练模型时，99% 的算力需求都在 GPU 上，而 PyTorch 不会因为你装了显卡就自动把你的张量往 GPU 上放。它选择把“设备管理”这件事完全交给开发者。这就是to(device)存在的根本原因——它是开发者和 PyTorch 之间显式约定“数据放哪”的桥梁。

1.2 一个“两个房间”的类比帮你彻底理解设备隔离

把 CPU 内存想象成家里的书房，GPU 显存想象成隔壁仓库。你在书房里放了一堆书（CPU 张量），在仓库里也放了一堆书（GPU 张量）。书房里的书和仓库里的书内容可以完全一样，但它们物理上不在同一个地方。你要在仓库里做“整理书架”这件事（GPU 计算），就必须把书房的书搬到仓库去。PyTorch 做的事情是保证“一本书”自己是完整的，但它绝不帮你判断“两本书”是否在同一个房间，更不会自动搬运。

这个类比能解释后续所有报错：RuntimeError: Expected all tensors to be on the same device的本质，就是你在仓库里做运算时，发现参与运算的几个张量，有的在书房有的在仓库，PyTorch 直接不干了。它不帮你搬，因为自动搬运会导致隐藏的巨额性能开销，也会让内存管理变得不可预测。

1.3 to(device) 和 .cuda() 到底有什么区别

很多老代码里用的是x.cuda()、model.cuda()。.cuda()是早期 PyTorch 提供的方法，它的行为是把张量或模型搬到 GPU，是to(device)的特例。但.cuda()有两个缺点：一是写死了 CUDA，你没法用它把东西搬回 CPU；二是代码里一旦写死cuda:0，换一台只有cuda:1可用的机器就麻烦。

to(device)则是一个更通用的接口，目标设备可以是cpu、cuda、cuda:0，还能顺便转换数据类型。现在的官方推荐是统一用.to()，把.cuda()看作历史遗留写法。我自己重构老项目时，第一件事就是把所有.cuda()替换成.to(device)，代码可迁移性立刻上一个台阶。

2. device 对象的两种写法：硬编码和动态适配

2.1 字符串形式目标设备的完整清单

to()方法接受一个目标设备参数，可以是一个torch.device对象，也可以直接传字符串。常见写法如下表：

'cuda'和'cuda:0'在单卡环境下几乎没有区别，'cuda'会被解析为当前默认设备，默认设备通常是cuda:0。但在多卡或者分布式环境下，'cuda'的行为会变得微妙——它指向当前进程的默认设备（由环境变量或初始化逻辑决定），所以写代码时如果想强调“某一张具体的卡”，建议显式写'cuda:0'或由外部参数传入。

2.2 用 torch.device 做全局统一管理

torch.device对象的优势在于它本身携带设备类型和编号信息，可以作为参数在函数间传递。最经典的一段代码是：

import torch device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

这一行几乎出现在所有 PyTorch 训练脚本开头。它的逻辑是：优先使用 GPU，没有 GPU 就退化到 CPU。这样写的好处是，整个脚本里只需要维护device这一个变量，后续所有to(device)都指向同一个目标。换机器、换环境，只改这一行逻辑就够了。

在此基础上，多卡判断可以这样写：

device = torch.device("cuda" if torch.cuda.is_available() else "cpu") if torch.cuda.is_available() and torch.cuda.device_count() > 1: # 多卡环境后续考虑 DataParallel 或分布式 pass

2.3 分布式训练里的 device 不能照搬单卡写法

有一类代码在单卡环境跑得很好，一上多卡分布式就崩，问题往往出在 device 的表示上。在torch.distributed场景下，每个进程负责一张卡，每个进程的“当前设备”由local_rank决定。此时再写device = "cuda" if torch.cuda.is_available() else "cpu"就错了，因为torch.cuda.is_available()在每个进程里都可能返回 True，但真正该用的卡是local_rank指定的那张。

正确做法是用初始化时传入的local_rank构造设备，例如：

local_rank = int(os.environ.get("LOCAL_RANK", 0)) torch.cuda.set_device(local_rank) device = torch.device("cuda", local_rank)

这种细节在单机单卡下完全看不出来，但一旦代码要扩展到多机多卡，设备选择的写法就是你第一道坎儿。

3. tensor.to() 的四个必须记住的细节

3.1 to 返回新对象，原 Tensor 纹丝不动

这是新手踩得最多的一个坑。看这行代码：

x = torch.randn(3, 3) x.to(device) # 错！结果丢了

x.to(device)返回的是一个新的张量，它把x的数据拷贝到目标设备并返回，但x本身还是 CPU 上的。必须接收返回值：

x = x.to(device) # 对！

或者是：

y = x.to(device) # x 还在 CPU，y 在 GPU，x 可以继续留在 CPU 使用

这个行为和很多 Python 库里的“原地修改”方法完全不同，原因在于张量在不同设备上的迁移本质是数据拷贝，它无法在原有内存地址上做“原地搬运”。理解这个点之后，你就不会写出“调用了 to 但没接住返回值”的代码了。

3.2 to 能同时完成设备迁移和 dtype 转换

to()的另一个强大之处是它同时接受设备参数和数据类型参数。比如：

x = x.to(device="cuda", dtype=torch.float16) y = y.to(torch.float32) # 只转 dtype，设备不变 z = z.to("cpu", torch.float32) # 同时搬设备和改精度

这个特性在混合精度训练中非常有用。你可以在把数据搬到 GPU 的同时把它转成半精度，减少显存占用和带宽压力。很多代码里分开写两步：

x = x.to(device) x = x.half()

这两行完全可以用一行替代，还少了一次遍历数据的过程。实际测试下来，千万级参数张量在这种合并写法下确实能省一点时间，更重要的是代码更精简，不容易漏掉其中一步。

3.3 non_blocking 参数：数据加载提速的隐藏开关

to()函数签名里有一个容易被忽略的参数non_blocking。默认是 False，表示同步搬运；设为 True 时，只要源张量在 CPU 上的内存是pin_memory分配的（即页锁定内存），拷贝就可以异步执行，不阻塞主线程。

配合 DataLoader 使用时的经典写法是：

data_loader = torch.utils.data.DataLoader( dataset, batch_size=32, pin_memory=True, # 关键前提 ) for x, y in data_loader: x = x.to(device, non_blocking=True) y = y.to(device, non_blocking=True)

pin_memory=True让 DataLoader 在 CPU 侧分配页锁定内存，non_blocking=True让 GPU 拷贝可以不占用计算主线程。这套组合在 CPU 数据加载耗时较高的场景下，实测能带来可观的每轮 epoch 时间缩减。但也有个陷阱：异步拷贝需要你确认后续对x的访问确实发生在拷贝完成之后。如果你紧接着就用x做同步计算，效果会被抵消，甚至引入隐晦的错误。稳妥起见，只有在数据加载确实是瓶颈时才启用这个参数。

3.4 真正“原地迁移”的写法：copy_()

有些场景你希望保持某个张量对象的引用不变，只是把它的数据从另一个设备拷贝过来。这时可以用copy_()：

target = torch.zeros_like(src) # 目标张量，在目标设备上 target.copy_(src.to(target.device), non_blocking=True)

copy_()是原地操作，会直接改写target的内存数据。但要注意它要求src和target形状一致，且它虽然是原地修改，内部的设备端拷贝依然有自己的开销。平时训练循环里，直接x = x.to(device)就够用了，copy_()更多用在需要保留变量引用、或者自己管理内存池的底层代码里。

4. model.to(device) 的机制：迁移的不只是参数

4.1 model.to(device) 会递归处理所有 Parameter 和 Buffer

调用model.to(device)时，模型会把自身持有的所有Parameter（比如nn.Linear的权重和偏置）以及所有Buffer（比如BatchNorm的running_mean和running_var）递归迁移到目标设备。正因为模型内部状态都被逐一搬过去了，你才能放心地在 GPU 上执行前向计算。

这个操作是 inplace 的，也就是说model.to(device)会直接修改模型内部状态并返回self。所以你可以写：

model = MyModel().to(device)

也可以不接收返回值：

model.to(device)

两者等价。很多资料强调“model.to() 不需要接收返回值”，本质就是因为它是原地操作，这和tensor.to()的行为形成鲜明对比。记住这个区别，能避免不少无意义的困惑。

4.2 没被注册进模型的成员不会被迁移

model.to(device)只对“注册过的”参数和 buffer 生效。什么是注册？nn.Parameter类型赋值给模块属性会自动被注册，register_buffer()显式注册的也会被跟踪。但如果你在__init__里写：

class MyModel(nn.Module): def __init__(self): super().__init__() self.fc = nn.Linear(16, 16) self.my_tensor = torch.randn(4, 4) # 普通张量，不是 Parameter

执行model.to(device)之后，self.fc的权重确实去了 GPU，但self.my_tensor还在 CPU。更隐蔽的是，如果你把自定义的 NN 模块放在普通 list、dict 里，而不是用nn.ModuleList、nn.ModuleDict，同样不会被迁移。排查这类问题的方法是打印设备：

print(next(model.parameters()).device) # 看模型参数在哪 print(model.my_tensor.device) # 看自定义张量在哪

解决方案很简单：需要跟随模型走的张量，要么用nn.Parameter包装，要么用register_buffer注册，要么干脆在forward()里根据输入x.device动态创建。

4.3 forward 内部创建的中间张量也要注意设备

即使模型本身迁移正确，forward()内部创建的临时张量也需要明确设备。我见过太多这种代码：

def forward(self, x): mask = torch.zeros(x.size(0), x.size(1)) # 永远在 CPU return self.fc(x) * mask # CPU 张量乘 GPU 张量，报错

这种问题的正确写法是从输入动态获取设备：

def forward(self, x): device = x.device mask = torch.zeros(x.size(0), x.size(1), device=device) return self.fc(x) * mask

核心思路是“让设备跟着数据走”，而不是在模型内部写死"cuda"或"cuda:0"。这样无论是 CPU 推理还是 GPU 训练，代码都能自适应。把这条经验用到所有中间张量的创建上，能帮你避开一大半设备相关 bug。

5. 一份可以直接用的完整实操模板

5.1 基础训练框架：一套代码 CPU、GPU 通吃

下面是一个完整的单卡训练流程骨架，标出了所有涉及设备迁移的位置：

import torch import torch.nn as nn from torch.utils.data import DataLoader # 1. 全局设备定义 device = torch.device("cuda" if torch.cuda.is_available() else "cpu") # 2. 模型迁移（注意这一步要在构造之后、训练之前完成） model = nn.Sequential( nn.Linear(64, 128), nn.ReLU(), nn.Linear(128, 10) ).to(device) optimizer = torch.optim.SGD(model.parameters(), lr=0.01) criterion = nn.CrossEntropyLoss() # 3. 模拟数据 data = torch.randn(256, 64) # CPU 数据 labels = torch.randint(0, 10, (256,)) # 4. 训练循环中的关键迁移点 for epoch in range(10): x, y = data, labels x, y = x.to(device), y.to(device) # 数据、标签同步迁移 optimizer.zero_grad() output = model(x) # 输入在 GPU，模型参数在 GPU，全链路一致 loss = criterion(output, y) loss.backward() optimizer.step() print(f"epoch {epoch}, loss: {loss.item():.4f}")

这段代码里每一次出现to(device)的位置都有讲究：模型构造完立刻迁移，避免后续任何参数访问在不同设备间穿梭；数据和标签在送入模型前统一迁移；loss不需要单独迁移，因为它由输出和标签计算而来，前两者已经在同一设备上。

5.2 多卡训练：DataParallel 的正确姿势

如果有多张显卡，最简单的方式是用nn.DataParallel包装模型：

if torch.cuda.device_count() > 1: model = nn.DataParallel(model) model = model.to(device)

这里有两件事容易搞混。第一，DataParallel会把输入 batch 沿 batch 维自动切分到各张卡上，所以模型本身得先能在 GPU 上跑，建议先包装再整体.to(device)，确保包括包装器内部引用在内的所有参数都迁移完毕。第二，DataParallel包装后，模型参数名多了一层module.前缀，保存 checkpoint 时要注意：

torch.save(model.module.state_dict(), "model.pth") # 用 module 的 state_dict

或者保存时不解包，加载时也不解包，保持命名一致。这两种策略选一种即可，来回混用会报Missing key(s) in state_dict之类的错误。

5.3 加载 checkpoint 时，map_location 几乎是必选项

训练完要加载模型，下面这行代码救过很多人：

checkpoint = torch.load("model.pth", map_location=device) model.load_state_dict(checkpoint)

map_location的作用是告诉torch.load把保存的张量放到哪个设备上。如果训练时在 GPU 保存，而当前环境没有 GPU，不加map_location就会报RuntimeError: Attempting to deserialize object on a CUDA device but torch.cuda.is_available() is False。反过来，在 GPU 机器上加载 CPU 保存的模型，也建议通过map_location=device让所有参数统一到目标设备，避免后续训练时一半参数在 CPU、一半在显卡的尴尬。

6. 常见报错与排查技巧实录

6.1 “Expected all tensors to be on the same device”

这是出现频率最高的错误。排查思路分三步：第一步，定位是哪个操作触发的，通常报错信息里会提示张量形状和设备；第二步，检查参与操作的每个张量在哪个设备，用print(x.device)或print(next(model.parameters()).device)逐一确认；第三步，找出“漏网之鱼”——常见原因是数据加载时没迁移、标签没迁移、模型内部中间张量固定在 CPU。

一个快捷小技巧：在训练循环开头一次性打印当前 batch 和模型的设备，可以极快缩小范围：

print("x:", x.device, "y:", y.device, "model:", next(model.parameters()).device)

正常情况下，三者应该一致。看到不一致的那一个，就是需要加to(device)的地方。

6.2 保存和加载时设备不匹配

训练时显卡是cuda:0，测试机器只有cuda:1，直接torch.load常常遇到设备索引错误。此时把map_location写成更具体的设备就可以了：

checkpoint = torch.load("model.pth", map_location="cuda:1")

或者干脆写map_location="cpu"，加载后手动再迁移：

checkpoint = torch.load("model.pth", map_location="cpu") model.load_state_dict(checkpoint) model = model.to(device)

这种“先统一到 CPU，再迁往目标设备”的做法是最稳妥的，能避免一次加载过程跨越多个设备导致的混乱。

6.3 多卡切换单卡时的显存问题

训练时用了DataParallel，保存的state_dict带module.前缀。后来单卡推理，直接load_state_dict，报 key 对不上。解决代码给你了：

state_dict = torch.load("model.pth", map_location=device) from collections import OrderedDict new_state_dict = OrderedDict() for k, v in state_dict.items(): if k.startswith("module."): k = k[7:] new_state_dict[k] = v model.load_state_dict(new_state_dict)

这段代码把所有module.前缀剥掉，就能在单卡模型上加载多卡训练的结果。反过来，如果单卡模型想加载多卡模型，就需要用model.module.load_state_dict或者在load_state_dict前手动包装成DataParallel。这个问题本质上是 key 命名不一致，理解了前缀来源，处理起来就非常机械。

6.4 一套常见的设备相关报错速查表

排查设备问题的核心方法论就一条：确认每一个张量都在你期望的设备上。怎么确认？打印.device属性。不要靠猜，不要相信代码“看起来是对的”。

7. 写在最后的几个实战心得

这些是踩过很多次坑之后沉淀下来的习惯，分享给需要的朋友。

第一个习惯：所有训练脚本开头统一写好device变量，后续绝对不出现tensor.cuda()这类硬编码写法。这样做的直接好处是，代码从单卡迁到多卡、从本地迁到服务器，全程只需要改设备判断逻辑，不用满项目替换关键字。

第二个习惯：在模型内部一律通过x.device创建中间张量。你可能会觉得device = "cuda:0"写起来更快，但一旦模型被包装进DataParallel或者在 CPU 环境下做推理，硬编码的设备就变成了一颗定时炸弹。从输入张量身上拿设备信息，是最安全、最优雅的做法。

第三个习惯：写完训练循环主动做一次“设备体检”——打印输入、标签、模型参数的设备，确认三者在同一个地方再开始跑训练。这个过程只需要几行代码，但能在早期发现 80% 的设备 bug，省下的调试时间非常可观。

最后再分享一个小技巧：把nvidia-smi开成一个独立的小窗口，训练的同时观察显存变化。如果模型和数据明明都在 GPU，但显存利用率异常低，基本可以断定有隐性 CPU 到 GPU 的频繁拷贝，这时候优先检查DataLoader是否启用了pin_memory、以及to(device)是否写在循环内部反复执行。设备管理的本质就是数据的流向管理，把每个张量的位置搞清楚了，to(device)那点事也就彻底拿捏了。