简介YOLOv13是清华大学联合太原理工大学、北京理工大学等团队于2025年6月发布的最新实时目标检测模型延续YOLO系列“只需看一次”的设计思想首次在实时检测中引入超图理论适合正在进行课程设计、期末大作业或毕业设计的目标检测学习者使用。压缩包内共486个文件以Python源码、YAML配置、模型权重pt、示例图片及Docker部署脚本等类型为主整体263.76MB目录结构较完整便于按代码、配置和权重模块对照学习。其中还包括训练日志、推理示例和说明文档可帮助快速跑通检测流程并理解多目标高阶语义建模思路。目前已有237人学习下载适合作为入门到进阶的目标检测项目基础工具。1. yolov13 源码 权重文件这套资源到底能拿来干什么如果你手里正好有一批图想跑目标检测又不想从数据标注一路干到训练收敛那么一套带权重文件的完整源码比你自己从零搭要省几天时间。yolov13 这个版本号在社区里已经被传了很久我这里拿到的这套资源是完整工程源码加配套权重文件解压后可以直接推理也能直接开训练。它适合两类人一是已经被数据集折磨过、想立刻跑通一条检测链路的老手二是刚接触 YOLO 系列、需要一个能跑通的基线工程来对照学习的新手。源码里包含模型定义、训练入口、推理入口和权重文件你不需要自己拼装模块缺的只是把环境调对、把路径看清。下面我把拆包过程和复现路径完整走一遍包括我踩过的坑。2. 环境与工程结构先把源码跑起来再谈权重2.1 拿到压缩包之后先看什么解压后不要急着装环境先把根目录结构扫一遍。常见做法是用tree命令或者直接在文件管理器里看重点关注以下几个入口train.py、detect.py、models/、cfg/、weights/。其中weights/里放的就是权重文件yolov13 的权重文件一般是一整个.pt或者.pth几百 MB 到 1GB 不等这个体积决定了加载后推理速度的下限。有些包里还会带requirements.txt但很多社区分享的包是不带的这时候依赖冲突就得靠你自己试错。unzip yolov13-full.zip -d yolov13-project cd yolov13-project find . -maxdepth 2 -type d | sort find . -maxdepth 2 -type f -name *.pt -o -name *.yaml | sort第一条命令解压第二条进入目录第三条列出两层目录结构第四条筛出权重文件和配置文件。我第一次拿到这套资源时直接跳过了目录检查结果cfg路径写错模型加载报错来回调了半小时。所以建议你先看目录再跑后续命令。2.2 Python 虚拟环境与依赖版本对齐yolov13 源码对 PyTorch 版本比较挑剔至少 1.9 以上的版本才支持它用到的一些算子推荐直接用 2.x 版本。CUDA 版本和 PyTorch 的匹配在资源包里没有固定死所以你自己装的时候要注意版本对齐。我一般习惯用 conda 单独建一个环境不跟系统 Python 混在一起这样后面装 OpenCV 或其它依赖时不容易污染系统环境。conda create -n yolov13 python3.10 -y conda activate yolov13 pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu118 pip install opencv-python numpy tqdm pyyaml matplotlib pandas这里把 torch 版本固定到 2.1.0对应 CUDA 11.8 的 wheel 包是兼容性比较好的一组组合。如果你机器上 CUDA 版本更高比如 12.1也可以换成cu121的地址但注意权重文件和模型代码不受 CUDA 版本影响只影响训练和推理速度。装完依赖之后建议先做一次导入检查确认没有torch和cv2的版本冲突。这一步看起来很基础但恰恰是最容易翻车的地方。2.3 模型定义与配置文件怎么对应起来# models/yolov13.py 片段示例 def build_model(cfg_path): import yaml with open(cfg_path, r, encodingutf-8) as f: cfg yaml.safe_load(f) model YOLOv13(cfg) return model这段代码做的事情很简单从 yaml 文件里读配置然后实例化模型。关键点是cfg_path和权重文件里的模型结构必须一一对应如果你换了别人的配置文件加载你的权重文件就很容易报size mismatch之类的问题。yolov13 的配置文件里通常包含骨干网络深度倍数、宽度倍数、检测头层数、类别数这些参数。参数和权重的对应关系用一句话概括就是权重文件里存的是每个层的张量值配置决定了张量形状形状对不上权重就加载不了。3. 推理链路用权重文件五分钟出一张图结果3.1 单张图片推理跑通把环境装好、权重文件路径确认之后第一件事是拿一张图跑推理验证整套源码能不能通。yolov13 的推理入口通常封装在detect.py里命令行直接传参数即可。python detect.py --weights weights/yolov13.pt --source data/test.jpg --conf-thres 0.25 --iou-thres 0.45 --device 0这行命令里--weights指定权重文件--source是输入图片路径--conf-thres是置信度阈值低于这个值的检测框会被过滤掉。--iou-thres是 NMS 的 IoU 阈值控制重叠框的合并力度。--device 0表示用第一张 GPU。我第一次跑的时候直接把--device 0改成--device cpu发现速度慢到怀疑人生后来确认了这套源码里 TensorRT 之外的部分对 CPU 并不友好纯 CPU 推理一张 1080p 图要 3 秒以上。推理完成后结果默认保存到runs/detect/exp下里面包含原图加画框的图片、检测结果的 txt 文件以及一个统计了检测数量和耗时的日志文件。这个输出结构是 YOLO 系列一贯的套路如果你的工程里没有这个目录多半是源码把输出模块重构了去detect.py里搜save_path就能找到。3.2 批量推理与推理速度的取舍实际使用场景里单张跑通常不够文件夹批量推理更常见。yolov13 源码里--source可以传一个目录它会自动遍历目录下所有图片。python detect.py --weights weights/yolov13.pt --source data/images --batch-size 8 --img-size 640 --conf-thres 0.3--batch-size在推理阶段的意义是把多张图拼成一个 batch 一次过网络GPU 利用率会提高但显存占用也会跟着涨。--img-size是输入网络的尺寸640 是 YOLO 系列的常用值改大到 1280 会提升小目标召回率但速度会明显下降。这里推荐一个习惯先在--img-size 640下跑一遍看日志里的单张耗时如果一秒钟能处理 5 张以上的图就不要再盲目调大输入尺寸了。3.3 把推理结果接进自己的脚本如果你不是只想要一张画框图而是想把这套检测能力嵌到自己的工程里可以直接在 Python 里调用它的封装 API这样比命令行嵌套更可控。import torch model torch.hub.load(./, custom, pathweights/yolov13.pt, sourcelocal) results model(data/test.jpg) boxes results.xyxy[0].cpu().numpy() for box in boxes: x1, y1, x2, y2, conf, cls_id box print(f类别ID:{int(cls_id)} 置信度:{conf:.2f} 坐标:({x1:.1f},{y1:.1f})-({x2:.1f},{y2:.1f}))这里torch.hub.load的sourcelocal表示加载本地源码而不是从 GitHub 拉取路径指向工程根目录就行。返回的results.xyxy是 xyxy 格式的检测框张量每个框包含坐标、置信度和类别索引。这套接口的好处是检测结果直接以数组形式给你可以无缝对接到跟踪、计数或者别的后续逻辑里。注意results.pandas().xyxy在老版本源码里也能用但新版更推荐直接取.xyxy。4. 训练闭环从标注到权重文件自己产出的完整流程4.1 数据集目录结构与标签格式必须是 YOLO 格式yolov13 的训练入口是train.py但训练前必须先搞定数据。跟官方 YOLO 系列一样v13 的数据集目录结构遵循images和labels一一对应的原则。每一张图片对应一个同名 txt 文件txt 里每一行是一个物体类别ID cx cy w h其中cx cy w h都是相对于图片宽度和高度的归一化数值。data/ images/ train/ 001.jpg val/ 002.jpg labels/ train/ 001.txt val/ 002.txt我曾经直接把标注软件导出的 VOC 格式喂进去训练跑了一轮才发现类别全对不上因为 VOC 的坐标是绝对像素值、格式是xmin ymin xmax ymax不归一化的话损失值会直接炸掉。所以拿到别的工具导出的标注后第一件事是转格式第二件事是检查归一化坐标是否在 0-1 之间。yolov13 的 data yaml 文件里需要指定train/val路径和类别名称。# data/custom.yaml train: ./data/images/train val: ./data/images/val nc: 2 names: [person, car]4.2 训练命令与参数记忆表python train.py --data data/custom.yaml --weights weights/yolov13.pt --epochs 100 --batch-size 16 --imgsz 640 --device 0 --hyp data/hyps/hyp.scratch.yaml训练命令里最核心的参数是--weights、--epochs、--batch-size。用已有权重文件做微调可以大幅缩短训练时间这也就是权重文件在你手上的第二个价值不是只能拿来推理还能作为预训练起点。下面列一下常见参数调整区间参数默认值建议范围影响--epochs30050-200太多容易过拟合太少欠拟合--batch-size84-32越大收敛越快但吃显存--imgsz640416-1280越大小目标越友好显存压力越大--workers80-16数据加载线程数内存不足时调小--cacheFalseTrue/False开启后把图缓存进内存训练提速明显4.3 断点续训与权重文件保存逻辑训练过程中途断了是常态尤其 batch-size 开大之后显存溢出是家常便饭所以断点续训非常重要。yolov13 源码里默认每个 epoch 都会往runs/train/exp/weights/目录下写一个最新权重训练完成后还会额外存一个最佳权重。恢复训练的命令一般是这样的python train.py --data data/custom.yaml --weights runs/train/exp/weights/last.pt --epochs 100用last.pt续训而不是从预训练权重开始优化器的动量状态会被保留学习率调度也能接上。如果你是从零开始跑的第一次训练结束后先看一眼best.pt的验证集 mAP别急着把它当作最终交付物。经验是best.pt的评判指标通常是在验证集上选的如果你业务场景的测试集分布和验证集差别很大这个权重不一定是最优的。我自己一般会在训练完后再拿best.pt在测试集上跑一遍全量检测人工抽几十张图看漏检和误检。4.4 训练日志怎么看tensorboard --logdirruns/train训练时如果开了 tensorboard 日志直接用上面命令启动可视化面板。浏览器里重点看两条曲线train/loss和metrics/mAP_0.5。loss 曲线如果一直在震荡不下降大概率是学习率太大或者数据标注有问题。mAP 曲线如果训练集很高但验证集很低就是过拟合这时候减小--epochs或者增大数据增强强度。训练日志里还有一个容易被忽略的参数--cos-lr开启后学习率按余弦曲线衰减后期收敛更稳。5. 高频避坑yolov13 源码里最常见的五个坑及排查5.1 权重文件加载就报size mismatch现象运行detect.py或加载权重文件时报错信息里出现size mismatch for ... expected [128, 64, 3, 3], got [256, 128, 3, 3]之类的字样。原因权重文件里的模型结构和当前代码默认的配置文件不一致通常是类别数对不上比如权重文件是用 80 类 COCO 训练的但代码里的 yaml 文件写的nc: 2。解决打开cfg/下的模型配置文件把nc改成和权重文件训练时一致的类别数或者反过来如果你要微调自己的数据集就改类别数并加载预训练权重。5.2 推理速度正常但检测框全部错位现象图片能出框但框的位置完全不对有的框在物体旁边有的框尺寸异常大。原因--img-size和训练时不一致且源码的 letterbox 填充逻辑没有自动适配。训练用的是 640推理时改成 1280而模型的 anchor 是按训练尺寸设计的直接错乱。解决推理时保持--img-size与训练时一致或者统一用 640。如果确实需要更大输入尺寸建议用训练时的尺寸微调几个 epoch让模型适应新尺度。5.3 显存明明够用却 OOM现象训练或推理运行到一半报CUDA out of memory但nvidia-smi显示显存还有余量。原因PyTorch 的显存缓存机制导致显存碎片化或者 batch 里某张特别大的图短时峰值很高。解决训练时调小--batch-size同时开启--cache减少数据加载抖动。推理阶段逐张图跑或者torch.cuda.empty_cache()在循环里清理缓存。5.4 训练 loss 前几个 epoch 不降反升现象训练日志里 loss 从 0.05 涨到 0.2然后才开始降。原因预训练权重文件和自己的数据集类别差异很大时模型需要先调整检测头的分类分支前几个 epoch 上涨是正常现象。尤其当你的类别数远少于预训练类别数时分类分支的权重初始化差异较大。解决不要在前 10 个 epoch 内因为 loss 上涨就停掉训练跑满 30 个 epoch 再看曲线趋势。如果 30 个 epoch 后还在涨再检查数据和标签格式。5.5 输出结果 txt 里没有内容现象图片能推理花框也正常但保存的检测结果 txt 文件空空如也。原因detect.py里保存 txt 的开关没有开启或者源码默认只在--save-txt参数打开时才输出文件。解决在推理命令里加上--save-txt参数。这也算是一个典型的新手误导点很多人以为输出是默认带框文件就够了实际上做后续分析时 txt 里的坐标才是最有价值的部分。6. 导出与提速把权重做成可交付的推理服务6.1 导出 ONNX 格式yolov13 训练或下载得到的权重文件在部署阶段通常要先导成 ONNX再用 TensorRT 或 ONNX Runtime 跑。导出命令在 YOLO 系列里一般是export.pyv13 源码里如果有就优先用没有就手动加载模型后调torch.onnx.export。import torch from models.yolov13 import build_model model build_model(cfg/yolov13.yaml) ckpt torch.load(weights/yolov13.pt, map_locationcpu) model.load_state_dict(ckpt[model_state_dict]) model.eval() dummy_input torch.randn(1, 3, 640, 640) torch.onnx.export( model, dummy_input, yolov13.onnx, opset_version12, input_names[images], output_names[output], dynamic_axes{images: {0: batch}, output: {0: batch}} )导出时注意model.eval()必须放在 load 之后不然 BatchNorm 层的均值方差还是训练状态导出的模型会有偏差。另一个细节是dynamic_axes如果你只需要固定 batch 大小推理可以去掉这个参数会省一点模型体积。导出完成后用 ONNX Runtime 跑一次对比原始 PyTorch 推理结果框坐标误差应该非常小。6.2 用 ONNX Runtime 跑一次推理import onnxruntime as ort import numpy as np session ort.InferenceSession(yolov13.onnx, providers[CUDAExecutionProvider]) input_data np.random.randn(1, 3, 640, 640).astype(np.float32) outputs session.run(None, {images: input_data})这段代码是最简单的 ONNX Runtime 调用providers里指定了 CUDA 执行器如果你的环境没有装 onnxruntime-gpu就改成[CPUExecutionProvider]。ONNX 模型的输出是一堆原始检测张量后续 NMS 需要自己写这也是很多人在这一步卡住的原因。如果不想重复造轮子可以看看源码里有没有封装好的 ONNX 后处理模块yolov13 这类社区版本一般都会带上。6.3 部署时最容易翻车的一个细节推理入口换成 ONNX 之后预处理逻辑必须和训练时完全对齐。YOLO 系列训练用的预处理是 letterbox 加归一化letterbox 的填充颜色是灰色值 114如果部署端的预处理用了直接 resize 或者填充值不对检测精度会肉眼可见地下降。我见过一个部署项目在 PyTorch 里 mAP 0.85转到 ONNX Runtime 后掉到 0.7查半天发现是图像 Resize 方式不一致。从那以后我每次做模型导出都会强制走一遍流程先在原模型上跑三张图记录结果再在导出模型上跑同样的三张图比对输出的类别、置信度和坐标全部对得上才继续做服务封装。希望帮到你这套流程虽然多花十分钟但能省下部署现场排查的数小时。本文还有配套的精品资源点击获取