YOLO 这个系列可以说是目标检测领域里“最难绕开”的知识点。很多零基础的同学第一次接触深度学习第一个跑通的模型就是 YOLO第一个部署到嵌入式设备上的模型也是 YOLO。但问题在于网上的 YOLO 教程实在太多了有的讲网络结构有的讲训练技巧有的直接丢给你一个命令看完之后反而不知道怎么上手项目。这篇文章不打算带你从头推导边界框回归公式也不打算把 Backbone、Neck、Head 的每个细节都讲一遍。我准备按照“先跑通、再理解、后优化”的顺序把从环境搭建、模型推理、数据集标注、模型训练、模型导出到接口部署的完整流程梳理出来。文章会直接给出可复制的命令和代码也会把最容易踩的坑提前列出来。你不需要有很强的算法基础只要会打开终端、能装环境就可以跟着把 YOLO 项目跑起来。废话不多说直接开始。1. YOLO 核心能力速览先看一张速览表把 YOLO 最关键的几个信息放在前面。能力项说明项目类型目标检测算法系列同时覆盖实例分割、姿态估计、分类、旋转框检测等任务常见开源实现ultralytics 的 YOLOv5/YOLOv8/YOLO11、OpenMMLab 的 MMDetection 等不同版本功能和接口有差异核心功能图像与视频中的目标检测、实例分割、关键点检测、目标跟踪硬件门槛NVIDIA GPU 优先支持 CPU 推理CPU 推理速度较慢嵌入式设备可部署到瑞芯微、Jetson 等平台显存占用跟模型尺寸、输入分辨率、batch size 有关毫升级模型显存较低大模型高分辨率下显存需求明显增加需按实际环境测试支持平台Windows、Linux、macOS训练通常建议 Linux 环境启动方式命令行 CLI、Python SDK、Web 界面、Docker接口能力支持 PyTorch 模型导出为 ONNX、TensorRT、OpenVINO 等格式可以封装 HTTP API 服务批量任务支持批量图片推理、批量视频推理也可以自己写脚本做任务队列适合人群零基础入门者、算法工程师、嵌入式开发、AI 应用开发从这张表可以看到YOLO 并不是一个单独的模型而是一整套可以做训练、推理、部署的工程体系。所以零基础学 YOLO不应该只停留在“跑通预测”还要把训练、导出、部署这条链路走通才算真正上手项目。2. YOLO 目标检测原理与适用场景2.1 YOLO 到底解决什么问题YOLO 的全称是 You Only Look Once核心思路是把目标检测当成一个回归问题来处理。输入一张图片网络一次性输出所有目标的位置、类别和置信度。相比早期的两阶段检测算法YOLO 最大的优势是快结构上更直接工程落地更容易。YOLO 的基本原理可以概括为把输入图片划分成网格每个网格负责预测中心点落在该网格内的目标。每个预测结果包括目标边界框的位置信息、置信度以及多个类别的分类概率。再加上多尺度特征融合YOLO 能够兼顾不同尺寸的目标。零基础阶段你可以先不深究每个细节但有几个核心名词需要记住。Backbone负责提取图像特征。Neck负责融合不同尺度的特征。Head负责输出最终的类别和边界框。后续看网络结构图和训练日志都会反复用到这几个词。2.2 哪些场景适合用 YOLOYOLO 目标检测在实际项目中的覆盖面很广从公开热度较高的关键词也能看出来工业质检桥梁病害识别、道路积雪检测、裂缝识别、果实检测。安防与交通车辆检测、行人检测、车牌识别。生物与医学鱼类识别、细胞检测、毛发毛囊检测。移动端与嵌入式RK3588、Jetson、树莓派等设备上的实时检测。互动娱乐体感交互、游戏辅助中的目标识别这类场景要特别注意合规边界不能用于绕过安全限制或破坏游戏公平性。此外YOLO 也可以扩展到实例分割、姿态估计、旋转目标检测等领域。比如你想检测图片里每个物体的精确轮廓可以选 YOLOv8-seg想检测人体关键点可以选 YOLOv8-pose。2.3 适用边界与合规提醒YOLO 是一个通用的视觉检测工具但用在哪里、怎么用边界必须清楚。涉及人脸检测、行人检测、车辆识别等场景要注意肖像权、隐私保护不能在未授权的情况下收集和识别个人敏感信息。涉及版权图片、视频、游戏素材必须取得授权不能擅自用于商用或公开传播。涉及游戏辅助、自动瞄准等自动化脚本必须符合游戏平台规则本文不提供任何绕过检测、破坏公平性的实现。涉及工业检测、医学辅助诊断只能作为人工判断的辅助工具不能直接作为最终决策依据。使用任何 AI 模型前都要先确认数据来源合法、使用场景授权完整。3. YOLO 本地部署环境准备YOLO 的部署方式有很多种这里以目前社区最常用的 ultralytics 系列为例。它是把模型结构、训练、推理、导出封装好的 Python 包零基础入门非常合适。3.1 操作系统与硬件要求训练和推理建议使用 64 位 Windows 10/11、Ubuntu 18.04 或更高版本。Ubuntu 在环境兼容性上更好尤其后续要部署到 Docker 或嵌入式设备时建议优先使用 Linux。硬件方面NVIDIA 显卡是首选因为 GPU 能极大加速训练和推理。没有独立显卡也能跑CPU 模式可以验证整个流程但训练速度会明显变慢。显存建议至少 4GB8GB 以上体验更好实际占用取决于你选择的模型尺寸和输入分辨率。3.2 Python 与 CUDA 环境检查ultralytics 是基于 PyTorch 的所以第一步是安装好 Python 和 PyTorch。打开终端后先确认基本环境。python --version pip --version nvidia-smi看一下 Python 版本建议 3.8 到 3.12 之间。nvidia-smi可以查看显卡驱动和 CUDA 版本。PyTorch 的 CUDA 版本不需要和驱动显示的最高版本完全一致但驱动不能太老。3.3 创建独立的 Python 虚拟环境新手很容易犯的错误是把所有依赖都装到全局环境里后面项目多了会冲突。建议每一个 YOLO 项目使用一个独立的虚拟环境。# 创建虚拟环境 python -m venv yolo_env # Windows 激活 yolo_env\Scripts\activate # Linux / macOS 激活 source yolo_env/bin/activate激活后接下来的所有安装和训练命令都在这个环境内执行。3.4 安装 PyTorch 与 ultralytics在 PyTorch 官网根据自己的 CUDA 版本选择安装命令。这里给一个通用示例CPU 版本安装方式如下pip install torch torchvision torchaudio如果你有 NVIDIA GPU建议到 PyTorch 官网选择带 CUDA 的安装命令安装完成后可以用下面代码验证 GPU 是否可用。import torch print(torch.__version__) print(torch.cuda.is_available())然后安装 ultralytics。pip install ultralytics安装完成后可以查看版本。yolo version如果输出正常说明基本环境已经搭好。4. YOLO 模型启动与第一次推理环境装好后下一步就是跑一个推理看看效果。这是整个 YOLO 工程的第一个里程碑。4.1 通过命令行 CLI 快速推理ultralytics 提供了命令行工具最简单的推理方式是一条命令。yolo predict modelyolo11n.pt sourcehttps://ultralytics.com/images/bus.jpg第一次运行会自动下载模型权重到本地然后对示例图片进行检测推理。执行完成后终端会显示检测结果数量和耗时同时在runs/detect/predict目录下生成标注后的图片。如果你没有 GPU可以指定使用 CPU 推理。yolo predict modelyolo11n.pt sourcehttps://ultralytics.com/images/bus.jpg devicecpu换成本地图片或视频也很简单。yolo predict modelyolo11n.pt source./images/test.jpg # 检测视频 yolo predict modelyolo11n.pt source./videos/test.mp44.2 通过 Python SDK 推理CLI 适合快速体验Python SDK 适合集成到自己的项目里。新建一个predict.py文件内容如下from ultralytics import YOLO # 加载模型 model YOLO(yolo11n.pt) # 对图片进行推理 results model.predict(source./images/test.jpg, conf0.25, saveTrue) # 输出检测结果 for result in results: boxes result.boxes print(f检测到 {len(boxes)} 个目标) if boxes is not None: for box in boxes: print(box.cls, box.conf, box.xyxy)运行后观察终端输出python predict.pyconf0.25表示只保留置信度大于 0.25 的目标阈值可以根据项目需求调节调高可以过滤误检调低会召回更多目标。4.3 摄像头实时检测如果想要实时检测可以用摄像头作为输入源。yolo predict modelyolo11n.pt source0 showTruesource0表示默认摄像头。这个功能在视频流处理、边缘设备调试时很常见。4.4 验证是否成功的标准第一次推理是否成功可以参考以下两个标准终端没有报错并且输出了类似Speed: 5.0ms preprocess, 20.0ms inference, 2.0ms postprocess的信息。在runs/detect/predict目录下生成了带检测框的结果图检测框位置和类别基本合理。5. YOLO 数据集准备与标注训练自己的模型需要先准备数据集。这一步决定了模型效果的上限。5.1 数据集的目录结构ultralytics 要求数据集按图片和标签分目录存放训练集、验证集分开。dataset/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── data.yaml图片与对应的标注文件放在相同子目录中文件名保持一致。标注文件是.txt格式每行内容为类别id x_center y_center width height坐标统一使用归一化后的值范围在 0 到 1 之间。5.2 使用标注工具标注图片常用的开源标注工具有 LabelImg、Label Studio、X-AnyLabeling 等。标注时要遵循同一套规则一个目标只用一个框框要贴合目标边缘。遮挡严重的目标可以标注出来但要看数据集用途决定是否保留。类别定义要统一不要在一个项目中混合不同语义的类别。标注完成后把生成的.txt文件保存到对应的labels目录中。5.3 编写 data.yamldata.yaml是训练时的数据配置文件。path: ./dataset train: images/train val: images/val names: 0: person 1: car 2: dognames中的类别顺序要和标注文件中的类别 id 一致。如果训练时报Dataset not found优先检查path路径是否正确。5.4 训练集与验证集划分训练集负责让模型学到特征验证集负责评估模型效果。建议训练集和验证集按 8:2 或 9:1 划分。划分时先打乱图片顺序避免同一条视频里的连续帧全部进入训练集导致验证结果虚高。6. YOLO 模型训练全流程6.1 使用预训练权重从零开始训练 YOLO 网络通常需要大量数据和很长时间新手不建议这么做。更好的方式是加载 COCO 数据集上的预训练权重然后基于自己的数据微调。yolo detect train data./dataset/data.yaml modelyolo11n.pt epochs100 imgsz640 batch16 device0各参数含义如下参数作用model指定预训练权重也可以传入模型配置文件data数据配置文件路径epochs训练轮数imgsz输入图片尺寸一般 640 起步batch单次训练的图片数量显存不足时减小device0表示使用第一个 GPUcpu表示使用 CPU如果显存不够可以减少batch或imgsz。例如yolo detect train data./dataset/data.yaml modelyolo11n.pt epochs50 imgsz416 batch86.2 训练过程观察什么训练时终端会持续打印指标box_loss边界框回归损失。cls_loss分类损失。df1_loss分布焦点损失。mAP50、mAP50-95模型检测精度的核心指标。mAP50-95是更严格的指标一般越高越好。刚开始训练时指标会偏低多跑几个 epoch 后逐渐上升。6.3 训练完成后验证模型训练结束后模型权重保存在runs/detect/train/weights/best.pt。用验证集测试效果yolo val modelruns/detect/train/weights/best.pt data./dataset/data.yaml看一下验证输出的mAP50和mAP50-95。如果指标过低先检查数据是否标注正确、类别是否均衡。6.4 训练常见失败原因训练指标全为 0是最常见的问题通常由锚框计算失败、标签格式错误或data.yaml路径错误引起。排查顺序是先确认标签文件内容非空再确认类别 id 是否在names范围内最后看训练日志中是否有WARNING提示。训练一开始统计的参数量和最后训练完得到的参数量不一致这种情况通常是启用了分布式训练或中途修改了模型结构一般不影响正常训练。7. YOLO 模型导出与接口 API 部署模型训练完不能只停留在本地测试下一步是接入业务系统或部署到服务器。7.1 导出为 ONNX 格式ONNX 是通用的模型交换格式方便部署到不支持 PyTorch 的环境中。yolo export modelruns/detect/train/weights/best.pt formatonnx imgsz640导出成功后目录下会出现best.onnx文件。ONNX 模型可以在 ONNX Runtime 中加载也可以转换到 TensorRT 或 OpenVINO。如果你需要在嵌入式设备上运行比如瑞芯微 RK3588通常需要先导出 ONNX再转换成 RKNN 格式。yolo export modelbest.pt formatonnx opset12 imgsz6407.2 用 Flask 封装 HTTP 接口ONNX 只是模型文件还需要服务包装。下面是一个简单的 Flask 推理服务示例新人可以直接参考。from flask import Flask, request, jsonify from ultralytics import YOLO import os app Flask(__name__) model YOLO(best.pt) app.route(/detect, methods[POST]) def detect(): file request.files.get(image) if file is None: return jsonify({error: no image}), 400 path ./tmp.jpg file.save(path) results model.predict(sourcepath, conf0.25) boxes results[0].boxes output [] if boxes is not None: for box in boxes: output.append({ class: int(box.cls[0]), conf: float(box.conf[0]), box: box.xyxy[0].tolist() }) os.remove(path) return jsonify({detections: output}) if __name__ __main__: app.run(host0.0.0.0, port8000)启动服务python app.py然后在另一个终端里调用接口测试import requests url http://127.0.0.1:8000/detect files {image: open(./test.jpg, rb)} response requests.post(url, filesfiles, timeout30) print(response.json())需要注意这只是功能验证示例。正式对外提供服务时要考虑接口鉴权、请求大小限制、模型并发加载、服务日志等问题。7.3 批量任务处理思路YOLO 本身支持批量预测可以一次传入多张图片yolo predict modelbest.pt source./images/ batch4如果你需要处理大量图片或视频建议写一个任务队列把待处理文件放入目录脚本循环扫描并处理处理结果写入输出目录并记录日志。import glob from ultralytics import YOLO model YOLO(best.pt) image_list glob.glob(./inputs/*.jpg) for image_path in image_list: model.predict(sourceimage_path, saveTrue) print(fprocessed: {image_path})批量任务的核心不是代码多复杂而是可观测、可恢复。每条任务必须有日志失败的任务要能记录并重新执行。8. 资源占用与性能观察8.1 显存占用观察方式训练和推理过程中可以用nvidia-smi实时查看显卡占用。nvidia-smi在 PyTorch 代码里也可以打印当前显存占用import torch print(torch.cuda.memory_allocated() / 1024**2, MB) print(torch.cuda.memory_reserved() / 1024**2, MB)显存占用会随 batch size、输入分辨率、模型尺寸变化。如果推理或训练时出现CUDA out of memory错误优先把 batch 调小或者把imgsz从 640 降到 416/320。8.2 CPU 推理与 GPU 推理的差异YOLO 支持 CPU 推理零基础在没有 GPU 的机器上也可以完成功能验证。但 CPU 推理速度通常远低于 GPU特别是高分辨率输入和大模型。有网友反馈遇到过 CPU 多进程推理单张图片约 1.4 秒的情况这个数值会随机器性能和模型版本变化但整体趋势具有参考意义。CPU 推理更适合模型效果验证、小型批量任务实时摄像头检测建议使用 GPU 或嵌入式 NPU。8.3 影响性能的关键参数imgsz输入分辨率越高检测小目标能力越强但显存占用和推理耗时上升。batch批量数越大GPU 利用率越高但显存占用线性上升。conf置信度阈值越低输出框越多后处理耗时上升。device模型运算是跑在 GPU 还是 CPU。9. YOLO 常见问题与排查方法零基础上手 YOLO环境和训练阶段的问题最多。下面列出几个高频问题。问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named ultralytics依赖没有安装到当前虚拟环境检查当前环境python -c import ultralytics激活正确环境后重新安装推理时提示缺少模型文件权重文件路径错误或未下载查看终端日志中的下载/加载路径重新指定model路径CUDA out of memory显存不足nvidia-smi查看显存占用调小batch、imgsz或换更小的模型训练时 mAP 全为 0标签文件为空、类别 id 越界检查labels目录和data.yaml修正标签文件核对类别 id页面或服务端口打不开端口被占用或服务未启动检查终端日志查看端口占用换端口或重启服务视频检测很慢CPU 推理且分辨率高看推理日志中的单帧耗时降低imgsz改用 GPU 部署导出 ONNX 失败PyTorch 版本与 opset 不兼容查看导出报错日志升级或降级 PyTorch调整opset检测框重叠严重conf 阈值过低或 NMS 参数不合理打印结果中的置信度分布提高conf阈值或调整 NMS 参数排查问题的大原则是先看日志再确认路径和环境最后检查数据。很多人卡在“训练没效果”基本都是数据标注或路径问题不是模型问题。10. YOLO 最佳实践与使用建议10.1 先跑通最小流程不要一上来就追求高精度。第一次项目尝试建议用 YOLO 自带的预训练权重跑通推理然后再用一小批数据训练 10 到 20 个 epoch验证训练流程是否正常。这样可以把“环境问题”和“算法问题”分开。10.2 数据质量优先于模型大小同一个模型数据标注质量差和标注质量好最终 mAP 可能差很多。标注时尽可能保证框贴合目标、类别统一、正负样本均衡。训练前检查一遍标签文件确认没有空标签。10.3 管理好模型、数据和输出目录我建议项目目录按以下结构组织project/ ├── dataset/ │ ├── images/ │ ├── labels/ │ └── data.yaml ├── models/ ├── runs/ ├── scripts/ └── outputs/模型权重、训练日志、输出结果分开存放方便后续回溯实验。10.4 批量任务要做日志和失败重试批量处理大量图片或视频时不能只跑一个for循环不管结果。每处理一张图片记录一行日志处理完成后统计成功数量和失败数量。如果任务中断能快速定位到失败文件。10.5 接口服务要控制访问范围部署 API 服务后不要直接暴露到公网至少加上 token 鉴权和 IP 白名单。模型文件本身可能包含业务敏感信息也要限制下载和访问权限。11. 总结与下一步YOLO 学习真正有用的起点不是背网络结构图而是先把“推理、训练、导出、部署”这条链路跑通。第一次推理成功你就知道模型输入输出长什么样第一次训练完你就能理解数据集、标注和 mAP 的关系第一次导出 ONNX 并封装接口你才真正具备把 YOLO 接入实际项目的能力。这篇内容里最容易踩的坑有三个一是环境没配对安装版本混乱二是数据集格式和data.yaml不对训练指标全为 0三是显存不足还强行开大分辨率导致训练中断。这三个问题只要能提前规避你的 YOLO 项目进度会快很多。下一步可以做的事选一个你熟悉的业务场景拍 100 到 300 张图片完成标注、训练和验证。用yolo export把模型导出成 ONNX再研究 TensorRT 或 OpenVINO 加速。尝试换主干网络或检测头观察精度和速度的变化。如果想上嵌入式设备可以研究 RK3588、Jetson 平台的部署流程并注意不同平台算子兼容性问题。从零基础到能自己训练和部署模型最合理的路径就是“先跑通、再训练、后部署”。先别纠结原理细节动手把流程走通再回头补理论理解速度会快很多。 YOLO目标检测从零上手：环境搭建、训练部署全流程指南
YOLO 这个系列可以说是目标检测领域里“最难绕开”的知识点。很多零基础的同学第一次接触深度学习第一个跑通的模型就是 YOLO第一个部署到嵌入式设备上的模型也是 YOLO。但问题在于网上的 YOLO 教程实在太多了有的讲网络结构有的讲训练技巧有的直接丢给你一个命令看完之后反而不知道怎么上手项目。这篇文章不打算带你从头推导边界框回归公式也不打算把 Backbone、Neck、Head 的每个细节都讲一遍。我准备按照“先跑通、再理解、后优化”的顺序把从环境搭建、模型推理、数据集标注、模型训练、模型导出到接口部署的完整流程梳理出来。文章会直接给出可复制的命令和代码也会把最容易踩的坑提前列出来。你不需要有很强的算法基础只要会打开终端、能装环境就可以跟着把 YOLO 项目跑起来。废话不多说直接开始。1. YOLO 核心能力速览先看一张速览表把 YOLO 最关键的几个信息放在前面。能力项说明项目类型目标检测算法系列同时覆盖实例分割、姿态估计、分类、旋转框检测等任务常见开源实现ultralytics 的 YOLOv5/YOLOv8/YOLO11、OpenMMLab 的 MMDetection 等不同版本功能和接口有差异核心功能图像与视频中的目标检测、实例分割、关键点检测、目标跟踪硬件门槛NVIDIA GPU 优先支持 CPU 推理CPU 推理速度较慢嵌入式设备可部署到瑞芯微、Jetson 等平台显存占用跟模型尺寸、输入分辨率、batch size 有关毫升级模型显存较低大模型高分辨率下显存需求明显增加需按实际环境测试支持平台Windows、Linux、macOS训练通常建议 Linux 环境启动方式命令行 CLI、Python SDK、Web 界面、Docker接口能力支持 PyTorch 模型导出为 ONNX、TensorRT、OpenVINO 等格式可以封装 HTTP API 服务批量任务支持批量图片推理、批量视频推理也可以自己写脚本做任务队列适合人群零基础入门者、算法工程师、嵌入式开发、AI 应用开发从这张表可以看到YOLO 并不是一个单独的模型而是一整套可以做训练、推理、部署的工程体系。所以零基础学 YOLO不应该只停留在“跑通预测”还要把训练、导出、部署这条链路走通才算真正上手项目。2. YOLO 目标检测原理与适用场景2.1 YOLO 到底解决什么问题YOLO 的全称是 You Only Look Once核心思路是把目标检测当成一个回归问题来处理。输入一张图片网络一次性输出所有目标的位置、类别和置信度。相比早期的两阶段检测算法YOLO 最大的优势是快结构上更直接工程落地更容易。YOLO 的基本原理可以概括为把输入图片划分成网格每个网格负责预测中心点落在该网格内的目标。每个预测结果包括目标边界框的位置信息、置信度以及多个类别的分类概率。再加上多尺度特征融合YOLO 能够兼顾不同尺寸的目标。零基础阶段你可以先不深究每个细节但有几个核心名词需要记住。Backbone负责提取图像特征。Neck负责融合不同尺度的特征。Head负责输出最终的类别和边界框。后续看网络结构图和训练日志都会反复用到这几个词。2.2 哪些场景适合用 YOLOYOLO 目标检测在实际项目中的覆盖面很广从公开热度较高的关键词也能看出来工业质检桥梁病害识别、道路积雪检测、裂缝识别、果实检测。安防与交通车辆检测、行人检测、车牌识别。生物与医学鱼类识别、细胞检测、毛发毛囊检测。移动端与嵌入式RK3588、Jetson、树莓派等设备上的实时检测。互动娱乐体感交互、游戏辅助中的目标识别这类场景要特别注意合规边界不能用于绕过安全限制或破坏游戏公平性。此外YOLO 也可以扩展到实例分割、姿态估计、旋转目标检测等领域。比如你想检测图片里每个物体的精确轮廓可以选 YOLOv8-seg想检测人体关键点可以选 YOLOv8-pose。2.3 适用边界与合规提醒YOLO 是一个通用的视觉检测工具但用在哪里、怎么用边界必须清楚。涉及人脸检测、行人检测、车辆识别等场景要注意肖像权、隐私保护不能在未授权的情况下收集和识别个人敏感信息。涉及版权图片、视频、游戏素材必须取得授权不能擅自用于商用或公开传播。涉及游戏辅助、自动瞄准等自动化脚本必须符合游戏平台规则本文不提供任何绕过检测、破坏公平性的实现。涉及工业检测、医学辅助诊断只能作为人工判断的辅助工具不能直接作为最终决策依据。使用任何 AI 模型前都要先确认数据来源合法、使用场景授权完整。3. YOLO 本地部署环境准备YOLO 的部署方式有很多种这里以目前社区最常用的 ultralytics 系列为例。它是把模型结构、训练、推理、导出封装好的 Python 包零基础入门非常合适。3.1 操作系统与硬件要求训练和推理建议使用 64 位 Windows 10/11、Ubuntu 18.04 或更高版本。Ubuntu 在环境兼容性上更好尤其后续要部署到 Docker 或嵌入式设备时建议优先使用 Linux。硬件方面NVIDIA 显卡是首选因为 GPU 能极大加速训练和推理。没有独立显卡也能跑CPU 模式可以验证整个流程但训练速度会明显变慢。显存建议至少 4GB8GB 以上体验更好实际占用取决于你选择的模型尺寸和输入分辨率。3.2 Python 与 CUDA 环境检查ultralytics 是基于 PyTorch 的所以第一步是安装好 Python 和 PyTorch。打开终端后先确认基本环境。python --version pip --version nvidia-smi看一下 Python 版本建议 3.8 到 3.12 之间。nvidia-smi可以查看显卡驱动和 CUDA 版本。PyTorch 的 CUDA 版本不需要和驱动显示的最高版本完全一致但驱动不能太老。3.3 创建独立的 Python 虚拟环境新手很容易犯的错误是把所有依赖都装到全局环境里后面项目多了会冲突。建议每一个 YOLO 项目使用一个独立的虚拟环境。# 创建虚拟环境 python -m venv yolo_env # Windows 激活 yolo_env\Scripts\activate # Linux / macOS 激活 source yolo_env/bin/activate激活后接下来的所有安装和训练命令都在这个环境内执行。3.4 安装 PyTorch 与 ultralytics在 PyTorch 官网根据自己的 CUDA 版本选择安装命令。这里给一个通用示例CPU 版本安装方式如下pip install torch torchvision torchaudio如果你有 NVIDIA GPU建议到 PyTorch 官网选择带 CUDA 的安装命令安装完成后可以用下面代码验证 GPU 是否可用。import torch print(torch.__version__) print(torch.cuda.is_available())然后安装 ultralytics。pip install ultralytics安装完成后可以查看版本。yolo version如果输出正常说明基本环境已经搭好。4. YOLO 模型启动与第一次推理环境装好后下一步就是跑一个推理看看效果。这是整个 YOLO 工程的第一个里程碑。4.1 通过命令行 CLI 快速推理ultralytics 提供了命令行工具最简单的推理方式是一条命令。yolo predict modelyolo11n.pt sourcehttps://ultralytics.com/images/bus.jpg第一次运行会自动下载模型权重到本地然后对示例图片进行检测推理。执行完成后终端会显示检测结果数量和耗时同时在runs/detect/predict目录下生成标注后的图片。如果你没有 GPU可以指定使用 CPU 推理。yolo predict modelyolo11n.pt sourcehttps://ultralytics.com/images/bus.jpg devicecpu换成本地图片或视频也很简单。yolo predict modelyolo11n.pt source./images/test.jpg # 检测视频 yolo predict modelyolo11n.pt source./videos/test.mp44.2 通过 Python SDK 推理CLI 适合快速体验Python SDK 适合集成到自己的项目里。新建一个predict.py文件内容如下from ultralytics import YOLO # 加载模型 model YOLO(yolo11n.pt) # 对图片进行推理 results model.predict(source./images/test.jpg, conf0.25, saveTrue) # 输出检测结果 for result in results: boxes result.boxes print(f检测到 {len(boxes)} 个目标) if boxes is not None: for box in boxes: print(box.cls, box.conf, box.xyxy)运行后观察终端输出python predict.pyconf0.25表示只保留置信度大于 0.25 的目标阈值可以根据项目需求调节调高可以过滤误检调低会召回更多目标。4.3 摄像头实时检测如果想要实时检测可以用摄像头作为输入源。yolo predict modelyolo11n.pt source0 showTruesource0表示默认摄像头。这个功能在视频流处理、边缘设备调试时很常见。4.4 验证是否成功的标准第一次推理是否成功可以参考以下两个标准终端没有报错并且输出了类似Speed: 5.0ms preprocess, 20.0ms inference, 2.0ms postprocess的信息。在runs/detect/predict目录下生成了带检测框的结果图检测框位置和类别基本合理。5. YOLO 数据集准备与标注训练自己的模型需要先准备数据集。这一步决定了模型效果的上限。5.1 数据集的目录结构ultralytics 要求数据集按图片和标签分目录存放训练集、验证集分开。dataset/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── data.yaml图片与对应的标注文件放在相同子目录中文件名保持一致。标注文件是.txt格式每行内容为类别id x_center y_center width height坐标统一使用归一化后的值范围在 0 到 1 之间。5.2 使用标注工具标注图片常用的开源标注工具有 LabelImg、Label Studio、X-AnyLabeling 等。标注时要遵循同一套规则一个目标只用一个框框要贴合目标边缘。遮挡严重的目标可以标注出来但要看数据集用途决定是否保留。类别定义要统一不要在一个项目中混合不同语义的类别。标注完成后把生成的.txt文件保存到对应的labels目录中。5.3 编写 data.yamldata.yaml是训练时的数据配置文件。path: ./dataset train: images/train val: images/val names: 0: person 1: car 2: dognames中的类别顺序要和标注文件中的类别 id 一致。如果训练时报Dataset not found优先检查path路径是否正确。5.4 训练集与验证集划分训练集负责让模型学到特征验证集负责评估模型效果。建议训练集和验证集按 8:2 或 9:1 划分。划分时先打乱图片顺序避免同一条视频里的连续帧全部进入训练集导致验证结果虚高。6. YOLO 模型训练全流程6.1 使用预训练权重从零开始训练 YOLO 网络通常需要大量数据和很长时间新手不建议这么做。更好的方式是加载 COCO 数据集上的预训练权重然后基于自己的数据微调。yolo detect train data./dataset/data.yaml modelyolo11n.pt epochs100 imgsz640 batch16 device0各参数含义如下参数作用model指定预训练权重也可以传入模型配置文件data数据配置文件路径epochs训练轮数imgsz输入图片尺寸一般 640 起步batch单次训练的图片数量显存不足时减小device0表示使用第一个 GPUcpu表示使用 CPU如果显存不够可以减少batch或imgsz。例如yolo detect train data./dataset/data.yaml modelyolo11n.pt epochs50 imgsz416 batch86.2 训练过程观察什么训练时终端会持续打印指标box_loss边界框回归损失。cls_loss分类损失。df1_loss分布焦点损失。mAP50、mAP50-95模型检测精度的核心指标。mAP50-95是更严格的指标一般越高越好。刚开始训练时指标会偏低多跑几个 epoch 后逐渐上升。6.3 训练完成后验证模型训练结束后模型权重保存在runs/detect/train/weights/best.pt。用验证集测试效果yolo val modelruns/detect/train/weights/best.pt data./dataset/data.yaml看一下验证输出的mAP50和mAP50-95。如果指标过低先检查数据是否标注正确、类别是否均衡。6.4 训练常见失败原因训练指标全为 0是最常见的问题通常由锚框计算失败、标签格式错误或data.yaml路径错误引起。排查顺序是先确认标签文件内容非空再确认类别 id 是否在names范围内最后看训练日志中是否有WARNING提示。训练一开始统计的参数量和最后训练完得到的参数量不一致这种情况通常是启用了分布式训练或中途修改了模型结构一般不影响正常训练。7. YOLO 模型导出与接口 API 部署模型训练完不能只停留在本地测试下一步是接入业务系统或部署到服务器。7.1 导出为 ONNX 格式ONNX 是通用的模型交换格式方便部署到不支持 PyTorch 的环境中。yolo export modelruns/detect/train/weights/best.pt formatonnx imgsz640导出成功后目录下会出现best.onnx文件。ONNX 模型可以在 ONNX Runtime 中加载也可以转换到 TensorRT 或 OpenVINO。如果你需要在嵌入式设备上运行比如瑞芯微 RK3588通常需要先导出 ONNX再转换成 RKNN 格式。yolo export modelbest.pt formatonnx opset12 imgsz6407.2 用 Flask 封装 HTTP 接口ONNX 只是模型文件还需要服务包装。下面是一个简单的 Flask 推理服务示例新人可以直接参考。from flask import Flask, request, jsonify from ultralytics import YOLO import os app Flask(__name__) model YOLO(best.pt) app.route(/detect, methods[POST]) def detect(): file request.files.get(image) if file is None: return jsonify({error: no image}), 400 path ./tmp.jpg file.save(path) results model.predict(sourcepath, conf0.25) boxes results[0].boxes output [] if boxes is not None: for box in boxes: output.append({ class: int(box.cls[0]), conf: float(box.conf[0]), box: box.xyxy[0].tolist() }) os.remove(path) return jsonify({detections: output}) if __name__ __main__: app.run(host0.0.0.0, port8000)启动服务python app.py然后在另一个终端里调用接口测试import requests url http://127.0.0.1:8000/detect files {image: open(./test.jpg, rb)} response requests.post(url, filesfiles, timeout30) print(response.json())需要注意这只是功能验证示例。正式对外提供服务时要考虑接口鉴权、请求大小限制、模型并发加载、服务日志等问题。7.3 批量任务处理思路YOLO 本身支持批量预测可以一次传入多张图片yolo predict modelbest.pt source./images/ batch4如果你需要处理大量图片或视频建议写一个任务队列把待处理文件放入目录脚本循环扫描并处理处理结果写入输出目录并记录日志。import glob from ultralytics import YOLO model YOLO(best.pt) image_list glob.glob(./inputs/*.jpg) for image_path in image_list: model.predict(sourceimage_path, saveTrue) print(fprocessed: {image_path})批量任务的核心不是代码多复杂而是可观测、可恢复。每条任务必须有日志失败的任务要能记录并重新执行。8. 资源占用与性能观察8.1 显存占用观察方式训练和推理过程中可以用nvidia-smi实时查看显卡占用。nvidia-smi在 PyTorch 代码里也可以打印当前显存占用import torch print(torch.cuda.memory_allocated() / 1024**2, MB) print(torch.cuda.memory_reserved() / 1024**2, MB)显存占用会随 batch size、输入分辨率、模型尺寸变化。如果推理或训练时出现CUDA out of memory错误优先把 batch 调小或者把imgsz从 640 降到 416/320。8.2 CPU 推理与 GPU 推理的差异YOLO 支持 CPU 推理零基础在没有 GPU 的机器上也可以完成功能验证。但 CPU 推理速度通常远低于 GPU特别是高分辨率输入和大模型。有网友反馈遇到过 CPU 多进程推理单张图片约 1.4 秒的情况这个数值会随机器性能和模型版本变化但整体趋势具有参考意义。CPU 推理更适合模型效果验证、小型批量任务实时摄像头检测建议使用 GPU 或嵌入式 NPU。8.3 影响性能的关键参数imgsz输入分辨率越高检测小目标能力越强但显存占用和推理耗时上升。batch批量数越大GPU 利用率越高但显存占用线性上升。conf置信度阈值越低输出框越多后处理耗时上升。device模型运算是跑在 GPU 还是 CPU。9. YOLO 常见问题与排查方法零基础上手 YOLO环境和训练阶段的问题最多。下面列出几个高频问题。问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named ultralytics依赖没有安装到当前虚拟环境检查当前环境python -c import ultralytics激活正确环境后重新安装推理时提示缺少模型文件权重文件路径错误或未下载查看终端日志中的下载/加载路径重新指定model路径CUDA out of memory显存不足nvidia-smi查看显存占用调小batch、imgsz或换更小的模型训练时 mAP 全为 0标签文件为空、类别 id 越界检查labels目录和data.yaml修正标签文件核对类别 id页面或服务端口打不开端口被占用或服务未启动检查终端日志查看端口占用换端口或重启服务视频检测很慢CPU 推理且分辨率高看推理日志中的单帧耗时降低imgsz改用 GPU 部署导出 ONNX 失败PyTorch 版本与 opset 不兼容查看导出报错日志升级或降级 PyTorch调整opset检测框重叠严重conf 阈值过低或 NMS 参数不合理打印结果中的置信度分布提高conf阈值或调整 NMS 参数排查问题的大原则是先看日志再确认路径和环境最后检查数据。很多人卡在“训练没效果”基本都是数据标注或路径问题不是模型问题。10. YOLO 最佳实践与使用建议10.1 先跑通最小流程不要一上来就追求高精度。第一次项目尝试建议用 YOLO 自带的预训练权重跑通推理然后再用一小批数据训练 10 到 20 个 epoch验证训练流程是否正常。这样可以把“环境问题”和“算法问题”分开。10.2 数据质量优先于模型大小同一个模型数据标注质量差和标注质量好最终 mAP 可能差很多。标注时尽可能保证框贴合目标、类别统一、正负样本均衡。训练前检查一遍标签文件确认没有空标签。10.3 管理好模型、数据和输出目录我建议项目目录按以下结构组织project/ ├── dataset/ │ ├── images/ │ ├── labels/ │ └── data.yaml ├── models/ ├── runs/ ├── scripts/ └── outputs/模型权重、训练日志、输出结果分开存放方便后续回溯实验。10.4 批量任务要做日志和失败重试批量处理大量图片或视频时不能只跑一个for循环不管结果。每处理一张图片记录一行日志处理完成后统计成功数量和失败数量。如果任务中断能快速定位到失败文件。10.5 接口服务要控制访问范围部署 API 服务后不要直接暴露到公网至少加上 token 鉴权和 IP 白名单。模型文件本身可能包含业务敏感信息也要限制下载和访问权限。11. 总结与下一步YOLO 学习真正有用的起点不是背网络结构图而是先把“推理、训练、导出、部署”这条链路跑通。第一次推理成功你就知道模型输入输出长什么样第一次训练完你就能理解数据集、标注和 mAP 的关系第一次导出 ONNX 并封装接口你才真正具备把 YOLO 接入实际项目的能力。这篇内容里最容易踩的坑有三个一是环境没配对安装版本混乱二是数据集格式和data.yaml不对训练指标全为 0三是显存不足还强行开大分辨率导致训练中断。这三个问题只要能提前规避你的 YOLO 项目进度会快很多。下一步可以做的事选一个你熟悉的业务场景拍 100 到 300 张图片完成标注、训练和验证。用yolo export把模型导出成 ONNX再研究 TensorRT 或 OpenVINO 加速。尝试换主干网络或检测头观察精度和速度的变化。如果想上嵌入式设备可以研究 RK3588、Jetson 平台的部署流程并注意不同平台算子兼容性问题。从零基础到能自己训练和部署模型最合理的路径就是“先跑通、再训练、后部署”。先别纠结原理细节动手把流程走通再回头补理论理解速度会快很多。