Back to Details

vss-deploy-detection-tracking-3d

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Purpose

用途

Deploy and operate the RTVI-CV-3D microservice as MV3DT (
MODE=mv3dt
) — per-camera DeepStream perception plus BEV Fusion over multiple calibrated cameras — on the bundled sample dataset, custom videos, or live RTSP, without the full warehouse agent / LLM / VLM stack.
无需完整的仓库Agent/LLM/VLM栈，即可在捆绑样本数据集、自定义视频或实时RTSP流上，以MV3DT模式（
MODE=mv3dt
）部署并运行RTVI-CV-3D微服务——基于多台已校准摄像头的单摄像头DeepStream感知，再结合BEV Fusion。

Instructions

操作说明

Work top-to-bottom: answer the routing questions (Q0–Q3) under Routing, then follow the reference for the chosen path. Detailed step-by-step procedures live in 
references/
(deploy, calibration chain, camera configuration, verification, teardown, troubleshooting).
按从上到下的顺序操作：回答【路由】章节下的路由问题（Q0-Q3），然后按照所选路径的参考文档执行。详细的分步流程位于
references/
目录下（包含部署、校准流程、摄像头配置、验证、拆除、故障排查）。

Examples

示例

  • Enable multi-camera tracking on the sample dataset.
  • Deploy RTVI-CV-3D on my videos here: 
    <path/to/videos>
    .
  • Run MV3DT on RTSP streams after calibration.
  • 在样本数据集上启用多摄像头追踪。
  • 在指定路径的视频上部署RTVI-CV-3D：
    <path/to/videos>
    。
  • 校准完成后在RTSP流上运行MV3DT。

VSS Deploy Detection & Tracking — 3D (RTVI-CV-3D / MV3DT)

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

Bring up the RTVI-CV-3D microservice as the MV3DT stack (
MODE=mv3dt
) from the warehouse blueprint: per-camera DeepStream perception (
vss-rtvi-cv-mv3dt
) + BEV Fusion (
vss-rtvi-cv-bev-fusion
) + mosquitto MQTT bus + broker + VST sensor stack — without the agent / LLM / VLM stack that comes with the full warehouse blueprint.
The actual compose machinery lives in 
deploy/docker/industry-profiles/warehouse-operations/warehouse-mv3dt-app/
. This skill drives the env overrides, calibration chain, and verification.
从仓库蓝图中启动作为MV3DT栈（
MODE=mv3dt
）的RTVI-CV-3D微服务：单摄像头DeepStream感知（
vss-rtvi-cv-mv3dt
）+ BEV Fusion（
vss-rtvi-cv-bev-fusion
）+ mosquitto MQTT总线 + 消息代理 + VST传感器栈——无需完整仓库蓝图附带的Agent/LLM/VLM栈。
实际的compose配置位于
deploy/docker/industry-profiles/warehouse-operations/warehouse-mv3dt-app/
目录下。本技能负责环境变量覆盖、校准流程衔接以及验证操作。

Routing

路由

Ask the user at most four questions, then dispatch.
最多向用户提出四个问题，然后根据回答进行任务分发。

Q0 — Profile size (overlays or not)

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

Default to extended unless the user explicitly asks for minimal. Extended deploys ELK + 
vss-video-analytics-api-mv3dt
+ 
vss-kibana-init-mv3dt
+ 
vss-import-calibration-output-mv3dt
on top of MV3DT core — these are what the VST video wall needs to render bounding-box overlays. Without them, the video wall works but shows raw streams without overlays.
User answer
MINIMAL_PROFILE
What you getWhen to choose
extended (default)
""
MV3DT core + ELK + analytics API + Kibana. Overlays work in VST video wall. Recommended for a complete e2e experience."I want the full e2e experience", "I want to see bounding boxes", or no preference stated
minimal
"true"
MV3DT core only. ~5 fewer containers. No overlays in VST. Metadata still on Kafka/Redis."I only need the data", "edge / Thor host", "minimum footprint"
Note on selective ELK: there's no "minimal + ELK only" middle path in the current compose. Every 
${MINIMAL_PROFILE:+_extended}
-gated service comes up together (ES, Logstash, Kibana, video-analytics-api, kibana-init, import-calibration). 
bash
's 
:+
parameter expansion produces the 
_extended
suffix when 
MINIMAL_PROFILE
is set; extended switches the gating string back to plain 
bp_wh_kafka_mv3dt
which the active compose profile already matches. Either you accept the full extended bundle or you stay minimal.
除非用户明确要求最小化配置，否则默认使用扩展版。扩展版在MV3DT核心之上额外部署ELK + 
vss-video-analytics-api-mv3dt
+ 
vss-kibana-init-mv3dt
+ 
vss-import-calibration-output-mv3dt
——这些组件是VST视频墙渲染 bounding-box 叠加层所必需的。如果没有这些组件，视频墙仍可运行，但仅显示原始流，无叠加层。
用户回答
MINIMAL_PROFILE
值		获得的组件选择场景
extended（默认）
""
MV3DT核心 + ELK + 分析API + Kibana。VST视频墙可显示叠加层。 推荐用于完整端到端体验。用户需求为“我想要完整的端到端体验”、“我想看到bounding boxes”，或未明确说明偏好时
minimal
"true"
仅MV3DT核心。少约5个容器。VST无叠加层。 元数据仍存储在Kafka/Redis中。用户需求为“我只需要数据”、“边缘/Thor主机”、“最小资源占用”时
关于选择性ELK的说明： 当前compose中没有“最小化+仅ELK”的中间选项。所有受
${MINIMAL_PROFILE:+_extended}
控制的服务会一起启动（ES、Logstash、Kibana、video-analytics-api、kibana-init、import-calibration）。当设置
MINIMAL_PROFILE
时，
bash
的
:+
参数扩展会生成
_extended
后缀；扩展版会将控制字符串切换回普通的
bp_wh_kafka_mv3dt
，这与当前激活的compose配置文件匹配。您只能选择完整的扩展包或保持最小化配置。

Q1 — Data source

Q1 — 数据源

Ask this unless the source is explicit in the user's first message. A bare request like "deploy rtvi-cv-3d" routes to this MV3DT skill (
MODE=mv3dt
), but does not imply 
sample
.
  • sample — the bundled 4-camera synthetic dataset (
    warehouse-4cams-20mx20m-synthetic
    ). Calibration ships in-tree; no AMC run needed.
  • videos — the user has local video files (any 
    *.mp4
    named after their cameras). Standalone AMC (
    auto_calib
    profile) will run if calibration is missing.
  • rtsp — the user has live RTSP URLs. Calibration via VIOS-driven AMC; final deploy also needs a Sensor Info File (
    camera_info.json
    ) with those RTSP URLs.
除非用户的初始请求中明确指定数据源，否则需询问此问题。类似“部署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的传感器信息文件（
    camera_info.json
    ）。

Q2 — Calibration coverage (skip for 
sample
)

Q2 — 校准覆盖情况（
sample
数据源可跳过）

For 
videos
and 
rtsp
, check whether calibration is already on disk at the mount path the perception container expects:
bash
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}"
对于
videos
和
rtsp
数据源，需检查感知容器预期挂载路径下是否已存在校准信息：
bash
DATASET="${SAMPLE_VIDEO_DATASET:?}"          # 用户的数据集标识；详见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

查找以下任意文件：calibration.json，以及camInfo/目录下命名为'cam_'或'Camera'的*.yml或*.yaml文件（随附样本使用Camera*.yml，AMC可能生成cam_*.yaml——需扩大查找范围）

'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

If the user supplied a calibration path themselves, validate that path instead — don't recompute. See `configure-cameras.md` for camera-name normalization and authoritative camera-count discovery (parses `calibration.json`).
test -f "${CAL_DIR}/calibration.json"
&& ls "${CAL_DIR}/camInfo/"*.{yml,yaml} 2>/dev/null

如果用户自行提供了校准路径，则验证该路径即可——无需重新计算。有关摄像头名称标准化和权威摄像头数量检测（解析`calibration.json`）的内容，请查看`configure-cameras.md`。

Q3 — Detector + dataset slug (only when Q2 triggers AMC)

Q3 — 检测器+数据集标识（仅当Q2触发AMC时需询问）

  • resnet
    (default, fast) or 
    transformer
    (slower, better under occlusion) — passed to the AMC 
    /v1/calibrate/<id>
    API at Step B (see 
    vss-generate-video-calibration/SKILL.md:48-62
    ).
  • A short kebab-case dataset slug used as 
    SAMPLE_VIDEO_DATASET
    (e.g. 
    customer-aisle-4cams
    ). This drives the calibration mount path and gets persisted in 
    .env
    .
  • 选择
    resnet
    （默认，速度快）或
    transformer
    （速度慢，遮挡场景下表现更好）——该参数会在步骤B中传递给AMC的
    /v1/calibrate/<id>
    API（详见
    vss-generate-video-calibration/SKILL.md:48-62
    ）。
  • 提供一个短横线分隔格式（kebab-case）的数据集标识，用作
    SAMPLE_VIDEO_DATASET
    的值（例如
    customer-aisle-4cams
    ）。该标识将决定校准挂载路径，并被持久化到
    .env
    文件中。

Routing table

路由表

Q1Q2 resultPath
sample
(cal ships in-tree and already normalized)
references/deploy-rtvi-cv-3d-stack.md
 directly
videos
cal present
references/configure-cameras.md
 → 
references/deploy-rtvi-cv-3d-stack.md
videos
cal missing
references/calibration-workflow.md
 (videos mode) → 
references/configure-cameras.md
 → 
references/deploy-rtvi-cv-3d-stack.md
rtsp
cal present
references/configure-cameras.md
 → 
references/deploy-rtvi-cv-3d-stack.md
rtsp
cal missing
references/calibration-workflow.md
 (rtsp mode) → 
references/configure-cameras.md
 → 
references/deploy-rtvi-cv-3d-stack.md
Every path converges on 
references/verify-and-view.md
 once 
up -d
completes. 
references/troubleshooting.md
 and 
references/teardown.md
 are linked but off the happy path.
Disambiguation rule. In this skill, "RTVI-CV-3D" means the MV3DT microservice deployment and uses 
MODE=mv3dt
. Route to 
../vss-deploy-profile/references/warehouse.md
 only when the user asks for the full warehouse blueprint, Sparse4D, 
MODE=3d
, or 
warehouse-3d-app
. This skill is for MV3DT only without the agent stack / LLM / VLM.
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
。本技能仅适用于不含Agent栈/LLM/VLM的MV3DT。

Prerequisites

前置条件

1. Repo path

1. 代码库路径

Locate 
video-search-and-summarization/
on disk. All compose commands run from 
<repo>/deploy/docker/
. If unknown, ask the user.
在磁盘上找到
video-search-and-summarization/
目录。所有compose命令都需在
<repo>/deploy/docker/
目录下执行。如果路径未知，请询问用户。

2. NGC CLI + key

2. NGC CLI + API密钥

$NGC_CLI_API_KEY
must be set and must have access to 
nvidia/vss-core/*
images. See 
vss-deploy-profile/references/ngc.md
for setup if missing.
If the user previously ran 
ngc config set
but 
$NGC_CLI_API_KEY
isn't exported in this shell, the key is already on disk:
bash
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"
Make sure the key value also lands in 
industry-profiles/warehouse-operations/.env:164
(
NGC_CLI_API_KEY=...
) — compose only reads it from there at 
up
time, not from your shell env.
必须设置
$NGC_CLI_API_KEY
，且该密钥需有权限访问
nvidia/vss-core/*
镜像。如果未设置，请查看
vss-deploy-profile/references/ngc.md
进行配置。
如果用户之前执行过
ngc config set
但当前shell中未导出
$NGC_CLI_API_KEY
，则密钥已存储在磁盘上：
bash
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
slug

3. 
HARDWARE_PROFILE
标识

The public MV3DT supported stream counts are listed in the Warehouse Quickstart Guide under "MV3DT Vision AI Profile Supported Deployment Options." Use the matching 
HARDWARE_PROFILE
slug below.
Pick from 
nvidia-smi --query-gpu=name --format=csv,noheader
:
GPU name
HARDWARE_PROFILE
MV3DT supported streams
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
If the user's GPU is not listed here, check 
industry-profiles/warehouse-operations/.env
for available 
HARDWARE_PROFILE
values, then confirm the matching profile exists in 
blueprint-configurator/blueprint_config.yml
before using it. Do not infer a stream count from the slug alone.
The per-GPU MV3DT cap is enforced at deploy time. 
vss-configurator-mv3dt
computes 
final_stream_count = min(NUM_STREAMS, max_streams_supported)
and applies a 
keep_count
file-management op against 
${VSS_DATA_DIR}/videos/${SAMPLE_VIDEO_DATASET}/
so only 
final_stream_count
.mp4
files remain (sorted lexicographically, last N kept). If your GPU's MV3DT supported stream count (above table) is below your camera count, perception / 
mdx-raw
/ 
mdx-bev
run with the supported stream count. Either pick a GPU with a higher supported stream count or surface the cap explicitly to the user so they're aware which streams will be processed.
公开的MV3DT支持流数量列在《仓库快速入门指南》的“MV3DT视觉AI配置支持的部署选项”章节下。请使用下方匹配的
HARDWARE_PROFILE
标识。
从
nvidia-smi --query-gpu=name --format=csv,noheader
命令的输出中选择对应的GPU：
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流数量（如上表）低于摄像头数量，则感知服务/
mdx-raw
/
mdx-bev
将以支持的流数量运行。您可以选择支持更高流数量的GPU，或明确告知用户该上限，让他们了解哪些流会被处理。

4. App data on disk

4. 磁盘上的应用数据

VSS_DATA_DIR
must point at the extracted 
vss-warehouse-app-data
directory (separate from the repo). Pointing it at the repo's 
deploy/docker/
causes the deploy to stall: the configurator can't find the dataset, redis can't open its log file, and perception stays in 
Created
. Verify the path before deploy.
Pre-flight check before deploy:
bash
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
VSS_DATA_DIR
必须指向已解压的
vss-warehouse-app-data
目录（与代码库分离）。如果指向代码库的
deploy/docker/
目录，部署将停滞：配置工具无法找到数据集，Redis无法打开日志文件，感知服务将一直处于
Created
状态。部署前请验证该路径。
部署前的预检检查：
bash
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

对于sample/videos模式——视频目录必须存在

test -d "${DATA_DIR}/videos/${DATASET}"
|| { echo "ERROR: ${DATA_DIR}/videos/${DATASET} missing — wrong slug or app-data not extracted"; exit 1; }
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

已知部分发布的应用数据压缩包中，样本数据集的视频数量少于数据集名称暗示的数量——如果您的GPU的mv3dt上限足够高可以使用所有摄像头，请验证并单独获取缺失的摄像头视频。

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
ls "${DATA_DIR}/videos/${DATASET}/"*.mp4 2>/dev/null | wc -l

Ensure every per-service subdir under data_log/ exists. kafka / elasticsearch /

确保data_log/下的每个服务子目录都存在。kafka/elasticsearch/

redis / postgres and the video-analytics API upload path (
/web-api-app/files
)

redis/postgres以及视频分析API的上传路径（
/web-api-app/files
）

run as non-root UIDs against these bind mounts. Without write access the daemons

以非root UID身份运行这些绑定挂载。没有写入权限的话，守护进程

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"
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

仅向特定容器UID授予写入权限——使用范围化ACL，而非777权限或chown。UID（来自data-directory.md）：postgres=70，redis=999，elasticsearch/VST/

NOT chown. UIDs (per data-directory.md): postgres=70, redis=999, elasticsearch / VST /

kafka=1000。第一个命令覆盖现有文件；第二个命令设置默认ACL，以便

kafka=1000. The first call covers existing files; the second sets default ACLs so

守护进程在运行时创建的文件/目录（例如postgres的PGDATA）继承访问权限。

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"

> **Scoped ACLs, not `chmod 777`.** This grants only the known container UIDs access — it does
> **not** make `data_log` world-writable, and it does **not** `chown` (which would break postgres /
> Elasticsearch, since they re-own their dirs on first start). Prefer this for agent-driven runs and
> shared hosts. The canonical [`../vss-deploy-profile/references/data-directory.md`](../vss-deploy-profile/references/data-directory.md)
> documents the broad `chmod -R 777` and the per-container UID table; this skill uses the scoped-ACL
> equivalent instead. **Ask the user for confirmation before changing host permissions.**
>
> Requires a POSIX-ACL filesystem (ext4 / xfs — the default) and the `acl` package (`setfacl`). If a
> daemon still logs a permission error after deploy, find its UID
> (`docker inspect <container> --format '{{.Config.User}}'`) and add `-m u:<uid>:rwx` to both calls.

If app-data isn't extracted yet: download via `ngc registry resource download-version "nvidia/vss-warehouse/vss-warehouse-app-data:<version>"` and `tar -xvf` (see [`references/deploy-rtvi-cv-3d-stack.md`](references/deploy-rtvi-cv-3d-stack.md) for tag discovery and full steps).
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`](../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`](references/deploy-rtvi-cv-3d-stack.md)）。

5. Pre-flight (system)

5. 系统预检

nvidia-smi
, NVIDIA Docker runtime visible (
docker info | grep -i runtimes
), and 
docker run --rm --gpus all ubuntu:24.04 nvidia-smi
all green. Full driver / kernel / sysctl checks live in 
vss-deploy-profile/references/prerequisites.md
.
If any check fails, fix before continuing — don't proceed to deploy.
确保
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. Browser reachability (cloud / corp-VPN hosts only)

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

If the user will view the VST video wall through a browser on a different network than the deploy host (cloud VM, corp VPN, ssh-tunnelled session), upstream firewall rules may block VST WebRTC (STUN to 
stun.l.google.com:19302
, plus random UDP for media). See 
references/verify-and-view.md#browser-reachability
 for symptoms and workarounds. Also: some hosts block the AMC microservice's default port (TCP/8010); if the user reports the AMC UI on 
:5000
works but its data calls fail, retry with a different 
VSS_AUTO_CALIBRATION_PORT
.
如果用户将通过与部署主机不同网络的浏览器查看VST视频墙（云VM、企业VPN、SSH隧道会话），上游防火墙规则可能会阻止VST WebRTC（连接到
stun.l.google.com:19302
的STUN，以及用于媒体的随机UDP端口）。有关症状和解决方法，请查看
references/verify-and-view.md#browser-reachability
。此外：部分主机会阻止AMC微服务的默认端口（TCP/8010）；如果用户报告AMC的
:5000
UI可正常工作但数据调用失败，请尝试使用不同的
VSS_AUTO_CALIBRATION_PORT
。

Troubleshooting

故障排查

When any deploy, calibration, or verification step fails, stop and classify the failure before retrying. The quick checks below cover the most common MV3DT errors; use 
references/troubleshooting.md
 for full diagnostic commands and fixes, 
../vss-generate-video-calibration/SKILL.md
 for AMC workflow failures, and 
../vss-deploy-profile/references/warehouse-debug.md
 for broader warehouse-stack issues.
SymptomLikely causeFirst check or fix
vss-rtvi-cv-bev-fusion
is unhealthy or 
/tmp/fusion_ready
is missing		Broker not ready, 
MAX_EXPECTED_SENSORS
mismatch, or 
STREAM_TYPE
mismatch		Check 
broker-health-check
, 
docker inspect --format '{{.State.Health.Status}}' vss-rtvi-cv-bev-fusion
, and 
mdx-raw
/ 
mdx-bev
; then re-run 
references/configure-cameras.md
 if stream counts differ
Perception shows 
Active sources : 0
, no FPS, or fewer cameras than expected		Stale VST sensor state, wrong dataset slug, missing calibration, or per-GPU stream capVerify 
SAMPLE_VIDEO_DATASET
, 
NUM_STREAMS
, 
camInfo/
, and the VST sensor list; if old sensors remain, follow 
references/teardown.md
 before redeploying
vss-rtvi-cv-mv3dt
exits with 
MqttCommunicator
"invalid node" or tracker submit failures		Camera names in videos, 
calibration.json
, and 
camInfo/
do not match the 
Camera
, 
Camera_01
, ... convention		Normalize all camera names together with 
references/configure-cameras.md
 Step 0, then clear stale VST state and redeploy
AMC project creation, upload, calibration, or MV3DT export failsAutoMagicCalib service/API issue outside this MV3DT deploy pathUse 
../vss-generate-video-calibration/SKILL.md
 to deploy/debug AMC, then return to 
references/calibration-workflow.md
 after export succeeds
vss-behavior-analytics-mv3dt
restarts with calibration schema validation errors		AMC export has empty 
group
, 
region
, or 
place
fields		Apply the placeholder patch in 
references/calibration-workflow.md
 Step 4a, or populate those fields in AMC before export
Extended profile has no overlays and 
vss-import-calibration-output-mv3dt
logs 
imageMetadata.json not found
AMC MV3DT export did not produce 
images/Top.png
and 
images/imageMetadata.json
Synthesize both files with 
references/calibration-workflow.md
 Step 4b, then restart the one-shot importer
Image pulls, model load, or first-start engine build failMissing / expired 
NGC_CLI_API_KEY
, incorrect 
VSS_DATA_DIR
, missing BodyPose3DNet files, or GPU OOM		Re-check NGC auth, confirm 
${VSS_DATA_DIR}/models/mv3dt/BodyPose3DNet/
, tail 
vss-rtvi-cv-mv3dt
logs, and free or change 
RT_CV_DEVICE_ID
if the GPU is exhausted
Before destructive recovery (
docker compose down -v
, clearing 
data_log
, deleting VST sensor state, or changing host ACLs), explain the impact and get user confirmation. Capture the failing command, relevant 
.env
values, 
docker compose ps
, and the last container logs before making state-reset changes.
当部署、校准或验证步骤失败时，请先停止操作并分类故障，然后再重试。以下快速检查涵盖了最常见的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
文件缺失		消息代理未就绪、
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传感器状态过期、数据集标识错误、缺少校准信息或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
的输出以及容器的最新日志。

How it fits together

组件协作关系

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)
SKILL.md（即本文件——Q0/Q1/Q2/Q3路由）
  └─ 若缺少校准信息 ─> calibration-workflow.md
  │                     └─ 衔接vss-generate-video-calibration（部署+驱动API）
  │                     └─ 获取/v1/result/{project_id}/mv3dt_result?result_type=amc（启用优化时还会获取vggt）
  │                     └─ 将校准文件存储到warehouse-mv3dt-app/calibration/sample-data/<slug>/
  ├─> configure-cameras.md（摄像头名称标准化、NUM_STREAMS同步、VST传感器修剪）
  └─> deploy-rtvi-cv-3d-stack.md（使用bp_wh_kafka_mv3dt + 扩展/最小化配置执行compose up）
        └─> verify-and-view.md（FPS、fusion_ready、mdx-bev、VST视频墙+WebRTC检查）

Related Skills

相关技能

  • vss-generate-video-calibration
     — the AMC skill. Owns AMC deployment, RTSP capture, calibration API, and the 
    /v1/result/.../mv3dt_result
    export hook this skill consumes. 
    calibration-workflow.md
    chains into it.
  • vss-deploy-profile
     — cross-profile umbrella. Use that instead when the user wants the full warehouse blueprint (with agents / LLM / VLM), not just MV3DT.
  • vss-manage-video-io-storage
     — VIOS / VST API skill. Useful for the VST video wall (overlay viz) and for sensor management referenced in 
    configure-cameras.md
    .
The repo's authoritative warehouse-blueprint reference at 
../vss-deploy-profile/references/warehouse.md
 covers 2D / 3D / MV3DT inside the full warehouse stack — this skill is the MV3DT-only companion that trims the agent / LLM / VLM layer.
  • 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层。