【Bug已解决】Calling cuda() with async results in SyntaxError 解决方案

问题描述

在 PyTorch 中，将张量或模型从 CPU 移到 GPU 是日常操作。许多开发者从旧版教程或文档中看到过tensor.cuda(async=True)这样的写法，但在较新版本的 PyTorch 中运行时，会遇到SyntaxError或TypeError。

具体表现为：

1. 使用tensor.cuda(async=True)时报错SyntaxError
2. 使用tensor.cuda(async=True)时报错TypeError: cuda() got an unexpected keyword argument 'async'
3. 从旧代码库迁移到新版本 PyTorch 时，大量async参数导致错误
4. 不清楚async参数被什么替代了

这个问题的根本原因是 Python 语言本身的演进和 PyTorch API 的更新。

错误复现

场景一：Python 3.7+ 中的 SyntaxError

import torch # 创建张量 x = torch.randn(10, 10) # 尝试使用 async 参数 x = x.cuda(async=True)

在 Python 3.7+ 中报错：

SyntaxError: invalid syntax

这是因为从 Python 3.7 开始，async和await成为保留关键字，不能用作变量名或参数名。

场景二：旧代码迁移

# 旧代码（PyTorch < 1.0） model = MyModel() model = model.cuda(async=True) for batch in dataloader: inputs, labels = batch inputs = inputs.cuda(async=True) labels = labels.cuda(async=True) # ...

在 PyTorch 2.x 中报错：

TypeError: Tensor.cuda() got an unexpected keyword argument 'async'

场景三：教程代码不兼容

从网上找到的教程代码使用了async参数：

# 从某教程复制的代码 x = x.cuda(async=True)

报错：

SyntaxError: invalid syntax

根因分析

1. Pythonasync关键字演进

• Python 3.5：引入async和await作为协程语法
• Python 3.6：async和await可以用作变量名（但有警告）
• Python 3.7：async和await成为正式保留关键字，不能用作标识符
• Python 3.7+：使用async作为参数名会导致SyntaxError

2. PyTorch API 变更

• PyTorch < 1.0：tensor.cuda(async=True)是合法的，async参数控制是否异步传输数据到 GPU
• PyTorch 1.0-1.x：async参数被弃用，改用non_blocking参数
• PyTorch 2.0+：async参数被完全移除，只支持non_blocking

3.asyncvsnon_blocking的语义

async=True（旧）和non_blocking=True（新）的语义相同：当张量的pin_memory=True时，允许异步将数据从 CPU 传输到 GPU，不阻塞 CPU 线程。如果张量没有被 pin 住内存，non_blocking=True没有实际效果。

4. 代码迁移的常见遗漏

开发者在升级 PyTorch 版本时，往往只升级了 PyTorch 本身，但没有更新代码中的 API 调用。旧教程和 StackOverflow 答案中的代码也可能使用过时的async参数。

解决方案

方案一：将async=True替换为non_blocking=True

import torch # 旧代码（报错） # x = x.cuda(async=True) # 新代码（正确） x = x.cuda(non_blocking=True)

方案二：使用to()方法（推荐）

import torch # 使用 to() 方法，更通用 x = x.to('cuda', non_blocking=True) # 对于模型 model = model.to('cuda')

方案三：批量替换旧代码

如果代码库中有大量async=True，可以使用文本替换工具：

# 使用 sed 批量替换（Linux/macOS） find . -name "*.py" -exec sed -i 's/\.cuda(async=True)/\.cuda(non_blocking=True)/g' {} + find . -name "*.py" -exec sed -i 's/\.cuda(async=False)/\.cuda(non_blocking=False)/g' {} + # 或者使用 Python 脚本批量替换

批量替换 Python 脚本：

""" 批量替换 .cuda(async=...) 为 .cuda(non_blocking=...) """ import os import re def fix_async_in_file(filepath): """修复单个文件中的 async 参数""" with open(filepath, 'r', encoding='utf-8') as f: content = f.read() original = content # 替换 .cuda(async=True) -> .cuda(non_blocking=True) content = re.sub( r'\.cuda\(\s*async\s*=\s*True\s*\)', '.cuda(non_blocking=True)', content ) # 替换 .cuda(async=False) -> .cuda(non_blocking=False) content = re.sub( r'\.cuda\(\s*async\s*=\s*False\s*\)', '.cuda(non_blocking=False)', content ) # 替换 .to('cuda', async=True) -> .to('cuda', non_blocking=True) content = re.sub( r"\.to\(\s*['\"]cuda['\"]\s*,\s*async\s*=\s*True\s*\)", ".to('cuda', non_blocking=True)", content ) if content != original: with open(filepath, 'w', encoding='utf-8') as f: f.write(content) return True return False def fix_async_in_directory(directory): """递归修复目录中的所有 Python 文件""" fixed_files = [] for root, dirs, files in os.walk(directory): # 跳过常见的不需要检查的目录 dirs[:] = [d for d in dirs if d not in { '__pycache__', '.git', 'node_modules', '.venv', 'venv', 'env', '.eggs', 'build', 'dist' }] for filename in files: if filename.endswith('.py'): filepath = os.path.join(root, filename) if fix_async_in_file(filepath): fixed_files.append(filepath) print(f"Fixed: {filepath}") return fixed_files if __name__ == '__main__': import sys target_dir = sys.argv[1] if len(sys.argv) > 1 else '.' fixed = fix_async_in_directory(target_dir) print(f"\nTotal files fixed: {len(fixed)}")

完整修复代码

以下是一个完整的示例，展示新旧 API 的对比和正确用法：

""" PyTorch cuda() async 参数迁移指南 演示 non_blocking 参数的正确用法 """ import torch import torch.nn as nn import time from torch.utils.data import DataLoader, TensorDataset class SimpleModel(nn.Module): def __init__(self): super().__init__() self.fc1 = nn.Linear(784, 256) self.fc2 = nn.Linear(256, 10) def forward(self, x): x = torch.relu(self.fc1(x)) return self.fc2(x) def demo_non_blocking(): """演示 non_blocking 参数的效果""" print("=" * 60) print("non_blocking 参数演示") print("=" * 60) if not torch.cuda.is_available(): print("CUDA 不可用，使用 CPU 演示") device = 'cpu' else: device = 'cuda' # 创建数据 num_samples = 10000 X = torch.randn(num_samples, 784) y = torch.randint(0, 10, (num_samples,)) # ========== 方式1：不使用 pin_memory 和 non_blocking ========== print("\n方式1: 不使用 pin_memory 和 non_blocking") dataset = TensorDataset(X, y) loader = DataLoader(dataset, batch_size=256, shuffle=True, num_workers=0, pin_memory=False) model = SimpleModel().to(device) optimizer = torch.optim.Adam(model.parameters()) criterion = nn.CrossEntropyLoss() start = time.time() for batch_X, batch_y in loader: # 同步传输 batch_X = batch_X.to(device, non_blocking=False) batch_y = batch_y.to(device, non_blocking=False) optimizer.zero_grad() output = model(batch_X) loss = criterion(output, batch_y) loss.backward() optimizer.step() sync_time = time.time() - start print(f" 时间: {sync_time:.4f}s") # ========== 方式2：使用 pin_memory + non_blocking ========== if device == 'cuda': print("\n方式2: 使用 pin_memory + non_blocking") # pin_memory=True 使 DataLoader 将数据放入锁页内存 loader_pinned = DataLoader(dataset, batch_size=256, shuffle=True, num_workers=0, pin_memory=True) model2 = SimpleModel().to(device) optimizer2 = torch.optim.Adam(model2.parameters()) start = time.time() for batch_X, batch_y in loader_pinned: # non_blocking=True 允许异步传输 batch_X = batch_X.to(device, non_blocking=True) batch_y = batch_y.to(device, non_blocking=True) optimizer2.zero_grad() output = model2(batch_X) loss = criterion(output, batch_y) loss.backward() optimizer2.step() async_time = time.time() - start print(f" 时间: {async_time:.4f}s") print(f" 加速比: {sync_time/async_time:.2f}x") else: print("\n方式2: 需要 CUDA 支持，跳过") def demo_api_comparison(): """新旧 API 对比""" print("\n" + "=" * 60) print("新旧 API 对比") print("=" * 60) comparisons = [ ("旧 API (已废弃)", "新 API (推荐)"), ("x.cuda(async=True)", "x.cuda(non_blocking=True)"), ("x.cuda(async=False)", "x.cuda(non_blocking=False)"), ("x.cuda(0, async=True)", "x.cuda(0, non_blocking=True)"), ("model.cuda(async=True)", "model.cuda(non_blocking=True)"), ("x.to('cuda', async=True)", "x.to('cuda', non_blocking=True)"), ("x.to(device, async=True)", "x.to(device, non_blocking=True)"), ] for old, new in comparisons: print(f" {old:40s} -> {new}") def demo_correct_usage(): """演示正确的 GPU 数据传输方式""" print("\n" + "=" * 60) print("正确的 GPU 数据传输方式") print("=" * 60) device = torch.device('cuda' if torch.cuda.is_available() else 'cpu') # 1. 模型移到 GPU model = SimpleModel() model = model.to(device) print(f"模型设备: {next(model.parameters()).device}") # 2. 创建 pin_memory 的 DataLoader X = torch.randn(1000, 784) y = torch.randint(0, 10, (1000,)) dataset = TensorDataset(X, y) pin_memory = device.type == 'cuda' loader = DataLoader( dataset, batch_size=64, shuffle=True, num_workers=2, pin_memory=pin_memory # GPU 环境下启用 ) # 3. 训练循环 optimizer = torch.optim.Adam(model.parameters()) criterion = nn.CrossEntropyLoss() model.train() for batch_X, batch_y in loader: # 使用 non_blocking=True（配合 pin_memory） batch_X = batch_X.to(device, non_blocking=pin_memory) batch_y = batch_y.to(device, non_blocking=pin_memory) optimizer.zero_grad() output = model(batch_X) loss = criterion(output, batch_y) loss.backward() optimizer.step() print("训练完成！") def demo_migration_check(): """检查代码中是否有过时的 async 用法""" print("\n" + "=" * 60) print("代码迁移检查工具") print("=" * 60) import ast import inspect import sys # 检查当前 PyTorch 版本的 cuda 方法签名 x = torch.randn(1) sig = inspect.signature(x.cuda) print(f"Tensor.cuda() 签名: {sig}") # 检查 to 方法签名 sig_to = inspect.signature(x.to) print(f"Tensor.to() 签名: {sig_to}") print(f"\nPyTorch 版本: {torch.__version__}") print(f"Python 版本: {sys.version}") print("\n迁移检查清单:") print(" [ ] 搜索代码中的 'async=True' 并替换为 'non_blocking=True'") print(" [ ] 搜索代码中的 'async=False' 并替换为 'non_blocking=False'") print(" [ ] 确认 DataLoader 的 pin_memory 参数设置正确") print(" [ ] 确认 .to() 调用使用了 non_blocking 参数") print(" [ ] 测试修改后的代码是否正常运行") def main(): print("\n" + "=" * 60) print(" PyTorch cuda() async 参数迁移指南") print("=" * 60) demo_api_comparison() demo_non_blocking() demo_correct_usage() demo_migration_check() print("\n" + "=" * 60) print(" 演示完成！") print("=" * 60) if __name__ == '__main__': main()

常见陷阱与注意事项

1.non_blocking=True需要pin_memory=True才有效

non_blocking=True只有在数据位于锁页内存（pinned memory）时才能实现真正的异步传输。如果数据没有被 pin 住，non_blocking=True会被忽略，传输仍然是同步的。

# 正确：pin_memory + non_blocking loader = DataLoader(dataset, batch_size=64, pin_memory=True) for batch in loader: batch = batch.to('cuda', non_blocking=True) # 真正异步 # 无效：没有 pin_memory loader = DataLoader(dataset, batch_size=64, pin_memory=False) for batch in loader: batch = batch.to('cuda', non_blocking=True) # 实际同步，non_blocking 被忽略

2.non_blocking可能导致数据竞争

如果使用non_blocking=True异步传输数据，但在数据传输完成前就使用了该数据，可能导致未定义行为。PyTorch 通常会在需要时自动同步，但在某些边缘情况下可能出问题。

# 潜在问题：异步传输后立即使用 x = x.to('cuda', non_blocking=True) y = torch.mm(x, x) # PyTorch 会自动等待 x 传输完成 # 通常安全，但要注意不要在 CUDA 流之间混用

3. Python 3.6 的过渡期

在 Python 3.6 中，async作为参数名会产生DeprecationWarning但不会报错。从 Python 3.7 开始，它成为SyntaxError。如果你的代码需要在 Python 3.6 上运行，也不能使用async作为参数名。

4.async作为变量名

除了cuda()的参数，代码中其他地方使用async作为变量名也会在 Python 3.7+ 中报错：

# 旧代码（Python 3.7+ 报错） async = True # 修复 is_async = True

5. 模型的cuda()方法不支持non_blocking

Tensor.cuda()支持non_blocking参数，但Module.cuda()不支持。模型移动到 GPU 总是同步的：

# 正确：张量支持 non_blocking x = x.cuda(non_blocking=True) # 错误：模型不支持 non_blocking # model = model.cuda(non_blocking=True) # TypeError # 正确：模型移动不需要 non_blocking model = model.cuda()

6.to()方法的参数顺序

Tensor.to(device, non_blocking=True)的non_blocking是关键字参数，不能作为位置参数：

# 正确 x = x.to('cuda', non_blocking=True) # 错误 # x = x.to('cuda', True) # 会被解释为其他参数

7. 旧版 PyTorch 的兼容性

如果你的代码需要在 PyTorch 0.4 和 PyTorch 2.x 上同时运行，可以使用条件判断：

import torch # 兼容性写法 try: # PyTorch 1.0+ x = x.cuda(non_blocking=True) except TypeError: # PyTorch 0.4 x = x.cuda(async=True)

但这种做法不推荐，建议统一升级到新版本 API。

总结

cuda(async=True)导致的SyntaxError或TypeError是一个简单的版本迁移问题，解决方法非常直接：

1. 将async=True替换为non_blocking=True——这是最核心的修改
2. 使用to()方法替代cuda()——更通用，支持 CPU 和 GPU 之间的灵活切换
3. 配合pin_memory=True使用——non_blocking只有在数据位于锁页内存时才真正异步
4. 批量替换旧代码——使用提供的脚本可以快速修复整个代码库

这个问题的出现反映了 PyTorch API 的成熟化过程。non_blocking比async更准确地描述了参数的语义（非阻塞传输），也避免了与 Pythonasync关键字的冲突。在编写新代码时，始终使用non_blocking参数和to()方法。