Label Studio 接入 SAM2Segment Anything 2实现视频目标跟踪标注从 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本指南以 segment_anything_2_video.md 为骨架结合仓库内 ML 集成文档、Video/VideoRectangle 标签参考与源码级细节展开说明如何在 Label Studio 中接入 Meta 的 Segment Anything 2SAM2模型借助交互式智能框选能力完成视频中的单目标跟踪标注。Segment Anything 2SAM 2是 Meta 于 2024 年 7 月发布的分割模型在继承第一代 Segment Anything 提示分割能力的同时将统一的分割与跟踪能力扩展到视频领域。本指南介绍的是 Label Studio 官方 ML 后端示例中面向视频目标跟踪的实现segment_anything_2_video标注人员只需在视频的某一帧上框选目标对象SAM2 就会利用视频时序信息在后续帧中持续跟踪该对象大幅降低逐帧标注的成本。读完本文你将掌握该示例的完整部署流程从源码运行、权重下载、环境变量配置到服务启动、如何将模型连接至 Label Studio 项目以及配套的视频标注配置VideoRectangleLabelsVideo组合的写法与参数细节。一、SAM2 视频示例与图像示例的区别在开始之前需要先明确本仓库内两个 SAM2 教程的分工。当前仓库的 docs/source/guide/ml_tutorials 目录下同时存在两个教程segment_anything_2_video.md本文讲解对象专门用于视频中的目标跟踪object tracking标注交互输入是视频帧上的框输出是逐帧跟上的目标框segment_anything_2_image.md用于单张图像的分割通过KeypointLabels关键点或RectangleLabels矩形框提示模型输出BrushLabels掩码。两者共用同一套 Label Studio ML 后端框架与 SAM2 权重但下游标注组件与交互方式不同。视频场景的核心价值在于模型自动把第一帧的框传播到后续所有帧实现半自动的视频对象跟踪标注。二、开始前的准备在动手部署前需要确认以下前置条件对应原文档 Before you begin 一节安装 Label Studio ML 后端框架。segment_anything_2_video是 Label Studio ML backend 官方仓库中的一个示例模型因此需要先安装 ML 后端环境。ML 后端的概念、目录结构与接入方式可参见 ml.md 以及 ml_create.md后者描述了从零编写自定义 ML 后端的五步流程包括predict方法、LabelStudioMLBase基类与label-studio-ml start启动命令。GPU 环境。截至原文档记录的 2024-08-11 时间点SAM2 仅支持在 GPU 服务器上运行详见下文已知限制CPU 推理暂不可用。一个可访问的 Label Studio 实例以及该实例的 API Key可在个人账户页面获取参见 access_tokens.md。说明本仓库的label_studio目录是 Label Studio 主体源码Django 后端与 web 前端而 SAM2 示例位于独立的label-studio-ml-backend官方仓库。因此下文涉及的git clone、pip install操作目标均为 ML 后端示例目录本仓库仅承载其配套文档。三、从源码运行 ML 后端完整步骤原文档的 Running from source 一节给出了四条核心步骤下面逐条展开并补充关键细节。1. 克隆仓库并安装依赖git clone https://github.com/HumanSignal/label-studio-ml-backend.git cd label-studio-ml-backend pip install -e . cd label_studio_ml/examples/segment_anything_2_video pip install -r requirements.txt要点说明pip install -e .在 ML 后端仓库根目录执行以可编辑模式安装label-studio-ml命令行工具即后面用到的label-studio-mlrequirements.txt位于segment_anything_2_video示例目录内除框架依赖外还会引入 SAM2 推理所需的 Python 包与图像版示例相比视频版还需要额外处理视频帧的解码与帧号对齐逻辑因此示例目录内的模型逻辑文件如model.py会包含视频专用的预测处理代码可在此目录内自由查看与修改。2. 下载 segment-anything-2 仓库与模型检查点原文档强调需要把segment-anything-2仓库下载到 ML 后端示例的根目录即进入segment_anything_2_video后SAM2 源码作为其子目录并按照 Meta 官方安装文档完成 SAM2 的安装与检查点checkpoint文件下载这一步极易遗漏——只安装 SAM2 代码而忘记下载*.pt权重文件会导致启动时模型加载失败默认配置使用的检查点对应sam2_hiera_large.pt大尺寸 Hiera 主干具体默认值可参考图像版示例文档 segment_anything_2_image.md 的 Configuration 一节所列参数MODEL_CONFIG默认为sam2_hiera_l.yamlMODEL_CHECKPOINT默认为sam2_hiera_large.pt。视频版示例共用同一套 SAM2 权重体系下载时应保证检查点与配置文件匹配。3. 导出环境变量原文档要求在运行前导出以下两个环境变量必须填入真实凭据export LABEL_STUDIO_URLhttp://localhost:8080/ # 你的 Label Studio 实例地址必须带 http:// 或 https:// 前缀 export LABEL_STUDIO_API_KEYyour-api-key # 个人账户页面获取的 API Key为什么必须设置这两个变量在 ml.md 的 Allow the ML backend to access Label Studio data 一节有明确说明ML 后端在处理视频任务时需要通过 Label Studio 的 HTTP API 拉取任务数据视频文件与提交预测结果LABEL_STUDIO_URL就是后端访问 Label Studio 的入口LABEL_STUDIO_API_KEY则是身份凭证。同时该节也给出三点约束LABEL_STUDIO_URL必须能被 ML 后端实例访问到若 ML 后端跑在 Docker 里LABEL_STUDIO_URL不能写localhost或0.0.0.0要使用宿主机的完整 IP如192.168.42.42可用ifconfigUnix或ipconfigWindows获取LABEL_STUDIO_URL必须以http://或https://开头。4. 启动 ML 后端服务cd ../ label-studio-ml start ./segment_anything_2_video默认监听端口为9090默认 host 为本地回环地址如果运行在云服务器上需要让服务监听对外暴露的端口追加-p port number即可修改端口结合 ml_create.md 的示例需要同时修改 host 时应写成label-studio-ml start ./segment_anything_2_video -p 9091 --host 0.0.0.0启动成功后可用curl http://localhost:9090/验证正常会返回{status:UP}之类的健康检查响应该验证方式在图像版教程 segment_anything_2_image.md 的 Docker 小节中有同样用法。5. 连接 ML 后端到 Label Studio进入目标项目的Settings → Machine Learning → Add Model填写模型 URL 为http://localhost:9090。如果在云服务器上运行则需要把localhost替换为容器的外部 IP 地址并带上暴露的端口。ml.md 的 Connect the model to Label Studio 一节给出了连接表单的完整字段含义这里一并整理成表字段说明Name为该模型起一个名称例如SAM2 VideoBackend URL模型服务地址。本地场景为http://localhost:9090Label Studio 与 ML 后端同在 Docker 中时注意localhost指向容器自身而非宿主机应改用http://host.docker.internal:9090或内部 IPSelect authentication method若模型服务启用了用户名/密码Basic Authentication在此选择并填入凭据Extra params传递给模型的额外参数Interactive preannotations开启后模型以交互式预标注模式工作标注人员在界面上绘制框的同时ML 后端实时接收输入并返回预测结果。SAM2 视频示例正是依赖该模式实现框选即跟踪连接完成后也可以改用 Label Studio API 方式添加 ML 后端需要项目 ID 与模型 URL但图形界面方式最为直观。四、标注配置Labeling Config详解原文档提供了一个开箱即用的视频标注配置可直接复制到项目的标注设置中View Labels namevideoLabels toNamevideo allowEmptytrue Label valuePlayer background#11A39E/ Label valueBall background#D4380D/ /Labels !-- Please specify FPS carefully, it will be used for all project videos -- Video namevideo value$video framerate25.0/ VideoRectangle namebox toNamevideo smarttrue/ /View这个配置由三个核心标签组成它们的定义与参数在 videorectangle.md 与 video.md 中有完整参考1.Video视频播放器参数类型默认值说明namestring—元素名称被其他标签toName引用valuestring—视频的 URL任务数据字段如$videoframeRatenumber24视频每秒帧数默认 24可引用任务数据如$fpssyncstring—要同步的对象名称mutedbooleanfalse是否静音heightnumber600播放器高度timelineHeightnumber64带标注区域的时间轴高度defaultPlaybackSpeednumber1播放器加载时的默认播放速度minPlaybackSpeednumber1允许的最小播放速度defaultPlaybackSpeed不能低于该值原文档在示例中特别注释请谨慎指定 FPS它会被用于该项目的所有视频。这是因为帧号frame number是视频标注与跟踪结果对齐的基础单位framerate被用于计算时间戳与帧号的换算若与实际视频帧率不符会导致跟踪框在时间轴上的位置错位。因此配置时应使用项目中所有视频统一的真实帧率。2.VideoRectangle目标跟踪框参数类型说明namestring元素名称toNamestring要控制的元素名称即Video的 name按 videorectangle.md 的说明VideoRectangle为视频带来**目标跟踪Object Tracking**能力与Video、Labels配合使用支持的数据类型为 video。它在前端对应一个智能矩形框工具示例中通过smarttrue开启标注人员按下并在某一帧上拖拽出目标框后即可触发 SAM2 的交互式预测。3.Labels跟踪对象的类别集合allowEmptytrue允许不选择标签即标注本示例中为先框选、后由模型产出留出空间每个Label声明一个跟踪目标类别value为类别名background为颜色例如示例中的Player青绿色#11A39E与Ball红色#D4380D。工作流串联整条交互链路如下标注人员播放视频到关键帧 → 用VideoRectangle在目标上画出边界框 → 前端把该框作为提示发送给 SAM2 ML 后端 → 模型基于 SAM2 的时空记忆机制memory bank在后续帧中持续跟踪并返回预测框 → 前端把预测结果渲染为带标签的跟踪框。这正是 ml.md 中 Interactive pre-annotations交互式预标注与 Smart tools智能工具一节描述的能力用户绘制区域时 ML 后端接收输入并实时返回预测。五、视频素材的格式建议虽然原文档未展开但视频标注的成败与素材格式强相关。仓库内 video.md 给出了明确的格式建议这里作为配套知识补充Label Studio 依赖浏览器播放视频并统计总帧数因此应使用广泛支持的容器与编码推荐MP4 容器 H.264 (AVC) 视频编码 AAC 音频编码并尽量转为恒定帧率CFR建议 30 fps 左右避免帧数统计不一致、重复帧或丢帧同一文件内的音视频流时长必须一致否则会出现多余的帧数可用 FFmpeg 完成转码关键参数为-c:v libx264 -profile:v high -level 4.0 -pix_fmt yuv420p -r 30H.264 编码、兼容性参数、浏览器兼容像素格式、恒定 30 fps音频用-c:a aac -b:a 128k并用-to $DUR截掉音频尾部多余部分DUR由ffprobe提取的精确视频流时长得出转码前后可用ffprobe -v error -show_format -show_streams -print_format json input.mp4检查视频全部参数。素材符合上述规范后Video标签才能准确识别时长与帧率SAM2 的跟踪结果也才能与时间轴精确对齐。六、已知限制截至原文档记录的 2024-08-11原文档明确列出的限制如下接入前需要据此评估适用场景仅支持 GPU 服务器SAM2 当前只能在 GPU 上运行无 GPU 的机器无法启动该后端仅支持单目标跟踪虽然 SAM2 原生支持多对象但当前示例实现只跟踪视频中的一个对象不支持视频分割video segmentation当前实现输出的是跟踪框矩形区域并不产出像素级掩码序列暂无 Docker 支持与图像版示例不同该视频示例没有提供 Docker 镜像与docker-compose.yml一键部署方式需要按从源码运行一节手动部署。以上限制均以当前文档记录为准后续版本可能发生变化若需要参与改进可以基于示例目录内的模型逻辑提交 PRPull Request例如扩展为多目标跟踪或补充掩码输出。七、自定义与扩展原文档的 Customization 一节指出ML 后端可以在./segment_anything_2_video目录内自由定制添加自己的模型与逻辑。具体来说示例目录内的model.py继承LabelStudioMLBase基类重写predict()方法完成交互式预测你可以在此处替换提示处理逻辑、接入自有跟踪模型或修改帧处理方式环境变量与启动参数决定服务行为参照 ml_create.md 与 ml.md 中关于LabelStudioMLBase的方法说明self.label_interface获取标注界面对象、self.model_version获取模型版本等可在预测逻辑中读取任务数据、过滤结果或组合多种模型目录下的requirements.txt可增删依赖启动命令不变。八、常见问题与调试提示结合 ml.md 与 ml_create.md 中的相关说明汇总接入过程中最常遇到的问题现象排查方向启动报模型加载失败检查 SAM2 检查点.pt是否已下载、路径是否与MODEL_CONFIG/MODEL_CHECKPOINT默认值匹配Label Studio 连不上后端确认端口与 host本地用localhost:9090容器/云服务器改用host.docker.internal:9090或公网 IP 暴露端口label-studio-ml start ... -p port --host 0.0.0.0后端能连但拉不到视频数据检查LABEL_STUDIO_URL是否带http(s)://前缀、LABEL_STUDIO_API_KEY是否正确、LABEL_STUDIO_URL能否被后端访问Docker 内不能用localhost跟踪框与画面错位核对Video framerate是否与素材真实帧率一致默认 24示例用 25.0并确认视频为恒定帧率结语本文以仓库内的 segment_anything_2_video.md 为主线完整覆盖了从环境准备、SAM2 后端源码部署、环境变量配置、服务启动与连接到视频标注配置写法与参数细节的全过程并结合 ml.md、ml_create.md、video.md、videorectangle.md 等仓库文档补全了连接表单字段、FPS 对齐、视频格式转码与故障排查等实操要点。按此流程部署后标注人员即可在 Label Studio 中通过一个框选动作获得 SAM2 驱动的视频目标跟踪结果显著提升视频类数据集的标注效率。若需要处理单张图像的分割任务可参考配套教程 segment_anything_2_image.md。【免费下载链接】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），仅供参考