在 PyCharm Notebook 中安装 YOLO

在 PyCharm Notebook 中安装 YOLO

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

适用人群 & 前置条件

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

适用人群

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

必备条件

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

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

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（更快）

1. 检查驱动是否正常

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

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

2. 选择匹配的 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

3. 安装示例（以 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

4. 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 要不要装？

常见坑位 & 快速排错

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

python -m pip uninstall -y torch torchvision torchaudio

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

import sys; print(sys.executable)

一、创建 PyCharm Notebook 项目

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

二、安装依赖

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

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

1. 打开右下角解释器 → Python 软件包。
2. 依次搜索并安装：torch、torchvision、torchaudio、ultralytics、onnx、onnxruntime、onnxsim。
3. 注意：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) 相关扩展库
• 提供了很多跟图像任务相关的工具和数据。

主要内容：

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

作用场景：

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

3) torchaudio

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

主要内容：

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

作用场景：

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

4) ultralytics

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

主要内容：

1. 模型与权重：内置多种预训练权重（n/s/m/l/x），可自动下载与加载。
2. 高层 API：一行完成训练、评估、推理、导出；回调与日志管理。
3. 多后端导出：ONNX、TorchScript、OpenVINO、CoreML、TensorRT 等。
4. 数据接口：兼容 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") 导出时，此包 必装。

主要内容：

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

作用场景：

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

6) onnxruntime

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

主要内容：

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

作用场景：

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

7) onnxsim

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

主要内容：

1. 简化流程：加载 → 常量折叠/子图折叠 → 验证等价性 → 输出精简模型。
2. 用法：Python API 或命令行 onnxsim input.onnx output.onnx。
3. 与 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）")

十、结语

• 通过 PyCharm Notebook，你可以快速完成从 安装 → 验证 → 推理 → 导出 的全流程；
• 使用统一的 models/、data/、runs/ 结构，便于后续训练与结果管理；
• 如果要在其它项目使用模型，直接采用 model.export(...) 导出为 ONNX/torchscript/engine 等格式即可。