vss-setup-behavior-analytics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Purpose

用途

Deploy the behavior-analytics service standalone with the user's chosen entrypoint, config, and calibration.

独立部署行为分析服务，支持用户自定义入口点、配置及校准选项。

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/

and helper scripts live in

scripts/

— call them via

run_script

when the skill points to a script by name.

请遵循下方的路由表和分步工作流程。所有以workflow、quick start或flow结尾的章节需按从上到下的顺序执行。详细参考资料位于

references/

目录，辅助脚本位于

scripts/

目录——当技能指向某个脚本名称时，可通过

run_script

调用该脚本。

Examples

示例

Worked end-to-end examples are kept under

evals/

(each

*.json

manifest contains a runnable scenario). Run a Tier-3 evaluation to replay them:

bash

nv-base validate skills/vss-setup-behavior-analytics --agent-eval

A minimal standalone bring-up looks like:

bash

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
docker compose -f services/analytics/behavior-analytics/compose.yml up -d vss-behavior-analytics-base

references/deploy-behavior-analytics-service.md

for the full workflow (entrypoint pick, config source, dynamic updates).

完整的端到端示例存放在

evals/

目录下（每个

*.json

清单包含一个可运行的场景）。运行Tier-3评估即可复现这些场景：

bash

nv-base validate skills/vss-setup-behavior-analytics --agent-eval

最小化独立启动示例如下：

bash

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
docker compose -f services/analytics/behavior-analytics/compose.yml up -d vss-behavior-analytics-base

完整工作流程（入口点选择、配置源、动态更新）请参考

references/deploy-behavior-analytics-service.md

。

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资源。

VSS Setup Behavior Analytics — Standalone

VSS Setup Behavior Analytics — 独立部署

Deploy just the

vss-behavior-analytics

container (the spatial-AI analytics pipeline from the upstream

behavior-analytics

repo), not as part of the full warehouse blueprint stack.

The full operational walkthrough — entrypoint table, config-source options, calibration types, dynamic-update wire contract, troubleshooting — is

references/deploy-behavior-analytics-service.md

. This SKILL.md only handles routing and prerequisites.

仅部署

vss-behavior-analytics

容器（源自上游

behavior-analytics

仓库的空间AI分析流水线），而非作为完整仓库蓝图栈的一部分。

完整的操作指南——入口点表、配置源选项、校准类型、动态更新通信协议、故障排查——请参考

references/deploy-behavior-analytics-service.md

。本SKILL.md仅处理路由和前置条件。

When to use

使用场景

"Deploy behavior analytics" / "run behavior-analytics standalone"
"I just want to run analytics, not the full stack"
"Change the entrypoint to fusion_search / dev_example / analytics 3D / mv3dt"
"Use my own behavior-analytics config / calibration JSON"
"Point behavior-analytics at the warehouse-3d (or mv3dt) config without spinning up the rest of the warehouse profile"
"Dynamic config / dynamic calibration into a running behavior-analytics"

“部署行为分析服务” / “独立运行behavior-analytics”
“我只想运行分析服务，而非完整栈”
“将入口点切换为fusion_search / dev_example / analytics 3D / mv3dt”
“使用我自己的behavior-analytics配置/校准JSON文件”
“将behavior-analytics指向warehouse-3d（或mv3dt）配置，而无需启动仓库配置文件的其余部分”
“对运行中的behavior-analytics进行动态配置/动态校准”

Prerequisites

前置条件

Repo checkout with
```
$VSS_APPS_DIR
```
pointing at
```
<repo>/deploy/docker/
```
. Required by the service compose's volume binds.
NGC credentials —
```
$NGC_CLI_API_KEY
```
set so docker can pull the image. See
```
../vss-deploy-profile/references/ngc.md
```
.
Docker runtime — Docker Engine 28.3.3 with Docker Compose plugin v2.39.1+. Verify with
```
docker --version
```
and
```
docker compose version
```
.
Optional broker (Kafka / Redis Streams / MQTT). The container starts fine without one — the Kafka client retries a bounded number of times, then the app exits and
```
restart: always
```
cycles the container. Status will show
```
Restarting (N)
```
in
```
docker ps
```
until a broker is reachable. With a broker, dynamic config / dynamic calibration over
```
mdx-notification
```
become available.
Optional config / calibration files on disk if the user is bringing their own.

If any required prerequisite fails, surface the gap before going further.

仓库检出：确保
```
$VSS_APPS_DIR
```
指向
```
<repo>/deploy/docker/
```
目录。这是服务compose文件的卷绑定所必需的。
NGC凭据：已设置
```
$NGC_CLI_API_KEY
```
，以便Docker能够拉取镜像。参考
```
../vss-deploy-profile/references/ngc.md
```
。
Docker运行时：Docker Engine版本为28.3.3，且Docker Compose插件版本为v2.39.1+。可通过
```
docker --version
```
和
```
docker compose version
```
验证。
可选消息代理（Kafka / Redis Streams / MQTT）：容器无需代理即可正常启动——Kafka客户端会进行有限次数的重试，之后应用退出，
```
restart: always
```
配置会循环重启容器。在
```
docker ps
```
中状态会显示
```
Restarting (N)
```
，直到代理可访问。若配置了代理，则可通过
```
mdx-notification
```
实现动态配置/动态校准功能。
可选本地配置/校准文件：如果用户使用自定义文件，则需提前准备好。

若任何必需的前置条件未满足，请在继续操作前指出问题所在。

Workflow

工作流程

Hand the user

references/deploy-behavior-analytics-service.md

and walk them through its steps in order:

Pick an entrypoint (analytics 2D / 3D / mv3dt, dev_example, fusion_search).
Choose a config — profile-shipped or custom.
Choose a calibration — optional; profile-shipped or custom; otherwise the app waits for a dynamic-calibration notification.
Decide whether a broker is reachable; if yes, point them at the dynamic-update flows.

The compose-file edits, YAML diffs, deploy + verify commands, and troubleshooting table all live in that reference — don't duplicate them here.

将

references/deploy-behavior-analytics-service.md

提供给用户，并按顺序引导他们完成其中的步骤：

选择入口点（analytics 2D / 3D / mv3dt、dev_example、fusion_search）。
选择配置文件——可使用配置包自带的或自定义的。
选择校准选项——可选；可使用配置包自带的或自定义的；若不选择，应用将等待动态校准通知。
判断是否可访问消息代理；若可以，引导用户了解动态更新流程。

compose文件编辑、YAML差异对比、部署+验证命令及故障排查表均位于该参考文档中——请勿在此处重复内容。

Dynamic updates (runtime, no restart)

动态更新（运行时，无需重启）

Once the container is up and a broker is reachable, two runtime-update flows are available — neither requires redeploying:

容器启动后且消息代理可访问时，可使用两种运行时更新流程——均无需重新部署：

Dynamic config

动态配置

Publish an

upsert

(per-key patch) or

upsert-all

(full snapshot) message to the

mdx-notification

topic with Kafka key

behavior-analytics-config

and headers:

event.type

upsert

upsert-all

request-config

ack

```
reference-id
```
:
```
video-analytics-api-<uuid>
```
(web-api originated),
```
behavior-analytics-<uuid>
```
(bootstrap reply), or the source-type literal (
```
kafka
```
/
```
redis
```
/
```
mqtt
```
) for direct-publisher upserts.

Body:

{"status": ..., "config": <patch>, "error": ...}

The listener validates each message at the envelope layer (rejects unknown keys, missing config, malformed status/error) and at the per-payload layer (rejects forbidden sections, bad item shapes). Successful upserts are persisted to disk, applied to every worker, and ACK'd back over the topic.

Full wire contract + ack semantics:

references/dynamic-config.md

向

mdx-notification

主题发布

upsert

（按键补丁更新）或

upsert-all

（全量快照更新）消息，Kafka键为

behavior-analytics-config

，消息头包含：

event.type

upsert

upsert-all

request-config

ack

```
reference-id
```
:
```
video-analytics-api-<uuid>
```
（源自web-api）、
```
behavior-analytics-<uuid>
```
（启动回复），或直接发布者的源类型字面量（
```
kafka
```
/
```
redis
```
/
```
mqtt
```
）。

消息体：

{"status": ..., "config": <patch>, "error": ...}

。

监听器会在信封层验证每条消息（拒绝未知键、缺失配置、格式错误的状态/错误信息），并在负载层进行验证（拒绝禁用的配置段、格式错误的项）。成功的更新会持久化到磁盘，应用于所有工作进程，并通过主题回复ACK。

完整通信协议+ACK语义：

references/dynamic-config.md

。

Dynamic calibration

动态校准

Publish to the same topic with Kafka key

calibration

and headers:

```
event.type
```
:
```
upsert-all
```
(full snapshot) |
```
upsert
```
(per-sensor merge) |
```
delete
```
(per-sensor removal)
```
timestamp
```
: ISO-8601 UTC (
```
YYYY-MM-DDTHH:MM:SS.fffZ
```
).

Body: JSON sensor list (and ROIs / tripwires / homographies for

upsert-all

The listener validates against the vendored AJV schema before persisting. Schema violations log a

calibration schema violation

warning and are dropped — the previously-good calibration stays loaded.

Full wire contract + per-action validation policy:

references/dynamic-calibration.md

Both flows live entirely on the broker — the producer can be

video-analytics-api

, your own script, or any Kafka client that mirrors the wire shape. They're the recommended way to change configuration after the container is running, so the operator doesn't have to redeploy.

向同一主题发布消息，Kafka键为

calibration

，消息头包含：

```
event.type
```
:
```
upsert-all
```
（全量快照） |
```
upsert
```
（按传感器合并） |
```
delete
```
（按传感器移除）
```
timestamp
```
: ISO-8601 UTC格式（
```
YYYY-MM-DDTHH:MM:SS.fffZ
```
）。

消息体：JSON格式的传感器列表（

upsert-all

操作还需包含ROIs / 触发线 / 单应性）。

监听器会根据内置的AJV schema进行验证，然后持久化。违反schema的消息会记录

calibration schema violation

警告并被丢弃——之前的有效校准配置将保持加载状态。

完整通信协议+各操作验证规则：

references/dynamic-calibration.md

。

这两种流程均完全基于消息代理——生产者可以是

video-analytics-api

、自定义脚本或任何符合通信格式的Kafka客户端。这是容器运行后修改配置的推荐方式，无需重新部署。

Routing rules

路由规则

If the user wants "the full stack" (UI / agent / perception): hand off to
```
vss-deploy-profile
```
with profile
```
warehouse
```
(or
```
alerts
```
). Don't run this skill in parallel.
If the user wants to publish a runtime config / calibration update to an already-running container: walk the Dynamic updates section above. Both flows need a reachable broker.
If the user describes a behavior-analytics behavior change they want to validate (new incident type, new ROI rule, new sensor): point them at
```
references/configuration.md
```
,
```
references/dynamic-config.md
```
, or
```
references/dynamic-calibration.md
```
before editing the JSON.

bump:1

如果用户需要“完整栈”（UI / 代理 / 感知）：将其引导至
```
vss-deploy-profile
```
，选择
```
warehouse
```
（或
```
alerts
```
）配置文件。请勿并行运行本技能。
如果用户需要向已运行的容器发布运行时配置/校准更新：引导其查看上方的动态更新章节。两种流程均需可访问的消息代理。
如果用户描述了想要验证的behavior-analytics行为变更（新事件类型、新ROI规则、新传感器）：在编辑JSON前，引导其参考
```
references/configuration.md
```
、
```
references/dynamic-config.md
```
或
```
references/dynamic-calibration.md
```
。

bump:1