YOLOv8检测结果保存详解：JSON/TXT/视频全格式教学

你是不是也遇到过这样的情况？刚跑完YOLOv8的目标检测模型，满心期待地打开输出文件夹，却发现不知道怎么把检测结果保存下来。实习生小李最近就碰上了这个难题——领导让他整理一批监控视频的检测数据，要求分别导出为文本、JSON和带标注的视频文件，可他连参数都不知道在哪设，急得直挠头。

别慌！这其实是每个刚接触YOLOv8的人都会踩的坑。Ultralytics官方虽然提供了丰富的保存选项，但文档分散、参数繁多，新手很容易搞混。其实只要掌握几个关键参数和操作逻辑，无论是单张图片、批量图像还是整段视频，都能轻松实现多种格式的结果导出。

本文就是为你量身打造的一站式解决方案。我会像老同事带新人那样，手把手教你如何用CSDN星图平台上的YOLOv8镜像，快速部署并完成各类检测结果的保存任务。从最基础的save_txt到复杂的视频写入流程，再到结构化数据导出，每一个步骤都配有可直接复制的命令和真实场景示例。哪怕你是第一次用YOLOv8，也能在30分钟内搞定所有格式的输出需求。

更重要的是，这些方法不仅适用于你现在手头的任务，还能迁移到未来各种项目中——比如智能巡检、行为分析、违禁品识别等需要数据留存与复审的场景。看完这篇，你会彻底告别“结果去哪了”的困惑，真正把模型输出变成可用的数据资产。

1. 环境准备与YOLOv8基础运行

1.1 如何快速启动YOLOv8镜像环境

在开始之前，我们先解决最实际的问题：怎么最快跑起来YOLOv8？如果你还在折腾conda环境、CUDA版本或者pip依赖，那效率肯定跟不上工作节奏。推荐使用CSDN星图提供的预置YOLOv8镜像，一键部署就能进入开发状态。

当你在平台上选择YOLOv8相关镜像后，系统会自动配置好PyTorch、CUDA、OpenCV以及Ultralytics库，省去了手动安装可能遇到的各种报错。部署完成后，你可以通过Jupyter Lab或终端直接运行代码，整个过程就像打开一个已经装好Office的电脑，插上U盘就能办公。

举个例子，假设你要处理一批校园监控截图中的异常行为检测任务。传统方式你需要先确认Python版本是否兼容，再逐个安装ultralytics、torchvision等包，稍有不慎就会出现“DLL load failed”这类让人崩溃的错误。而使用预置镜像，你只需要输入一行命令：

yolo detect predict model=yolov8s.pt source=./data/images/

系统就会自动加载模型并对指定目录下的所有图片进行推理。这就是现代AI开发的正确姿势——专注业务逻辑，而不是被环境问题拖累进度。

⚠️ 注意
首次运行时建议先测试一张图片，确保路径无误。如果提示“model not found”，说明模型权重未下载，程序通常会自动从云端获取，保持网络畅通即可。

1.2 YOLOv8默认输出结构解析

当你执行完上面那条命令，会在当前目录下看到一个runs/detect/predict（或predict2, predict3…）的文件夹。这里面就是YOLOv8默认生成的结果。我们来拆解一下它的内容结构：

image0.jpg,image1.jpg：这是原始图片加上边界框和标签后的可视化结果。
labels/子文件夹：如果启用了save_txt，这里会存放每张图对应的.txt文件，记录检测框坐标。
results.csv：包含整体性能统计，如mAP、precision、recall等指标。
confusion_matrix.png：分类混淆矩阵图表，帮助评估类别区分效果。

你会发现，默认情况下YOLOv8只会保存带框的图片，其他格式都需要手动开启参数。这也是为什么很多人跑完模型后“找不到数据”的原因——不是没生成，而是没开开关。

打个比方，这就像是相机拍照，默认只存照片，但如果你想同时记录GPS位置、拍摄时间戳、光圈快门等元数据，就得提前设置好EXIF保存选项。YOLOv8的保存机制也是类似的思路：功能都有，但要按需启用。

接下来我们要做的，就是把这些“隐藏功能”一个个打开，并且让它们按照你的要求输出成特定格式。

1.3 快速验证模型是否正常工作的技巧

在正式导出数据前，一定要先确认模型本身是正常工作的。我见过太多人花几小时导出一堆文件，最后发现模型压根没识别出目标，白忙一场。

最简单的验证方法是“三看原则”：

一看日志输出：运行命令后，终端会实时打印每张图片的推理耗时、检测数量等信息。例如：

image 1/10 /data/images/test001.jpg: 640x480 2 persons, 1 backpack, 45.6ms

这表示这张图检测到了2个人和1个背包，耗时45.6毫秒。如果没有检测到任何对象，也不会报错，只会显示空列表。

二看可视化图片：打开predict目录里的图片，检查框是否准确贴合目标。注意观察是否存在大量漏检（该框的没框）或误检（不该框的框了）。

三看标签文件：如果有启用save_txt，进labels文件夹看对应.txt文件内容。每一行代表一个检测框，格式为：

<class_id> <x_center> <y_center> <width> <height> <confidence>

数值都在0~1之间，表示相对于图像宽高的归一化坐标。

这三个环节都通过了，才说明模型处于可用状态，可以放心进入下一步的数据导出阶段。

2. 文本与JSON格式结果保存实战

2.1 TXT格式保存：参数设置与应用场景

现在我们进入正题——如何将检测结果保存为文本文件。这是最常见也是最容易集成到后续分析流程的格式，尤其适合做自动化处理。

核心参数只有一个：save_txt=True。加上它，YOLOv8就会在labels目录下为每张图片生成同名的.txt文件。完整命令如下：

yolo detect predict \ model=yolov8s.pt \ source=./data/images/ \ save_txt=True

这里的./data/images/是你存放待检测图片的路径，可以是单个图片也可以是整个文件夹。运行后你会发现runs/detect/predict/labels/里多了若干.txt文件，每个文件对应一张图的检测结果。

那这种TXT格式到底有什么用呢？举个实际例子：你在做一个工厂安全帽佩戴检测项目，安监部门要求每周提交违规人员名单。你可以编写一个脚本，读取这些TXT文件，筛选出class_id=0（代表“未戴安全帽”）且置信度高于0.7的记录，再结合图片名称提取时间戳，自动生成Excel报表。整个过程完全无需人工查看图片，极大提升效率。

💡 提示
如果你还想保留置信度分数，记得加上save_conf=True参数。否则TXT文件里只会写前五个值（类别+坐标），不包含置信度。

这两个参数经常一起使用，形成标准搭配：

save_txt=True save_conf=True

这样每一行就会完整保留六个数值，方便后期做阈值过滤或排序。

2.2 JSON格式保存：结构化数据导出与分析

相比TXT的纯文本格式，JSON更适合现代数据分析工具处理。它可以保存更丰富的信息层级，比如一张图里有多少个目标、每个目标的详细属性、全局统计等。

遗憾的是，YOLOv8原生命令行接口并不直接支持save_json=True这样的参数。但我们可以通过Python脚本的方式轻松实现。

创建一个export_json.py文件，内容如下：

from ultralytics import YOLO import json import os # 加载模型 model = YOLO('yolov8s.pt') # 运行预测并获取结果 results = model.predict(source='./data/images/', save=True) # 构建JSON数据结构 output_data = [] for r in results: image_result = { 'filename': r.path, 'width': r.orig_shape[1], 'height': r.orig_shape[0], 'objects': [] } for box in r.boxes: obj = { 'class_id': int(box.cls), 'class_name': model.names[int(box.cls)], 'confidence': float(box.conf), 'bbox': [float(x) for x in box.xywhn[0]] } image_result['objects'].append(obj) output_data.append(image_result) # 保存为JSON文件 with open('detection_results.json', 'w', encoding='utf-8') as f: json.dump(output_data, f, indent=2, ensure_ascii=False) print("✅ JSON结果已保存！")

这段代码做了三件事： 1. 调用YOLOv8模型对图片目录进行预测； 2. 遍历每张图的检测结果，提取文件名、尺寸、类别、置信度、归一化坐标； 3. 组织成标准JSON格式并写入文件。

生成的detection_results.json长这样：

[ { "filename": "./data/images/camera1_0800.jpg", "width": 1920, "height": 1080, "objects": [ { "class_id": 0, "class_name": "person", "confidence": 0.92, "bbox": [0.45, 0.67, 0.08, 0.21] } ] } ]

这种结构可以直接被Pandas读取，也能作为API接口返回数据，非常适合构建Web系统或移动端应用。

2.3 不同格式的适用场景对比

面对TXT和JSON两种格式，很多人会纠结“到底该用哪个”。其实答案很简单：看你的下游系统需要什么。

格式	优点	缺点	适用场景
TXT	文件小、读取快、兼容性强	结构简单、无法嵌套信息	批量训练数据准备、轻量级脚本处理
JSON	层次清晰、语义明确、易扩展	文件较大、解析稍慢	Web服务对接、数据库入库、可视化平台

举个典型例子：如果你要做一个城市道路违停检测系统，前端摄像头每分钟上传一张图，后台需要快速判断是否有车辆停留超过时限。这时用TXT最合适——体积小、写入快，配合Shell脚本就能实现实时监控。

但如果你是在做一个AI辅助医疗影像分析平台，医生需要点击查看某次扫描的所有病灶位置及其置信度分布，那就必须用JSON。因为它能清晰表达“哪张图→哪些区域→什么类型→多大把握”的完整链条，用户体验更好。

所以记住一句话：简单任务用TXT，复杂系统用JSON。两者不是替代关系，而是互补工具箱里的不同扳手。

3. 视频检测结果保存全流程

3.1 视频输出的基本原理与参数设置

如果说图片处理是“快照”，那视频处理就是“连续录像”。YOLOv8对视频的支持非常友好，只需把source指向视频文件路径即可自动逐帧处理。

基本命令如下：

yolo detect predict \ model=yolov8s.pt \ source=./videos/traffic.mp4 \ save=True

注意这里的关键是save=True，它会让程序自动调用OpenCV的VideoWriter模块，将每一帧加框后的画面拼接成新视频，保存在runs/detect/predict目录下。

但要注意，默认情况下输出视频的编码格式和帧率是根据输入自动匹配的。如果你想自定义参数，比如降低码率节省空间，就需要通过Python脚本控制。

下面是一个增强版的视频处理脚本：

from ultralytics import YOLO import cv2 model = YOLO('yolov8s.pt') video_path = './videos/drone_footage.mp4' output_path = './output/annotated_drone.avi' # 打开视频 cap = cv2.VideoCapture(video_path) fps = int(cap.get(cv2.CAP_PROP_FPS)) width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) # 定义编码器和创建VideoWriter对象 fourcc = cv2.VideoWriter_fourcc(*'XVID') out = cv2.VideoWriter(output_path, fourcc, fps, (width, height)) # 逐帧处理 while cap.isOpened(): ret, frame = cap.read() if not ret: break # 推理 results = model(frame, verbose=False) annotated_frame = results[0].plot() # 绘制检测框 # 写入视频 out.write(annotated_frame) # 释放资源 cap.release() out.release() cv2.destroyAllWindows() print(f"✅ 视频已保存至 {output_path}")

这个脚本的优势在于你可以灵活控制输出质量。比如把XVID换成MP4V可以获得更好的压缩比；调整fps参数可以加快或减慢播放速度；甚至可以在plot()函数中传入line_width、font_size等参数美化显示效果。

3.2 自定义视频编码与性能优化技巧

在实际项目中，视频文件往往很大，动辄几个GB。如果不做优化，不仅存储成本高，传输也慢。这里有三个实用技巧帮你控制输出质量与体积：

技巧一：调整分辨率很多监控视频是1080p甚至4K，但YOLOv8在640×640输入下就能取得不错效果。可以在推理前先缩放：

resized = cv2.resize(frame, (1280, 720)) # 降为720p results = model(resized)

技巧二：降低帧率并非所有场景都需要30FPS。如果是静态场景巡查，可以每隔N帧处理一次：

frame_count = 0 skip_frames = 2 # 每3帧处理1帧 while cap.isOpened(): ret, frame = cap.read() if not ret: break if frame_count % (skip_frames + 1) == 0: results = model(frame) annotated = results[0].plot() else: annotated = frame # 直接透传 out.write(annotated) frame_count += 1

技巧三：使用高效编码H.264是最通用的编码格式，兼容性最好。修改fourcc为：

fourcc = cv2.VideoWriter_fourcc(*'H264')

虽然部分系统可能不支持，但大多数播放器都能解码。

综合运用这些技巧，原本10分钟、2GB的原始视频，处理后可能只有300MB左右，节省70%以上空间，特别适合边缘设备部署。

3.3 多路视频并发处理策略

在真实安防项目中，往往需要同时处理多个摄像头的视频流。这时候就不能简单地串行运行，否则会严重延迟。

解决方案是使用多线程或异步处理。以下是基于Pythonconcurrent.futures的简易并发框架：

from concurrent.futures import ThreadPoolExecutor import glob def process_video(video_file): # 上面的视频处理逻辑封装成函数 ... return f"✅ {video_file} 处理完成" video_files = glob.glob('./videos/*.mp4') with ThreadPoolExecutor(max_workers=4) as executor: results = list(executor.map(process_video, video_files)) for r in results: print(r)

这里max_workers=4表示最多同时处理4路视频，具体数值应根据GPU显存和CPU核心数调整。一般来说，每路1080p@30fps视频大约占用2GB显存，确保总量不超过设备上限。

这套方案已在多个智慧工地项目中验证，稳定支持8路高清视频同步分析，满足日常巡查需求。

4. 高级技巧与常见问题避坑指南

4.1 自定义保存路径与文件命名规则

默认情况下，YOLOv8会把结果存到runs/detect/predict，编号递增。但在生产环境中，我们需要更有意义的命名方式。

可以通过project和name参数自定义路径：

yolo detect predict \ model=yolov8s.pt \ source=./data/test_set/ \ project=reports \ name=202408_security_check \ save_txt=True \ save_conf=True

这样结果就会保存在reports/202408_security_check/目录下，便于归档管理。

对于视频文件，还可以在脚本中加入时间戳命名：

from datetime import datetime timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") output_path = f"./output/detection_{timestamp}.avi"

避免重复覆盖，也方便追溯。

4.2 GPU资源合理分配与显存优化

YOLOv8默认使用第一块GPU。如果你有多卡环境，可以用device参数指定：

device=0 # 使用第1块GPU device=1 # 使用第2块GPU device=0,1 # 多卡并行（需模型支持）

对于显存不足的情况，有两个办法： 1.降低imgsz参数：从640降到320，显存消耗减少约60%bash imgsz=3202.启用半精度推理：bash half=True利用FP16加速，速度提升明显，精度损失极小。

组合使用效果更佳：

yolo detect predict model=yolov8s.pt source=... imgsz=320 half=True device=0

4.3 常见报错与解决方案汇总

问题1：CUDA out of memory- 原因：显存不足 - 解决：降低imgsz、关闭save、使用half=True

问题2：No labels found- 原因：未启用save_txt- 解决：添加save_txt=True

问题3：视频输出无声或无法播放- 原因：OpenCV不处理音频轨道 - 解决：使用ffmpeg合并音视频：bash ffmpeg -i annotated_video.avi -i original.mp4 -c copy -map 0:v:0 -map 1:a:0 output_with_audio.mp4

问题4：中文路径乱码- 原因：OpenCV不支持Unicode路径 - 解决：改用英文路径，或通过np.fromfile()读取：python frame = cv2.imdecode(np.fromfile(path, dtype=np.uint8), cv2.IMREAD_COLOR)

这些问题我都亲自踩过坑，现在列出来帮你少走弯路。