Label Studio 中的 TimelineLabels：基于 YOLO 特征提取与 LSTM 的时序视频多标签分类 ML 后端-创锋一号

Label Studio 中的 TimelineLabels：基于 YOLO 特征提取与 LSTM 的时序视频多标签分类 ML 后端

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio

本指南以 Label Studio 官方示例 ML 后端中的TimelineLabels模型为核心，系统讲解如何利用「YOLO 特征提取 + LSTM 时序建模」在 Label Studio 中实现视频的时序多标签分类。读者将掌握<TimelineLabels>标签的完整标注配置、model_trainable简单模式与可训练模式的切换、全部神经网络参数的语义与调优方法，以及该后端从前端标签解析到后端增量训练（partial_fit）的完整源码级工作原理。

一、模型概述与适用场景

TimelineLabels 是 Label Studio ML 后端示例中的时序视频分类模型，用于对视频逐帧或按时间区间进行多标签分类（例如检测"球是否在画面内""是否发生触球"这类事件状态）。它采用两段式架构：

特征提取：利用预训练的 YOLO 分类模型（如yolov8n-cls.pt）提取视频帧特征，具体做法是移除 YOLO 最后一层分类层，改用倒数第二层的特征表示；
时序建模：在 YOLO 特征之上叠加一个自定义 LSTM 神经网络，捕捉帧与帧之间的时序依赖关系，输出逐帧的多标签概率。

该模型最典型的玩法是可训练模式（trainable mode）：先手动标注少量视频，每次点击Submit提交标注后，模型即基于新标注增量重训；当模型开始在新任务上预测出标签后，会自动把预测结果填充到时间轴（timeline）上。标注人员可以验证或修正这些预测，修正后模型再次训练，从而形成"人工标注 → 增量训练 → 自动预标注 → 人工校验 → 再训练"的迭代闭环，实现少样本（few-shot）条件下的持续改进。

提示：如果需求是更先进的时序分类方案，可以参考 VideoMAE 模型（Label Studio 未附带其示例后端，但可以自行按 ML 后端开发指南集成）。

二、安装与快速开始

在使用本模型前，需要先安装 Label Studio ML 后端 SDK（label-studio-ml-backend），并获取本教程依赖的YOLO 示例后端（位于label-studio-ml-backend仓库的label_studio_ml/examples/yolo目录，内含本模型所使用的timeline_labels.py、neural_nets.py、converter.py等核心文件）。整体安装流程如下：

克隆并安装 ML 后端 SDK，进入yolo示例目录；
检查docker-compose.yml，配置所需的模型路径与环境变量；
执行docker compose up启动后端服务（默认监听http://localhost:9090）；
在 Label Studio 项目Settings > Model中点击Connect Model，填入后端 URL 完成接入；
确认Interactive Preannotations（交互式预标注）保持关闭（默认即关闭）。

对接完成后，建议通过curl http://localhost:9090验证后端状态，返回类似{"model_class":"...","status":"UP"}即表示服务正常。

三、标注配置：`<TimelineLabels>`标签的完整用法

在 Label Studio 的标注配置（labeling config）中，<TimelineLabels>作为控制标签（control tag）配合<Video>对象标签使用。完整示例：

<View> <TimelineLabels name="label" toName="video" model_trainable="true" model_classifier_epochs="1000" model_classifier_sequence_size="16" model_classifier_hidden_size="32" model_classifier_num_layers="1" model_classifier_f1_threshold="0.95" model_classifier_accuracy_threshold="0.99" model_score_threshold="0.5" > <Label value="Ball touch" background="red"/> <Label value="Ball in frame" background="blue"/> </TimelineLabels> <Video name="video" value="$video" height="700" frameRate="25.0" timelineHeight="200" /> </View>

3.1 前端标签语义（源码佐证）

<TimelineLabels>在前端（web/libs/editor/src/tags/control/TimelineLabels.jsx）中由TimelineLabelsModel组合ControlBase、LabelsModel与SelectedModelMixin而成，注册为timelinelabels标签，其生成的标注区域（region）类型为TimelineRegion（见 web/libs/editor/src/regions/TimelineRegion.js）。使用方式为：先选择一个标签，单击标注单帧，按住鼠标拖动即可一次标注多帧区间。

其标注结果以 JSON 形式存储，核心字段定义在 docs/source/includes/tags/timelinelabels.md：

value.ranges：区间数组，每个区间对象含start与end两个帧号属性，一个 region 对应一个区间；
value.timelinelabels：该区间对应的标签名称字符串数组。

{ "value": { "ranges": [{"start": 3, "end": 5}], "timelinelabels": ["Moving"] } }

3.2 必须注意的`frameRate`约束

<Video>标签中的frameRate属性必须设置为正确的值（可参考 docs/source/includes/tags/video.md，默认值为 24，也可用任务数据动态指定，如$fps）。所有视频的帧率必须一致，否则提交的标注将与视频画面错位（misaligned）。

此外，Label Studio 依赖浏览器解析视频总帧数，建议使用H.264 编码的 MP4（恒定帧率 CFR，约 30fps）以获得稳定的帧数与时长识别（参见 docs/source/tags/video.md 中的 FFmpeg 转码示例）。

四、参数详解

<TimelineLabels>标签支持以下模型参数（均可直接在标注配置中修改，无需改动代码）：

参数	类型	默认值	说明
`model_trainable`	bool	`false`	启用可训练模式，使模型能从你的标注中增量学习
`model_classifier_epochs`	int	`1000`	LSTM 神经网络的训练轮数
`model_classifier_sequence_size`	int	`16`	LSTM 输入序列长度（按帧计）。调整以捕获更长或更短的时序依赖；在 25 帧率下 16 帧约为 0.6 秒
`model_classifier_hidden_size`	int	`32`	LSTM 隐藏状态维度，调整以改变 LSTM 容量
`model_classifier_num_layers`	int	`1`	LSTM 层数，增大可获得更深的 LSTM 网络
`model_classifier_f1_threshold`	float	`0.95`	训练时基于 F1 分数的早停阈值，防止过拟合
`model_classifier_accuracy_threshold`	float	`1.00`	训练时基于准确率的早停阈值，防止过拟合
`model_score_threshold`	float	`0.5`	预测最低置信度阈值，低于该值的标签将被忽略
`model_path`	string	`None`	自定义 YOLO 模型路径（详见下方"自定义 YOLO 模型"一节）

需要特别说明两点：

自定义 YOLO 模型：可以通过model_path指向自己的 YOLO 模型，但该模型需具备与yolov8-cls系列相似的架构，因为特征提取依赖对倒数第二层的钩取（hook）。
predicted_values属性：在可训练模式下，<Label>标签上的predicted_values属性不生效——可训练模式不使用预训练 YOLO 类名做预测，而是学习你自己的标签集合。

五、两种运行模式

5.1 简单模式（Simple mode）

简单模式直接使用预训练 YOLO 的分类结果生成预测，不做任何额外训练。

适用场景：快速搭建、无需自定义训练，启动即可出预测；
配置方法：model_trainable="false"（或不写该属性，默认即为 false）；
示例：

<View> <Video name="video" value="$video" height="700" frameRate="25.0" timelineHeight="200" /> <TimelineLabels name="label" toName="video" model_trainable="false"> <Label value="Ball" predicted_values="soccer_ball"/> <Label value="tiger_shark" /> </TimelineLabels> </View>

注意：简单模式通过predicted_values建立"你的标签 → YOLO 预训练类别名"的映射，YOLO 对每一帧给出类别概率，超过model_score_threshold的类别即被渲染到时间轴上。

5.2 可训练模式（Trainable mode）

可训练模式在预训练 YOLO 分类特征之上叠加自定义 LSTM 网络，捕获视频的时序依赖。LSTM 从零开始训练，大约需要 10～20 段、每段约 500 帧（约 20 秒）的标注良好的视频，才能开始产出有意义的预测。

适用场景：需要自定义标签，或相对简单模式需要更高精度；
配置方法：model_trainable="true"；
训练流程：用TimelineLabels开始标注 → 提交第一条标注后模型开始训练 → 每次新标注通过partial_fit()方法增量更新模型；
样本需求：约 10～20 个标注任务即可达到合理效果（few-shot learning）。

可训练模式的完整配置示例：

<View> <Video name="video" value="$video" height="700" frameRate="25.0" timelineHeight="200" /> <TimelineLabels name="label" toName="video" model_trainable="true" model_classifier_epochs="1000" model_classifier_sequence_size="16" model_classifier_hidden_size="32" model_classifier_num_layers="1" model_classifier_f1_threshold="0.95" model_classifier_accuracy_threshold="0.99" model_score_threshold="0.5"> <Label value="Ball in frame"/> <Label value="Ball touch"/> </TimelineLabels> </View>

六、可训练模型的工作原理

可训练模式使用自定义的时序 LSTM 分类模型实现，每次标注提交或更新时增量训练，并为视频的每一帧生成预测。整体可拆分为三步。

6.1 第一步：YOLO 特征提取

预训练 YOLO 模型：使用 YOLO 分类模型（如yolov8n-cls.pt）提取视频帧特征；
层修改：移除 YOLO 最后一层分类层，取倒数第二层的特征表示（对应源码utils/neural_nets.py::cached_feature_extraction()）；
缓存机制：使用缓存保存 YOLO 中间特征，避免重复计算，支撑"边训练边预测"的实时性。

缓存目录位于/app/cache_dir，保存 YOLO 模型最后一层提取的中间特征，用于增量训练与预测加速。

6.2 第二步：LSTM 神经网络

目的：对 YOLO 最后一层输出的特征向量序列进行时序建模，捕获视频中的时间依赖；
架构（对应MultiLabelLSTM）：
- 输入层：接收 YOLO 特征向量；
- 全连接层：降维；
- Layer Normalization 与 Dropout：提升训练稳定性、防止过拟合；
- LSTM 层：处理序列，建模时序关系；
- 输出层：生成每个时间步的多标签预测；
损失函数：使用带 logits 的二元交叉熵损失（BCEWithLogitsLoss）做多标签分类，并加入权重衰减（weight decay）实现 L2 正则化。

6.3 第三步：`partial_fit()`增量训练

功能：每次新标注到达时更新模型参数；
流程：
1. 通过utils/converter.py::convert_timelinelabels_to_probs()从标注视频中提取特征与标签；
2. 按model_classifier_sequence_size将数据切分为适合 LSTM 输入的序列块；
3. 增量训练模型，并以 F1 分数与准确率阈值做早停；
优势：少样本学习能力强；早停机制避免在有限数据上过拟合。

七、限制与注意事项

非最终生产模型：该模型主要作为 demo 示例，用于生产前需要进一步验证；
性能依赖数据：至少需要 10～20 个标注任务且数据要多样，才能开始有良好表现；
参数敏感：调整神经网络参数可能显著影响性能；
训练数据上的早停：由于每次只基于单条标注更新、缺少验证集，模型在训练数据上做 F1/准确率早停，可能导致对训练数据过拟合（这是权衡之举）；
YOLO 的局限：预训练 YOLO 面向图像分类任务，其特征未必适配所有场景（如事件检测）；本方案不微调 YOLO，只训练 YOLO 最后一层之上的 LSTM 部分；
标签不平衡：模型对标签分布不平衡的数据可能效果不佳，需保证训练数据中标签分布均匀；可考虑修改损失函数（BCEWithLogitsLoss）并使用类别正样本权重（class pos weights）缓解；
未实现全量数据训练：目前模型只基于最近一条标注训练，尚未实现基于全部数据训练（见源码timeline_labels.py::fit()）。

八、实战示例：足球视频中的球体检测

8.1 环境搭建

标注配置：

<View> <TimelineLabels name="videoLabels" toName="video"> <Label value="Ball touch" background="red"/> <Label value="Ball in frame" background="blue"/> </TimelineLabels> <Video name="video" value="$video" height="700" timelineHeight="200" frameRate="25.0" /> </View>

连接模型后端：
- 新建项目，进入Settings > Model添加 YOLO 后端；
- 在终端进入本仓库的yolo示例目录；
- 更新docker-compose.yml；
- 执行docker compose up启动后端；
- 在项目设置中连接该后端，并确认Interactive Preannotations关闭（默认关闭）。

8.2 标注与训练

标注视频：上传足球视频到项目，使用<TimelineLabels>控制标签标注球在画面中可见的时间区间；
模型训练：提交标注后模型开始增量训练，持续标注直到模型能产出准确预测；
校验预测：模型为未标注视频自动建议标签，标注人员验证并修正预测，进一步改进模型。

九、调参与重置模型

若模型效果不佳，可修改标注配置中以model_classifier_为前缀的 LSTM 与分类器训练参数。修改以下参数后模型将被重置：

model_classifier_sequence_size
model_classifier_hidden_size
model_classifier_num_layers
标注配置中新增或删除标签

模型重置后，需要对新旧标注执行Update操作才能看到改进效果。若需修改更多参数，可直接修改代码中的utils/neural_nets.py::MultiLabelLSTM。若需彻底重置模型，可删除/app/models下的模型文件——模型文件名以timelinelabels-前缀开头，具体路径见timeline_labels.py::get_classifier_path()。

十、调试与日志

以LOG_LEVEL=DEBUG环境变量运行后端（可配置在docker-compose.yml中），然后在（Docker）控制台查看日志输出即可进行调试。

十一、核心数据结构：TimelineLabels 区域与标签数组互转

utils/converter.py提供两个核心转换函数：

convert_timelinelabels_to_probs()：将 TimelineLabels 区域（ranges）转换为标签数组；
convert_probs_to_timelinelabels()：将标签数组转换回 TimelineLabels 区域。

标签数组是一个二元矩阵：每一行对应视频的一帧，每一列对应一个标签；若该帧存在某标签，则对应单元格为1，否则为0。例如：

[ [0, 0, 1], [0, 1, 0], [1, 0, 0] ]

对应标签顺序[label3, label2, label1]分别出现在第 1、2、3 帧。更多示例可参考tests/test_timeline_labels.py::test_convert_probs_to_timelinelabels()。

十二、面向开发者的架构解析

本部分深入剖析后端架构与代码调用流，帮助开发者理解组件交互与扩展方式。

12.1 类继承关系

ControlModel：Label Studio 控制标签的基类；
TimelineLabelsModel：继承ControlModel，实现<TimelineLabels>标签专属功能（文件timeline_labels.py）；
torch.nn.Module：PyTorch 所有神经网络模块的基类；
BaseNN：自定义神经网络基类，继承torch.nn.Module（文件neural_nets.py）；
MultiLabelLSTM：继承BaseNN，实现多标签分类的 LSTM 网络。

12.2 预测调用流

12.3 训练调用流

12.4 关键类与工具函数

TimelineLabelsModel（timeline_labels.py）

is_control_matched(cls, control)：类方法，检查给定的控制标签是否为<TimelineLabels>；
create(cls, *args, **kwargs)：创建模型实例，初始化trainable、label_map等属性；
predict_regions(video_path)：预测主入口，根据trainable属性分流到简单模式或可训练模式；
- create_timelines_simple(video_path)：调用cached_yolo_predict获取 YOLO 预测，处理逐帧结果得到概率，再经convert_probs_to_timelinelabels转为时间轴标签；
- create_timelines_trainable(video_path)：调用cached_feature_extraction提取特征，加载已训练分类器，预测概率后转为时间轴标签；
fit(event, data, **kwargs)：标注创建/更新事件触发，处理增量训练：提取特征与标签 → 预处理 → 加载或新建分类器 →partial_fit→ 保存模型；
get_classifier_path(project_id)：根据项目 ID 与模型名生成分类器模型文件的存储路径。

BaseNN（neural_nets.py）

set_label_map(label_map)/get_label_map()：存储/获取标签映射字典；
save(path)：用torch.save保存模型；
load(cls, path)：从指定路径加载模型；
load_cached_model(cls, model_path)：缓存命中则加载，否则返回None。

MultiLabelLSTM（neural_nets.py）

__init__(...)：初始化网络层与超参数（输入维度、隐藏层、dropout、优化器）；
forward(x)：前向传播——全连接降维 → LayerNorm + Dropout → LSTM → 全连接输出；
preprocess_sequence(sequence, labels=None, overlap=2)：切分与填充输入序列及标签；
partial_fit(sequence, labels, ...)：增量训练——预处理序列、构建 DataLoader 分批、按准确率与 F1 阈值早停；
predict(sequence)：将序列切块、以评估模式前向传播、拼接输出以对齐原始序列长度。

工具与辅助函数

cached_yolo_predict(yolo_model, video_path, cache_params)：基于 joblibMemory缓存 YOLO 预测结果，避免重复计算；
cached_feature_extraction(yolo_model, video_path, cache_params)：通过钩取 YOLO 倒数第二层提取特征并缓存；
convert_probs_to_timelinelabels(probs, label_map, threshold)：概率输出 → Label Studio 时间轴标签；
convert_timelinelabels_to_probs(regions, label_map, max_frame)：标注区域 → 训练用概率序列。

十三、结语

TimelineLabels ML 后端将 Label Studio 的时序标注能力与「YOLO 特征提取 + LSTM 时序建模」的深度学习管线无缝衔接，为视频数据提供开箱即用的时序多标签分类方案。其核心价值在于：通过partial_fit增量训练实现少样本迭代，通过标注配置即可调节全部网络超参数，且代码结构清晰（ControlModel → TimelineLabelsModel、BaseNN → MultiLabelLSTM两条继承线），非常适合作为二次开发与自定义时序分类模型的基础骨架。

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析