vss-deploy-detection-tracking-3d

用途

将 RTVI-CV-3D 微服务部署并作为 MV3DT（MODE=mv3dt）运行——针对每个摄像头执行 DeepStream 感知，并通过多个已校准摄像头进行 BEV Fusion——可使用随附的示例数据集、自定义视频或实时 RTSP，无需完整的仓库 Agent / 大模型 / VLM 技术栈。

说明

从上到下操作：先回答 路由 中的路由问题（Q0–Q3），然后按照所选路径的参考文档操作。详细的分步流程见 references/（部署、校准链、摄像头配置、验证、拆除、故障排查）。

示例

• 在示例数据集上启用多摄像头跟踪。
• 在此处部署 RTVI-CV-3D，使用我的视频：<path/to/videos>。
• 校准后，在 RTSP 流上运行 MV3DT。

VSS 部署检测与跟踪 — 3D（RTVI-CV-3D / MV3DT）

从仓库蓝图启动 RTVI-CV-3D 微服务，作为 MV3DT 技术栈（MODE=mv3dt）运行：针对每个摄像头执行 DeepStream 感知（vss-rtvi-cv-mv3dt）+ BEV Fusion（vss-rtvi-cv-bev-fusion）+ mosquitto MQTT 总线 + broker + VST 传感器技术栈——无需完整仓库蓝图附带的 Agent / 大模型 / VLM 技术栈。

实际的 compose 配置位于 deploy/docker/industry-profiles/warehouse-operations/warehouse-mv3dt-app/。此技能负责环境变量覆盖、校准链和验证。

路由

最多向用户提问 四个问题，然后选择对应路径。

Q0 — 配置规模（是否包含叠加层）

除非用户明确要求最小配置，否则默认选择扩展配置。扩展配置会在 MV3DT 核心服务之上添加 ELK + vss-video-analytics-api-mv3dt + vss-kibana-init-mv3dt + vss-import-calibration-output-mv3dt——VST 视频墙需要这些服务来渲染边界框叠加层。没有这些服务，视频墙仍可运行，但只显示原始视频流，不显示叠加层。

用户回答	MINIMAL_PROFILE	包含内容	适用情况
扩展（默认）	""	MV3DT 核心服务 + ELK + analytics API + Kibana。VST 视频墙支持叠加层。 推荐用于完整的端到端体验。	“我想要完整的端到端体验”、“我想看到边界框”，或未说明偏好
最小	"true"	仅 MV3DT 核心服务。容器少约 5 个。VST 不显示叠加层。 元数据仍会写入 Kafka/Redis。	“我只需要数据”、“边缘设备 / Thor 主机”、“占用空间最小”

关于选择性启用 ELK 的说明： 当前 compose 配置中没有“仅最小配置 + ELK”的折中选项。每个由 ${MINIMAL_PROFILE:+_extended} 控制的服务都会一起启动（ES、Logstash、Kibana、video-analytics-api、kibana-init、import-calibration）。bash 的 :+ 参数展开会在设置 MINIMAL_PROFILE 时生成 _extended 后缀；扩展配置会将门控字符串改回普通的 bp_wh_kafka_mv3dt，与当前启用的 compose 配置文件匹配。你只能接受完整的扩展套件，或选择最小配置。

Q1 — 数据源

除非用户的首条消息已明确说明数据源，否则询问此问题。像“部署 rtvi-cv-3d”这样的简单请求会路由到此 MV3DT 技能（MODE=mv3dt），但不代表用户选择了 sample。

• sample — 随附的 4 摄像头合成数据集（warehouse-4cams-20mx20m-synthetic）。数据集内含校准文件；无需运行 AMC。
• videos — 用户有本地视频文件（任意以摄像头名称命名的 *.mp4 文件）。如果缺少校准文件，将运行独立 AMC（auto_calib 配置文件）。
• rtsp — 用户有实时 RTSP URL。通过 VIOS 驱动 AMC 进行校准；最终部署还需要包含这些 RTSP URL 的 Sensor Info File（camera_info.json）。

Q2 — 校准覆盖范围（sample 可跳过）

对于 videos 和 rtsp，检查感知容器预期挂载路径上是否已有校准文件：

DATASET="${SAMPLE_VIDEO_DATASET:?}"          # the user's dataset slug; see Q3
CAL_DIR="${VSS_APPS_DIR}/industry-profiles/warehouse-operations/warehouse-mv3dt-app/calibration/sample-data/${DATASET}"

# Look for ANY of: calibration.json, plus camInfo/*.yml or *.yaml with either
# 'cam_*' or 'Camera*' naming (the shipped sample uses Camera*.yml, AMC may
# produce cam_*.yaml — broaden accordingly)
test -f "${CAL_DIR}/calibration.json" \
  && ls "${CAL_DIR}/camInfo/"*.{yml,yaml} 2>/dev/null

如果用户自行提供了校准路径，则改为验证该路径——不要重新计算。摄像头名称规范化和权威摄像头数量的确定（解析 calibration.json）请参阅 configure-cameras.md。

Q3 — 检测器 + 数据集 slug（仅当 Q2 触发 AMC 时）

• resnet（默认，速度快）或 transformer（速度较慢，在遮挡情况下效果更好）——在步骤 B 中传递给 AMC /v1/calibrate/<id> API（参见 vss-generate-video-calibration/SKILL.md:48-62）。
• 一个简短的 kebab-case 数据集 slug，用作 SAMPLE_VIDEO_DATASET（例如 customer-aisle-4cams）。它决定校准挂载路径，并会保存到 .env 中。

路由表

Q1	Q2 结果	路径
sample	（校准文件随代码库提供且已规范化）	直接前往 references/deploy-rtvi-cv-3d-stack.md
videos	存在校准文件	references/configure-cameras.md → references/deploy-rtvi-cv-3d-stack.md
videos	缺少校准文件	references/calibration-workflow.md（videos 模式）→ references/configure-cameras.md → references/deploy-rtvi-cv-3d-stack.md
rtsp	存在校准文件	references/configure-cameras.md → references/deploy-rtvi-cv-3d-stack.md
rtsp	缺少校准文件	references/calibration-workflow.md（rtsp 模式）→ references/configure-cameras.md → references/deploy-rtvi-cv-3d-stack.md

所有路径都会在 up -d 完成后汇入 references/verify-and-view.md。references/troubleshooting.md 和 references/teardown.md 也有链接，但不属于顺利完成部署的主路径。

消歧规则。 在此技能中，“RTVI-CV-3D”指 MV3DT 微服务部署，并使用 MODE=mv3dt。仅当用户要求完整仓库蓝图、Sparse4D、MODE=3d 或 warehouse-3d-app 时，才路由到 ../vss-deploy-profile/references/warehouse.md。此技能仅适用于 MV3DT，不包含 Agent 堆栈 / LLM / VLM。

先决条件

1. 仓库路径

在磁盘上找到 video-search-and-summarization/。所有 compose 命令都从 <repo>/deploy/docker/ 运行。如果路径未知，请询问用户。

2. NGC CLI + 密钥

必须设置 $NGC_CLI_API_KEY，且该密钥必须有权访问 nvidia/vss-core/* 镜像。若未设置，请参阅 vss-deploy-profile/references/ngc.md 了解配置方法。

如果用户之前运行过 ngc config set，但 $NGC_CLI_API_KEY 未在当前 shell 中导出，密钥已保存在磁盘上：

NGC_CLI_API_KEY=$(awk -F'= ' '/^apikey/{print $2}' ~/.ngc/config 2>/dev/null)
test -n "${NGC_CLI_API_KEY}" && echo "key sourced from ~/.ngc/config"

确保密钥值也写入 industry-profiles/warehouse-operations/.env:164（NGC_CLI_API_KEY=...）——compose 只会在运行 up 时从该文件读取密钥，不会从 shell 环境读取。

3. HARDWARE_PROFILE 标识

MV3DT 支持的公开视频流数量列于 Warehouse Quickstart Guide 的“MV3DT Vision AI Profile Supported Deployment Options”部分。请使用下方匹配的 HARDWARE_PROFILE 标识。

从 nvidia-smi --query-gpu=name --format=csv,noheader 的输出中选择：

GPU 名称	HARDWARE_PROFILE	MV3DT 支持的视频流数量
RTX PRO 6000 Blackwell	RTXPRO6000BW	18
H100 (NVL, SXM HBM3)	H100	13
L40S	L40S	7
IGX Thor	IGX-THOR	4
DGX Spark	DGX-SPARK	4

如果用户的 GPU 未列在此处，请检查 industry-profiles/warehouse-operations/.env 中可用的 HARDWARE_PROFILE 值，然后确认 blueprint-configurator/blueprint_config.yml 中存在匹配的配置文件，再使用它。不要仅根据标识推断视频流数量。

每个 GPU 的 MV3DT 上限会在部署时强制执行。 vss-configurator-mv3dt 会计算 final_stream_count = min(NUM_STREAMS, max_streams_supported)，并对 ${VSS_DATA_DIR}/videos/${SAMPLE_VIDEO_DATASET}/ 执行 keep_count 文件管理操作，使目录中只保留 final_stream_count 个 .mp4 文件（按字典序排序，保留最后 N 个）。如果 GPU 支持的 MV3DT 视频流数量（见上表）少于摄像头数量，则 perception / mdx-raw / mdx-bev 将按支持的视频流数量运行。请改用支持更多视频流的 GPU，或明确向用户说明此上限，让他们了解将处理哪些视频流。

4. 磁盘上的应用数据

VSS_DATA_DIR 必须指向已解压的 vss-warehouse-app-data 目录（与代码库分开）。如果将其指向代码库中的 deploy/docker/，部署会卡住：配置器无法找到数据集，redis 无法打开其日志文件，而 perception 会一直处于 Created 状态。部署前请确认路径。

部署前检查：

DATA_DIR="${VSS_DATA_DIR:?VSS_DATA_DIR not set in .env}"
DATASET="${SAMPLE_VIDEO_DATASET:-warehouse-4cams-20mx20m-synthetic}"

for sub in videos models data_log; do
  test -d "${DATA_DIR}/${sub}" || { echo "ERROR: ${DATA_DIR}/${sub} missing"; exit 1; }
done

# For sample / videos modes — videos directory must exist
test -d "${DATA_DIR}/videos/${DATASET}" \
  || { echo "ERROR: ${DATA_DIR}/videos/${DATASET} missing — wrong slug or app-data not extracted"; exit 1; }

# Sanity: video count should match calibration count.
# Some published app-data tarballs are known to ship the sample dataset with
# fewer videos than the dataset name implies — verify and source any missing
# cams separately if your GPU's mv3dt cap is high enough to use them all.
ls "${DATA_DIR}/videos/${DATASET}/"*.mp4 2>/dev/null | wc -l

# Ensure every per-service subdir under data_log/ exists. kafka / elasticsearch /
# redis / postgres and the video-analytics API upload path (`/web-api-app/files`)
# run as non-root UIDs against these bind mounts. Without write access the daemons
# or calibration/image import can fail with permission errors.
mkdir -p \
  "${DATA_DIR}/data_log/analytics_cache" \
  "${DATA_DIR}/data_log/calibration_toolkit" \
  "${DATA_DIR}/data_log/elastic/data" \
  "${DATA_DIR}/data_log/elastic/logs" \
  "${DATA_DIR}/data_log/kafka" \
  "${DATA_DIR}/data_log/redis/data" \
  "${DATA_DIR}/data_log/redis/log" \
  "${DATA_DIR}/data_log/vss_video_analytics_api"

# Grant write access to the specific container UIDs only — scoped ACLs, NOT 777 and
# NOT chown. UIDs (per data-directory.md): postgres=70, redis=999, elasticsearch / VST /
# kafka=1000. The first call covers existing files; the second sets *default* ACLs so
# files/dirs the daemons create at runtime (e.g. postgres PGDATA) inherit the access.
ACL='u:70:rwx,u:999:rwx,u:1000:rwx'
setfacl -R    -m "$ACL" "${DATA_DIR}/data_log"
setfacl -R -d -m "$ACL" "${DATA_DIR}/data_log"

使用限定范围的 ACL，而不是 chmod 777。 这只会授予已知容器 UID 访问权限，不会让 data_log 对所有用户可写，也不会执行 chown（这会导致 postgres / Elasticsearch 出错，因为它们会在首次启动时重新取得各自目录的所有权）。对于由 Agent 驱动的运行和共享主机，建议使用此方法。规范的 ../vss-deploy-profile/references/data-directory.md 介绍了广泛使用的 chmod -R 777 和各容器的 UID 表；此技能改用对应的限定范围 ACL 方法。更改主机权限前，请征得用户确认。

需要使用 POSIX-ACL 文件系统（ext4 / xfs——默认文件系统），并安装 acl 软件包（setfacl）。如果部署后某个守护进程仍记录权限错误，请查找其 UID （docker inspect <container> --format '{{.Config.User}}'），并在两次调用中添加 -m u:<uid>:rwx。

如果应用数据尚未解压：使用 ngc registry resource download-version "nvidia/vss-warehouse/vss-warehouse-app-data:<version>" 下载，再执行 tar -xvf（标签查找和完整步骤见 references/deploy-rtvi-cv-3d-stack.md）。

5. 部署前检查（系统）

nvidia-smi、可见的 NVIDIA Docker 运行时（docker info | grep -i runtimes），以及 docker run --rm --gpus all ubuntu:24.04 nvidia-smi 均应通过。完整的驱动程序 / 内核 / sysctl 检查位于 vss-deploy-profile/references/prerequisites.md。

如果任何检查未通过，请先修复，再继续操作——不要继续部署。

6. 浏览器可访问性（仅限云端／企业 VPN 主机）

如果用户要通过浏览器查看 VST 视频墙，且浏览器所在网络与部署主机所在网络不同（云 VM、企业 VPN、SSH 隧道会话），上游防火墙规则可能会阻止 VST WebRTC（向 stun.l.google.com:19302 发送 STUN 请求，以及用于媒体传输的随机 UDP 端口）。症状和解决方法请参阅 references/verify-and-view.md#browser-reachability。另外：有些主机会阻止 AMC 微服务的默认端口（TCP/8010）；如果用户报告 AMC UI 在 :5000 上可以正常工作，但数据调用失败，请更换 VSS_AUTO_CALIBRATION_PORT 的值后重试。

故障排查

任何部署、校准或验证步骤失败时，请先停止并判断故障类型，再重试。以下快速检查涵盖最常见的 MV3DT 错误；完整的诊断命令和修复方法请参阅 references/troubleshooting.md，AMC 工作流故障请参阅 ../vss-generate-video-calibration/SKILL.md，更广泛的仓库堆栈问题请参阅 ../vss-deploy-profile/references/warehouse-debug.md。

症状	可能原因	首先检查或修复
vss-rtvi-cv-bev-fusion 状态不健康，或缺少 /tmp/fusion_ready	Broker 尚未就绪、MAX_EXPECTED_SENSORS 不匹配，或 STREAM_TYPE 不匹配	检查 broker-health-check、docker inspect --format '{{.State.Health.Status}}' vss-rtvi-cv-bev-fusion 以及 mdx-raw / mdx-bev；如果流数量不匹配，请重新运行 references/configure-cameras.md
感知服务显示 Active sources : 0、没有 FPS，或摄像头数量少于预期	VST 传感器状态过期、数据集 slug 错误、缺少校准，或每 GPU 流数量上限	验证 SAMPLE_VIDEO_DATASET、NUM_STREAMS、camInfo/ 和 VST 传感器列表；如果仍有旧传感器，请按照 references/teardown.md 操作后再重新部署
vss-rtvi-cv-mv3dt 因 MqttCommunicator 的 "invalid node" 错误或跟踪器提交失败而退出	视频、calibration.json 和 camInfo/ 中的摄像头名称不符合 Camera、Camera_01……这一命名约定	按照 references/configure-cameras.md 步骤 0 统一所有摄像头名称，然后清除过期的 VST 状态并重新部署
AMC 项目创建、上传、校准或 MV3DT 导出失败	AutoMagicCalib 服务/API 问题，不属于此 MV3DT 部署流程	使用 ../vss-generate-video-calibration/SKILL.md 部署或调试 AMC；导出成功后，再返回 references/calibration-workflow.md
vss-behavior-analytics-mv3dt 因校准架构验证错误而重启	AMC 导出的 group、region 或 place 字段为空	按照 references/calibration-workflow.md 步骤 4a 应用占位符补丁，或在 AMC 中填写这些字段后再导出
扩展配置没有叠加层，且 vss-import-calibration-output-mv3dt 日志显示 imageMetadata.json not found	AMC MV3DT 导出未生成 images/Top.png 和 images/imageMetadata.json	按照 references/calibration-workflow.md 步骤 4b 生成这两个文件，然后重启一次性导入器
拉取镜像、加载模型或首次启动时构建引擎失败	NGC_CLI_API_KEY 缺失或过期、VSS_DATA_DIR 不正确、缺少 BodyPose3DNet 文件，或 GPU OOM	重新检查 NGC 身份验证，确认 ${VSS_DATA_DIR}/models/mv3dt/BodyPose3DNet/，查看 vss-rtvi-cv-mv3dt 的日志，并在 GPU 资源耗尽时释放资源或更改 RT_CV_DEVICE_ID

在执行破坏性恢复操作（docker compose down -v、清除 data_log、删除 VST 传感器状态或更改主机 ACL）之前，请说明影响并征得用户确认。在进行状态重置更改之前，请记录失败的命令、相关的 .env 值、docker compose ps 输出以及最近的容器日志。

工作原理

SKILL.md (this file — Q0/Q1/Q2/Q3 routing)
  └─ if cal missing ─> calibration-workflow.md
  │                     └─ chains to vss-generate-video-calibration (deploy + drive API)
  │                     └─ fetches /v1/result/{project_id}/mv3dt_result?result_type=amc (plus vggt when refinement is enabled)
  │                     └─ lands calibration files at warehouse-mv3dt-app/calibration/sample-data/<slug>/
  ├─> configure-cameras.md (camera-name normalization, NUM_STREAMS sync, VST sensor trim)
  └─> deploy-rtvi-cv-3d-stack.md (compose up with bp_wh_kafka_mv3dt + extended/minimal)
        └─> verify-and-view.md (FPS, fusion_ready, mdx-bev, VST video wall + WebRTC checks)

相关技能

• vss-generate-video-calibration — AMC 技能。负责 AMC 部署、RTSP 采集、校准 API，以及本技能使用的 /v1/result/.../mv3dt_result 导出钩子。calibration-workflow.md 会调用此技能。
• vss-deploy-profile — 跨配置档总入口。如果用户需要完整的仓库蓝图（包含 Agent / LLM / VLM），而不仅仅是 MV3DT，请改用此技能。
• vss-manage-video-io-storage — VIOS / VST API 技能。适用于 VST 视频墙（叠加可视化），以及 configure-cameras.md 中提到的传感器管理。

代码库中权威的仓库蓝图参考 ../vss-deploy-profile/references/warehouse.md，涵盖完整仓库技术栈中的 2D / 3D / MV3DT；此技能是仅针对 MV3DT 的配套技能，精简掉 Agent / LLM / VLM 层。