企业官网建设流程全解析

几小时监控录像秒级检索：VModal CCTV时间戳上传与绝对时间搜索全解析

【免费下载链接】vmodal_sdk_flutterV- Modal AI: Visual Video / Image Search - SDK Flutter项目地址: https://gitcode.com/gh_mirrors/vm/vmodal_sdk_flutter

VModal Flutter SDK（vmodal_sdk_flutter）让 Android/iOS 应用拥有"多模态记忆"：上传监控视频后，可用自然语言按画面内容 + 元数据 + 绝对时间范围检索任意一帧。本文将带你完整走通 CCTV 时间戳上传与绝对时间搜索的全流程，几小时的录像也能秒级定位关键画面。

🎯 为什么 CCTV 场景必须用"绝对时间"

普通视频搜索只回答"画面里有什么"，而监控排查还要回答"什么时候发生的"。VModal 的 CCTV 契约把摄像头时钟直接带进索引：

• 上传时由调用方提供录像起始时间startDatetimeUser（带时区的绝对时间）；
• SDK 原样透传，后端负责归一化并回传标准的 UTC 毫秒值startTsUnixUserMs；
• 搜索时用一对"起始含、结束不含"的绝对时间边界，把检索范围锁定到精确到分钟。

这意味着多路摄像头、跨时区的录像库都能按真实世界时间对齐检索。

📋 完整流程一览

仓库中提供了编译校验过的 CCTV 示例工程 example/03_cctv/README.md，其渐进式流程如下：

运行时 API Key → auth.me() 鉴权 → 列出项目集合 / 列出索引任务 → 上传带时间戳的监控录像 → 创建帧索引并轮询等待完成 → 在绝对时间范围内搜索元数据

项目、集合、流的组织方式定义在 example/03_cctv/lib/cctv_example.dart 中：projectId → collectionName → streamName三级作用域（如cctv_app / entrance_cameras / camera_01），一路相机对应一个 stream，天然支持多路监控。

⏱️ 第一步：CCTV 时间戳上传

核心是构造CctvUploadInput，一次上传携带"文件 + 公开文件名 + 起始时间 + 元数据文本 + 标签"（完整定义见 CctvUploadInput）：

final input = CctvUploadInput( file: File('/camera/incoming/segment_001.mp4'), videoFilename: 'entrance_20260730_091500.mp4', startDatetimeUser: '2026-07-30T09:15:00+09:00', // 必须含 Z 或 UTC 偏移 metadataText: 'Entrance camera during opening hours', metadataTags: const ['cctv', 'entrance', 'camera_01'], ); final uploaded = await example.upload(input).result; print(uploaded.startTsUnixUserMs); // 后端归一化的 UTC 毫秒值

三个容易踩的坑，SDK 已在本地校验中帮你守住（validateCctvUpload）：

上传字段（公开文件名、元数据文本、重复标签、时间戳、reProcess重刷开关）由VideoUploadOptions承载，签名上传、分片上传、断点续传等所有通道都会透传，详见 lib/src/collection_uploads.dart。

🔄 第二步：创建索引并等待完成

上传后需要为摄像头集合创建图像索引并轮询状态，示例里的createIndex/waitForIndex（实现位置）做了两件贴心的事：

• 以 5 秒间隔轮询，10 分钟超时；
• 识别completed / success / done三种完成态，遇到failed / error立即抛出，避免无意义等待。

🔍 第三步：绝对时间范围搜索

索引就绪后，用"视觉查询 + 元数据查询 + 起止时间"三元组发起检索：

final found = await example.search( const CctvSearchInput( visualQuery: 'a person entering the building', // 画面语义 metadataQuery: 'entrance', // 元数据文本/标签 startDate: '2026-07-30T09:15:00+09:00', endDate: '2026-07-30T09:16:00+09:00', ), ); print('matches=${found.cntActual}');

契约要点（完整定义见 doc/sdk_contract.md）：

• 起始含、结束不含：09:15:00 ~ 09:16:00表示左闭右开区间；
• 时区等价：2026-07-30T00:15:00Z与09:15:00+09:00指向同一段录像；
• 元数据走字符串契约：queryMetadataText序列化为query_metadata字符串值，旧的 map 形式已被弃用；
• 结果类型化：videoHits中每条命中带playbackOffsetMs（距录像起点的毫秒偏移）与distance（越小越相关），可直接定位到具体帧。

🧪 如何本地验证

示例自带行为测试 example/03_cctv/test/cctv_example_test.dart，覆盖字段映射、不可变标签快照、时间边界透传等契约细节，可直接运行确认你的集成没有偏差：

export VMODAL_API_KEY='your-runtime-api-key' dart run bin/main.dart \ /camera/incoming/segment_001.mp4 \ entrance_20260730_091500.mp4 \ 2026-07-30T09:15:00+09:00 \ 2026-07-30T09:16:00+09:00

📚 延伸阅读

小结：VModal Flutter SDK 把"摄像头时钟 → 上传时间戳 → UTC 归一化 → 绝对时间边界检索"封装成了几个类型安全的方法调用。只要记住三件事——时间戳必须带时区、边界是左闭右开、元数据用字符串契约——几小时的监控录像也能实现秒级精准检索。🎬

【免费下载链接】vmodal_sdk_flutterV- Modal AI: Visual Video / Image Search - SDK Flutter项目地址: https://gitcode.com/gh_mirrors/vm/vmodal_sdk_flutter