当前位置：首页 > news >正文

在 PyCharm Notebook 中安装 YOLO

news 2025/8/19 7:55:32

在 PyCharm Notebook 中安装 YOLO

目标：用 PyCharm 的 Jupyter Notebook 在一个全新虚拟环境中完成 PyTorch 和 YOLO(ultralytics) 的安装、验证与推理；并给出统一的目录结构、常见问题、训练/导出示例。

适用人群 & 前置条件

这段放在正式创建 Notebook 之前，解决“版本怎么选、先装啥、怎么自检”。

适用人群

想在 Notebook 下做小规模 YOLO 实验与训练，并把模型导出给其它项目（ONNX / TorchScript 等）。

必备条件

操作系统：Windows 10/11 x64（推荐）；macOS 也可（MPS）。
PyCharm：社区版 / 专业版均可，建议最新稳定版。

安装并选择合适的 Python（非常重要）

推荐版本：Python 3.10 或 3.11（64 位）。
不要一上来用刚发布的 最新大版本（3.x.0），很多第三方轮子会滞后，易装不上或报错。
安装后在 PyCharm 新建 venv 虚拟环境；后续所有 pip 都在该 venv 内执行。

自检

python --version
python -c "import sys,torch,ultralytics; print('python:',sys.executable); print('torch:',torch.__version__,'cuda?',torch.cuda.is_available(),'cuda_ver:',torch.version.cuda); print('ultralytics:',ultralytics.__version__)"

升级基础工具

python -m pip install --upgrade pip setuptools wheel

决定跑 CPU 还是 GPU（NVIDIA）

建议先走 CPU 路线把流程跑通，再切 GPU 提升速度。

A. 仅 CPU（最稳）

# PyTorch（CPU 轮子）
python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
# YOLO（Ultralytics）
python -m pip install ultralytics
# ONNX 导出与本机验证（CPU）
python -m pip install onnx onnxruntime

B. 使用 NVIDIA GPU（更快）

检查驱动是否正常

nvidia-smi
# 关注两项：Driver Version / CUDA Version

在这里插入图片描述

有正常输出说明驱动已装；若没有，请到 NVIDIA 官网安装匹配你显卡的最新驱动（GeForce/Studio Driver 均可）。

选择匹配的 PyTorch CUDA 轮子（按 nvidia-smi 中的 CUDA 大版本就近选择）

CUDA 11.8 → cu118
CUDA 12.1 → cu121
CUDA 12.4 → cu124
CUDA 12.6 → cu126
CUDA 12.8 → cu128

安装示例（以 CUDA 12.1 为例）

python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
python -m pip install ultralytics
# 若要 GPU 运行 ONNX，装 GPU 版 ORT：
python -m pip install onnx onnxruntime-gpu

GPU 自检

python -c "import torch;print('cuda available:',torch.cuda.is_available()); import sys; torch.cuda.is_available() and print('torch cuda:',torch.version.cuda); torch.cuda.is_available() and print('gpu name:',torch.cuda.get_device_name(0))"

在这里插入图片描述

cuda available: True 才表示 PyTorch 正在使用 GPU；若为 False，大概率是装成 CPU 轮子，或者 驱动/版本不匹配。

CUDA Toolkit 要不要装？

一般不需要 单独安装 CUDA Toolkit（PyTorch 的 CUDA 轮子已内置运行时依赖）。
只有当你要 编译自定义 CUDA 算子 或某些库需要 nvcc，才安装 Toolkit。
在没有 GPU（或不打算用 GPU）的机器上“悬空安装” Toolkit 没意义，且可能带来 DLL/路径冲突。

常见坑位 & 快速排错

Python 太新：刚发布的 3.x.0 往往缺轮子 → 用 3.10/3.11。
CPU/GPU 轮子混装：同一 venv 内先装 CPU 又装 CUDA（或反之）→ 卸载重装或重建 venv：

python -m pip uninstall -y torch torchvision torchaudio

驱动过旧：安装了 cu12x 的 PyTorch，但驱动不满足要求 → 升级 NVIDIA 驱动至相应分支（例如 12.1 需 R530+）。
onnxruntime 装错包：CPU 机器装了 onnxruntime-gpu 会报 Provider 错 → CPU 用 onnxruntime，GPU 用 onnxruntime-gpu。
Notebook 用错解释器：右上角核选择器切到当前项目 venv；或打印确认：

import sys; print(sys.executable)

一、创建 PyCharm Notebook 项目

打开 PyCharm → 选择 新建 Notebook。
等待 IDE 自动创建 venv 并生成 notebook.ipynb 示例。
右下角状态栏确认解释器为本项目的 .venv。

在这里插入图片描述

二、安装依赖

你可以用 图形化（GUI） 或 命令行（Terminal）。两种方式等价，建议命令行，可精确选择 CPU/GPU 版本。

方式 A：PyCharm 图形化安装（Python 软件包）

打开右下角解释器 → Python 软件包。
依次搜索并安装：torch、torchvision、torchaudio、ultralytics、onnx、onnxruntime、onnxsim。
注意：GUI 方式有时会默认装 CPU 版 PyTorch。若你有 NVIDIA GPU 并想用 CUDA，请改用方式 B 按官方轮子安装。

在这里插入图片描述

方式 B：命令行安装（推荐）

在 PyCharm 底部打开 Terminal（确保左侧提示是你项目的 .venv）：

# 升级基础工具（加上 setuptools / wheel 更稳）
python -m pip install --upgrade pip setuptools wheel# 仅 CPU（无独显/不需要 GPU）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu# 如果你有 NVIDIA GPU（以 CUDA 12.1 为例）
# ⚠️ 请按自己驱动/Toolkit 匹配的版本选择官方命令
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121# 安装 YOLO（Ultralytics）
python -m pip install ultralytics# 导出 ONNX 需要的依赖
#   - onnx        ：必须，有它才能导出 ONNX
#   - onnxruntime ：建议，导出后在本机验证 ONNX 推理
#   - onnxsim/onnxslim：可选，用于简化/瘦身 ONNX（export 时 simplify/optimize 会用到）
python -m pip install onnx onnxruntime onnxsim "onnxslim>=0.1.59"

安装完成后，在 Notebook 新建一个单元格验证：

import torch
print(torch.__version__)
print("CUDA Available:", torch.cuda.is_available())

在这里插入图片描述

三、这些包分别做什么？

1) torch

核心库 (PyTorch 本体)
提供 张量 (Tensor) 这种类似于 NumPy 的数据结构，但可以支持 GPU/CPU 加速运算。
实现了 自动微分 (autograd)，训练神经网络时可以自动求梯度。
包含构建深度学习模型的所有基础功能：神经网络层、优化器、损失函数、数据加载工具等。

作用场景：

定义模型结构，例如 CNN、RNN、Transformer
搭建训练循环：前向传播 → 计算 loss → 反向传播 → 更新参数
做数值计算（矩阵乘法、卷积、统计等）

2) torchvision

计算机视觉 (CV) 相关扩展库
提供了很多跟图像任务相关的工具和数据。

主要内容：

数据集 (datasets)：如 CIFAR-10、MNIST、ImageNet 等，方便快速加载。
数据增强 (transforms)：如旋转、裁剪、归一化等，用于数据预处理。
预训练模型 (models)：ResNet、VGG、MobileNet 等，可以直接拿来做迁移学习。
图像操作：处理 PIL、Tensor 格式的图片，便于训练和推理。

作用场景：

图像分类、目标检测、语义分割等视觉任务
加载常用 benchmark 数据集，做快速实验
使用预训练模型进行迁移学习

3) torchaudio

音频处理扩展库
类似 torchvision 之于图像，torchaudio 专门处理语音和声音。

主要内容：

数据集：常见的语音识别数据集（如 LibriSpeech）。
特征提取：将音频波形转为梅尔频谱、MFCC 等特征。
预训练模型：支持一些语音识别、语音增强的模型。
IO 工具：直接读写常见音频格式（wav, mp3）。

作用场景：

语音识别 (ASR)
语音合成 (TTS)
音频事件检测（如枪声检测）
做时序信号的深度学习研究

4) ultralytics

YOLO 官方 Python 包（YOLOv8/YOLOv11 等）。
提供一体化 训练 / 验证 / 推理 / 导出 API（model.train/val/predict/export）与命令行工具 yolo。
支持多任务：检测（detect）、分割（segment）、关键点（pose）、旋转框（obb）等。

主要内容：

模型与权重：内置多种预训练权重（n/s/m/l/x），可自动下载与加载。
高层 API：一行完成训练、评估、推理、导出；回调与日志管理。
多后端导出：ONNX、TorchScript、OpenVINO、CoreML、TensorRT 等。
数据接口：兼容 YOLO 标注格式与 YAML 数据配置。

作用场景：

在 Notebook 中快速完成从 数据到结果 的端到端实验。
轻量训练与迁移学习，产出可移植的部署文件（如 .onnx）。
快速验证与演示（内置可视化、results[0].plot()）。

小贴士：results = model(img) 返回 list；Notebook 内嵌显示建议用 results[0].plot()；保存输出用 save=True, project=..., name=...。

5) onnx

Open Neural Network Exchange 的 Python 包，提供 ONNX 模型的定义 / 读写 / 校验。
使用 model.export(format="onnx") 导出时，此包必装。

主要内容：

模型结构：onnx.load/save、onnx.helper 构图、onnx.checker.check_model 校验。
opset / 兼容性：不同框架/引擎以 opset 版本对齐。
形状推理：onnx.shape_inference.infer_shapes 可补全张量形状信息。

作用场景：

作为 跨框架中间格式，便于在 onnxruntime / TensorRT / OpenVINO 等引擎部署。
导出后进行基本的合法性检查与工具链处理。

6) onnxruntime

ONNX 官方高性能推理引擎。
CPU 机器用 onnxruntime；有 NVIDIA GPU 时用 onnxruntime-gpu（二选一，不要同装）。

主要内容：

推理会话：InferenceSession、session.run()；支持多 Provider（CPU/CUDA/DirectML 等）。
图优化：多级别图优化与内核加速；支持量化、内存与并行优化选项。
生态：与多数部署框架/服务端配合良好（如 Triton、OpenVINO 互通）。

作用场景：

本地/服务器 加载 ONNX 并执行推理，验证导出是否正确或直接作为生产后端。
对比不同导出参数/优化策略的性能差异。

7) onnxsim

ONNX 模型简化工具（可选）：常量折叠、冗余节点消除，减小模型体积、提升推理效率。
仅当需要 simplify=True 或离线简化时才安装。

主要内容：

简化流程：加载 → 常量折叠/子图折叠 → 验证等价性 → 输出精简模型。
用法：Python API 或命令行 onnxsim input.onnx output.onnx。
与 Ultralytics：model.export(format="onnx", simplify=True) 将调用它。

作用场景：

部署前对 ONNX 进行 体积与结构优化，缩短加载时间，提升运行效率。

Windows 提示 Long Path 报错时：启用系统“长路径支持”或临时跳过简化（simplify=False）；必要时改短临时目录。

四、统一目录结构（强烈推荐）

为避免文件与 notebook.ipynb 混在一起，使用下面的布局：

PyCharmMiscProject/
│── .venv/
│── models/          # 预训练模型与你训练好的权重
│── data/
│   └── images/      # 输入图片/测试图片
│── runs/
│   └── detect/      # YOLO 推理输出
│── notebook.ipynb

在这里插入图片描述

五、下载模型与样例图片（自定义保存路径）

YOLO 可自动下载模型；为便于管理，我们显式指定路径。

# --- 统一路径 ---
from pathlib import Path
import requests
from ultralytics import YOLOROOT = Path.cwd()
MODELS_DIR = ROOT / "models"
DATA_DIR   = ROOT / "data" / "images"
MODELS_DIR.mkdir(parents=True, exist_ok=True)
DATA_DIR.mkdir(parents=True, exist_ok=True)# 1) 模型（不存在会自动下载到指定路径）
model = YOLO(str(MODELS_DIR / "yolov8n.pt"))# 2) 样例图片（手动下载）
img_path = DATA_DIR / "bus.jpg"
if not img_path.exists():r = requests.get("https://ultralytics.com/images/bus.jpg", timeout=15)r.raise_for_status()img_path.write_bytes(r.content)

在这里插入图片描述

六、推理：保存可视化结果并在 Notebook 内嵌显示

results 是列表；在 Notebook 中用 plot() + PIL 内嵌显示更稳定。

from PIL import Imageresults = model(source=str(img_path),save=True,                  # 保存图像project="runs/detect",      # 输出根目录name="test",                # 子目录名exist_ok=True               # 若已存在则复用
)# 内嵌显示第一张结果
display(Image.fromarray(results[0].plot()))
print("结果保存到:", results[0].save_dir)

在这里插入图片描述

七、训练与导出速览 & 设备选择

适合“在 Notebook 里快速跑通训练→导出”，并清晰地指定在 CPU / GPU 上运行。

训练与导出（最小可用）

适合你只需要训练完把权重给其它项目。

from ultralytics import YOLO# 1) 选择基础模型（可换成 yolov8s/yolov8m 等）
model = YOLO(str(MODELS_DIR / "yolov8n.pt"))# 2) 官方演示集训练
model.train(data="coco128.yaml", epochs=1, imgsz=640, device="cpu")# 3) 导出（例如导出为 ONNX，便于集成到其它项目/C++/推理引擎）
model.export(format="onnx", dynamic=False)

在这里插入图片描述

训练与导出（稳健增强）

# ==== 训练 -> 导出（稳健增强版）====
from pathlib import Path
from datetime import datetime
from ultralytics import YOLO
import torch# -------- 0) 路径兜底 --------
MODELS_DIR = Path("models"); MODELS_DIR.mkdir(parents=True, exist_ok=True)
RUNS_DIR   = Path("runs");   RUNS_DIR.mkdir(parents=True, exist_ok=True)# -------- 1) 自动设备选择（CUDA/MPS/CPU）--------
def auto_device():if torch.cuda.is_available():return 0  # 或 "cuda:0"if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():return "mps"return "cpu"DEVICE = auto_device()
print("device:", DEVICE)# （可选）固定随机性，提升复现性
SEED = 42
try:import random, numpy as nptorch.manual_seed(SEED)random.seed(SEED)np.random.seed(SEED)if torch.cuda.is_available():torch.cuda.manual_seed_all(SEED)
except Exception as _:pass# -------- 2) 选择基础模型（不存在会自动下载）--------
model = YOLO(str(MODELS_DIR / "yolov8n.pt"))# 运行名加时间戳，避免覆盖
run_name = f"quickstart_{datetime.now().strftime('%Y%m%d_%H%M%S')}"# -------- 3) 训练（coco128 验证流程可跑）--------
model.train(data="coco128.yaml",epochs=1,imgsz=640,batch=8,workers=0,          # Windows 建议 0device=DEVICE,project=str(RUNS_DIR / "train"),name=run_name,exist_ok=True,seed=SEED,plots=True          # 保存训练曲线 results.png/csv
)# 训练输出的 best.pt 路径（优先导出它）
best_pt = RUNS_DIR / "train" / run_name / "weights" / "best.pt"
export_source = str(best_pt if best_pt.exists() else (MODELS_DIR / "yolov8n.pt"))
print("export source:", export_source)# -------- 4) 导出 ONNX（自动探测 onnx/onnxsim）--------
def export_onnx(weights_path: str):try:import onnx          # 必需：ONNX 格式支持except ModuleNotFoundError:print("[export] 未安装 onnx，跳过导出。请先安装：pip install onnx onnxruntime")return None# 是否启用 simplify（若装了 onnxsim 则自动开启）try:import onnxsim       # noqa: F401simplify = Trueexcept ModuleNotFoundError:simplify = Falseret = YOLO(weights_path).export(format="onnx",dynamic=False,simplify=simplify,opset=None  # 让框架选择推荐 opset；需要特定版本可自行指定，如 16/17)# 兼容不同返回类型：str/Path 或 list/tupledef pick_onnx_path(x):if isinstance(x, (list, tuple)):for item in x:s = str(item)if s.lower().endswith(".onnx"):return sreturn str(x[0]) if x else Nonereturn str(x)onnx_path = pick_onnx_path(ret)print("ONNX saved at:", onnx_path)return onnx_pathonnx_path = export_onnx(export_source)# -------- 5) （可选）onnxruntime 自检推理 --------
if onnx_path:try:import onnxruntime as ortimport numpy as npfrom PIL import Image# 准备一张 640x640 的输入（按需替换为你的图片路径）img_file = Path("data/images/bus.jpg")if img_file.exists():img = Image.open(img_file).convert("RGB").resize((640, 640))x = np.array(img).transpose(2,0,1)[None].astype(np.float32) / 255.0providers = ["CPUExecutionProvider"] if DEVICE == "cpu" else ["CUDAExecutionProvider","CPUExecutionProvider"]sess = ort.InferenceSession(onnx_path, providers=providers)inp = sess.get_inputs()[0].nameouts = sess.run(None, {inp: x})print("onnxruntime outputs shapes:", [o.shape for o in outs])else:print(f"[ort] 跳过自检：{img_file} 不存在。")except ModuleNotFoundError:print("[ort] 未安装 onnxruntime，自检推理已跳过。（可安装：pip install onnxruntime 或 onnxruntime-gpu）")

在这里插入图片描述

设备选择（device）参数

Ultralytics 在 预测 model(...)、训练 model.train(...)、验证/导出 等流程中均支持 device 参数，用于指定运算设备。

常用取值：

"cpu"：在 CPU 上运行；
0 / "0" / "cuda:0"：第 0 块 NVIDIA GPU；
"0,1" 或 [0,1]：多卡（主要用于训练）；
"mps"：Apple Silicon（macOS 的 Metal）。

自动选择（推荐）：

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

在预测中使用：

pred = model(source=str(img_path),save=True,project="runs/detect",name="test",exist_ok=True,device=DEVICE
)

在训练中使用：

model.train(data="coco128.yaml",epochs=1,imgsz=640,device=DEVICE,workers=0  # Windows 建议 0，避免多进程问题
)

自检（务必先确认）：

import torch
print("cuda available:", torch.cuda.is_available())
if torch.cuda.is_available():print("cuda version:", torch.version.cuda)print("gpu:", torch.cuda.get_device_name(0))

提醒：若安装的是 CPU 版 PyTorch，torch.cuda.is_available() 会是 False，此时填 device=0 不会生效；需要按 CUDA 版本重新安装匹配的 PyTorch 轮子。

八、常见问题与排错

下面按“症状 → 原因 → 解决办法”的格式整理，优先覆盖你已遇到/可能会遇到的情况。

1) `AttributeError: 'list' object has no attribute 'show'`

症状：results = model(img) 后调用 results.show() 报错。

原因：Ultralytics 返回 list（一次可处理多张图）。

解决：取第 1 个元素再显示，或用内嵌显示。

# GUI 弹窗（不稳定）
results[0].show()# Notebook 内嵌显示（推荐）
from PIL import Image
display(Image.fromarray(results[0].plot()))

2) 推理结果没有保存 / 找不到保存目录

症状：跑完没有在期望目录看到图片。

原因：未开启保存或目录与想象不一致。

解决：推理时显式指定保存参数，并打印实际保存目录。

results = model(source=str(img_path), save=True,project="runs/detect", name="test", exist_ok=True
)
print("Saved to:", results[0].save_dir)  # 以此为准

3) `FileNotFoundError: '.../data.yaml' does not exist`

症状：训练启动前直接报找不到 data.yaml。

原因：数据集配置路径错误/不存在；或使用了占位路径。

解决：

使用 绝对路径 + 正斜杠（Windows 也推荐 /）。
或者直接传 dict 而非 yaml 文件。

# A. 写 yaml（示例）
"""
path: C:/Users/25526/PyCharmMiscProject/datasets/mydata
train: images/train
val: images/val
names: [class0, class1]
"""# B. 直接传 dict（不依赖文件）
data_cfg = {"path": "C:/Users/25526/PyCharmMiscProject/datasets/mydata","train": "images/train","val": "images/val","names": ["class0", "class1"],
}
model.train(data=data_cfg, workers=0, device="cpu")

还需确保 images/* 与 labels/* 一一对应同名，标签是 YOLO 格式（相对坐标，class 从 0 开始）。

4) `ModuleNotFoundError: onnx`（导出 ONNX 时报）

原因：导出 ONNX 需要 onnx 包，未安装。

解决：

python -m pip install onnx
# 建议再装 onnxruntime 用于本机验证
python -m pip install onnxruntime

重新导出：

f, _ = model.export(format="onnx", simplify=False)
print(f)

5) 安装 `onnxsim` 报 Windows `Long Path`（WinError 3）

症状：安装时在很深的临时路径报错。

原因：系统未启用“长路径”，源码构建路径过长。

解决（三选一）：

启用长路径：
- 组策略：计算机配置→管理模板→系统→文件系统→启用 Win32 长路径，重启；
- 或注册表：HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled=1，重启。
改短临时目录：

mkdir C:\piptemp
setx TMP C:\piptemp
setx TEMP C:\piptemp

重开终端后再执行：

python -m pip install --no-cache-dir --prefer-binary onnxsim

暂时跳过简化：导出时 simplify=False，等需要再处理。

6) CPU / CUDA 轮子混装导致环境混乱

症状：torch.cuda.is_available() 返回异常；或导入冲突。

原因：同一环境里先后安装了 CPU 版和 CUDA 版 PyTorch。

解决：

最干净：重建 venv 并只安装一种；
或卸载后重装：

python -m pip uninstall -y torch torchvision torchaudio
# 再按 CPU 或 CUDA 二选一的官方命令重装

7) 机器有 GPU 但 `CUDA Available: False`

原因：装了 CPU 轮子；或 CUDA/驱动不匹配。

排查：

import torch
print(torch.__version__, torch.version.cuda)

若 torch.version.cuda is None → 安装的是 CPU 版。
若有 CUDA 版本仍为 False → 更新 NVIDIA 驱动/Toolkit，换与驱动匹配的 PyTorch 轮子（例如 --index-url ... cu121）。

8) Notebook 中 `show()` 不弹窗

原因：cv2.imshow 在 Notebook/某些 IDE 中不可用。

解决：改用内嵌显示。

from PIL import Image
display(Image.fromarray(results[0].plot()))

9) DataLoader 在 Windows 卡住 / 报多进程错误

原因：Windows 的多进程行为与 Linux 不同。

解决：把 workers=0。

model.train(..., workers=0)

10) 下载超时 / 连接慢

建议：

仅对 非 PyTorch 轮子 的包可换镜像（PyTorch 仍用官方 --index-url）。
遇到超时可重试：--timeout 60 --retries 5 --no-cache-dir。

11) 中文或空格路径导致的问题

症状：某些工具链对非 ASCII/含空格路径兼容性差。

解决：优先使用英文、无空格目录；代码中用：

from pathlib import Path
p = Path("你的路径").resolve().as_posix()  # 统一为正斜杠

12) 训练时报：标签缺失 / 数量不匹配 / `not enough values to unpack`

原因：images/train 与 labels/train 文件名未一一对应，或标签格式不符合 YOLO 规范。

解决：

确保 xxx.jpg 对应 xxx.txt；
标签每行：class x_center y_center width height，值均为 0~1 的相对坐标；
先用少量样本快速验证目录结构正确。

13) 导出 ONNX 后在 onnxruntime 运行失败 / opset 不兼容

原因：opset 版本或自定义算子不被当前 onnxruntime 支持。

解决：

指定/降低 opset（示例）：

f, _ = model.export(format="onnx", opset=16, simplify=False)

更新 onnx/onnxruntime；或改用 TorchScript：

ts, _ = model.export(format="torchscript")

14) CPU 训练内存/速度压力大

建议：

减小 imgsz、batch；
缩短 epochs 做功能验证；
关闭不必要的增强；
使用更小的模型（如 yolov8n）。

15) `ImportError: DLL load failed`（导入 torch/onnxruntime 失败）

症状：ImportError: DLL load failed while importing ...。

原因：缺少依赖运行库（常见：Microsoft Visual C++ Redistributable 2015–2022 x64），或 32/64 位不匹配，或与旧版 DLL 冲突。

解决：

安装/修复 VC++ 运行库（x64），并重启；
保证 Python、依赖均为 64 位；
避免 CPU/GPU 轮子混装，必要时重建 venv 并仅装一种；
重新安装报错包：python -m pip install --force-reinstall onnxruntime（或 torch）。

16) `ModuleNotFoundError: cv2` / `OSError: cannot identify image file`

原因：OpenCV 未安装；或 Pillow 无法识别图片/路径包含中文与空格导致 IO 失败。

解决：

python -m pip install opencv-python -U
python -m pip install pillow -U

路径尽量使用英文与正斜杠：

from pathlib import Path
p = Path('data/images/bus.jpg').resolve().as_posix()

快速验证图片：

from PIL import Image
Image.open(p).verify()

17) `UnicodeDecodeError: 'gbk' ...` 读取 YAML/文本时报

原因：Windows 默认编码为 GBK，文件实际是 UTF-8 或含特殊字符。

解决：

将文件另存为 UTF-8；
代码读取时指定编码：open(path, 'r', encoding='utf-8')；
YAML 中避免 BOM 与非 ASCII 键名。

18) Notebook 使用了错误的解释器/内核

症状：明明已安装的包在 Notebook 里 import 失败。

解决：

右上角核选择器切换到当前项目的 .venv；
在 Notebook 里打印可执行路径确认：

import sys; print(sys.executable)

若不一致，改用该解释器的 pip：<上面路径> -m pip install 包名。

19) `PermissionError: [WinError 5]` 保存失败

原因：写入系统受保护目录（如 C:/Program Files）或无权限。

解决：

输出目录改到用户工程（例如 runs/）；
必要时以管理员身份运行 PyCharm；
避免把项目放在系统盘受限目录下。

20) 训练提示 `Found 0 images` / `images not found` / `labels missing`

原因：YAML 中路径不对、扩展名不匹配、或图片与标签未一一对应。

解决：

使用 绝对路径 + 正斜杠；
确认 images/train 与 labels/train 下文件名一一对应（a.jpg ↔ a.txt）；
允许的扩展名：.jpg/.jpeg/.png/.bmp；
先用少量样本验证目录结构。

21) `DataLoader worker exited unexpectedly` / `BrokenPipeError`

原因：Windows 多进程兼容性与数据集问题。

解决：

model.train(..., workers=0)

排查是否存在损坏图片；
如使用自定义 collate_fn/增强，逐步回退定位。

22) `yolo` 命令不可用（CLI 报“不是内部或外部命令”）

原因：Scripts 未入 PATH 或安装在别的解释器里。

解决：

在当前解释器下使用：python -m ultralytics；
或把当前 venv 的 Scripts 目录加入 PATH；
确认 pip -V 与 python -V 指向同一解释器。

23) 标签格式错误：`Expected 5 values` / `labels outside [0,1]`

原因：YOLO 标签需 相对坐标（0~1），顺序为 class x_center y_center width height。

解决：

校验并转换标注；
确保 class 从 0 开始且小于类别数。

24) CUDA 相关错误（如 `cudnn error`、`no kernel image is available`）

场景：仅在使用 GPU 时。

解决：

确保安装与驱动匹配的 PyTorch 轮子（如 --index-url ... cu121）；
更新 NVIDIA 驱动与 CUDA Toolkit；
若短期无法解决，先切回 device="cpu" 验证流程。

25) ONNXRuntime 报 `no available execution provider` / `CUDAExecutionProvider` 不可用

原因：安装的是 CPU 版 onnxruntime，或 provider 不匹配。

解决：

CPU：providers=["CPUExecutionProvider"]；
GPU：安装 onnxruntime-gpu 并确认 CUDA 可用；

import onnxruntime as ort
sess = ort.InferenceSession(path, providers=["CPUExecutionProvider"])  # 或 CUDAExecutionProvider

九、附录

本附录用于快速上手与复现，包含两部分：①「命令速查」用于一键安装（区分 CPU / CUDA）；②「完整流程一键脚本」用于从下载到导出的一条龙验证。适合：新环境搭建和自检。

命令速查

# 升级 pip
python -m pip install --upgrade pip# CPU 版 PyTorch
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu# CUDA 12.1 版（示例）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121# YOLO
pip install ultralytics# 导出 ONNX 需要的依赖
#   - onnx        ：必须，有它才能导出 ONNX
#   - onnxruntime ：建议，导出后在本机验证 ONNX 推理
#   - onnxsim/onnxslim：可选，用于简化/瘦身 ONNX（export 时 simplify/optimize 会用到）
python -m pip install onnx onnxruntime onnxsim "onnxslim>=0.1.59"

完整流程一键脚本

一键完成：环境检查 → 路径准备 → 模型/图片下载 → 推理与保存 → 训练（coco128）→ 导出 ONNX。

# ==== 一键完成：下载模型与图片 -> 推理保存 -> 训练 -> 导出 ONNX ====
from pathlib import Path
from datetime import datetime
import requests
from ultralytics import YOLO
from PIL import Image
import torch
import sysprint(f"[env] python={sys.executable}")
print(f"[env] torch={torch.__version__}, cuda_available={torch.cuda.is_available()}")# ---------- 0) 设备选择（自动） ----------
def auto_device():# CUDA 优先，其次 Apple MPS，最后 CPUif torch.cuda.is_available():return 0  # 等价 "cuda:0"if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():return "mps"return "cpu"DEVICE = auto_device()
print("[env] device:", DEVICE)# （可选）固定随机种子，提升复现性
SEED = 42
try:import random, numpy as nptorch.manual_seed(SEED)random.seed(SEED)np.random.seed(SEED)if torch.cuda.is_available():torch.cuda.manual_seed_all(SEED)
except Exception:pass# ---------- 1) 统一目录 ----------
ROOT = Path.cwd()
MODELS_DIR = ROOT / "models"
DATA_DIR   = ROOT / "data" / "images"
RUNS_DIR   = ROOT / "runs"
MODELS_DIR.mkdir(parents=True, exist_ok=True)
DATA_DIR.mkdir(parents=True, exist_ok=True)
RUNS_DIR.mkdir(parents=True, exist_ok=True)# ---------- 2) 工具：若不存在则下载 ----------
def download_if_missing(url: str, dst: Path, timeout: int = 30):if dst.exists():print(f"[exists]  {dst.as_posix()}")returndst.parent.mkdir(parents=True, exist_ok=True)r = requests.get(url, timeout=timeout)r.raise_for_status()dst.write_bytes(r.content)print(f"[download] {dst.as_posix()}")# ---------- 3) 模型（不存在会自动下载到该路径） ----------
model_path = MODELS_DIR / "yolov8n.pt"
model = YOLO(str(model_path))
print("[model] file:", model_path.as_posix())# ---------- 4) 图片：下载到 data/images/ ----------
img_path = DATA_DIR / "bus.jpg"
download_if_missing("https://ultralytics.com/images/bus.jpg", img_path)# ---------- 5) 推理并保存（runs/detect/<timestamp>/） ----------
run_name = f"demo_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
pred = model(source=str(img_path),save=True,project=str(RUNS_DIR / "detect"),name=run_name,exist_ok=True,device=DEVICE
)# Notebook/IDE 显示（若在 Jupyter 可用 display(...)）
try:from IPython.display import display  # noqadisplay(Image.fromarray(pred[0].plot()))
except Exception:Image.fromarray(pred[0].plot()).show()print("[predict] saved to:", getattr(pred[0], "save_dir", "<unknown>"))# ---------- 6) 训练（coco128：验证流程是否可跑） ----------
# 若你想统一用自动设备，把 device=DEVICE；仅 CPU 训练则写 "cpu"
train_result = model.train(data="coco128.yaml",epochs=1,imgsz=640,batch=8,workers=0,               # Windows 建议 0，避免多进程问题device=DEVICE,           # ← 与上面保持一致project=str(RUNS_DIR / "train"),name=run_name,exist_ok=True,seed=SEED,plots=True               # 保存训练曲线 results.png/csv
)# ---------- 7) 选择导出权重（优先训练得到的 best.pt） ----------
best_pt = RUNS_DIR / "train" / run_name / "weights" / "best.pt"
export_source = str(best_pt if best_pt.exists() else model_path)
print("[export] source:", export_source)# ---------- 8) 导出 ONNX（兼容不同返回类型；自动探测 onnx/onnxsim） ----------
def export_onnx(weights_path: str):try:import onnx  # 必需except ModuleNotFoundError:print("[export] 未安装 onnx，跳过导出。请先安装：pip install onnx onnxruntime")return None# 若安装了 onnxsim 则自动简化try:import onnxsim  # noqasimplify = Trueexcept ModuleNotFoundError:simplify = Falseret = YOLO(weights_path).export(format="onnx",dynamic=False,simplify=simplify,opset=None  # 留空：由框架选择推荐 opset；如需固定可写 16/17)# 兼容返回值：str/Path 或 list/tupledef pick_onnx_path(x):if isinstance(x, (list, tuple)):for item in x:s = str(item)if s.lower().endswith(".onnx"):return sreturn str(x[0]) if x else Nonereturn str(x)onnx_path = pick_onnx_path(ret)print("[export] onnx saved at:", onnx_path)return onnx_pathonnx_path = export_onnx(export_source)# ---------- 9) （可选）onnxruntime 自检推理 ----------
if onnx_path:try:import onnxruntime as ortimport numpy as npimg = Image.open(img_path).convert("RGB").resize((640, 640))x = (np.array(img).transpose(2, 0, 1)[None].astype(np.float32)) / 255.0  # NCHW, [0,1]providers = ["CPUExecutionProvider"]if DEVICE != "cpu" and "cuda" in str(DEVICE):providers = ["CUDAExecutionProvider", "CPUExecutionProvider"]sess = ort.InferenceSession(onnx_path, providers=providers)inp = sess.get_inputs()[0].nameouts = sess.run(None, {inp: x})print("[ort] output shapes:", [o.shape for o in outs])except ModuleNotFoundError:print("[ort] 未安装 onnxruntime，自检推理已跳过。（可安装：pip install onnxruntime 或 onnxruntime-gpu）")