mcpField
V
vss-search

vss-search

github.com/open-edge-platform创意与媒体175102 次安装今天更新
代码仓库

关于 vss-search

vss-search 是用于自然语言检索已索引视频库的技能，指导用户准备可搜索的视频、查询排序片段，并整理文件名和时间信息。

主要功能

  1. 01自然语言视频检索
  2. 02上传和列出视频
  3. 03搜索前生成嵌入
  4. 04按标签和时间筛选
  5. 05持久化及监控查询

适用场景

  1. 01查找符合画面描述的片段
  2. 02按标签或日期范围缩小结果
  3. 03持续刷新已保存的查询
  4. 04显示片段文件名和跳转时间

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/open-edge-platform/edge-ai-libraries --skill vss-search

安装后在 Claude Code 中输入/vss-search确认已加载。

附带文件references/search-request.md

详细介绍

VSS 搜索

在已索引的视频库中进行自然语言搜索。请自行运行 curl 命令 并转述结果。端点使用 nginx /manager 前缀。

设置 HOST=http://${HOST_IP:-localhost}:${APP_HOST_PORT:-12345}。

前提条件

后端运行正常且已启用搜索——先探测；如果未启用，请使用 vss-doctor / vss-up：

curl -sf "$HOST/manager/health" >/dev/null && \
curl -s "$HOST/manager/app/features" | jq '.search // .'

1. 上传视频（如果尚未摄取）

POST /manager/videos — multipart/form-data，字段名为 video，可选的 逗号分隔 tags。文件必须是可流式传输的 MP4（否则服务器会拒绝）。

curl -s -X POST "$HOST/manager/videos" \
  -F "video=@/path/to/clip.mp4" \
  -F "tags=outdoor,daytime" | jq .
# → { "videoId": "<VIDEO_ID>" }

改为列出 / 检查现有视频。列表响应是一个对象 { "videos": [...] }，不是裸数组；name 是生成的哈希值，因此请使用 url / dataStore.fileName 获取真实文件名：

curl -s "$HOST/manager/videos" | jq '.videos[] | {videoId, file: .dataStore.fileName}'
curl -s "$HOST/manager/videos/<VIDEO_ID>" | jq '.video'   # single record is wrapped under .video

2. 生成搜索嵌入

视频只有在嵌入生成后才能搜索。上传后触发生成 （也可用于重试失败的任务）：

curl -s -X POST "$HOST/manager/videos/search-embeddings/<VIDEO_ID>" | jq .

等待任务完成（重新检查视频记录）后再查询。

3. 查询

单次查询 — POST /manager/search/query。响应是一个对象 { "results": [ { "query_id", "results": [ … ] } ] } — 带有包装层，不是裸 数组 — 因此，排序后的片段位于 .results[].results[]：

curl -s -X POST "$HOST/manager/search/query" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "person wearing a hat",
    "tags": "indoor",
    "timeFilter": { "value": 7, "unit": "days" }
  }' | jq -r '.results[].results[]
      | "score=\(.metadata.relevance_score)  clip=\(.metadata.segment_start)-\(.metadata.segment_end)s  seek=\(.metadata.seek_timestamp)s  video_id=\(.metadata.video_id)"'
  • query（必需）：自然语言。
  • tags（可选）：逗号分隔，与查询取交集。
  • timeFilter（可选）：可以是相对时间（value + unit = minutes|hours|days|weeks），也可以是绝对时间（start/end ISO-8601）。参见 references/search-request.md。

每个片段的 metadata 包含 relevance_score（0..1；最高命中可恰好为 1）、video_id、video_url、segment_start/segment_end、seek_timestamp、 tags 和 video_metadata（时长/fps）。在搜索模式下，page_content 是一个片段 定位信息（“从 Ns 到 Ms 的视频片段…”），而非字幕。

结果中不包含文件名——metadata 有 video_id，但没有 video / file_name。要显示片段的文件名，请将 video_id 与视频列表中的 .videos[].dataStore.fileName 关联：

curl -s "$HOST/manager/videos" \
  | jq '[.videos[] | {key:.videoId, value:.dataStore.fileName}] | from_entries' > /tmp/idmap.json
curl -s -X POST "$HOST/manager/search/query" -H 'Content-Type: application/json' \
  -d '{ "query": "person wearing a hat" }' \
  | jq --slurpfile m /tmp/idmap.json -r '.results[].results[]
      | "score=\(.metadata.relevance_score)  file=\($m[0][.metadata.video_id] // "?")  clip=\(.metadata.segment_start)-\(.metadata.segment_end)s"'

展示排名靠前的命中时，附上文件名 + 片段时间范围 + 跳转时间。

4. 已保存 / 托管的查询（可选）

curl -s -X POST "$HOST/manager/search" -H 'Content-Type: application/json' \
  -d '{"query":"forklift"}' | jq .          # create a persistent query → queryId
curl -s "$HOST/manager/search/<QUERY_ID>" | jq .          # fetch results
curl -s -X POST "$HOST/manager/search/<QUERY_ID>/refetch" | jq .   # re-run
curl -s -X PATCH "$HOST/manager/search/<QUERY_ID>/watch" \
  -H 'Content-Type: application/json' -d '{"watch":true}'   # auto-refresh
curl -s "$HOST/manager/search/watched" | jq .
curl -s -X DELETE "$HOST/manager/search/<QUERY_ID>"

评论

支持 Markdown