YOLOv13项目目录结构说明，新手必看
1. 为什么目录结构对YOLOv13新手至关重要
刚接触YOLOv13时，很多人会直接运行命令却不知道代码在哪、权重在哪、配置文件怎么改。结果就是：报错找不到路径、修改参数没生效、训练日志无处可查、想加新功能却不知从何下手。
这不是你不够聪明，而是YOLOv13的工程组织方式和传统YOLO版本有明显差异——它基于超图感知架构重构了整个代码流，模块解耦更彻底，但目录层级也更清晰。理解目录结构，等于拿到了YOLOv13项目的地图和钥匙。
本指南不讲抽象理论，不堆砌术语，只聚焦一个目标：让你在5分钟内看清每个文件夹是干什么的、哪些文件必须关注、哪些可以暂时忽略。所有说明都基于官方镜像/root/yolov13的真实路径，所见即所得。
关键提示：本文所有路径均以镜像内默认位置为准（
/root/yolov13），无需额外安装或编译，开箱即用。
2. 整体目录概览：4大核心区域
进入容器后执行ls -l /root/yolov13，你会看到如下一级目录结构：
├── cfg/ # 配置中心：模型定义、训练参数、数据集描述 ├── data/ # 数据中枢：示例图片、标注文件、预置数据集链接 ├── models/ # 模型工厂：骨干网、颈部、头部、超图增强模块源码 ├── utils/ # 工具箱：数据加载、后处理、可视化、评估脚本 ├── ultralytics/ # 主框架：YOLOv13核心API、CLI入口、训练循环封装 ├── weights/ # 权重仓库：预训练模型（.pt）、导出格式（.onnx/.engine） ├── examples/ # 实战样板：推理、训练、导出、部署的最小可运行示例 ├── notebooks/ # 交互沙盒：Jupyter笔记本，适合调试与教学演示 ├── tests/ # 质量护栏：单元测试、集成测试用例 └── README.md # 入口文档：一句话说明项目定位与快速启动方式这10个一级目录不是随意排列，而是严格遵循“配置驱动、数据就绪、模型可插拔、工具即用”的工程原则。下面逐层拆解真正影响你日常开发的7个关键目录。
3. cfg/：所有配置的源头，改这里才真正生效
3.1 为什么不能跳过cfg/
YOLOv13不再把模型结构硬编码在Python里，而是通过YAML配置文件声明式定义。这意味着：
- 修改
yolov13n.yaml就等于重定义整个网络拓扑； - 调整
default.yaml就能全局控制训练超参； - 替换
coco.yaml就可切换数据集而无需动代码。
3.2 核心配置文件详解
| 文件路径 | 作用 | 新手重点关注项 |
|---|---|---|
cfg/models/yolov13n.yaml | Nano版模型结构定义 | backbone,neck,head三段模块名；hyperace开关是否启用超图增强 |
cfg/models/yolov13s.yaml | Small版结构定义 | 对比yolov13n.yaml，观察depth_multiple和width_multiple如何放大网络 |
cfg/default.yaml | 训练默认参数 | batch,epochs,lr0,imgsz,device—— 这些是你每次训练最先要改的 |
cfg/datasets/coco.yaml | COCO数据集描述 | train,val,nc,names—— 换自己数据集时只需复制并修改这4行 |
cfg/hyperparameters/hyp.scratch-low.yaml | 低资源训练超参 | 内存不足时优先尝试此配置，学习率、warmup_epoch已调优 |
3.3 实操建议：如何安全修改配置
不要直接编辑原始yaml文件。正确做法是：
# 1. 复制一份自己的配置（避免污染原版） cp cfg/models/yolov13n.yaml cfg/models/my_yolov13n.yaml # 2. 用sed快速关闭超图增强（调试用） sed -i 's/hyperace: true/hyperace: false/g' cfg/models/my_yolov13n.yaml # 3. 启动训练时指定你的配置 yolo train model=cfg/models/my_yolov13n.yaml data=coco.yaml新手提醒：YOLOv13的
hyperace模块虽强，但在小数据集上易过拟合。首次训练建议先设为false，验证流程跑通后再开启。
4. models/：超图感知的核心实现地
4.1 不再是单一.py文件，而是模块化设计
YOLOv13将传统YOLO的models/common.py拆分为5个专注领域的子目录：
models/ ├── backbone/ # 超图骨干网：HGConv, HGResNet, DS-C3k ├── neck/ # 全管道聚合：FullPAD模块（FP-Neck, FP-Fusion） ├── head/ # 自适应检测头：HyperHead（支持动态anchor分配） ├── hyperace/ # 超图自适应相关性增强：消息传递层、超边构建器 └── __init__.py # 统一注册接口，所有模块自动被ultralytics识别4.2 新手最该看懂的3个文件
models/backbone/hgconv.py：HGConv是YOLOv13的基石模块，用深度可分离卷积替代标准卷积，参数量直降40%。打开它，你会看到DSConv2d类的简洁实现——这就是轻量化设计的物理载体。models/neck/fp_fusion.py：FullPAD的核心融合逻辑。注意forward()中的三路特征拼接顺序：[backbone_out, neck_internal, head_input]，这正是“全管道”信息协同的代码体现。models/hyperace/message_passing.py：超图消息传递的主干。别被名字吓到，核心就两行：# 节点特征聚合（像素级） node_agg = torch.einsum('bik,bkj->bij', edge_weight, node_feat) # 超边特征更新（关系级） edge_update = torch.sigmoid(node_agg.mean(dim=1))看懂这两行，你就抓住了YOLOv13区别于前代的本质。
4.3 如何快速验证模块改动
修改完某个模块（如hgconv.py）后，无需重新训练：
from models.backbone.hgconv import HGConv import torch x = torch.randn(1, 32, 64, 64) # 模拟输入特征 m = HGConv(32, 64, k=3) y = m(x) print(f"Input shape: {x.shape} → Output shape: {y.shape}") # 应输出 [1, 64, 64, 64]只要形状匹配、不报错，说明你的修改未破坏基础结构。
5. weights/：不只是存放模型，更是版本管理枢纽
5.1 镜像预置的4类权重文件
| 文件名 | 类型 | 用途 | 是否推荐新手使用 |
|---|---|---|---|
yolov13n.pt | 官方预训练权重 | 快速推理、迁移学习起点 | 强烈推荐 |
yolov13n_last.pt | 最后一次训练权重 | 断点续训、调试过程保存 | 仅当自己训练过才存在 |
yolov13n_best.pt | 验证集最优权重 | 正式部署、精度优先场景 | 推荐用于最终评估 |
yolov13n.onnx | ONNX导出格式 | 跨平台部署（Web、移动端） | 导出后必检 |
5.2 权重文件命名背后的秘密
YOLOv13采用语义化命名规则：{model}_{size}_{stage}.pt
model:yolov13（固定）size:n(nano),s(small),m(medium),l(large),x(extra-large)stage:pt(PyTorch),onnx,engine(TensorRT),torchscript
所以yolov13s_engine.pt表示Small版TensorRT引擎，而yolov13m.pt是Medium版PyTorch权重。
5.3 新手避坑指南：权重加载常见错误
| 错误现象 | 原因 | 解决方案 |
|---|---|---|
RuntimeError: size mismatch | 模型结构yaml与权重不匹配 | 检查yolo train model=yolov13s.yaml weights=yolov13n.pt—— 大小写必须一致 |
KeyError: 'model.0.conv.weight' | 权重来自旧版YOLO（v8/v10） | YOLOv13权重只能用YOLOv13模型加载，不可混用 |
FileNotFoundError: yolov13n.pt | 首次运行未触发自动下载 | 手动执行yolo predict model=yolov13n.pt source='https://ultralytics.com/images/bus.jpg'，系统会自动下载 |
实测技巧：首次使用时，先运行一次在线推理，让系统自动下载并校验权重完整性，比手动拷贝更可靠。
6. examples/：比文档更管用的“活代码教科书”
6.1 为什么examples比README更值得细读
README.md告诉你“能做什么”，而examples/直接展示“怎么做”。每个.py文件都是一个独立可运行的最小闭环，包含：
- 完整导入链
- 显式设备指定（
device='cuda:0'） - 错误处理兜底（
try...except） - 结果可视化逻辑（
cv2.imshow或results[0].show()）
6.2 新手应优先运行的3个例子
examples/inference_simple.py：5行代码完成端到端推理
from ultralytics import YOLO model = YOLO('weights/yolov13n.pt') # 自动识别设备 results = model.predict('data/images/bus.jpg', conf=0.25, iou=0.7) results[0].save('runs/predict/bus_result.jpg') # 保存带框图 print(f"Detected {len(results[0].boxes)} objects")价值：验证环境是否正常、确认图片路径写法、学会基础参数设置。
examples/train_custom.py：训练自己的数据集（COCO格式）
from ultralytics import YOLO model = YOLO('cfg/models/yolov13s.yaml') # 从yaml构建新模型 model.train( data='cfg/datasets/my_dataset.yaml', # 指向你的数据集 epochs=50, batch=64, imgsz=640, name='my_train_v13s', # 日志和权重保存到 runs/train/my_train_v13s/ device='0' # 显卡编号 )价值：掌握数据集接入全流程，理解name参数如何组织输出目录。
examples/export_onnx.py：导出ONNX供生产部署
from ultralytics import YOLO model = YOLO('weights/yolov13s.pt') model.export( format='onnx', dynamic=True, # 支持动态batch/size opset=17, # ONNX算子集版本 simplify=True # 自动优化图结构 ) # 输出：weights/yolov13s.onnx价值：避开TensorRT复杂配置，先用ONNX验证模型导出可行性。
7. ultralytics/：YOLOv13的“操作系统内核”
7.1 不是黑盒，而是高度可定制的API层
ultralytics/目录下没有魔法，只有清晰分层：
ultralytics/ ├── __init__.py # 暴露顶级API：YOLO, export, train, predict ├── engine/ # 核心引擎：Trainer, Validator, Predictor类 ├── models/ # 模型加载器：自动识别yaml/pt/onnx并实例化 ├── utils/ # 工具函数：非极大值抑制、坐标转换、指标计算 └── nn/ # 神经网络基类：BaseModel, DetectionModel7.2 新手可安全扩展的2个切入点
自定义预测后处理（不改源码）
from ultralytics import YOLO import cv2 model = YOLO('weights/yolov13n.pt') # 获取原始预测结果（tensor） results = model('data/images/bus.jpg', verbose=False) boxes = results[0].boxes.xyxy.cpu().numpy() # [x1,y1,x2,y2] conf = results[0].boxes.conf.cpu().numpy() cls = results[0].boxes.cls.cpu().numpy() # 自定义绘制逻辑（比如只画person类别） img = cv2.imread('data/images/bus.jpg') for i, (box, c, cls_id) in enumerate(zip(boxes, conf, cls)): if int(cls_id) == 0: # 0=person x1, y1, x2, y2 = map(int, box) cv2.rectangle(img, (x1, y1), (x2, y2), (0,255,0), 2) cv2.putText(img, f'person {c:.2f}', (x1, y1-10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0,255,0), 2) cv2.imwrite('custom_output.jpg', img)注入自定义指标（覆盖默认评估）
from ultralytics.models.yolo.detect import DetectionValidator from ultralytics.utils.metrics import ConfusionMatrix class MyValidator(DetectionValidator): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) self.confusion_matrix = ConfusionMatrix(nc=self.nc) def postprocess(self, preds): # 在这里插入你的后处理逻辑 return super().postprocess(preds) # 使用自定义验证器 model.val(data='cfg/datasets/coco.yaml', validator=MyValidator)重要原则：所有扩展都基于继承和组合，绝不修改
ultralytics/源码。这样升级镜像时你的代码依然可用。
8. 总结：建立你的YOLOv13工作流地图
回顾全文，你已掌握YOLOv13项目结构的黄金三角：
- 配置驱动：
cfg/是你的指挥中心，改yaml比改代码更安全高效； - 模块即服务：
models/中每个子目录都是可插拔组件，理解hyperace/才真正读懂YOLOv13； - 权重即资产：
weights/不是静态文件夹，而是版本化管理的模型资产库，命名规则就是你的操作手册。
下一步行动建议：
- 立即实践：进入容器，执行
tree -L 2 /root/yolov13，对照本文目录树亲手触摸每个文件夹； - 动手验证：运行
examples/inference_simple.py，确保第一张检测图成功生成； - 建立习惯：以后遇到任何问题，先问自己——这个功能涉及哪个目录？配置在哪？代码在哪？权重在哪？
YOLOv13的强大，不在于它有多复杂，而在于它的结构足够清晰。当你能在脑中构建出/root/yolov13的完整路径图谱，你就已经跨过了新手期最大的门槛。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
