Back to Details

vss-search-archive

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Purpose

用途

Run the top-level VSS fusion search across archived video, ingest new clips / RTSP streams for search, and delete search-ingested sources.
在归档视频中运行顶级VSS融合搜索，导入新片段/RTSP流以供搜索，并删除已导入的搜索源。

Prerequisites

前提条件

  • Active VSS deployment reachable on 
    $HOST_IP
    (see 
    vss-deploy-profile
    and 
    references/
    ).
  • vss-manage-video-io-storage
    skill installed (used to list and manage video sources before search).
  • NGC credentials in 
    $NGC_CLI_API_KEY
    and 
    $NVIDIA_API_KEY
    for any image pulls.
  • curl
    , 
    jq
    , and Docker available on the caller.
  • 可通过
    $HOST_IP
    访问的活跃VSS部署（请参阅
    vss-deploy-profile
    和
    references/
    ）。
  • 已安装
    vss-manage-video-io-storage
    技能（用于在搜索前列出和管理视频源）。
  • 用于镜像拉取的NGC凭据已存储在
    $NGC_CLI_API_KEY
    和
    $NVIDIA_API_KEY
    中。
  • 调用端已安装
    curl
    、
    jq
    和Docker。

Instructions

操作说明

Follow the routing tables and step-by-step workflows below. Each section that ends in workflow, quick start, or flow is intended to be executed top-to-bottom. Detailed reference material lives in 
references/
.
遵循以下路由表和分步工作流。所有以workflow、quick start或flow结尾的章节都需要从上到下执行。详细参考资料位于
references/
目录中。

Examples

示例

Worked end-to-end examples are kept under 
evals/
(each 
*.json
manifest contains a runnable scenario) and inline in the per-workflow 
curl
blocks below. Run a Tier-3 evaluation with 
nv-base validate <this-skill-dir> --agent-eval
to replay them.
完整的端到端示例保存在
evals/
目录下（每个
*.json
清单包含一个可运行的场景），同时内嵌在下方每个工作流的
curl
代码块中。运行
nv-base validate <this-skill-dir> --agent-eval
即可重放这些Tier-3评估用例。

Limitations

限制

  • Requires the matching VSS profile / microservice to be deployed and reachable from the caller.
  • NGC-hosted models and NIMs may be subject to rate-limits, GPU memory requirements, and license restrictions.
  • Concurrency, GPU memory, and storage limits depend on the host hardware and the profile's compose file.
  • 要求匹配的VSS配置文件/微服务已部署且可被调用端访问。
  • NGC托管的模型和NIM可能受速率限制、GPU内存要求和许可证限制的约束。
  • 并发数、GPU内存和存储限制取决于主机硬件和配置文件的compose文件。

Troubleshooting

故障排除

  • Error: REST call returns connection refused. Cause: target microservice not running. Solution: probe 
    /docs
    or 
    /health
    ; redeploy via 
    vss-deploy-profile
    or the matching 
    vss-deploy-*
    skill.
  • Error: HTTP 401/403 from NGC pulls. Cause: missing/expired 
    NGC_CLI_API_KEY
    . Solution: 
    docker login nvcr.io
    and re-export the key before retrying.
  • Error: container OOM or model fails to load. Cause: insufficient GPU memory for the selected profile. Solution: switch to a smaller variant or free GPUs via 
    docker compose down
    .
  • 错误：REST调用返回连接拒绝。原因：目标微服务未运行。解决方案：探测
    /docs
    或
    /health
    端点；通过
    vss-deploy-profile
    或匹配的
    vss-deploy-*
    技能重新部署。
  • 错误：NGC拉取时返回HTTP 401/403。原因：
    NGC_CLI_API_KEY
    缺失或过期。解决方案：执行
    docker login nvcr.io
    并重新导出密钥后重试。
  • 错误：容器内存不足（OOM）或模型加载失败。原因：所选配置文件的GPU内存不足。解决方案：切换到更小的变体，或通过
    docker compose down
    释放GPU资源。

Video Search Workflows

视频搜索工作流

Alpha Feature — not recommended for production use.
Search video archives by natural language using Cosmos Embed1 embeddings. Requires the search profile — deploy with the 
vss-deploy-profile
skill (
-p search
). These videos sources can be ingested files or RTSP streams.
Alpha特性 — 不建议用于生产环境。
使用Cosmos Embed1嵌入模型通过自然语言搜索视频归档。需要搜索配置文件 — 通过
vss-deploy-profile
技能部署（
-p search
参数）。这些视频源可以是导入的文件或RTSP流。

When to Use

使用场景

  • "Find all instances of forklifts"
  • "When did someone enter the restricted area?"
  • "Show me people near the loading dock"
  • "Search for vehicles between 8am and noon"
  • Any natural-language search across video archives
  • "Ingest 
    <file>
    for search" / "upload this video for search"
  • "Add this RTSP stream for search" / "register 
    <rtsp_url>
    for search"
  • "Delete 
    <file>
    from search" / "remove this video and embeddings"
  • "查找所有叉车出现的场景"
  • "有人进入限制区域的时间是什么时候？"
  • "展示装卸码头附近的人员"
  • "搜索上午8点到12点之间的车辆"
  • 任何针对视频归档的自然语言搜索
  • "导入
    <file>
    以供搜索" / "上传此视频用于搜索"
  • "添加此RTSP流以供搜索" / "注册
    <rtsp_url>
    用于搜索"
  • "从搜索中删除
    <file>
    " / "移除此视频及其嵌入数据"

Deployment prerequisite

部署前提

This skill requires the VSS search profile running on the host at 
$HOST_IP
. Before any request:
  1. Probe the stack:
    bash
    curl -sf --max-time 5 "http://${HOST_IP}:8000/docs" >/dev/null \
  && curl -sf --max-time 5 "http://${HOST_IP}:9200/" >/dev/null
    (The second check confirms Elasticsearch is up — unique to the search profile.)
  2. If the probe fails, ask the user:
    "The VSS 
    search
    profile isn't running on 
    $HOST_IP
    . Shall I deploy it now using the 
    /vss-deploy-profile
    skill with 
    -p search
    ?"
    • If yes → hand off to the 
      /vss-deploy-profile
      skill. Return here once it succeeds.
    • If no → stop. Do not run this skill against a missing or wrong-profile stack.
    (If your caller has granted explicit pre-authorization to deploy autonomously — e.g. the request says "pre-authorized to deploy prerequisites", or you are running in a non-interactive evaluation harness with that permission — skip the confirmation and invoke 
    /vss-deploy-profile
    directly.)
  3. If the probe passes, proceed.
本技能要求VSS search配置文件在
$HOST_IP
对应的主机上运行。发起任何请求前：
  1. 探测服务栈：
    bash
    curl -sf --max-time 5 "http://${HOST_IP}:8000/docs" >/dev/null \
  && curl -sf --max-time 5 "http://${HOST_IP}:9200/" >/dev/null
    （第二个检查用于确认Elasticsearch已启动 — 这是搜索配置文件独有的要求。）
  2. 如果探测失败，询问用户：
    "VSS 
    search
    配置文件未在
    $HOST_IP
    上运行。是否现在使用
    /vss-deploy-profile
    技能并通过
    -p search
    参数部署它？"
    • 如果是 → 转交至
      /vss-deploy-profile
      技能。部署成功后返回此处。
    • 如果否 → 停止操作。不要在缺失或错误配置的服务栈上运行本技能。
    （如果调用者已明确授权自主部署 — 例如请求中说明"已预授权部署前提条件"，或在非交互式评估环境中拥有该权限 — 则跳过确认步骤，直接调用
    /vss-deploy-profile
    。）
  3. 如果探测通过，继续操作。

Ingestion prerequisite (required before any 
/generate
)

导入前提（所有
/generate
调用前必须满足）

For a source to be searchable it must be ingested through the VSS agent backend, not through VIOS alone. The agent's ingest routes own the VIOS upload + RTVI-CV register + RTVI-embed pipeline as one transaction; a bare VIOS PUT only stores the bytes and never wires them into Elasticsearch.
Confirm the source exists in VIOS first (Mandatory workflow Step 2). If it is missing, ingest it with one of the recipes below before firing 
/generate
. After ingest succeeds, the source appears in 
sensor/list
under the name you provided and can be referenced from the natural-language query the agent forwards to its search-tool decomposer — you do NOT need to construct a structured 
video_sources
payload yourself.
要使源可被搜索，必须通过VSS agent后端导入，而不能仅通过VIOS导入。Agent的导入路由将VIOS上传 + RTVI-CV注册 + RTVI-embed流水线作为一个事务处理；直接的VIOS PUT操作仅存储文件字节，不会将其接入Elasticsearch。
首先确认源已存在于VIOS中（工作流第2步为必填项）。如果缺失，请先使用以下任一方法导入，再执行
/generate
。导入成功后，该源会以你提供的名称出现在
sensor/list
中，并且可被agent转发给搜索工具分解器的自然语言查询引用 — 你无需自行构造结构化的
video_sources
负载。

File upload — universal three-step flow

文件上传 — 通用三步流程

Use the timestamped upload form below. The VSS agent/search profile uses 
2025-01-01T00:00:00.000Z
as the uploaded 
video_file
base timestamp; VIOS storage and embeddings must share that timeline, otherwise screenshot URLs and critic frame fetches can fail.
bash
FILENAME="<filename.mp4>"
FILE_PATH="/path/to/${FILENAME}"
使用下方带时间戳的上传表单。VSS agent/搜索配置文件将
2025-01-01T00:00:00.000Z
作为上传
video_file
的基准时间戳；VIOS存储和嵌入数据必须共享该时间线，否则截图URL和关键帧获取可能失败。
bash
FILENAME="<filename.mp4>"
FILE_PATH="/path/to/${FILENAME}"

1. Ask the agent for the chunked-upload URL

1. 向agent请求分片上传URL

UPLOAD_URL=$(curl -s -X POST "http://${HOST_IP}:8000/api/v1/videos"
-H "Content-Type: application/json"
-d "{"filename":"${FILENAME}"}" | jq -r .url)
UPLOAD_URL=$(curl -s -X POST "http://${HOST_IP}:8000/api/v1/videos"
-H "Content-Type: application/json"
-d "{"filename":"${FILENAME}"}" | jq -r .url)

2. Chunked POST the file to that VST URL (nvstreamer protocol).

2. 将文件分片POST到该VST URL（nvstreamer协议）。

The final-chunk response carries sensorId.

最后一个分片的响应会包含sensorId。

IDENTIFIER=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid) UPLOAD_RESPONSE=$(curl -s -X POST "${UPLOAD_URL}"
-H "nvstreamer-chunk-number: 1"
-H "nvstreamer-total-chunks: 1"
-H "nvstreamer-is-last-chunk: true"
-H "nvstreamer-identifier: ${IDENTIFIER}"
-H "nvstreamer-file-name: ${FILENAME}"
-F "mediaFile=@${FILE_PATH};filename=${FILENAME}"
-F "filename=${FILENAME}"
-F 'metadata={"timestamp":"2025-01-01T00:00:00"}')
IDENTIFIER=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid) UPLOAD_RESPONSE=$(curl -s -X POST "${UPLOAD_URL}"
-H "nvstreamer-chunk-number: 1"
-H "nvstreamer-total-chunks: 1"
-H "nvstreamer-is-last-chunk: true"
-H "nvstreamer-identifier: ${IDENTIFIER}"
-H "nvstreamer-file-name: ${FILENAME}"
-F "mediaFile=@${FILE_PATH};filename=${FILENAME}"
-F "filename=${FILENAME}"
-F 'metadata={"timestamp":"2025-01-01T00:00:00"}')

3. Tell the agent the upload finished — this fans out to RTVI-CV + RTVI-embed

3. 告知agent上传完成 — 这会触发RTVI-CV + RTVI-embed的后续流程

SENSOR=$(printf '%s' "${UPLOAD_RESPONSE}" | jq -r .sensorId) [ -z "${SENSOR}" ] || [ "${SENSOR}" = "null" ]
&& { echo "Upload failed: no sensorId in response: ${UPLOAD_RESPONSE}"; exit 1; } printf '%s' "${UPLOAD_RESPONSE}"
| jq --arg filename "${FILENAME}" '. + {filename: $filename}'
| curl -s -X POST "http://${HOST_IP}:8000/api/v1/videos/${SENSOR}/complete"
-H "Content-Type: application/json"
-d @- | jq .

Wait for the `/complete` response (it returns `chunks_processed > 0` once embeddings land). Only then is the video searchable.

> The deprecated `PUT /api/v1/videos-for-search/{filename}` route is also wired in for legacy callers (single-shot, agent-driven), but its OpenAPI entry is flagged `deprecated`. Prefer the three-step flow above for new work.
SENSOR=$(printf '%s' "${UPLOAD_RESPONSE}" | jq -r .sensorId) [ -z "${SENSOR}" ] || [ "${SENSOR}" = "null" ]
&& { echo "上传失败：响应中无sensorId：${UPLOAD_RESPONSE}"; exit 1; } printf '%s' "${UPLOAD_RESPONSE}"
| jq --arg filename "${FILENAME}" '. + {filename: $filename}'
| curl -s -X POST "http://${HOST_IP}:8000/api/v1/videos/${SENSOR}/complete"
-H "Content-Type: application/json"
-d @- | jq .

等待`/complete`的响应（当嵌入数据生成完成后，会返回`chunks_processed > 0`）。只有此时视频才可被搜索。

> 已弃用的`PUT /api/v1/videos-for-search/{filename}`路由仍为旧版调用者提供支持（单次触发，由agent驱动），但其OpenAPI条目已标记为`deprecated`。新开发请优先使用上述三步流程。

RTSP stream — single endpoint

RTSP流 — 单端点操作

bash
curl -s -X POST "http://${HOST_IP}:8000/api/v1/rtsp-streams/add" \
  -H "Content-Type: application/json" \
  -d '{
    "sensorUrl": "rtsp://<host>:<port>/<path>",
    "name": "<sensor-name>",
    "username": "",
    "password": "",
    "location": "",
    "tags": ""
  }' | jq .
The response shape is 
{status, message, error}
— no 
sensorId
(the agent keys the stream by the 
name
you provided). On any step's failure earlier steps roll back. The 
start_embedding_generation
step is fire-and-verify: a 2xx confirms the request was accepted and the embedding pipeline is running in the background, not that the stream is searchable yet. Search hits will start appearing only after enough chunks land in Elasticsearch — poll with a low-
top_k
query a few seconds in if you need a readiness signal.
bash
curl -s -X POST "http://${HOST_IP}:8000/api/v1/rtsp-streams/add" \
  -H "Content-Type: application/json" \
  -d '{
    "sensorUrl": "rtsp://<host>:<port>/<path>",
    "name": "<sensor-name>",
    "username": "",
    "password": "",
    "location": "",
    "tags": ""
  }' | jq .
响应格式为
{status, message, error}
— 不包含
sensorId
（agent通过你提供的
name
来标识流）。任何步骤失败都会回滚之前的操作。
start_embedding_generation
步骤为触发即验证：2xx状态码仅确认请求已被接受且嵌入流水线在后台运行，不代表流已可被搜索。只有当足够多的分片存入Elasticsearch后才会出现搜索结果 — 如果需要就绪信号，可在几秒后用低
top_k
值的查询进行轮询。

Delete source — agent-backed cleanup

删除源 — agent后台清理

Delete through the agent backend, not bare VIOS, so VIOS storage and search embeddings are cleaned up together.
bash
undefined
通过agent后台删除，而非直接操作VIOS，这样可以同时清理VIOS存储和搜索嵌入数据。
bash
undefined

For video files: video_id is the VIOS sensor/video UUID

对于视频文件：video_id是VIOS传感器/视频的UUID

curl -s -X DELETE "http://${HOST_IP}:8000/api/v1/videos/<video_id>" | jq .
curl -s -X DELETE "http://${HOST_IP}:8000/api/v1/videos/<video_id>" | jq .

For RTSP streams: name is the registered source name

对于RTSP流：name是已注册的源名称

curl -s -X DELETE "http://${HOST_IP}:8000/api/v1/rtsp-streams/delete/<name>" | jq .

---
curl -s -X DELETE "http://${HOST_IP}:8000/api/v1/rtsp-streams/delete/<name>" | jq .

---

How Search Works

搜索工作原理

  1. Ingest — Files come in through the agent's three-step universal flow; RTSP streams through 
    /api/v1/rtsp-streams/add
    . Both routes hand the source to RTVI-CV (attribute detection) and RTVI-Embed (Cosmos Embed1) which generates vector embeddings for video segments.
  2. Index — Embeddings are stored in Elasticsearch via the Kafka pipeline.
  3. Query — Natural-language queries are embedded and matched against stored vectors by similarity.
  4. Results — Timestamped video segments ranked by relevance, with clip playback links.
This search orchestrated by VSS agent can lead to 3 behaviors:
  • Attribute-only: when the LLM decomposes the query and finds only appearance attributes with no action (e.g. "person wearing red jacket")
  • Embed-only: when the query has no extractable attributes (e.g. "show me forklifts")
  • Fusion: when the query has both an action and attributes (e.g., "person in red jacket running"), it runs embed search first, then reranks using attribute search
  1. 导入 — 文件通过agent的通用三步流程导入；RTSP流通过
    /api/v1/rtsp-streams/add
    导入。两种路由都会将源交给RTVI-CV（属性检测）和RTVI-Embed（Cosmos Embed1），后者为视频片段生成向量嵌入。
  2. 索引 — 嵌入数据通过Kafka流水线存储到Elasticsearch中。
  3. 查询 — 自然语言查询会被转换为嵌入向量，并与存储的向量进行相似度匹配。
  4. 结果 — 按相关性排序的带时间戳视频片段，包含剪辑播放链接。
由VSS agent编排的搜索会产生三种行为：
  • 仅属性搜索：当LLM分解查询后发现只有外观属性而无动作时（例如“穿红色夹克的人”）
  • 仅嵌入搜索：当查询无法提取属性时（例如“展示叉车”）
  • 融合搜索：当查询同时包含动作和属性时（例如“穿红色夹克的人在跑步”），会先执行嵌入搜索，再通过属性搜索重新排序

Mandatory workflow

强制工作流

When using this skill, ALWAYS follow this high-level workflow:
  1. Resolve inputs from user instructions — HARD STOP if 
    $HOST_IP
    is not explicitly provided.     See § Input resolution below. Do NOT default to 
    localhost
    , 
    127.0.0.1
    , the host the agent itself is running on, or any other guess. Do NOT issue a 
    POST http://.../generate
    request until the user has supplied an endpoint. Respond to the user with a single question asking for 
    HOST_IP
    / the VSS agent endpoint and wait.
  2. Resolve the source — HARD STOP before any 
    /generate
    call.     If the user query references a specific video / sensor name (e.g. "the airport video", "warehouse_cam_3", "sample warehouse"), verify it's actually registered in VIOS before firing 
    POST .../generate
    . List sources via the 
    vss-manage-video-io-storage
    skill.
    Then:
    • If the named source (or a clearly substring-matching name) IS in the list → proceed to step 3. Forward the user's natural-language query verbatim — the agent's own search tool decomposer (
      services/agent/src/vss_agents/tools/search.py
      ) extracts 
      video_sources
      from the prose given the available sources, so the skill does NOT need to construct a structured 
      video sources
      payload.
    • If the named source is NOT in the list → STOP. Do NOT fire 
      /generate
      as a probe. Respond to the user with the registered source names and ask whether they meant one of those, want to ingest the missing source (point them at Ingestion prerequisite and run the matching file or RTSP recipe through the agent backend, not bare VIOS), or want to abandon the query. Wait for clarification.
    • If the query names no specific source ("find forklifts in the ingested videos", "search across all sources") → skip the substring check, but 
      sensor/list
      must still return non-empty (otherwise no sources are ingested → HARD STOP).
  3. Run the search(es) via approach chosen
  4. Present the results to the user query. Format response as a professional inspection report but name it 
    Video Search Results
    : — Use clear section headers
    • Organize findings individually with supporting detail, and close with a summary
    • Use tables where comparisons help. Write like a technical report, not a chat message.
    • If criteria results are non-null, then in addition to a column "Critic result" ("confirmed" | "rejected" | "skipped"), include a column "Criteria" with all the criteria for this search result ({criteria_n}: ✓ | ✗)
  5. CRITICAL: Verify the results and explain this to the user concisely. If search fails, or returns unexpected results (i.e. videos that do not appear to match user query, zero matches, zero videos returned, error etc.), STOP. Do not proceed without reading troubleshooting.md to iterate with feedback loops until proper results are found and presented like a professional inspection report.
  6. Final verifications:
    • ALWAYS inform user that final and further verifications can be run. Present this as a 
      Verification Step
    • ONLY IF user agrees, download screenshots using the 
      screenshot_url
      of the best candidates (highest similarity scores) from the search hits (JSON results) to 
      /tmp
      . Read them and verify if they correspond to the user query
使用本技能时，必须遵循以下高层工作流：
  1. 从用户指令中解析输入 — 如果未明确提供
    $HOST_IP
    则立即停止    。请参阅下方的§ 输入解析部分。请勿默认使用
    localhost
    、
    127.0.0.1
    、agent自身运行的主机或其他猜测值。在用户提供端点前，请勿发起
    POST http://.../generate
    请求。向用户发送单一问题，请求提供
    HOST_IP
    /VSS agent端点并等待回复。
  2. 解析源 — 在任何
    /generate
    调用前立即停止    。如果用户查询引用了特定视频/传感器名称（例如“机场视频”、“warehouse_cam_3”、“样本仓库”），在执行
    POST .../generate
    前必须验证其已在VIOS中注册。通过
    vss-manage-video-io-storage
    技能列出源。
    然后：
    • 如果命名的源（或明显匹配的子字符串名称）在列表中 → 继续步骤3。直接转发用户的自然语言查询 — agent自身的搜索工具分解器（
      services/agent/src/vss_agents/tools/search.py
      ）会根据可用源从文本中提取
      video_sources
      ，因此本技能无需构造结构化的
      video sources
      负载。
    • 如果命名的源不在列表中 → 停止。请勿将
      /generate
      作为探测工具调用。向用户返回已注册的源名称，询问他们是否指其中之一、是否要导入缺失的源（引导至导入前提章节并通过agent后台运行匹配的文件或RTSP导入流程，而非直接操作VIOS），或是否要放弃查询。等待用户澄清。
    • 如果查询未指定特定源（“在已导入的视频中查找叉车”、“跨所有源搜索”） → 跳过子字符串检查，但
      sensor/list
      必须返回非空结果（否则无已导入源 → 立即停止）。
  3. 通过所选方式运行搜索
  4. 向用户呈现搜索结果。将响应格式化为专业检查报告，命名为
    视频搜索结果
    ： — 使用清晰的章节标题
    • 单独整理每个发现并附带支持细节，最后添加摘要
    • 在有助于对比的地方使用表格。撰写风格类似技术报告，而非聊天消息。
    • 如果标准结果非空，则除了“验证结果”列（“已确认” | “已拒绝” | “已跳过”）外，还需添加“标准”列，包含该搜索结果的所有标准（{criteria_n}: ✓ | ✗）
  5. 关键步骤：验证结果并向用户简要说明。 如果搜索失败，或返回意外结果（例如视频与用户查询不匹配、无匹配结果、无视频返回、错误等），立即停止。在获得正确结果并以专业检查报告形式呈现前，必须阅读troubleshooting.md并通过反馈循环迭代解决问题。
  6. 最终验证：
    • 必须告知用户可以进行最终和进一步的验证。将此作为
      验证步骤
      呈现
    • 仅当用户同意时，从搜索结果（JSON格式）中下载相似度最高的候选结果的
      screenshot_url
      到
      /tmp
      。查看截图并验证其是否符合用户查询

Input resolution

输入解析

Infer these inputs only from the conversation or user query (no other files unless provided). If some cannot be inferred, ask the user immediately:
  • $HOST_IP: where the VSS agent backend runs
仅从对话或用户查询中推断这些输入（除非提供了其他文件）。如果某些输入无法推断，立即询问用户：
  • $HOST_IP：VSS agent后台运行的地址

Gotchas

注意事项

  • ALWAYS step into the troubleshooting step of the workflow immediately if anything unexpected happens, read troubleshooting.md
  • Queries work best with concrete visual descriptions (objects, actions, locations). Augment user queries if needed to enhance the quality of the questions, expanding potential details
  • The skill assumes video sources are already ingested through the agent backend (see Ingestion prerequisite). It MAY run the agent-backed ingest recipes when the user explicitly asks ("ingest 
    <file>
    for search", "add 
    <rtsp_url>
    for search"); it does NOT search the local filesystem for files the user didn't name, and it does NOT use the bare-VIOS PUT path (no embeddings get generated). Workflow step 2 still makes confirming "this source exists in VIOS" a hard precondition before 
    /generate
    .
  • Use 
    vss-query-analytics
    skill to cross-reference search results with incident/alert data
  • 任何意外情况发生时，立即进入工作流的故障排除步骤，阅读troubleshooting.md
  • 查询在使用具体视觉描述（物体、动作、位置）时效果最佳。如有需要，可扩充用户查询以提升问题质量，补充潜在细节
  • 本技能假设视频源已通过agent后台导入（请参阅导入前提）。当用户明确要求时（“导入
    <file>
    以供搜索”、“添加
    <rtsp_url>
    以供搜索”），可运行agent后台导入流程；但不会在用户未指定的情况下搜索本地文件系统，也不会使用直接的VIOS PUT路径（不会生成嵌入数据）。工作流第2步仍将“此源存在于VIOS中”作为
    /generate
    调用前的强制前提。
  • 使用
    vss-query-analytics
    技能将搜索结果与事件/警报数据交叉引用

Search via REST API

通过REST API搜索

Default to using this REST API approach, unless user specifies otherwise.
bash
undefined
默认使用此REST API方式，除非用户指定其他方式。
bash
undefined

Consider only ingested video file sources by default

默认仅考虑已导入的视频文件源

curl -s -X POST http://${HOST_IP}:8000/generate
-H "Content-Type: application/json"
-d '{"input_message": "find all instances of forklifts"}' | jq .
undefined
curl -s -X POST http://${HOST_IP}:8000/generate
-H "Content-Type: application/json"
-d '{"input_message": "find all instances of forklifts"}' | jq .
undefined

More Examples

更多示例

bash
undefined
bash
undefined

Search by object

按物体搜索

curl -s -X POST http://${HOST_IP}:8000/generate
-H "Content-Type: application/json"
-d '{"input_message": "find vehicles in the parking lot"}' | jq .
curl -s -X POST http://${HOST_IP}:8000/generate
-H "Content-Type: application/json"
-d '{"input_message": "find vehicles in the parking lot"}' | jq .

Search by action

按动作搜索

curl -s -X POST http://${HOST_IP}:8000/generate
-H "Content-Type: application/json"
-d '{"input_message": "show me people running"}' | jq .
curl -s -X POST http://${HOST_IP}:8000/generate
-H "Content-Type: application/json"
-d '{"input_message": "show me people running"}' | jq .

Search by time context

按时间上下文搜索

curl -s -X POST http://${HOST_IP}:8000/generate
-H "Content-Type: application/json"
-d '{"input_message": "what happened at the entrance between 2pm and 3pm?"}' | jq .
curl -s -X POST http://${HOST_IP}:8000/generate
-H "Content-Type: application/json"
-d '{"input_message": "what happened at the entrance between 2pm and 3pm?"}' | jq .

Consider only RTSP sources with 
search_source_type
filter i.e. live camera streams

通过
search_source_type
过滤器仅考虑RTSP源（即实时摄像头流）

curl -s -X POST http://${HOST_IP}:8000/generate
-H "Content-Type: application/json"
-d '{"input_message": "find all instances of forklifts", "search_source_type": "rtsp"}' | jq .
undefined
curl -s -X POST http://${HOST_IP}:8000/generate
-H "Content-Type: application/json"
-d '{"input_message": "find all instances of forklifts", "search_source_type": "rtsp"}' | jq .
undefined

Advanced control knobs

高级控制选项

If user query is ambiguous, user wants more guidance or when fine-grained control is needed, augment the user 
input_message
by calling out explicitly certain options in plain-text and steering the agent in the desired direction. Available control axes:
AxesTypeDefaultDescription
video sources
string[]nullFilter to specific cameras or sensor names
top k
int10Max results
minimum similarity
float0.0Min similarity threshold; raise (e.g. 0.3) to filter noise
critic usage
booltrueVLM verifies each result and removes false positives
description
stringnullFilter by camera metadata (e.g. location, category) if metadata is available
Pick and choose some of these tuning options. Adjust them as needed for the user’s situation and query. For examples of discovery modes leveraging these, see discovery_modes.md.
当用户查询模糊、用户需要更多指导或需要细粒度控制时，可通过在纯文本中明确调用某些选项来扩充用户的
input_message
，引导agent朝所需方向执行。可用控制维度：
维度类型默认值说明
video sources
string[]null过滤到特定摄像头或传感器名称
top k
int10最大结果数
minimum similarity
float0.0最小相似度阈值；提高值（例如0.3）可过滤噪声数据
critic usage
booltrueVLM验证每个结果并移除误报
description
stringnull如果有元数据，可按摄像头元数据（例如位置、类别）过滤
根据用户的场景和查询选择并调整这些调优选项。有关利用这些选项的发现模式示例，请参阅discovery_modes.md。

Search via Agent UI

通过Agent UI搜索

Open 
http://${HOST_IP}:3000/
and type natural-language queries:
find all instances of forklifts
show me people near the loading dock
when did a truck arrive at the gate?
find someone wearing a red jacket
Results include timestamped clips with similarity scores.
bump:2
打开
http://${HOST_IP}:3000/
并输入自然语言查询：
find all instances of forklifts
show me people near the loading dock
when did a truck arrive at the gate?
find someone wearing a red jacket
结果包含带时间戳的剪辑和相似度分数。
bump:2