开源：Yolo2CausalTCN，将YOLOv8数据集转换为因果TCN时序模型的开源工具

开源项目技术说明 | https://github.com/wxzz/iNeuOS_Yolo2CausalTCN

摘要

　　在视频分析场景中，YOLOv8可以逐帧输出目标检测框、类别与置信度等空间信息，但原始检测输出本质上是帧级的离散空间数据，无法直接作为时序预测模型的输入。因果时序卷积网络（Causal Temporal Convolutional Network，Causal-TCN）依靠因果卷积与空洞卷积，在保证不泄露未来信息的前提下具备长序列建模能力和并行计算优势，相比循环神经网络更适合此类任务。然而目前缺少一个把YOLO检测输出一键转换为TCN标准训练样本的开源工具，研究者往往需要重复编写帧对齐、窗口切分、归一化与数据集划分代码。

　　iNeuOS_Yolo2CausalTCN 项目实现了从YOLOv8推理结果到因果TCN时序数据集的完整转换流水线，支持滑动窗口构造时序样本、特征归一化与按时间顺序的数据集划分，并内置因果TCN的训练、评估与推理代码，打通了“视频目标检测—时序数据集生成—TCN时序预测”的全链路，可用于目标数量预测、轨迹趋势预测、视频异常时序预警等场景。

　　关键词：YOLOv8；因果TCN；时序数据集；时空序列；滑动窗口；视频预测

1 研究背景与问题

　　在视频监控与工业视觉场景中，很多任务并不止于单帧目标检测，还需要在历史帧检测结果的基础上预测未来趋势，例如预测区域内目标数量的变化、目标运动趋势以及异常事件的发生概率。YOLOv8逐帧输出的检测结果为坐标、宽高、类别与置信度构成的列表，属于空间检测结果，本身并不具备时序样本结构，不能直接送入时序模型。因果TCN要求输入为固定长度的时序样本，形状为“样本数×窗口长度×特征维度”，必须把连续多帧的观测统计值组织成历史序列作为输入、未来时刻的取值作为标签，才能用于训练。

　　现有开源项目大多把目标检测与时序模型训练分开实现，缺少自动化的转换工具，科研人员需要自行完成帧序号对齐、滑动窗口切分、缺失帧补全、特征归一化与数据集划分，重复劳动且容易在时序切分上出错。iNeuOS_Yolo2CausalTCN 正是为消除这一环节而提供的端到端工具链，其解决的三个具体问题如下。

（1）帧级检测结果无法直接建模。单帧检测结果只是空间信息，缺少时间维度的组织方式，需要按视频帧序号重排并聚合为可输入网络的定长序列。

（2）时序样本构造缺少标准流程。历史窗口长度、预测步长、标签对齐方式与归一化参数都会影响训练效果，需要统一的构造规则并可复现。

（3）数据划分容易造成时间泄露。时序任务必须按时间顺序切分训练集、验证集与测试集，随机打乱会使模型在验证阶段看到未来信息，导致指标虚高。

2 项目整体架构

　　项目由三个模块组成：YOLOv8检测结果导出模块、数据集转换模块、因果TCN训练与评估模块。转换器位于整条链路的中间位置，向上承接任意来源的逐帧检测结果，向下输出可直接被PyTorch的DataLoader加载的时序数据集，整体流程如图所示的四段结构。

视频文件 → YOLOv8推理 → 每帧检测结果 json / csv

↓

Yolo2CausalTCN 转换器（帧对齐、特征提取、滑窗采样、归一化、划分）

↓

TCN 标准时序数据集（npy 格式，X/Y 分离）

↓

Causal-TCN 训练 → 验证 → 预测 → 指标输出

图1 Yolo2CausalTCN 的整体数据处理流程

2.1 检测结果的输入格式

　　转换器接受两类输入：一是YOLOv8推理导出的JSON结果，其中每一帧记录该帧所有目标框的坐标、类别编号与置信度；二是CSV格式的逐帧检测汇总结果，每行对应一帧或一个目标。两类输入在解析后统一映射为“帧号—目标列表”的内部结构，因此后续转换逻辑与检测器型号无关，接入YOLOv9、YOLOv11等其他检测器时只需保证导出字段一致，无需修改转换代码。

2.2 数据集转换的核心逻辑

转换模块是整个项目最关键的部分，它把YOLO的检测结果映射为因果TCN可用的监督学习样本，具体包含五个环节。

（1）时序对齐。按视频帧序号排序，处理跳帧与漏检：缺失帧可按补零或线性插值填充，保证每个时间步都有确定的特征向量，避免窗口跨越时出现长度不齐。

（2）滑动窗口采样。设定历史窗口长度seq_len与预测步长pred_len，以步长stride在时间轴上滑动。输入样本X取t-seq_len至t-1共seq_len帧的统计特征，标签Y取t至t+pred_len-1的待预测取值。

（3）特征构造与归一化。可提取的特征包括每帧目标数量、检测框坐标均值、宽高均值、置信度均值及各类别计数等，用户可按需要组合。归一化支持Min-Max与Z-Score两种方式，统计量在训练集上计算并保存，供验证、测试与线上推理复用，避免训练与推理口径不一致。

（4）数据集划分。按时间顺序切分为训练集、验证集与测试集，严禁随机打乱；同时保证相邻窗口不跨越切分边界，防止同一段连续帧同时出现在训练集和测试集中。

（5）样本落盘。输出为NumPy数组文件，X与Y按数据集分别保存，形状为[X数, seq_len, feature_dim]与[X数, pred_len, output_dim]，可被torch.utils.data.TensorDataset直接包装。

这里需要强调因果性的约束：因果TCN在时刻t的输出只能依赖t及之前的输入，因此标签必须严格位于输入窗口之后。转换器在采样时校验窗口与标签的时间区间不重叠，从根本上排除时间泄露，这一点与允许双向注意力的普通序列模型有本质区别。

表1 转换器输出的数据集文件与用途

文件	形状	内容与用途
X_train.npy	[N, seq_len, F]	训练集输入序列，滑动窗口截取的历史检测特征
Y_train.npy	[N, pred_len, O]	训练集标签，窗口之后若干帧的待预测取值
X_val.npy / Y_val.npy	[N, seq_len, F] / [N, pred_len, O]	验证集，用于早停与超参数选择
X_test.npy / Y_test.npy	[N, seq_len, F] / [N, pred_len, O]	测试集，按时间顺序位于最后一段时间
norm_params.json	—	归一化统计量，推理阶段复用，保证口径一致

表1中的N为样本数量，F为特征维度，O为输出维度。对于单变量目标数量预测，O取1；多步多变量预测时O随输出变量数量扩展，转换器不对此作硬性约束。

2.3 内置因果TCN模型

　　项目内置标准因果TCN网络，由多层空洞因果卷积块、残差连接与Dropout堆叠构成。因果卷积保证时刻t的输出只依赖t及之前的时间步，从结构上杜绝未来信息泄露；空洞卷积使感受野随层数指数级扩大，用较少的层数即可覆盖长时序依赖；残差连接缓解深层网络的梯度消失，使训练更稳定。

　　模型支持单步与多步预测两种输出方式，损失函数可选均方误差或平均绝对误差，评估采用RMSE与MAE指标。训练与推理共用同一套数据加载与归一化参数，避免出现“训练时归一化、推理时未归一化”这类常见错误。

3 快速使用流程

　　以下流程假设已在具备Python与PyTorch的环境中完成代码克隆，整体分为四步：导出检测结果、转换数据集、训练模型、评估与预测。

3.1 环境依赖

pip install ultralytics torch numpy pandas scikit-learn
git clone https://github.com/wxzz/iNeuOS_Yolo2CausalTCN.git
cd iNeuOS_Yolo2CausalTCN

3.2 导出YOLOv8逐帧检测结果

　　使用YOLOv8对视频执行推理并将结果导出为JSON，导出文件按帧序号组织，作为转换器的输入。

from ultralytics import YOLO
model = YOLO("yolov8s.pt")
results = model.predict(source="demo.mp4", save_json=True)

3.3 转换为TCN时序数据集

实例化转换器并指定历史窗口长度、预测步长与归一化方式，即可生成训练所需的npy数据集。窗口与步长的取值需要结合视频帧率与预测任务的时间跨度确定，例如25fps的视频取seq_len=48约对应2秒历史。

from yolo2causaltcn import Yolo2CausalTCN

converter = Yolo2CausalTCN(
    seq_len=48,       # TCN 输入的历史窗口长度（帧）
    pred_len=6,       # 预测未来帧数
    stride=1,         # 滑动步长
    norm_type="z-score"
)
converter.convert(
    yolo_json_path="predictions.json",
    out_dir="./tcn_dataset/"
)

3.4 训练与评估

数据集生成后直接调用内置训练器，指定轮数、批大小与学习率即可完成训练，随后执行评估与预测。

from train_tcn import Trainer


trainer = Trainer(dataset_dir="./tcn_dataset")

trainer.train(epochs=100, batch_size=16, lr=1e-3)


trainer.evaluate()   # 输出 RMSE / MAE

trainer.predict()    # 对未来窗口做推理

4 适用场景与扩展方向

4.1 典型应用场景

　　智能监控场景中，可以基于历史帧检测到的目标数量预测区域内人流、车流的变化趋势，为调度与告警阈值调整提供依据；工业视觉场景中，可对设备视频的检测时序做趋势建模，在指标异常前给出预警；在通用的视频行为分析中，也可把目标统计特征作为轻量时序表征，完成短期趋势预报。

4.2 扩展能力

　　转换器的输入是统一的帧级检测字段，因此更换检测器型号不影响转换与训练流程，接入其他YOLO系列模型只需保证导出格式一致。特征层面可自行增加目标运动速度、位移差分、跟踪ID统计等衍生特征，用于刻画更丰富的动态信息。输出层面，生成的npy数据集同时兼容Temporal Convolution、LSTM与Transformer类时序模型，便于在同一数据口径下横向对比不同网络结构的效果。

5 总结与展望

　　iNeuOS_Yolo2CausalTCN 解决的是视觉检测与时序卷积网络之间的数据鸿沟问题。它把YOLO的逐帧检测输出自动整理成符合因果约束的时序样本，省去帧对齐、滑窗切分、归一化与数据集划分等重复工作，使研究者可以把精力集中在模型结构与任务设计上。项目在转换环节内置了时间泄露校验，这一点对时序任务的结论可靠性尤为关键。

　　后续可扩展的方向包括：接入ByteTrack等跟踪算法，把目标轨迹序列直接转换为TCN数据集，从“数量统计”升级为“个体轨迹预测”；增加可视化模块，对原始序列与预测结果绘图对比，便于快速判断模型是否学到有效趋势；以及补充多变量与多步预测的基准实验配置，方便复现与横向比较。

　　项目地址：https://github.com/wxzz/iNeuOS_Yolo2CausalTCN ，欢迎提交Issue与Pull Request。