本文详解在 Apple Silicon Mac（如 M2 MacBook Air）上启用 Metal Performance Shaders（MPS）加速 YOLOv8 训练的完整配置方法，解决因误调 CUDA API 导致的 AssertionError: Torch not compiled with CUDA enabled 报错，并提供兼容性检查、代码修正与性能优化建议。
本文详解在 apple silicon mac（如 m2 macbook air）上启用 metal performance shaders（mps）加速 yolov8 训练的完整配置方法，解决因误调 cuda api 导致的 `assertionerror: torch not compiled with cuda enabled` 报错，并提供兼容性检查、代码修正与性能优化建议。
YOLOv8 原生支持 Apple Silicon 的 MPS（Metal Performance Shaders）后端，但其内部自动批处理（autobatch）和部分设备检测逻辑仍默认依赖 CUDA 接口（如 torch.cuda.get_device_properties），这在 macOS 上会直接触发断言错误——并非 MPS 本身不可用，而是训练流程中未正确绕过 CUDA 相关检查。
✅ 正确启用 MPS 的关键步骤
1. 确保 PyTorch 版本支持 MPS
仅 torch >= 2.0 且为 Apple Silicon 专用构建版（非通用 wheel）才完整支持 MPS。安装命令必须显式指定：
# 卸载现有 torch（如有） pip uninstall torch torchvision torchaudio # 安装官方推荐的 MPS 兼容版本（以 macOS ARM64 为例） pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/apple
验证是否启用成功：
import torch print(torch.backends.mps.is_available()) # 应输出 True print(torch.backends.mps.is_built()) # 应输出 True
⚠️ 注意：若输出 False，说明安装了 x86_64 或 CUDA 版本的 PyTorch，请彻底清理并重装 Apple 官方 wheel。
2. 禁用自动批处理（Autobatch）——核心修复点
报错根源在于 check_train_batch_size() 函数内部硬编码调用了 torch.cuda.* 方法。YOLOv8 v8.1.0+ 已支持通过 batch=-1 显式跳过自动计算，从而规避该逻辑：
from ultralytics import YOLO
import torch
model = YOLO('yolov8s.pt')
# ✅ 关键修改：设置 batch=-1 并显式指定 device='mps'
results = model.train(
data='mot17_data.yml',
epochs=30,
batch=-1, # ← 强制禁用 autobatch，避免 CUDA 检查
imgsz=640,
project='models/yolo',
name='yolov8s_mot17_det10',
device='mps', # ← 字符串 'mps' 更稳妥（而非 torch.device('mps')）
workers=2, # MPS 不支持高 worker 数，建议设为 0~2
cache='ram', # 启用内存缓存可显著提升 I/O 效率
)? 提示：device='mps' 比 device=torch.device('mps') 更兼容；workers=0 或 1 可避免多进程与 MPS 的潜在冲突。
3. 手动设定合理 batch size（替代 autobatch）
由于禁用了自动批处理，需根据显存容量手动估算 batch size。M2 MacBook Air（8GB 统一内存）推荐起始值：
| 模型规模 | 推荐 batch size（MPS） |
|---|---|
| yolov8n | 32 ~ 64 |
| yolov8s | 16 ~ 32 |
| yolov8m | 8 ~ 16 |
示例（yolov8s）：
results = model.train(
# ... 其他参数
batch=24, # ← 显式指定，避免 -1 导致的潜在不确定性
device='mps',
)4. 额外优化建议
-
关闭 AMP（混合精度）：MPS 当前对 torch.cuda.amp 兼容性有限，建议显式关闭：
results = model.train(..., amp=False) # 默认为 True，易引发 MPS 不兼容警告
- 禁用 TensorBoard 冗余日志（可选）：若无需实时监控，添加 exist_ok=True 和 verbose=False 减少开销。
- 数据预加载优化：使用 cache='ram' 将训练集一次性加载至统一内存，大幅减少重复读取延迟。
? 总结：避坑清单
- ❌ 不要使用 torch.device('mps') —— 改用字符串 'mps'；
- ❌ 不要依赖默认 batch=-1 触发 autobatch —— 它会强制调用 CUDA API；
- ✅ 必须安装 --extra-index-url https://download.pytorch.org/whl/apple 下的 PyTorch；
- ✅ workers 建议 ≤2，cache='ram' 强烈推荐；
- ✅ MPS 不支持 torch.compile() 或 torch.distributed，勿启用相关选项。
完成上述配置后，YOLOv8 在 M2 Mac 上的训练速度可从 CPU 的 ≈1 小时/epoch 提升至 ≈15–25 分钟/epoch（具体取决于数据集大小与 batch 设置），真正实现本地高效开发与快速迭代。
