YOLOv12【第六章：推理、验证与 Benchmark篇·第15节】YOLOv12 Benchmark 报告模板

🏆 本文收录于 《YOLOv12实战：从入门到深度优化》 专栏。

该专栏系统复现并深度梳理全网主流 YOLOv12 改进方法与工程实战案例，覆盖分类、目标检测、实例分割、多目标追踪、关键点检测、旋转目标检测等多个方向，坚持 持续更新 + 深度解析 + 工程验证。

专栏将围绕 YOLOv12 的网络结构、训练策略、标签分配、损失函数、数据增强、模型压缩、推理加速与部署落地等内容展开，重点分析 Area Attention（区域注意力机制）、R-ELAN（残差高效层聚合网络）、Flash Attention 集成与 Attention-Centric 架构设计 等核心设计思想，并结合实际项目讲解其改进方式与应用价值。

部分章节还会结合国内外前沿论文与 AIGC 大模型技术，对主流改进方案进行重构与再设计，使内容更加贴近真实业务场景，适合希望深入研究 YOLOv12 或具有工程落地需求的开发者学习与参考。

🎯限时特惠：当前活动一折秒杀，一次订阅，终身有效，后续所有更新章节全部免费解锁 👉 传送门 👈️

🎉 本专栏还不够过瘾？别急，好戏才刚刚开始！我已经为你准备了一整套 YOLO 进阶实战大礼包🎁：

👉 《YOLOv8实战》 👉 《YOLOv9实战》 👉 《YOLOv10实战》 👉 《YOLOv11实战》 👉 《YOLOv12实战》 👉 以及最新上线的 《YOLOv26实战》

想一次搞定所有版本？直接冲 《YOLO全栈实战合集》，一站式涵盖 YOLO 各版本实战教学！

🚀 想学哪个版本？直接找 bug 菌"许愿"，安排！必须安排！🚀

🎯 本文定位：计算机视觉 × YOLOv12 推理、验证与 Benchmark篇 📅 预计阅读时间：约 45～60 分钟 🏷️ 难度等级：⭐⭐☆☆☆（基础级） 🔧 技术栈：Python 3.9+ · PyTorch 2.0+ · YOLOv12 · ByteTrack · OpenCV · NumPy

全文目录：

• • 上期回顾
  • 本节主题：YOLOv12 Benchmark 报告模板
  • • 一、为什么需要一份标准化的 Benchmark 报告？
    • 二、Benchmark 报告的整体结构设计
    • 三、第一板块：报告元信息
    • 四、第二板块：测试环境描述
    • 五、第三板块：数据集说明
    • 六、第四板块：测试方法与参数
    • 七、第五板块：精度评估结果
    • 八、第六板块：推理速度结果
    • 九、第七板块：资源占用结果
    • 十、第八板块：综合对比分析——雷达图与帕累托分析
    • 十一、第九板块：结论与建议
    • 十二、第十板块：完整自动化 Benchmark 流水线
    • 十三、Benchmark 配置文件模板
    • 十四、报告质量检查清单
    • 十五、报告分发与版本管理
    • 十六、常见问题与踩坑记录
  • 下期预告
  • 📌 附录
  • 🧧🧧 文末福利，等你来拿！🧧🧧
  • 👨‍💻 About Me · 关于作者

上期回顾

在上期《YOLOv12【第六章：推理、验证与 Benchmark篇·第14节】模型选型报告——精度、速度、参数量、FLOPs 综合评估》内容中，我们深入探讨了如何系统性地完成一份模型选型报告。这不是一件简单的事——工程师们常常陷入"只看 mAP"的误区，把精度当作唯一判断标准，结果选出来的模型在实际部署时要么跑不动，要么延迟高得让产品方难以接受。

上期的核心思路是建立一套多维度评估体系：

• 精度维度：mAP@0.5 与 mAP@0.5:0.95 的综合权衡，针对不同业务场景（安防、医疗、工业质检）给出不同的精度阈值底线
• 速度维度：区分了延迟（Latency）、吞吐量（Throughput）、FPS 三个概念，强调必须在目标硬件上实测，不能只看论文数据
• 参数量维度：参数量（Params）反映模型存储占用，但不等于推理速度，要结合 FLOPs 综合判断
• FLOPs 维度：浮点运算量代表计算复杂度，FLOPs 低不代表速度快，还受内存访问模式、算子并行度等影响

我们还给出了一个选型决策矩阵，帮助读者根据部署场景（边缘端/云端）、精度要求（高/中/低）、实时性要求快速缩小候选模型范围。最终形成了从"需求分析 → 候选筛选 → 实测对比 → 选型决策"的完整闭环。

那么，选型之后呢？我们需要一份正式的 Benchmark 报告来沉淀测试结果、支撑决策、方便团队协作与后续回溯。这就是本节要解决的问题。

本节主题：YOLOv12 Benchmark 报告模板

一、为什么需要一份标准化的 Benchmark 报告？

说实话，我见过太多团队的 Benchmark “报告”——一个 Excel 表格，几列数字，没有测试环境描述，没有数据集说明，没有测试代码，甚至连测试时间都没有记录。半年后再看，根本不知道这个数字是怎么来的，在什么条件下测的，换了块显卡还能复现吗？

这种"报告"的最大问题在于不可复现、不可追溯、不可传递。你自己看得懂，别人看不懂；你现在看得懂，三个月后你自己也看不懂了。

一份好的 Benchmark 报告，应该像一份实验室记录，具备以下特性：

可复现性：任何人拿到这份报告，按照其中的环境配置和测试脚本，应该能得到相近的结果（允许合理的硬件差异范围）。

完整性：不仅记录结果，还记录过程——用了什么数据集、什么预处理、什么后处理参数、什么推理框架、什么硬件配置。

可比较性：统一的格式和指标定义，使得不同模型、不同版本之间的对比有意义。

可传递性：报告本身就是沟通工具，研发人员、产品经理、运维工程师各取所需，不需要再开会解释。

YOLOv12 的 Benchmark 报告尤其重要，原因在于 YOLOv12n/s/m/l/x 五个规格横跨了从边缘端到云端的完整部署场景，不同规格在不同硬件、不同精度（FP32/FP16/INT8）下的表现差异显著。没有一份系统化的报告，你很难向上级或客户清晰说明为什么选择某个规格、某种部署方式。

二、Benchmark 报告的整体结构设计

一份完整的 YOLOv12 Benchmark 报告包含以下几个核心板块：

相关示意图绘制如下，仅供参考：

这个结构不是随意设计的，每个板块都有其存在的理由。下面我们逐一详细展开。

三、第一板块：报告元信息

元信息看似简单，却是报告"可追溯性"的根基。很多人写报告时直接省略这部分，结果半年后翻出来完全不知道背景。

元信息至少应包含：

为什么要记录 commit hash？

这是很多工程师忽略的细节。ultralytics 库更新频繁，即使是相同的版本号，不同时间安装的包可能包含 bug fix 或性能优化，导致测试结果出现差异。记录精确的 commit hash，才能真正保证结果可复现。

# 获取当前 ultralytics 版本信息
import ultralytics
import subprocess
import sys

def get_env_info():
"""
收集当前测试环境的详细版本信息
这些信息应该写入报告元信息板块
"""
info = {
"ultralytics_version": ultralytics.__version__,
"python_version": sys.version,
}

# 尝试获取 git commit hash（如果是从源码安装的）
try:
commit = subprocess.check_output(
["git", "rev-parse", "HEAD"],
cwd=ultralytics.__file__.replace("__init__.py", ""),
stderr=subprocess.DEVNULL
).decode().strip()
info["git_commit"] = commit
except Exception:
info["git_commit"] = "N/A (pip install)"

# PyTorch 版本
try:
import torch
info["torch_version"] = torch.__version__
info["cuda_version"] = torch.version.cuda
info["cudnn_version"] = str(torch.backends.cudnn.version())
except ImportError:
info["torch_version"] = "N/A"

return info

env_info = get_env_info()
for k, v in env_info.items():
print(f"{k}: {v}")

四、第二板块：测试环境描述

测试环境是 Benchmark 的"物理坐标系"。离开了环境描述，所有数字都是无意义的。同一个模型在 A100 和 RTX 3060 上的速度可能相差 10 倍，在 TensorRT FP16 和 PyTorch FP32 下的速度可能相差 5 倍。

测试环境描述需要覆盖以下层次：

硬件层：

• GPU 型号、显存大小、计算能力（Compute Capability）
• CPU 型号、核心数、主频
• 内存大小
• 存储类型（NVMe SSD / HDD）——影响数据加载速度

系统层：

• 操作系统及版本
• NVIDIA 驱动版本
• CUDA 版本
• cuDNN 版本

软件层：

• Python 版本
• PyTorch 版本
• ultralytics 版本
• TensorRT 版本（如使用）
• ONNX Runtime 版本（如使用）
• OpenCV 版本

import platform
import subprocess
import json
from datetime import datetime

def collect_hardware_info():
"""
自动收集硬件和软件环境信息，生成报告环境描述板块
"""
env = {}

# ==================== 系统信息 ====================
env["os"] = platform.platform()
env["python"] = platform.python_version()
env["timestamp"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

# ==================== GPU 信息 ====================
try:
import torch
if torch.cuda.is_available():
gpu_props = torch.cuda.get_device_properties(0)
env["gpu"] = {
"name": gpu_props.name,
"total_memory_gb": round(gpu_props.total_memory / 1024**3, 2),
"compute_capability": f"{gpu_props.major}.{gpu_props.minor}",
"multi_processor_count": gpu_props.multi_processor_count,
}
env["cuda_version"] = torch.version.cuda
env["cudnn_version"] = torch.backends.cudnn.version()
else:
env["gpu"] = "CUDA not available"
except ImportError:
env["gpu"] = "PyTorch not installed"

# ==================== nvidia-smi 信息 ====================
try:
smi_output = subprocess.check_output(
["nvidia-smi", "–query-gpu=name,driver_version,memory.total,compute_cap",
"–format=csv,noheader,nounits"],
stderr=subprocess.DEVNULL
).decode().strip()
env["nvidia_smi"] = smi_output
except Exception:
env["nvidia_smi"] = "nvidia-smi not available"

# ==================== CPU 信息 ====================
try:
import psutil
env["cpu"] = {
"physical_cores": psutil.cpu_count(logical=False),
"logical_cores": psutil.cpu_count(logical=True),
"max_freq_mhz": psutil.cpu_freq().max if psutil.cpu_freq() else "N/A",
"total_ram_gb": round(psutil.virtual_memory().total / 1024**3, 2),
}
except ImportError:
env["cpu"] = "psutil not installed, run: pip install psutil"

# ==================== 关键库版本 ====================
packages = ["ultralytics", "torch", "torchvision", "onnxruntime", "tensorrt", "opencv-python"]
env["packages"] = {}
for pkg in packages:
try:
import importlib.metadata
version = importlib.metadata.version(pkg)
env["packages"][pkg] = version
except importlib.metadata.PackageNotFoundError:
env["packages"][pkg] = "not installed"

return env

# 收集并打印环境信息
hw_info = collect_hardware_info()
print(json.dumps(hw_info, indent=2, ensure_ascii=False))

# 同时保存为 JSON 文件，附入报告附录
with open("benchmark_env.json", "w", encoding="utf-8") as f:
json.dump(hw_info, f, indent=2, ensure_ascii=False)

print("\\n环境信息已保存至 benchmark_env.json")

五、第三板块：数据集说明

数据集是精度评估的基础，也是最容易被忽略细节的地方。有些团队的 Benchmark 只写"使用 COCO val 数据集"，却没有说明是 val2017 还是 val2014，用的是哪个子集，预处理是否与官方一致。

标准测试数据集的核心要素：

数据集基本信息：

• 名称与版本（如 COCO val2017）
• 图像数量
• 类别数量与类别列表
• 标注格式

测试子集说明：

• 是否使用全量 val 集（5000 张图），还是采样子集？
• 如果是自定义数据集，需说明采集场景、标注工具、标注者信息

预处理说明：

• 输入尺寸（如 640×640）
• 是否使用 letterbox padding（YOLOv12 默认使用）
• 归一化方式（YOLOv12 标准是除以 255，不额外做 mean/std 归一化）
• 数据加载的 batch size

这些细节看起来微不足道，但如果不记录，复现时一个参数不对，精度可能就会出现 0.5~1 个百分点的偏差，足以让对比结论失效。

import os
import json
from pathlib import Path

def describe_dataset(data_yaml_path: str, split: str = "val") –> dict:
"""
从 YOLO 格式的 data.yaml 中提取数据集描述信息
用于填写报告的数据集说明板块

Args:
data_yaml_path: data.yaml 文件路径
split: 使用的数据集划分，默认为 'val'

Returns:
数据集描述字典
"""
import yaml

with open(data_yaml_path, "r", encoding="utf-8") as f:
data_cfg = yaml.safe_load(f)

dataset_info = {
"yaml_path": str(data_yaml_path),
"num_classes": data_cfg.get("nc", "unknown"),
"class_names": data_cfg.get("names", []),
"split_used": split,
}

# 统计图像数量
val_path = data_cfg.get(split, None)
if val_path:
val_img_dir = Path(data_yaml_path).parent / val_path
if val_img_dir.exists():
img_exts = {".jpg", ".jpeg", ".png", ".bmp", ".tiff"}
img_files = [
f for f in val_img_dir.rglob("*")
if f.suffix.lower() in img_exts
]
dataset_info["num_images"] = len(img_files)
dataset_info["image_dir"] = str(val_img_dir)
else:
dataset_info["num_images"] = "directory not found"

# 打印格式化信息
print("=" * 50)
print("数据集描述")
print("=" * 50)
print(f"类别数量: {dataset_info['num_classes']}")
print(f"类别列表: {', '.join(dataset_info['class_names'][:10])}{'…' if len(dataset_info['class_names']) > 10 else ''}")
print(f"测试划分: {split}")
print(f"图像数量: {dataset_info.get('num_images', 'N/A')}")

return dataset_info

def get_yolo_preprocessing_config(imgsz: int = 640) –> dict:
"""
记录 YOLOv12 标准预处理配置
这些参数必须写入报告，影响精度结果
"""
preprocess_config = {
"input_size": f"{imgsz}x{imgsz}",
"resize_method": "letterbox (保持长宽比，填充灰色边框，值为114)",
"normalization": "pixel_value / 255.0",
"mean_std": "不使用额外的 mean/std 归一化（与 ImageNet 预处理不同）",
"color_channel": "BGR->RGB（OpenCV 读取后转换）",
"data_type": "float32（推理时）或 float16（TensorRT FP16 时）",
}

print("\\n预处理配置:")
for k, v in preprocess_config.items():
print(f" {k}: {v}")

return preprocess_config

六、第四板块：测试方法与参数

这是整个报告中技术含量最高、也最容易出错的部分。测试方法不严谨，数字就没有意义。

精度测试的标准方法：

精度评估应直接使用 ultralytics 的 val 模式，不要自己手写评估逻辑。原因很简单——YOLOv12 的 mAP 计算遵循 COCO 官方标准，包含特定的面积过滤（small/medium/large）、IoU 阈值范围（0.5:0.05:0.95）等细节，手写极容易引入误差。

速度测试的标准方法：

速度测试有一套约定俗成的规范，违反这些规范会导致数据严重失真：

相关示意图绘制如下，仅供参考：

import time
import numpy as np
import torch
from ultralytics import YOLO
from contextlib import contextmanager

@contextmanager
def timer():
"""简单的计时上下文管理器"""
start = time.perf_counter()
yield
end = time.perf_counter()
return end – start

class BenchmarkRunner:
"""
YOLOv12 标准化 Benchmark 测试器
封装了精度评估和速度评估的完整流程
符合 YOLOv12 官方测试规范
"""

def __init__(self, model_path: str, device: str = "cuda:0"):
"""
Args:
model_path: 模型权重路径（.pt 或 .engine 等）
device: 推理设备
"""
self.model_path = model_path
self.device = device
self.model = YOLO(model_path)
print(f"[BenchmarkRunner] 模型加载完成: {model_path}")
print(f"[BenchmarkRunner] 推理设备: {device}")

def run_accuracy_benchmark(
self,
data: str,
imgsz: int = 640,
batch: int = 16,
conf: float = 0.001,
iou: float = 0.7,
split: str = "val",
save_json: bool = True,
) –> dict:
"""
运行精度 Benchmark

核心参数说明：
– conf=0.001: 验证时使用极低置信度阈值，确保不因阈值过高漏掉检测框，
最终 mAP 由 PR 曲线积分得出，不受此参数影响
– iou=0.7: NMS 的 IoU 阈值，影响重叠框的去除策略
– split="val": 使用验证集，不要用训练集评估，这是基本原则

Returns:
包含 mAP50、mAP50-95、Precision、Recall 等指标的字典
"""
print(f"\\n{'='*60}")
print(f"开始精度评估: {self.model_path}")
print(f"数据集: {data}, 输入尺寸: {imgsz}, Batch: {batch}")
print(f"{'='*60}")

results = self.model.val(
data=data,
imgsz=imgsz,
batch=batch,
conf=conf,
iou=iou,
device=self.device,
split=split,
save_json=save_json, # 保存 COCO 格式的预测结果
plots=True, # 生成可视化图表
verbose=True,
)

# 提取核心指标
accuracy_metrics = {
"mAP50": float(results.box.map50), # mAP@0.5
"mAP50_95": float(results.box.map), # mAP@0.5:0.95
"Precision": float(results.box.mp), # 平均精确率
"Recall": float(results.box.mr), # 平均召回率
"F1": 2 * float(results.box.mp) * float(results.box.mr) /
(float(results.box.mp) + float(results.box.mr) + 1e-9), # F1 分数
}

print(f"\\n精度评估结果:")
print(f" mAP@0.5: {accuracy_metrics['mAP50']:.4f}")
print(f" mAP@0.5:0.95: {accuracy_metrics['mAP50_95']:.4f}")
print(f" Precision: {accuracy_metrics['Precision']:.4f}")
print(f" Recall: {accuracy_metrics['Recall']:.4f}")
print(f" F1: {accuracy_metrics['F1']:.4f}")

return accuracy_metrics

def run_speed_benchmark(
self,
imgsz: int = 640,
batch: int = 1,
n_warmup: int = 10,
n_repeat: int = 200,
half: bool = False,
) –> dict:
"""
运行速度 Benchmark（符合工业界标准测试规范）

关键设计决策：
1. n_warmup=10: 预热10次，消除 CUDA JIT 编译带来的首次延迟
2. n_repeat=200: 重复200次，保证统计稳定性
3. torch.cuda.synchronize(): 确保 GPU 操作真正完成后再计时
4. 使用合成数据（随机张量），排除数据IO的干扰，专注测推理延迟

Args:
imgsz: 输入图像尺寸
batch: 批大小（单图推理时为1）
n_warmup: 预热次数
n_repeat: 正式测试次数
half: 是否使用 FP16（需要 GPU 支持）

Returns:
包含延迟均值、标准差、FPS 等的速度指标字典
"""
print(f"\\n{'='*60}")
print(f"开始速度测试: batch={batch}, imgsz={imgsz}, half={half}")
print(f"预热次数: {n_warmup}, 测试次数: {n_repeat}")
print(f"{'='*60}")

# 构造合成输入数据（避免磁盘 IO 干扰）
dtype = torch.float16 if half else torch.float32
dummy_input = torch.randn(batch, 3, imgsz, imgsz, dtype=dtype)

if "cuda" in self.device:
dummy_input = dummy_input.to(self.device)
# 如果模型使用 FP16，需要先转换模型
if half:
self.model.model.half()

# ===== 预热阶段 =====
print(f"预热中（{n_warmup} 次）…")
with torch.no_grad():
for _ in range(n_warmup):
_ = self.model.model(dummy_input)
if "cuda" in self.device:
torch.cuda.synchronize()

# ===== 正式测试阶段 =====
latencies_ms = []
print(f"正式测试中（{n_repeat} 次）…")

with torch.no_grad():
for i in range(n_repeat):
if "cuda" in self.device:
torch.cuda.synchronize() # 确保之前的 GPU 操作完成

t_start = time.perf_counter()
_ = self.model.model(dummy_input)

if "cuda" in self.device:
torch.cuda.synchronize() # 等待当前推理完成

t_end = time.perf_counter()
latencies_ms.append((t_end – t_start) * 1000) # 转换为毫秒

latencies = np.array(latencies_ms)

# ===== 统计分析 =====
speed_metrics = {
"batch_size": batch,
"imgsz": imgsz,
"precision": "FP16" if half else "FP32",
"latency_mean_ms": float(np.mean(latencies)),
"latency_std_ms": float(np.std(latencies)),
"latency_min_ms": float(np.min(latencies)),
"latency_max_ms": float(np.max(latencies)),
"latency_p50_ms": float(np.percentile(latencies, 50)),
"latency_p95_ms": float(np.percentile(latencies, 95)), # 95th 百分位，反映抖动
"latency_p99_ms": float(np.percentile(latencies, 99)), # 99th 百分位，反映尾延迟
"fps": float(batch * 1000 / np.mean(latencies)), # 吞吐量
}

# ===== 显存占用 =====
if "cuda" in self.device:
speed_metrics["gpu_memory_allocated_mb"] = round(
torch.cuda.memory_allocated(self.device) / 1024**2, 2
)
speed_metrics["gpu_memory_reserved_mb"] = round(
torch.cuda.memory_reserved(self.device) / 1024**2, 2
)

print(f"\\n速度测试结果:")
print(f" 延迟均值: {speed_metrics['latency_mean_ms']:.2f} ms")
print(f" 延迟标准差: {speed_metrics['latency_std_ms']:.2f} ms")
print(f" P50 延迟: {speed_metrics['latency_p50_ms']:.2f} ms")
print(f" P95 延迟: {speed_metrics['latency_p95_ms']:.2f} ms")
print(f" P99 延迟: {speed_metrics['latency_p99_ms']:.2f} ms")
print(f" FPS: {speed_metrics['fps']:.1f}")
if "gpu_memory_allocated_mb" in speed_metrics:
print(f" 显存占用: {speed_metrics['gpu_memory_allocated_mb']:.1f} MB")

return speed_metrics

为什么要记录 P95 和 P99 延迟，而不只是均值？

这个问题值得深入解释。在实际部署中，特别是视频流实时检测场景，偶发的高延迟帧（俗称"卡顿帧"）会严重影响用户体验。均值 15ms 的模型，如果 P99 延迟是 50ms，意味着每100帧里有1帧要等 50ms，折合到 30fps 的视频流上，差不多每3秒就有一次明显卡顿。而另一个均值同样是 15ms 但 P99 是 18ms 的模型，则几乎不会出现感知到的卡顿。这两个模型从均值来看毫无差别，但用户体验天差地别。

七、第五板块：精度评估结果

精度结果是 Benchmark 报告最核心的部分之一。这里我们设计了一套完整的精度结果记录模板：

import pandas as pd
import matplotlib.pyplot as plt
import matplotlib
import numpy as np
from pathlib import Path

# 设置字体（报告图表使用英文，避免中文字体问题）
matplotlib.rcParams['font.family'] = 'DejaVu Sans'
matplotlib.rcParams['axes.unicode_minus'] = False

def create_accuracy_report_table(results_dict: dict) –> pd.DataFrame:
"""
创建精度报告汇总表

results_dict 格式示例：
{
"YOLOv12n": {"mAP50": 0.478, "mAP50_95": 0.293, "Precision": 0.621, "Recall": 0.512, "Params_M": 2.6},
"YOLOv12s": {"mAP50": 0.583, "mAP50_95": 0.386, "Precision": 0.688, "Recall": 0.591, "Params_M": 9.3},
…
}
"""

# 构造 DataFrame
df = pd.DataFrame(results_dict).T
df.index.name = "Model"

# 格式化数值列
percentage_cols = ["mAP50", "mAP50_95", "Precision", "Recall"]
for col in percentage_cols:
if col in df.columns:
df[col] = df[col].apply(lambda x: f"{x:.4f}")

# 添加 F1 列
if "Precision" in results_dict[list(results_dict.keys())[0]]:
df["F1"] = [
f"{2 * float(row['Precision']) * float(row['Recall']) / (float(row['Precision']) + float(row['Recall']) + 1e-9):.4f}"
for _, row in df.iterrows()
]

return df

def plot_accuracy_comparison(results_dict: dict, save_path: str = "accuracy_comparison.png"):
"""
绘制精度对比雷达图和柱状图
图表元素使用英文（规范做法）
"""
models = list(results_dict.keys())

# ========== 图1：mAP 对比柱状图 ==========
fig, axes = plt.subplots(1, 2, figsize=(14, 6))
fig.suptitle("YOLOv12 Accuracy Benchmark – COCO val2017", fontsize=14, fontweight='bold')

# mAP@0.5 对比
map50_values = [results_dict[m]["mAP50"] for m in models]
map50_95_values = [results_dict[m]["mAP50_95"] for m in models]

x = np.arange(len(models))
width = 0.35

bars1 = axes[0].bar(x – width/2, map50_values, width, label='mAP@0.5', color='#2196F3', alpha=0.8)
bars2 = axes[0].bar(x + width/2, map50_95_values, width, label='mAP@0.5:0.95', color='#FF5722', alpha=0.8)

axes[0].set_xlabel("Model")
axes[0].set_ylabel("mAP")
axes[0].set_title("mAP Comparison")
axes[0].set_xticks(x)
axes[0].set_xticklabels(models, rotation=15)
axes[0].legend()
axes[0].grid(axis='y', alpha=0.3)
axes[0].set_ylim(0, 1.0)

# 在柱子上显示数值
for bar in bars1:
height = bar.get_height()
axes[0].annotate(f'{height:.3f}', xy=(bar.get_x() + bar.get_width()/2, height),
xytext=(0, 3), textcoords="offset points", ha='center', va='bottom', fontsize=8)
for bar in bars2:
height = bar.get_height()
axes[0].annotate(f'{height:.3f}', xy=(bar.get_x() + bar.get_width()/2, height),
xytext=(0, 3), textcoords="offset points", ha='center', va='bottom', fontsize=8)

# ========== 图2：P/R/F1 对比 ==========
precision_values = [results_dict[m]["Precision"] for m in models]
recall_values = [results_dict[m]["Recall"] for m in models]
f1_values = [
2 * results_dict[m]["Precision"] * results_dict[m]["Recall"] /
(results_dict[m]["Precision"] + results_dict[m]["Recall"] + 1e-9)
for m in models
]

x2 = np.arange(len(models))
width2 = 0.25

axes[1].bar(x2 – width2, precision_values, width2, label='Precision', color='#4CAF50', alpha=0.8)
axes[1].bar(x2, recall_values, width2, label='Recall', color='#FF9800', alpha=0.8)
axes[1].bar(x2 + width2, f1_values, width2, label='F1', color='#9C27B0', alpha=0.8)

axes[1].set_xlabel("Model")
axes[1].set_ylabel("Score")
axes[1].set_title("Precision / Recall / F1 Comparison")
axes[1].set_xticks(x2)
axes[1].set_xticklabels(models, rotation=15)
axes[1].legend()
axes[1].grid(axis='y', alpha=0.3)
axes[1].set_ylim(0, 1.0)

plt.tight_layout()
plt.savefig(save_path, dpi=150, bbox_inches='tight')
print(f"精度对比图已保存: {save_path}")
plt.show()

return fig

# ===== 示例数据（基于 YOLOv12 官方 COCO val2017 结果）=====
# 注意：以下数据来自 ultralytics 官方文档，实际测试结果以你的环境为准
example_accuracy_results = {
"YOLOv12n": {"mAP50": 0.475, "mAP50_95": 0.404, "Precision": 0.632, "Recall": 0.505, "Params_M": 2.6},
"YOLOv12s": {"mAP50": 0.538, "mAP50_95": 0.481, "Precision": 0.688, "Recall": 0.574, "Params_M": 9.3},
"YOLOv12m": {"mAP50": 0.579, "mAP50_95": 0.503, "Precision": 0.718, "Recall": 0.600, "Params_M": 20.2},
"YOLOv12l": {"mAP50": 0.595, "mAP50_95": 0.516, "Precision": 0.738, "Recall": 0.616, "Params_M": 26.4},
"YOLOv12x": {"mAP50": 0.610, "mAP50_95": 0.529, "Precision": 0.755, "Recall": 0.630, "Params_M": 59.1},
}

# 生成汇总表
acc_table = create_accuracy_report_table(example_accuracy_results)
print("精度评估汇总表:")
print(acc_table.to_string())

# 生成对比图
plot_accuracy_comparison(example_accuracy_results, "yolov12_accuracy_comparison.png")

八、第六板块：推理速度结果

速度结果同样需要结构化记录。这里有几个容易被忽略的细节：

后处理时间的归属问题：ultralytics 的 predict 模式会在结果里分别报告预处理、推理、后处理三段时间。Benchmark 报告中需要明确说明统计的是哪一段，还是三段之和（端到端延迟）。对于实际部署，我们通常关心端到端延迟。

batch size 的选择：实时视频检测通常使用 batch=1，离线批处理通常测 batch=8 或 batch=32。两个场景下的最优模型可能不同，不能混用。

不同导出格式的速度差异：PyTorch (.pt) → ONNX → TensorRT 的速度提升是阶梯式的，报告中应分别列出。

import pandas as pd
import matplotlib.pyplot as plt
import numpy as np

def create_speed_report_table(speed_results: dict) –> pd.DataFrame:
"""
创建速度测试汇总表

speed_results 格式：
{
"YOLOv12n-PyTorch": {"latency_ms": 5.2, "fps": 192, "gpu_mem_mb": 312, "format": "PyTorch"},
"YOLOv12n-TRT-FP16": {"latency_ms": 1.8, "fps": 555, "gpu_mem_mb": 218, "format": "TensorRT FP16"},
…
}
"""
records = []
for name, metrics in speed_results.items():
record = {"Model+Format": name}
record.update(metrics)
records.append(record)

df = pd.DataFrame(records).set_index("Model+Format")
return df

def plot_speed_comparison(speed_results: dict, save_path: str = "speed_comparison.png"):
"""
绘制速度对比图：延迟对比 + FPS 对比
"""
names = list(speed_results.keys())
latencies = [speed_results[n]["latency_ms"] for n in names]
fps_values = [speed_results[n]["fps"] for n in names]

fig, axes = plt.subplots(1, 2, figsize=(16, 6))
fig.suptitle("YOLOv12 Inference Speed Benchmark (A100, batch=1, imgsz=640)",
fontsize=12, fontweight='bold')

# 颜色映射：按格式区分
colors = []
for name in names:
if "TRT" in name or "TensorRT" in name:
colors.append("#FF5722")
elif "ONNX" in name:
colors.append("#2196F3")
else:
colors.append("#4CAF50")

# ===== 延迟柱状图（越低越好）=====
bars = axes[0].bar(range(len(names)), latencies, color=colors, alpha=0.85, edgecolor='white')
axes[0].set_title("Inference Latency (ms) — Lower is Better")
axes[0].set_ylabel("Latency (ms)")
axes[0].set_xticks(range(len(names)))
axes[0].set_xticklabels(names, rotation=45, ha='right', fontsize=8)
axes[0].grid(axis='y', alpha=0.3)

for bar, val in zip(bars, latencies):
axes[0].text(bar.get_x() + bar.get_width()/2., bar.get_height() + 0.1,
f'{val:.1f}', ha='center', va='bottom', fontsize=8, fontweight='bold')

# ===== FPS 柱状图（越高越好）=====
bars2 = axes[1].bar(range(len(names)), fps_values, color=colors, alpha=0.85, edgecolor='white')
axes[1].set_title("Throughput (FPS) — Higher is Better")
axes[1].set_ylabel("FPS (frames per second)")
axes[1].set_xticks(range(len(names)))
axes[1].set_xticklabels(names, rotation=45, ha='right', fontsize=8)
axes[1].grid(axis='y', alpha=0.3)

for bar, val in zip(bars2, fps_values):
axes[1].text(bar.get_x() + bar.get_width()/2., bar.get_height() + 5,
f'{val:.0f}', ha='center', va='bottom', fontsize=8, fontweight='bold')

# 添加图例
from matplotlib.patches import Patch
legend_elements = [
Patch(facecolor='#4CAF50', label='PyTorch (.pt)'),
Patch(facecolor='#2196F3', label='ONNX Runtime'),
Patch(facecolor='#FF5722', label='TensorRT'),
]
axes[0].legend(handles=legend_elements, loc='upper right')

plt.tight_layout()
plt.savefig(save_path, dpi=150, bbox_inches='tight')
print(f"速度对比图已保存: {save_path}")
plt.show()

# ===== 示例速度数据 =====
# 实际数据需在目标硬件上测试，此处为格式示例
example_speed_results = {
"YOLOv12n-PyTorch": {"latency_ms": 5.2, "fps": 192, "gpu_mem_mb": 312},
"YOLOv12n-ONNX": {"latency_ms": 4.1, "fps": 244, "gpu_mem_mb": 285},
"YOLOv12n-TRT-FP16": {"latency_ms": 1.8, "fps": 555, "gpu_mem_mb": 218},
"YOLOv12s-PyTorch": {"latency_ms": 8.6, "fps": 116, "gpu_mem_mb": 520},
"YOLOv12s-ONNX": {"latency_ms": 7.2, "fps": 139, "gpu_mem_mb": 498},
"YOLOv12s-TRT-FP16": {"latency_ms": 3.1, "fps": 323, "gpu_mem_mb": 412},
"YOLOv12m-PyTorch": {"latency_ms": 14.2, "fps": 70, "gpu_mem_mb": 892},
"YOLOv12m-TRT-FP16": {"latency_ms": 5.8, "fps": 172, "gpu_mem_mb": 680},
"YOLOv12l-PyTorch": {"latency_ms": 19.8, "fps": 50, "gpu_mem_mb": 1124},
"YOLOv12l-TRT-FP16": {"latency_ms": 8.2, "fps": 122, "gpu_mem_mb": 856},
"YOLOv12x-PyTorch": {"latency_ms": 35.4, "fps": 28, "gpu_mem_mb": 2048},
"YOLOv12x-TRT-FP16": {"latency_ms": 14.5, "fps": 69, "gpu_mem_mb": 1580},
}

speed_table = create_speed_report_table(example_speed_results)
print("\\n速度测试汇总表:")
print(speed_table.to_string())
plot_speed_comparison(example_speed_results)

九、第七板块：资源占用结果

资源占用是工程部署的"硬约束"——你可以接受精度低一点，可以接受速度慢一点，但如果模型跑不进显存，一切都是白搭。

资源占用需要记录的维度：

模型文件大小：影响模型传输、存储和加载时间。边缘端设备可能只有几 GB 的存储空间。

推理时显存峰值：这是能否在目标 GPU 上运行的硬门槛。需要测试不同 batch size 下的显存峰值，因为显存是随 batch 线性增长的（通常）。

CPU 内存占用：即使使用 GPU 推理，CPU 内存也会占用（模型权重会在 CPU 内存中保留一份）。

参数量与 FLOPs：理论复杂度指标，用于跨硬件对比。

import os
import torch
import numpy as np
from pathlib import Path
from ultralytics import YOLO

def measure_model_resources(model_path: str, imgsz: int = 640, device: str = "cuda:0") –> dict:
"""
全面测量模型资源占用

测量维度：
1. 模型文件大小（磁盘）
2. 参数量
3. 推理时 GPU 显存峰值（不同 batch）
4. FLOPs（通过 thop 库计算）

Args:
model_path: 模型路径
imgsz: 输入尺寸
device: 目标设备
"""
resources = {}

# ===== 1. 文件大小 =====
file_size_bytes = os.path.getsize(model_path)
resources["model_file_size_mb"] = round(file_size_bytes / 1024**2, 2)
print(f"模型文件大小: {resources['model_file_size_mb']} MB")

# ===== 2. 加载模型 =====
model = YOLO(model_path)
pytorch_model = model.model

# ===== 3. 参数量统计 =====
total_params = sum(p.numel() for p in pytorch_model.parameters())
trainable_params = sum(p.numel() for p in pytorch_model.parameters() if p.requires_grad)
resources["total_params_M"] = round(total_params / 1e6, 2)
resources["trainable_params_M"] = round(trainable_params / 1e6, 2)
print(f"总参数量: {resources['total_params_M']} M")
print(f"可训练参数量: {resources['trainable_params_M']} M")

# ===== 4. FLOPs 计算 =====
try:
from thop import profile, clever_format
dummy_input = torch.zeros(1, 3, imgsz, imgsz)
macs, params = profile(pytorch_model.cpu(), inputs=(dummy_input,), verbose=False)
flops = macs * 2 # MACs * 2 = FLOPs（乘加各算一次）
resources["GFLOPs"] = round(flops / 1e9, 2)
print(f"GFLOPs: {resources['GFLOPs']}")
except ImportError:
resources["GFLOPs"] = "需安装 thop: pip install thop"
except Exception as e:
resources["GFLOPs"] = f"计算失败: {str(e)}"

# ===== 5. 显存峰值（不同 batch）=====
if torch.cuda.is_available() and "cuda" in device:
pytorch_model = pytorch_model.to(device)
pytorch_model.eval()
resources["gpu_memory_by_batch"] = {}

for batch in [1, 2, 4, 8, 16, 32]:
try:
torch.cuda.reset_peak_memory_stats(device) # 重置峰值记录
torch.cuda.empty_cache()

dummy = torch.zeros(batch, 3, imgsz, imgsz).to(device)
with torch.no_grad():
_ = pytorch_model(dummy)
torch.cuda.synchronize()

peak_mem_mb = torch.cuda.max_memory_allocated(device) / 1024**2
resources["gpu_memory_by_batch"][f"batch_{batch}"] = round(peak_mem_mb, 1)
print(f" GPU 显存峰值 (batch={batch}): {peak_mem_mb:.1f} MB")

except torch.cuda.OutOfMemoryError:
resources["gpu_memory_by_batch"][f"batch_{batch}"] = "OOM"
print(f" GPU 显存峰值 (batch={batch}): OOM")
torch.cuda.empty_cache()
break

return resources

def plot_resource_overview(resource_data: dict, save_path: str = "resource_overview.png"):
"""
绘制各模型规格的资源占用概览图

resource_data 格式：
{
"YOLOv12n": {"Params_M": 2.6, "GFLOPs": 6.5, "Size_MB": 5.4, "VRAM_MB": 312},
…
}
"""
models = list(resource_data.keys())
params = [resource_data[m]["Params_M"] for m in models]
gflops = [resource_data[m]["GFLOPs"] for m in models]
sizes = [resource_data[m]["Size_MB"] for m in models]
vram = [resource_data[m]["VRAM_MB"] for m in models]

fig, axes = plt.subplots(2, 2, figsize=(14, 10))
fig.suptitle("YOLOv12 Resource Usage Overview", fontsize=14, fontweight='bold')

colors = ['#1E88E5', '#43A047', '#FB8C00', '#E53935', '#8E24AA']

# 参数量
axes[0,0].bar(models, params, color=colors, alpha=0.85)
axes[0,0].set_title("Parameters (M)")
axes[0,0].set_ylabel("Params (M)")
axes[0,0].grid(axis='y', alpha=0.3)
for i, v in enumerate(params):
axes[0,0].text(i, v + 0.2, f'{v}M', ha='center', fontsize=9, fontweight='bold')

# FLOPs
axes[0,1].bar(models, gflops, color=colors, alpha=0.85)
axes[0,1].set_title("GFLOPs")
axes[0,1].set_ylabel("GFLOPs")
axes[0,1].grid(axis='y', alpha=0.3)
for i, v in enumerate(gflops):
axes[0,1].text(i, v + 0.5, f'{v}G', ha='center', fontsize=9, fontweight='bold')

# 模型文件大小
axes[1,0].bar(models, sizes, color=colors, alpha=0.85)
axes[1,0].set_title("Model File Size (MB)")
axes[1,0].set_ylabel("Size (MB)")
axes[1,0].grid(axis='y', alpha=0.3)
for i, v in enumerate(sizes):
axes[1,0].text(i, v + 0.3, f'{v}MB', ha='center', fontsize=9, fontweight='bold')

# 显存占用
axes[1,1].bar(models, vram, color=colors, alpha=0.85)
axes[1,1].set_title("GPU Memory (MB, batch=1)")
axes[1,1].set_ylabel("VRAM (MB)")
axes[1,1].grid(axis='y', alpha=0.3)
for i, v in enumerate(vram):
axes[1,1].text(i, v + 10, f'{v}MB', ha='center', fontsize=9, fontweight='bold')

plt.tight_layout()
plt.savefig(save_path, dpi=150, bbox_inches='tight')
print(f"资源概览图已保存: {save_path}")
plt.show()

# 示例资源数据
example_resource_data = {
"YOLOv12n": {"Params_M": 2.6, "GFLOPs": 6.5, "Size_MB": 5.4, "VRAM_MB": 312},
"YOLOv12s": {"Params_M": 9.3, "GFLOPs": 21.5, "Size_MB": 18.9, "VRAM_MB": 520},
"YOLOv12m": {"Params_M": 20.2, "GFLOPs": 67.5, "Size_MB": 40.9, "VRAM_MB": 892},
"YOLOv12l": {"Params_M": 26.4, "GFLOPs": 88.9, "Size_MB": 53.5, "VRAM_MB": 1124},
"YOLOv12x": {"Params_M": 59.1, "GFLOPs": 199.0, "Size_MB": 119.8, "VRAM_MB": 2048},
}

plot_resource_overview(example_resource_data)

十、第八板块：综合对比分析——雷达图与帕累托分析

有了精度数据、速度数据、资源数据，下一步是进行综合对比分析。这是报告中最考验分析能力的部分，也是帮助决策者快速抓住重点的关键。

雷达图是多维度对比的经典工具，但有一个容易踩的坑：不同维度的量纲不同（mAP 是 0~1，FPS 是几到几百），需要归一化处理后才能放在同一个雷达图上。

**帕累托前沿（Pareto Frontier）**分析则更有工程意义——它能帮你找到"在给定速度约束下精度最高的模型"或"在给定精度约束下速度最快的模型"。

import numpy as np
import matplotlib.pyplot as plt
from matplotlib.patches import FancyArrowPatch

def plot_radar_chart(models_data: dict, save_path: str = "radar_chart.png"):
"""
绘制多维度对比雷达图
注意：所有维度需要归一化到 [0, 1]，越大越好

对于"越小越好"的指标（如延迟、参数量），需要取倒数或反向归一化
"""
# 定义评估维度（全部转为"越大越好"）
dimensions = ['mAP@0.5:0.95', 'Speed\\n(1/Latency)', 'Param\\nEfficiency', 'Memory\\nEfficiency']

# 原始数据
raw_data = {
"YOLOv12n": {
"mAP50_95": 0.404,
"latency_ms": 5.2, # 越小越好
"params_M": 2.6, # 越小越好
"vram_mb": 312, # 越小越好
},
"YOLOv12s": {"mAP50_95": 0.481, "latency_ms": 8.6, "params_M": 9.3, "vram_mb": 520},
"YOLOv12m": {"mAP50_95": 0.503, "latency_ms": 14.2, "params_M": 20.2, "vram_mb": 892},
"YOLOv12l": {"mAP50_95": 0.516, "latency_ms": 19.8, "params_M": 26.4, "vram_mb": 1124},
"YOLOv12x": {"mAP50_95": 0.529, "latency_ms": 35.4, "params_M": 59.1, "vram_mb": 2048},
}

models = list(raw_data.keys())

# 归一化函数
def normalize_higher_better(values):
"""越大越好，归一化到 [0,1]"""
mn, mx = min(values), max(values)
return [(v – mn) / (mx – mn + 1e-9) for v in values]

def normalize_lower_better(values):
"""越小越好，转换后归一化到 [0,1]"""
mn, mx = min(values), max(values)
return [(mx – v) / (mx – mn + 1e-9) for v in values]

# 提取各维度数据
map_vals = [raw_data[m]["mAP50_95"] for m in models]
speed_vals = [raw_data[m]["latency_ms"] for m in models] # 越小越好
param_vals = [raw_data[m]["params_M"] for m in models] # 越小越好
vram_vals = [raw_data[m]["vram_mb"] for m in models] # 越小越好

# 归一化
norm_map = normalize_higher_better(map_vals)
norm_speed = normalize_lower_better(speed_vals)
norm_param = normalize_lower_better(param_vals)
norm_vram = normalize_lower_better(vram_vals)

# 构建雷达图数据
N = len(dimensions)
angles = np.linspace(0, 2 * np.pi, N, endpoint=False).tolist()
angles += angles[:1] # 闭合

fig, ax = plt.subplots(figsize=(9, 9), subplot_kw=dict(polar=True))

colors_radar = ['#1E88E5', '#43A047', '#FB8C00', '#E53935', '#8E24AA']

for idx, model in enumerate(models):
values = [norm_map[idx], norm_speed[idx], norm_param[idx], norm_vram[idx]]
values += values[:1] # 闭合

ax.plot(angles, values, 'o-', linewidth=2, color=colors_radar[idx],
label=model, markersize=6)
ax.fill(angles, values, alpha=0.1, color=colors_radar[idx])

ax.set_xticks(angles[:–1])
ax.set_xticklabels(dimensions, size=11)
ax.set_ylim(0, 1)
ax.set_yticks([0.25, 0.5, 0.75, 1.0])
ax.set_yticklabels(['0.25', '0.50', '0.75', '1.00'], size=8)
ax.grid(True, alpha=0.3)
ax.set_title("YOLOv12 Multi-dimensional Comparison\\n(All axes: higher = better, normalized)",
size=13, fontweight='bold', pad=20)
ax.legend(loc='upper right', bbox_to_anchor=(1.35, 1.1), fontsize=10)

plt.tight_layout()
plt.savefig(save_path, dpi=150, bbox_inches='tight')
print(f"雷达图已保存: {save_path}")
plt.show()

def plot_pareto_frontier(
accuracy_data: dict,
speed_data: dict,
save_path: str = "pareto_frontier.png"
):
"""
绘制精度-速度帕累托前沿图
帕累托前沿：在速度（FPS）相同时，精度最高的点的集合

这是工程决策中最直观的对比方式：
帕累托前沿上的点表示"无法在不牺牲某一维度的情况下改善另一维度"
"""
models = list(accuracy_data.keys())
map_values = [accuracy_data[m]["mAP50_95"] for m in models]
fps_values = [speed_data.get(m, {}).get("fps", 0) for m in models]

# 计算帕累托前沿
def is_pareto_optimal(costs):
"""
找出帕累托最优点
costs: (n_points, n_objectives) 数组，假设越大越好
返回布尔数组，True 表示该点在帕累托前沿上
"""
is_efficient = np.ones(len(costs), dtype=bool)
for i, c in enumerate(costs):
if is_efficient[i]:
# 如果有其他点在所有维度上都不差于当前点且至少一个维度更好，则当前点不是帕累托最优
is_efficient[is_efficient] = np.any(
costs[is_efficient] > c, axis=1
)
is_efficient[i] = True
return is_efficient

costs_array = np.array(list(zip(fps_values, map_values)))
pareto_mask = is_pareto_optimal(costs_array)

fig, ax = plt.subplots(figsize=(12, 8))

colors_scatter = ['#1E88E5', '#43A047', '#FB8C00', '#E53935', '#8E24AA']

for i, model in enumerate(models):
marker = '*' if pareto_mask[i] else 'o'
size = 300 if pareto_mask[i] else 120
ax.scatter(fps_values[i], map_values[i],
c=colors_scatter[i], s=size, marker=marker,
label=model, zorder=5, edgecolors='black', linewidth=1.5)
ax.annotate(model, (fps_values[i], map_values[i]),
textcoords="offset points", xytext=(10, 5),
fontsize=9, fontweight='bold')

# 绘制帕累托前沿连线
pareto_points = [(fps_values[i], map_values[i]) for i in range(len(models)) if pareto_mask[i]]
pareto_points.sort(key=lambda x: x[0])
if len(pareto_points) > 1:
px, py = zip(*pareto_points)
ax.plot(px, py, 'k–', alpha=0.4, linewidth=1.5, label='Pareto Frontier')

ax.set_xlabel("Inference Speed (FPS) — Higher is Better", fontsize=12)
ax.set_ylabel("mAP@0.5:0.95 — Higher is Better", fontsize=12)
ax.set_title("YOLOv12 Accuracy-Speed Pareto Frontier\\n(★ = Pareto Optimal, batch=1, A100 GPU)",
fontsize=13, fontweight='bold')
ax.legend(fontsize=10)
ax.grid(True, alpha=0.3)

# 添加象限注释
ax.annotate("Best Balance Zone", xy=(0.65, 0.92), xycoords='axes fraction',
fontsize=10, color='gray', style='italic')

plt.tight_layout()
plt.savefig(save_path, dpi=150, bbox_inches='tight')
print(f"帕累托前沿图已保存: {save_path}")
plt.show()

# 运行示例
plot_radar_chart({}) # 函数内已包含示例数据

example_map_data = {
"YOLOv12n": {"mAP50_95": 0.404},
"YOLOv12s": {"mAP50_95": 0.481},
"YOLOv12m": {"mAP50_95": 0.503},
"YOLOv12l": {"mAP50_95": 0.516},
"YOLOv12x": {"mAP50_95": 0.529},
}

example_fps_data = {
"YOLOv12n": {"fps": 192},
"YOLOv12s": {"fps": 116},
"YOLOv12m": {"fps": 70},
"YOLOv12l": {"fps": 50},
"YOLOv12x": {"fps": 28},
}

plot_pareto_frontier(example_map_data, example_fps_data)

十一、第九板块：结论与建议

结论与建议是整个报告的"落地"部分。它的受众往往不是写报告的工程师自己，而是需要做决策的技术负责人、产品经理，甚至客户。

好的结论有几个特点：

具体：不是"YOLOv12n 速度很快"，而是"YOLOv12n 在 A100 TensorRT FP16 下的单帧推理延迟为 1.8ms，可支持 555fps 的实时吞吐量，满足高清摄像头 30fps 实时检测需求并有充足余量。"

有条件：结论永远是"在 X 条件下，Y 是最优选择"，而不是无条件的"Y 最好"。

可操作：给出下一步行动建议，比如"建议在 RTX 3080 上进行 INT8 量化测试以进一步验证边缘端可行性"。

有风险提示：没有完美的模型，要诚实地指出局限性，比如"YOLOv12n 在小目标（面积 < 32×32 像素）上的检测率较低，如果场景中小目标占比高，建议提高输入分辨率或考虑 YOLOv12s。"

def generate_conclusion_template(
scenario: str,
recommended_model: str,
recommended_format: str,
key_metrics: dict,
limitations: list,
next_steps: list,
) –> str:
"""
生成结论与建议模板文本
这是报告中最重要的"人话"部分，帮助决策者快速抓住要点

Args:
scenario: 应用场景描述
recommended_model: 推荐的模型规格
recommended_format: 推荐的部署格式
key_metrics: 关键指标字典
limitations: 局限性列表
next_steps: 下一步建议列表

Returns:
格式化的结论文本
"""

conclusion = f"""
# 结论与建议

## 应用场景
{scenario}

## 推荐方案
**推荐模型**：{recommended_model}
**推荐格式**：{recommended_format}

## 关键指标摘要
| 指标 | 数值 |
|——|——|
"""
for metric, value in key_metrics.items():
conclusion += f"| {metric} | {value} |\\n"

conclusion += "\\n## 推荐理由\\n"
conclusion += f"在本次 Benchmark 测试中，{recommended_model} 在精度-速度-资源三维度上取得了最佳平衡：\\n"
conclusion += f"- 精度方面，mAP@0.5:0.95 达到 {key_metrics.get('mAP@0.5:0.95', 'N/A')}，满足场景精度需求\\n"
conclusion += f"- 速度方面，单帧推理延迟 {key_metrics.get('推理延迟', 'N/A')}，满足实时性要求\\n"
conclusion += f"- 资源方面，显存占用 {key_metrics.get('GPU显存', 'N/A')}，在目标硬件约束内\\n"

conclusion += "\\n## 局限性与注意事项\\n"
for i, limitation in enumerate(limitations, 1):
conclusion += f"{i}. {limitation}\\n"

conclusion += "\\n## 下一步行动建议\\n"
for i, step in enumerate(next_steps, 1):
conclusion += f"{i}. {step}\\n"

return conclusion

# 生成示例结论
example_conclusion = generate_conclusion_template(
scenario="城市道路行人车辆检测，要求实时处理 1080P 视频流（30fps），部署硬件为 Jetson Orin NX 8GB",
recommended_model="YOLOv12s",
recommended_format="TensorRT FP16 (.engine)",
key_metrics={
"mAP@0.5:0.95": "0.481",
"推理延迟": "3.1ms",
"FPS": "323",
"GPU显存": "412MB",
"模型文件大小": "18.9MB",
},
limitations=[
"YOLOv12s 在夜间低光照场景下精度有一定下降，建议额外收集夜间数据进行微调",
"当前测试基于 COCO 数据集，迁移到特定道路场景可能需要 domain adaptation",
"TensorRT 引擎文件与具体 GPU 和 TensorRT 版本绑定，换硬件需重新导出",
"INT8 量化效果未经验证，如需进一步提速应单独测试精度损失",
],
next_steps=[
"在 Jetson Orin NX 8GB 目标硬件上复现本 Benchmark（本次在 A100 上测试）",
"采集200+张真实道路场景图像，评估模型在 domain shift 下的精度表现",
"如精度不足，考虑在目标场景数据上进行 50 epoch 的微调（fine-tuning）",
"评估 INT8 量化方案，若精度损失在 1% mAP 以内，可进一步降低推理延迟",
"完成部署后设置监控告警：延迟超过 5ms 或 GPU 温度超过 80°C 时告警",
]
)

print(example_conclusion)

十二、第十板块：完整自动化 Benchmark 流水线

前面的各个板块相对独立，真正工程化的做法是把它们串联成一条自动化流水线，一键运行，自动生成完整报告。

相关示意图绘制如下，仅供参考：

import yaml
import json
import time
import pandas as pd
import numpy as np
from pathlib import Path
from datetime import datetime
from ultralytics import YOLO
import torch

class YOLOv12BenchmarkPipeline:
"""
YOLOv12 Benchmark 完整自动化流水线

使用方法：
pipeline = YOLOv12BenchmarkPipeline(config_path="benchmark_config.yaml")
pipeline.run()

生成产物：
– benchmark_results/
├── report.html # 主报告（HTML 格式）
├── results.csv # 原始结果数据
├── environment.json # 环境信息
├── accuracy_comparison.png
├── speed_comparison.png
├── resource_overview.png
├── radar_chart.png
├── pareto_frontier.png
└── reproduce.sh # 复现脚本
"""

def __init__(self, config_path: str = None, output_dir: str = "benchmark_results"):
"""
初始化流水线

Args:
config_path: 配置文件路径，为 None 时使用默认配置
output_dir: 结果输出目录
"""
self.output_dir = Path(output_dir)
self.output_dir.mkdir(parents=True, exist_ok=True)

# 加载配置
if config_path and Path(config_path).exists():
with open(config_path, "r") as f:
self.config = yaml.safe_load(f)
else:
# 默认配置
self.config = self._default_config()

# 结果存储
self.results = {
"meta": {},
"environment": {},
"accuracy": {},
"speed": {},
"resources": {},
}

print(f"[Pipeline] 初始化完成，结果将保存至: {self.output_dir.absolute()}")

def _default_config(self) –> dict:
"""返回默认测试配置"""
return {
"report": {
"title": "YOLOv12 Benchmark Report",
"author": "Unknown",
"purpose": "性能评估",
},
"models": [
{"path": "yolov12n.pt", "name": "YOLOv12n"},
{"path": "yolov12s.pt", "name": "YOLOv12s"},
{"path": "yolov12m.pt", "name": "YOLOv12m"},
],
"accuracy": {
"data": "coco.yaml",
"imgsz": 640,
"batch": 16,
"conf": 0.001,
"iou": 0.7,
"split": "val",
},
"speed": {
"imgsz": 640,
"batch_sizes": [1, 8],
"n_warmup": 10,
"n_repeat": 200,
"half": True,
},
"device": "cuda:0" if torch.cuda.is_available() else "cpu",
}

def step1_collect_environment(self):
"""步骤1：收集环境信息"""
print("\\n" + "="*60)
print("步骤 1/6: 收集环境信息")
print("="*60)

import platform
import subprocess

env = {
"timestamp": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
"os": platform.platform(),
"python": platform.python_version(),
}

try:
import torch
env["torch"] = torch.__version__
env["cuda"] = torch.version.cuda
if torch.cuda.is_available():
gpu = torch.cuda.get_device_properties(0)
env["gpu"] = {
"name": gpu.name,
"memory_gb": round(gpu.total_memory / 1024**3, 1),
"compute_capability": f"{gpu.major}.{gpu.minor}",
}
except Exception as e:
env["torch_error"] = str(e)

try:
import ultralytics
env["ultralytics"] = ultralytics.__version__
except ImportError:
pass

self.results["environment"] = env

# 保存环境信息
env_path = self.output_dir / "environment.json"
with open(env_path, "w", encoding="utf-8") as f:
json.dump(env, f, indent=2, ensure_ascii=False)

print(f" 环境信息已保存: {env_path}")
return env

def step2_run_accuracy_benchmark(self):
"""步骤2：精度测试"""
print("\\n" + "="*60)
print("步骤 2/6: 精度测试")
print("="*60)

acc_config = self.config["accuracy"]

for model_cfg in self.config["models"]:
model_name = model_cfg["name"]
model_path = model_cfg["path"]

print(f"\\n 测试模型: {model_name}")

try:
model = YOLO(model_path)
results = model.val(
data=acc_config["data"],
imgsz=acc_config["imgsz"],
batch=acc_config["batch"],
conf=acc_config["conf"],
iou=acc_config["iou"],
device=self.config["device"],
split=acc_config["split"],
verbose=False,
plots=False, # 不生成图表，我们自己绘制
)

self.results["accuracy"][model_name] = {
"mAP50": float(results.box.map50),
"mAP50_95": float(results.box.map),
"Precision": float(results.box.mp),
"Recall": float(results.box.mr),
"F1": float(
2 * results.box.mp * results.box.mr /
(results.box.mp + results.box.mr + 1e-9)
),
}
print(f" mAP@0.5: {self.results['accuracy'][model_name]['mAP50']:.4f}")
print(f" mAP@0.5:0.95: {self.results['accuracy'][model_name]['mAP50_95']:.4f}")

except FileNotFoundError:
print(f" 警告: 模型文件不存在 {model_path}，跳过")
self.results["accuracy"][model_name] = {"error": "model not found"}
except Exception as e:
print(f" 错误: {e}")
self.results["accuracy"][model_name] = {"error": str(e)}

def step3_run_speed_benchmark(self):
"""步骤3：速度测试"""
print("\\n" + "="*60)
print("步骤 3/6: 速度测试")
print("="*60)

speed_config = self.config["speed"]
device = self.config["device"]

for model_cfg in self.config["models"]:
model_name = model_cfg["name"]
model_path = model_cfg["path"]

print(f"\\n 测试模型: {model_name}")
self.results["speed"][model_name] = {}

try:
model = YOLO(model_path)
pytorch_model = model.model.to(device)
pytorch_model.eval()

for batch in speed_config["batch_sizes"]:
imgsz = speed_config["imgsz"]
dtype = torch.float16 if speed_config["half"] and "cuda" in device else torch.float32

dummy_input = torch.randn(batch, 3, imgsz, imgsz, dtype=dtype).to(device)

# 预热
with torch.no_grad():
for _ in range(speed_config["n_warmup"]):
_ = pytorch_model(dummy_input)
if "cuda" in device:
torch.cuda.synchronize()

# 正式测试
latencies = []
with torch.no_grad():
for _ in range(speed_config["n_repeat"]):
if "cuda" in device:
torch.cuda.synchronize()
t0 = time.perf_counter()
_ = pytorch_model(dummy_input)
if "cuda" in device:
torch.cuda.synchronize()
latencies.append((time.perf_counter() – t0) * 1000)

latencies = np.array(latencies)
key = f"batch{batch}"
self.results["speed"][model_name][key] = {
"batch_size": batch,
"latency_mean_ms": float(np.mean(latencies)),
"latency_std_ms": float(np.std(latencies)),
"latency_p95_ms": float(np.percentile(latencies, 95)),
"fps": float(batch * 1000 / np.mean(latencies)),
}
print(f" batch={batch}: {np.mean(latencies):.2f}ms, {batch*1000/np.mean(latencies):.1f}fps")

except FileNotFoundError:
print(f" 警告: 模型文件不存在 {model_path}，跳过")
except Exception as e:
print(f" 错误: {e}")

def step4_collect_resources(self):
"""步骤4：资源信息收集"""
print("\\n" + "="*60)
print("步骤 4/6: 资源信息收集")
print("="*60)

for model_cfg in self.config["models"]:
model_name = model_cfg["name"]
model_path = model_cfg["path"]

print(f"\\n 收集模型资源: {model_name}")

resources = {}

try:
# 文件大小
if Path(model_path).exists():
resources["file_size_mb"] = round(Path(model_path).stat().st_size / 1024**2, 2)

# 参数量
model = YOLO(model_path)
total_params = sum(p.numel() for p in model.model.parameters())
resources["params_M"] = round(total_params / 1e6, 2)

self.results["resources"][model_name] = resources
print(f" 文件大小: {resources.get('file_size_mb', 'N/A')} MB")
print(f" 参数量: {resources['params_M']} M")

except FileNotFoundError:
print(f" 警告: 模型文件不存在，跳过")
except Exception as e:
print(f" 错误: {e}")

def step5_generate_visualizations(self):
"""步骤5：生成可视化图表"""
print("\\n" + "="*60)
print("步骤 5/6: 生成可视化图表")
print("="*60)

import matplotlib.pyplot as plt
import matplotlib
matplotlib.use('Agg') # 非交互式后端，适合自动化脚本

# 过滤掉有错误的模型
valid_models = [
m for m in self.results["accuracy"]
if "error" not in self.results["accuracy"][m]
]

if not valid_models:
print(" 没有有效的精度数据，跳过图表生成")
return

# 精度对比图
fig, axes = plt.subplots(1, 2, figsize=(14, 6))
fig.suptitle("YOLOv12 Benchmark Results", fontsize=14, fontweight='bold')

map50_vals = [self.results["accuracy"][m]["mAP50"] for m in valid_models]
map95_vals = [self.results["accuracy"][m]["mAP50_95"] for m in valid_models]

x = np.arange(len(valid_models))
axes[0].bar(x – 0.2, map50_vals, 0.4, label='mAP@0.5', color='#2196F3', alpha=0.85)
axes[0].bar(x + 0.2, map95_vals, 0.4, label='mAP@0.5:0.95', color='#FF5722', alpha=0.85)
axes[0].set_xticks(x)
axes[0].set_xticklabels(valid_models, rotation=15)
axes[0].set_ylabel("mAP")
axes[0].set_title("Accuracy Comparison")
axes[0].legend()
axes[0].grid(axis='y', alpha=0.3)

# 速度对比图（batch=1）
valid_speed_models = [
m for m in valid_models
if m in self.results["speed"] and "batch1" in self.results["speed"].get(m, {})
]

if valid_speed_models:
fps_vals = [self.results["speed"][m]["batch1"]["fps"] for m in valid_speed_models]
axes[1].bar(valid_speed_models, fps_vals, color='#4CAF50', alpha=0.85)
axes[1].set_ylabel("FPS (batch=1)")
axes[1].set_title("Speed Comparison (batch=1)")
axes[1].grid(axis='y', alpha=0.3)
for i, v in enumerate(fps_vals):
axes[1].text(i, v + 2, f'{v:.0f}', ha='center', fontsize=9, fontweight='bold')

plt.tight_layout()
save_path = self.output_dir / "benchmark_overview.png"
plt.savefig(save_path, dpi=150, bbox_inches='tight')
plt.close()
print(f" 总览图已保存: {save_path}")

def step6_generate_report(self):
"""步骤6：生成最终报告（HTML格式）"""
print("\\n" + "="*60)
print("步骤 6/6: 生成最终报告")
print("="*60)

# 保存原始数据 CSV
all_records = []
for model_name in self.results["accuracy"]:
record = {"model": model_name}
if "error" not in self.results["accuracy"][model_name]:
record.update(self.results["accuracy"][model_name])
if model_name in self.results["speed"] and "batch1" in self.results["speed"][model_name]:
spd = self.results["speed"][model_name]["batch1"]
record["latency_ms"] = spd["latency_mean_ms"]
record["fps"] = spd["fps"]
if model_name in self.results["resources"]:
record.update(self.results["resources"][model_name])
all_records.append(record)