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 Search

インデックス化された動画ライブラリを自然言語で検索します。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 はキャプションではなく、セグメントの位置情報（「Video segment from Ns to 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 対応