vss-deploy-detection-tracking-2d

用途

部署、调试和运行 RTVI-CV 检测／跟踪 2D 微服务，并调用其 REST API。

前提条件

• 可通过 $HOST_IP 访问的活动 VSS 部署（参见 vss-deploy-profile 和 references/）。
• 如需拉取任何镜像，请准备好 $NGC_CLI_API_KEY 和 $NVIDIA_API_KEY 中的 NGC 凭据。
• 调用方已安装 curl、jq 和 Docker。

说明

请按照下方的路由表和分步工作流操作。每个以 workflow、quick start 或 flow 结尾的部分，都应从头到尾依次执行。详细参考资料位于 references/，辅助脚本位于 scripts/——当技能指定脚本名称时，请通过 run_script 调用。

示例

完整端到端示例保存在 evals/ 下（每个 *.json 清单都包含一个可运行场景），也以内联形式提供在下方各工作流的 curl 代码块中。运行 Tier-3 评估：nv-base validate <this-skill-dir> --agent-eval，即可重放这些示例。

限制

• 需要部署匹配的 VSS 配置文件／微服务，并确保调用方可以访问。
• NGC 托管的模型和 NIM 可能受到速率限制、GPU 内存要求和许可限制。
• 并发、GPU 内存和存储限制取决于主机硬件和配置文件的 compose 文件。

故障排查

• 错误：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。

RTVI-CV — 检测与跟踪（统一技能）

用于 实时视频智能 CV（RTVI-CV） 微服务的统一技能。一个技能包含两个操作入口：

• 部署／运行／调试／拆除本地 RTVI-CV 容器 → 参见 references/deploy-vss-detection-tracking-2d.md
• 在运行实例上调用 RTVI-CV REST API（流、健康状态、指标、嵌入）→ 参见 references/usage-vss-detection-tracking-2d.md

服务：rtvi-cv（metropolis_perception_app） 镜像：nvcr.io/<org>/<repo>:<tag> — 由用户在部署时提供 REST 端口：9000（/api/v1 — /live、/ready、/startup、/metrics、/stream/add、/stream/remove、嵌入） 硬件：x86/aarch64 dGPU（T4、A100、L40、H100、B200、RTX）、SBSA（Spark、Grace-Hopper）、Jetson（Thor、Orin、Xavier）

---

操作路由 — 每次调用时只选择一次

用户意图（示例表述）	流程	加载此参考文档
deploy rtvi-cv warehouse 2d、run rtvicv warehouse-3d with 4 streams、start smartcity gdino、launch perception app、bring up sparse4d	部署	references/deploy-vss-detection-tracking-2d.md
stop rtvi-cv、tear down、kill the perception container、cleanup rtvicv-perception-docker	拆除（由部署文档中的“模式选择”处理）	references/deploy-vss-detection-tracking-2d.md + references/teardown-flow.md
check rtvi-cv logs、diagnose rtvi-cv crashing、troubleshoot healthcheck failing、rtvi-cv won't start	调试	references/deploy-vss-detection-tracking-2d.md + references/troubleshooting.md
add a stream、remove camera、list streams、health check、is rtvi-cv ready、get metrics、what's the FPS、check GPU usage、generate text embeddings、call rtvi-cv api	API 使用	references/usage-vss-detection-tracking-2d.md + references/api-reference.md

**选择规则：**将用户的表述与上表匹配，并立即加载对应的参考文件。不要混用流程 — 部署流程假定尚无正在运行的容器；API 使用流程假定容器已在 http://<host>:9000 上运行。

如果意图确实不明确（例如，用户只说“我想使用 rtvi-cv”），请通过一次 AskQuestion 询问：是要部署新实例，还是调用已在运行的实例？

---

内容分布

vss-deploy-detection-tracking-2d/
├── SKILL.md          # this file (routing + contracts)
├── assets/           # data files (deploy-defaults.yml — single source of truth for tags / refs / paths / GPU)
├── evals/            # Tier-3 eval manifests (deploy-evals.json, usage-evals.json)
├── scripts/          # 23 bash + python helpers (see `scripts/` for the full inventory)
└── references/       # workflow runbooks (deploy / api-usage / teardown / troubleshooting / …)

如需查看逐文件清单及各参考文档的涵盖内容，请参阅 references/workflow-reference.md。

所有脚本均通过 $SKILL_DIR/scripts/<name> 从技能根目录调用 — 部署参考文档中的路径原样保留，从技能根目录运行 Agent 时可正确解析。

---

可用脚本

辅助脚本位于 scripts/ 中，从技能根目录按名称调用 — 请通过 run_script("scripts/<name>") 调用每个脚本，以便 Agent 记录 规范的工具调用。

脚本	用途	参数
load_defaults.sh	检测平台（x86 dGPU / SBSA / Jetson），并从 assets/deploy-defaults.yml 解析 YAML 默认值。	--usecase <name>
fetch_resources.sh	下载并解压 NGC 资源，扫描文件布局。	--ngc-ref <ref>（可选）
apply_in_container.sh	第 4 步的主机端包装脚本（在运行中的容器内执行 apply_config.sh）。	<container_name>
apply_config.sh	在容器内替换路径、设置批次、接收端、源以及引擎缓存。	<usecase> <stream_count> <sink_type>
start_app_in_container.sh	第 5 步的主机端包装脚本（调用 run_app_and_wait.sh）。	<container_name>
run_app_and_wait.sh	在容器内启动应用，并执行就绪检查、收集指标及日志。	<config_path>
add_streams.sh / update_stream_sources.sh	第 6 步的 REST 流生命周期管理。	<rtsp_or_file_uri>...
collect_metrics.sh	拉取 /api/v1/metrics 快照。	无
discover_streams.sh	通过 /stream/get-stream-info 枚举活动流。	无
synthesize_docker_run.sh	输出适用于已解析环境的平台对应 docker run 命令行。	无
render_box.sh	呈现固定宽度的步骤回执。	<step_label>
calibration_manager.py	管理校准产物，并使每个用例的引擎缓存失效。	--usecase <name> --reset

如需查看所有辅助脚本（缓存、GPU 检查、设置）的完整清单，请浏览 scripts/；每个脚本的 --help 都会说明其参数。

如何使用此技能

1. **先阅读此文件。**它仅负责路由，不包含工作流。
2. 根据上方的路由表匹配用户意图。
3. 仅加载一份参考文档（DEPLOY 或 API USAGE）。不要预加载两份——每份参考文档都很长，并包含各自完整的契约。
4. **严格遵循已加载的参考文档。**这些参考文档是前身技能 vss-deploy-detection-tracking-2d（部署／拆除／调试）和 rtvicv-api（REST API）中逐字节保留的契约——每个步骤的顺序不变量、bash 批处理规则、方框渲染规则和 AskQuestion 契约均予以保留。
5. 对于 DEPLOY，参考文档会强制执行其自身的启动契约：单行确认 → 规划工具调用（TodoWrite 数组包含 5 个待办事项，或在较新版 Claude Code 中连续调用 5 次 TaskCreate）→ Step 1 问题。不要叙述，不要预先检查，也绝不能输出“正在加载 TodoWrite/TaskCreate”或任何有关延迟工具解析的文字——规划工具会静默加载。

---

输出契约 — DEPLOY 流程

运行 DEPLOY / TEARDOWN / DEBUG 流程时，每次成功部署都必须遵守以下四项。它们是用户在步骤之间唯一的反馈渠道；漏掉任何一项都属于行为回归。

1. 将每个步骤的结束状态渲染在定宽方框中——Step 1 部署目标、Step 2 Pipeline 配置、Step 3 容器、Step 4 应用配置、Step 5 计划 + 结果。不能只显示最终摘要。方框是用户的步骤回执。方框几何规格固定（见下文“通用方框格式”）。每个步骤的内容规则（方框内应包含哪些行）见 references/deploy-vss-detection-tracking-2d.md 中的“Step N box content rule”。
2. Step 5 结果方框之后，发出 references/next-steps.md § “11.c” 中的 Step 6 AskUserQuestion——绝不能用自由形式的 后续步骤 项目列表替代它。此菜单是部署流程的退出入口：用户可以一键运行指标检查、管理流、查看日志或拆除部署，无需记住 curl URL。
3. 用户选择 Step 6 类别后，发出 references/next-steps.md § “11.d” 中的后续 AskUserQuestion——绝不能用说明文字 + 可直接复制的 curl 示例 +“要我运行 X 吗？”之类的自由文本问题替代。每个类别都有各自的具体操作菜单；用户选择操作后，技能会输出 API 方框并运行 curl。各类别的后续操作：
   • 管理流 → 添加／移除／列出。移除选项须根据 /stream/get-stream-info 动态生成——每个活动流提供一个选项，标签为 <camera_id> · <camera_url>；当 ACTIVE > 1 时，另加“全部移除”（完整规格：§ “remove_streams 子流程”）。
   • 停止部署 → 停止应用 / 停止容器 / 完全拆除。
   • 检查指标和 FPS → 无需后续提问；打印 /api/v1/metrics API 方框后，直接运行 collect_metrics.sh。
   • 检查存活状态／就绪状态 → 无需后续提问；打印三个健康端点的 API 方框后，探测全部三个端点。
4. 渲染每个步骤的完整内容，而非概览行——渲染方框是必要条件，但并非充分条件。每个步骤的行组成规格见 references/deploy-vss-detection-tracking-2d.md 中的“Step N box content rule”。Step 4（应用配置）最容易被 Agent 简化——其规范的逐用例键列表位于 references/apply-config.md § “Per-use-case complete edit list”；对于当前用例和设置，Agent 必须为该表中的每个键输出一行 ✔ [section] key=value — annotation。包含 5 个键的区段 → 输出 5 行；包含 6 个键的区段 → 输出 6 行。绝不能每个区段只输出一行概览。 禁止的做法（这些是 Agent 在压力下会退回采用的捷径，会破坏用户体验）：

• ❌ 关于加载内部工具的叙述。 绝不要输出“I need to load TodoWrite (a deferred tool the skill calls for the task widget)”、 “Loading TaskCreate…”、“Calling ToolSearch for the planning tool…” 或任何其他关于解析／加载／获取延迟加载工具的文字。 Agent 会静默加载工具。用户只会看到 ✔ <pinned-values> 摘要行，随后是组件——绝不会看到工具解析相关的脚手架文字。
• ❌ 把全部 5 个部署步骤合并到一个 TaskCreate 的 description 字段中。 当 TaskCreate 是可用的规划工具时，应连续发起 5 次独立的 TaskCreate 调用（每个步骤一次）。逐字模板见 references/task-list.md §“Initial TaskCreate calls”。TodoWrite 也遵循同一规则——用一个调用在 todos:[…] 数组中包含全部 5 个待办事项；绝不能创建一个 content 为多行列表的待办事项。
• ❌ 擅自选择 dynamic 流模式。 该技能的默认模式是 stream_mode=static——Agent 会在应用启动前，将自动发现的 file:// URL 写入 DS 主配置的 [source-list] 区块。只有在用户明确提出要求（“之后通过 REST 添加流”、“使用动态流模式”），或用户在第 2 步的 AskQuestion 中选择 dynamic 时，才切换到 dynamic。面对“部署 rtvi-cv，包含 N 个流”这类一般性请求时选择 dynamic，会违反部署评审标准，也不符合用户对 /metrics 的预期。完整原因见 references/pipeline-config.md §“Defaults — the skill is static-mode by default”。
• ❌ 用一行 ✔ App ready in Ns, N streams, fps total Y 取代第 5 步的结果框。
• ❌ 使用 ASCII 框线字符（+、-、=、*），而不是轻量框线字符（┌ ─ ┐ │ └ ┘）。
• ❌ 以为“用户知道接下来该做什么”而跳过第 6 步。
• ❌ 第 6 步之后，输出大段 Markdown 文字、多个 curl 代码块，再以“要我运行其中任何一个吗？”收尾——这是 Agent 容易退回采用的形式，会绕过 11.d 菜单和每次 API 调用对应的方框。让用户从菜单中选择；技能展示解析后的 API 方框；技能执行该调用。不要提出开放式问题。
• ❌ 合并第 4 步的概览——部署文档的第 4 步内容规则明确禁止以下做法：
  • ✔ Batch size 3 (tile grid: 1×3) → 必须拆成 5 行（[streammux] batch-size=3、[primary-gie] batch-size=3、[source-list] max-batch-size=3、[tiled-display] rows=1、[tiled-display] columns=3）。
  • ✔ Output sink eglsink → 每个 sink 键各占一行（eglsink 共 4 个键，例如 [sink0] enable=1、type=2、sync=0、qos=0——确切列表请查阅 apply-config.md）。
  • ✔ Sources static (3 streams, http-port=9000) → 必须提供 6 行带注释的 [source-list] 配置。
  • ✔ Tile grid 1 row × 3 cols（单行）→ 必须拆成两行：[tiled-display] rows=1 和 [tiled-display] columns=3。

通用框格式

每个步骤退出框（步骤 1 到步骤 5 结果）的几何规范。所有框形状相同；只有标题和正文行会因步骤而异。

• 宽度：从一角到另一角共 128 个字符——┌ 位于第 1 列，┐ 位于第 128 列。终端较宽时，框保持左对齐；不要拉伸。内部内容区域为 124 个字符（在 │ 边框内，两侧各留一个空格边距）。
• 仅使用轻型框线字符：┌ ─ ┐ │ └ ┘。不要使用 +、-、=、* ASCII 替代字符。
• 顶边框——标题居中：┌ + N₁ 个短横线 + ␣ + 标题 + ␣ + N₂ 个短横线 + ┐，其中 N₁ + N₂ + len(title) + 2 = 126。均匀分配填充：N₁ = floor((126 − len(title) − 2) / 2)，N₂ = 126 − len(title) − 2 − N₁。N₁ 和 N₂ 的差最多为 1。
• 正文：每项事实占一行，格式为 │ <填充至内部内容区域 124 字符的内容> │。每行事实采用 ✔ <补齐至 13 个字符的键> <值> 格式（前置两个空格、符号、右侧补齐至 13 个字符的键、两个空格、值）。
• 组间空行：在逻辑分组之间（例如步骤 1 中的 Identity / Model / Videos）输出 │ <124 个空格> │，方便用户一目了然地浏览框内容。
• 底边框：└ + 126 个短横线 + ┘——实线边框，不带标题。

各步骤框顶部使用的标准步骤标题：

┌─────────────────────────────────────────────────────── Deploy targets ───────────────────────────────────────────────────────┐
┌─────────────────────────────────────────────────── Pipeline configuration ───────────────────────────────────────────────────┐
┌───────────────────────────────────────────────────────── Container ──────────────────────────────────────────────────────────┐
┌──────────────────────────────────────────────────── Apply configuration ─────────────────────────────────────────────────────┐
┌──────────────────────────────────────────────── Perception Application — Plan ───────────────────────────────────────────────┐
┌────────────────────────────────────────────── Perception Application — Results ──────────────────────────────────────────────┐

各步骤的内容规则（每个框中应包含哪些行、根据模式隐藏行、apply-config 的分段布局、步骤 5 的 PLAN-then-RESULT 模式、步骤 3 的 docker run 合成要求）位于 references/deploy-vss-detection-tracking-2d.md 的“Step N box content rule”部分——渲染相应步骤时请阅读这些规则。

快速触发词（助记）

短语	流程
deploy rtvicv warehouse 2d with 4 streams and display	部署
run smartcity gdino on gpu 1	部署
stop the perception container	拆除（部署文档）
rtvi-cv healthcheck failing	调试（部署文档 + 故障排除）
add a stream to rtvi-cv	API 使用
is rtvi-cv ready on localhost:9000	API 使用
get rtvi-cv metrics	API 使用
generate text embeddings via rtvi-cv	API 使用

bump:1