
名称	vss-deploy-detection-tracking-3d
描述	> 将RTVI-CV-3D微服务作为MV3DT（`MODE=mv3dt`）进行部署和运营：每个摄像头的DeepStream感知加上校准摄像头上的BEV融合。支持捆绑的示例数据集、自定义视频文件和RTSP流，并在缺少校准时链接到`vss-generate-video-calibration`。有关完整的仓库蓝图，请使用`vss-deploy-profile`；有关单摄像头2D检测，请使用`vss-deploy-detection-tracking-2d`。
开源协议	Apache-2.0 metadata:
版本	“3.2.1” github-url: “https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization” tags: “nvidia blueprint rtvi-cv-3d mv3dt detection tracking 3d warehouse”

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

目标

部署并运行RTVI-CV-3D微服务作为MV3DT（MODE=mv3dt）——每个摄像头的DeepStream感知加上多个校准摄像头上的BEV融合——在捆绑的示例数据集、自定义视频或实时RTSP上运行，无需完整仓库智能体/LLM/VLM套件。

使用说明

自上而下工作：回答路由下的路由问题（Q0–Q3），然后遵循所选路径的参考。详细的分步程序位于references/中（部署、校准链、摄像头配置、验证、拆卸、故障排除）。

示例

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

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

从仓库蓝图以MV3DT套件（MODE=mv3dt）启动RTVI-CV-3D微服务：每摄像头DeepStream感知（vss-rtvi-cv-mv3dt）+ BEV融合（vss-rtvi-cv-bev-fusion）+ mosquitto MQTT总线 + broker + VST传感器堆栈——不含完整仓库蓝图中随附的智能体/LLM/VLM堆栈。

实际组合机制位于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 + 分析API + Kibana。VST视频墙中的叠加层可正常工作。推荐用于完整的端到端体验。	“我想要完整的e2e体验”，“我想看到边界框”，或没有明确偏好
最小	`"true"`	仅MV3DT核心。大约少5个容器。VST中无叠加层。元数据仍位于Kafka/Redis上。	“我只需要数据”，“边缘/Thor主机”，“最小占用空间”

关于选择性ELK的说明： 在当前组合服务中不存在“最小+仅ELK”的中间路径。每个由${MINIMAL_PROFILE:+_extended}门控的服务会一起启动（ES、Logstash、Kibana、video-analytics-api、kibana-init、import-calibration）。bash的:+参数扩展在设置MINIMAL_PROFILE时生成_extended后缀；扩展版将门控字符串切换回普通的bp_wh_kafka_mv3dt，而已激活的组合配置文件已匹配。要么接受完整的扩展捆绑包，要么保持最小化。

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进行校准；最终部署还需要一个传感器信息文件（camera_info.json），其中包含这些RTSP URL。

Q2 — 校准覆盖范围（对于`sample`跳过）

对于videos和rtsp，检查校准是否已存在于感知容器期望的挂载路径上：

DATASET="${SAMPLE_VIDEO_DATASET:?}"          # 用户的dataset slug；参见Q3
CAL_DIR="${VSS_APPS_DIR}/industry-profiles/warehouse-operations/warehouse-mv3dt-app/calibration/sample-data/${DATASET}"

# 查找任一：calibration.json，加上camInfo/*.yml或*.yaml，命名方式为
# 'cam_*'或'Camera*'（随附的示例使用Camera*.yml，AMC可能生成cam_*.yaml—相应地放宽条件）
test -f "${CAL_DIR}/calibration.json" \
  && ls "${CAL_DIR}/camInfo/"*.{yml,yaml} 2>/dev/null

如果用户自己提供了校准路径，请验证该路径——不要重新计算。参见configure-cameras.md以了解摄像头名称规范化和权威摄像头数量发现（解析calibration.json）。

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

resnet（默认，快速）或transformer（较慢，遮挡下更好）— 在步骤B中传递给AMC /v1/calibrate/<id> API（参见vss-generate-video-calibration/SKILL.md:48-62）。
一个短的kebab大小写数据集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，没有智能体套件/LLM/VLM。

先决条件

1. 仓库路径

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

2. NGC CLI + 密钥

必须设置$NGC_CLI_API_KEY并且必须有权访问nvidia/vss-core/*镜像。如果缺失，请参见vss-deploy-profile/references/ngc.md进行设置。

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

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=...）——组合服务在up时只从该文件读取，而不是从shell环境。

3. `HARDWARE_PROFILE` slug

公共MV3DT支持的流数在仓库快速入门指南中的“MV3DT Vision AI Profile Supported Deployment Options”下列出。使用下面匹配的HARDWARE_PROFILE slug。

根据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中确认匹配的配置文件存在后再使用。不要仅从slug推断流数。

每个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无法打开日志文件，感知停留在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

# 对于sample / videos模式—videos目录必须存在
test -d "${DATA_DIR}/videos/${DATASET}" \
  || { echo "ERROR: ${DATA_DIR}/videos/${DATASET} missing — wrong slug or app-data not extracted"; exit 1; }

# 合理性检查：视频计数应与校准计数匹配。
# 一些已发布的应用数据tarball带有示例数据集，但视频数量少于数据集名称所暗示的数量—
# 如果您的GPU的mv3dt上限足以使用所有摄像头，请单独验证并补充缺失的cams。
ls "${DATA_DIR}/videos/${DATASET}/"*.mp4 2>/dev/null | wc -l

# 确保data_log/下的每个服务子目录存在。kafka / elasticsearch /
# redis / postgres和video-analytics API上传路径（`/web-api-app/files`）
# 以非root UID在这些绑定挂载上运行。如果没有写访问权限，守护进程或校准/图像导入可能会因权限错误失败。
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"

# 仅向特定容器UID授予写访问权限—限定ACL，而不是777或chown。
# UID（根据data-directory.md）：postgres=70, redis=999, elasticsearch / VST /
# kafka=1000。第一个调用覆盖现有文件；第二个设置*默认*ACL，以便
# 守护进程在运行时创建的文件/目录（例如postgres PGDATA）继承访问权限。
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，因为它们在首次启动时会重新拥有自己的目录）。对于代理驱动的运行和共享主机，优先采用这种做法。规范化的../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到stun.l.google.com:19302，以及媒体用的随机UDP）。请参阅references/verify-and-view.md#browser-reachability查看症状和解决方法。另外：某些主机可能阻止AMC微服务的默认端口（TCP/8010）；如果用户报告:5000上的AMC UI可以工作，但其数据调用失败，请尝试使用不同的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`因校准schema验证错误而重启	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内存不足	重新检查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（本文件—Q0/Q1/Q2/Q3路由）
  └─ 如果校准缺失 ─> calibration-workflow.md
  │                   └─ 链接到vss-generate-video-calibration（部署 + 驱动API）
  │                   └─ 获取/v1/result/{project_id}/mv3dt_result?result_type=amc（当refinement启用时还有vggt）
  │                   └─ 将校准文件放入warehouse-mv3dt-app/calibration/sample-data/<slug>/
  ├─> configure-cameras.md（摄像头名称规范化、NUM_STREAMS同步、VST传感器修剪）
  └─> deploy-rtvi-cv-3d-stack.md（使用bp_wh_kafka_mv3dt +扩展/最小组合启动）
        └─> verify-and-view.md（FPS、fusion_ready、mdx-bev、VST视频墙 + WebRTC检查）

VSS部署-3D检测与跟踪Skill vss-deploy-detection-tracking-3d

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

目标

使用说明

示例

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

路由

Q0 — 配置文件大小（是否使用叠加层）

Q1 — 数据源

Q2 — 校准覆盖范围（对于`sample`跳过）

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

路由表

先决条件

1. 仓库路径

2. NGC CLI + 密钥

3. `HARDWARE_PROFILE` slug

4. 磁盘上的应用数据

5. 预检（系统）

6. 浏览器可达性（仅限云/企业VPN主机）

故障排除

组合结构

相关技能

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

目标

使用说明

示例

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

路由

Q0 — 配置文件大小（是否使用叠加层）

Q1 — 数据源

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

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

路由表

先决条件

1. 仓库路径

2. NGC CLI + 密钥

3. HARDWARE_PROFILE slug

4. 磁盘上的应用数据

5. 预检（系统）

6. 浏览器可达性（仅限云/企业VPN主机）

故障排除

组合结构

相关技能

Q2 — 校准覆盖范围（对于`sample`跳过）

3. `HARDWARE_PROFILE` slug