vss-setup-video-analytics-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Purpose

用途

Deploy the video-analytics-api REST service standalone with the user's chosen config, data-log bind, and Elasticsearch / Kafka connectivity.

独立部署video-analytics-api REST服务，支持用户自定义配置、数据日志绑定，以及Elasticsearch/Kafka连接。

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-video-analytics-api --agent-eval

A minimal standalone bring-up looks like:

bash

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
export VSS_DATA_DIR=${VSS_DATA_DIR:-/tmp/vss-data}
mkdir -p "$VSS_DATA_DIR/data_log/vss_video_analytics_api"
docker compose -f services/analytics/video-analytics-api/compose.yml up -d vss-video-analytics-api
curl -sf http://localhost:8081/livez

references/deploy-video-analytics-api-service.md

for the full workflow (config source, data-log bind, infrastructure dependencies, REST endpoints).

完整的端到端示例保存在

evals/

目录下（每个

*.json

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

bash

nv-base validate skills/vss-setup-video-analytics-api --agent-eval

最小化独立启动步骤如下：

bash

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
export VSS_DATA_DIR=${VSS_DATA_DIR:-/tmp/vss-data}
mkdir -p "$VSS_DATA_DIR/data_log/vss_video_analytics_api"
docker compose -f services/analytics/video-analytics-api/compose.yml up -d vss-video-analytics-api
curl -sf http://localhost:8081/livez

完整工作流程（配置源、数据日志绑定、基础设施依赖、REST端点）请参考

references/deploy-video-analytics-api-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 Video Analytics API — Standalone

VSS Setup Video Analytics API — 独立部署

Deploy just the

vss-video-analytics-api

container (the Node.js REST API from the upstream

video-analytics-api

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

The full operational walkthrough — config-source options, data-log volume behavior, infrastructure dependencies, REST API endpoints, deploy + verify, troubleshooting — is

references/deploy-video-analytics-api-service.md

. This SKILL.md only handles routing and prerequisites.

仅部署

vss-video-analytics-api

容器（来自上游

video-analytics-api

仓库的Node.js REST API），而非作为完整仓库蓝图栈的一部分。

完整的操作指南——配置源选项、数据日志卷行为、基础设施依赖、REST API端点、部署+验证、故障排除——请参考

references/deploy-video-analytics-api-service.md

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

When to use

使用场景

"Deploy video analytics api" / "run video-analytics-api standalone"
"I just want to run the REST API, not the full stack"
"Use my own video-analytics-api config"
"Point the API at a different Elasticsearch / Kafka"
"Start the API without Kafka" / "run the API broker-less"
"Check what REST endpoints are available"

"部署视频分析API" / "独立运行video-analytics-api"
"我只想运行REST API，不想部署完整栈"
"使用我自己的video-analytics-api配置"
"将API指向其他Elasticsearch/Kafka"
"不使用Kafka启动API" / "无代理运行API"
"查看可用的REST端点"

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
```
.
Secure-handling note for
NGC_CLI_API_KEY
: this key is a long-lived credential that pulls all NVIDIA private images available to your NGC org. Never commit the key, never paste it into chat, never store it in
```
/tmp
```
. Read it interactively (
```
read -rs NGC_CLI_API_KEY
```
) or load it from your secret manager (Vault, AWS Secrets Manager, sealed-secrets) at deploy time. Write any derived
```
.env
```
files with
```
umask 077
```
+
```
chmod 600
```
, add them to
```
.gitignore
```
, and rotate the key on a defined cadence and after every host decommission. If it has ever been exposed (host snapshot, shared screen, ticket attachment), rotate immediately.
Docker runtime — Docker Engine 28.3.3 with Docker Compose plugin v2.39.1+. Verify with
```
docker --version
```
and
```
docker compose version
```
.
Elasticsearch — must be reachable at the URL configured in
```
elasticsearch.node
```
. The server pings ES on startup; if unreachable, it exits (and
```
restart: always
```
brings it back). If you need to bring up ES too, use the infra compose:
```
docker compose -f services/infra/compose.yml up -d elasticsearch
```
.
Optional Kafka broker. The API can run without Kafka. If you want a quiet broker-less deployment, use the image-baked config or a custom config with
```
kafka.brokers: []
```
; the service-shipped compose config points at
```
localhost:9092
```
, so Kafka-dependent features (dynamic config, dynamic calibration, RTLS/AMR) will fail until a broker is reachable.
$VSS_DATA_DIR
for the default compose. The base compose bind-mounts
```
$VSS_DATA_DIR/data_log/vss_video_analytics_api
```
for multipart upload handling and file-backed assets such as calibration images. Set the directory to a writable host path and pre-create it, or remove that mount if image uploads are not needed.

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
```
。
NGC_CLI_API_KEY
安全处理注意事项：该密钥是长期有效的凭证，可拉取NGC组织下所有可用的NVIDIA私有镜像。绝不要提交密钥，绝不要粘贴到聊天中，绝不要存储在
```
/tmp
```
目录。通过交互式方式读取（
```
read -rs NGC_CLI_API_KEY
```
），或在部署时从密钥管理器（Vault、AWS Secrets Manager、sealed-secrets）加载。生成的
```
.env
```
文件需设置
```
umask 077
```
+
```
chmod 600
```
，将其添加到
```
.gitignore
```
，并按规定周期以及每次主机退役后轮换密钥。若密钥曾暴露（如主机快照、共享屏幕、工单附件），请立即轮换。
Docker运行时：Docker Engine 28.3.3及以上版本，搭配Docker Compose插件v2.39.1+。通过
```
docker --version
```
和
```
docker compose version
```
验证版本。
Elasticsearch：必须在
```
elasticsearch.node
```
配置的URL处可访问。服务器启动时会ping ES；若无法访问，则会退出（
```
restart: always
```
会使其重新启动）。如果需要同时部署ES，可使用基础设施compose文件：
```
docker compose -f services/infra/compose.yml up -d elasticsearch
```
。
可选Kafka代理：API可以在无Kafka的情况下运行。如果需要无代理的静默部署，可使用镜像内置的配置，或自定义配置并设置
```
kafka.brokers: []
```
；服务自带的compose配置指向
```
localhost:9092
```
，因此依赖Kafka的功能（动态配置、动态校准、RTLS/AMR）在代理可访问前会失效。
默认compose所需的
$VSS_DATA_DIR
：基础compose文件将
```
$VSS_DATA_DIR/data_log/vss_video_analytics_api
```
绑定挂载，用于处理多部分上传和基于文件的资产（如校准图像）。需将该目录设置为可写的主机路径并预先创建，若不需要图像上传则可移除该挂载。

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

Workflow

工作流程

Hand the user

references/deploy-video-analytics-api-service.md

and walk them through its steps in order:

Choose a config — image-baked default, service-shipped, or custom.
Decide whether a data-log volume is needed for file uploads.
Confirm infrastructure dependencies — Elasticsearch (required), Kafka (optional).
Deploy + verify with
```
docker compose up
```
and health check.

The compose-file edits, config options, deploy + verify commands, REST API endpoint table, and troubleshooting table all live in that reference — don't duplicate them here.

将

references/deploy-video-analytics-api-service.md

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

选择配置——镜像内置默认配置、服务自带配置或自定义配置。
确定是否需要数据日志卷用于文件上传。
确认基础设施依赖——Elasticsearch（必需）、Kafka（可选）。
使用
```
docker compose up
```
部署并验证健康状态。

compose文件编辑、配置选项、部署+验证命令、REST API端点表和故障排除表均在该参考文档中——请勿在此处重复。

REST API capabilities

REST API功能

Once the container is up and Elasticsearch is reachable, the API serves the endpoint groups listed in

references/deploy-video-analytics-api-service.md

§ REST API endpoints.

The server must initialize against Elasticsearch before

/livez

can return healthy. Data-query endpoints also need matching Elasticsearch indices and data. Endpoints that publish notifications (config, calibration) or expose RTLS / AMR streams also require Kafka.

容器启动且Elasticsearch可访问后，API将提供

references/deploy-video-analytics-api-service.md

§ REST API端点中列出的端点组。

服务器必须先完成Elasticsearch初始化，

/livez

才能返回健康状态。数据查询端点还需要匹配的Elasticsearch索引和数据。发布通知（配置、校准）或暴露RTLS/AMR流的端点也需要Kafka。

Kafka-dependent features (runtime, requires broker)

依赖Kafka的功能（运行时，需要代理）

Once the container is up and a Kafka broker is reachable, three additional capabilities are available:

容器启动且Kafka代理可访问后，将提供三个额外功能：

Dynamic config

动态配置

The API acts as the producer for dynamic config updates. When an operator POSTs to

/config

, the API publishes an

upsert

message to the

mdx-notification

topic with Kafka key

behavior-analytics-config

. The downstream

behavior-analytics

container consumes this and ACKs back. The API also handles the bootstrap flow — when

behavior-analytics

starts, it publishes a

request-config

message, and the API replies with

upsert-all

containing the latest verified config from Elasticsearch.

Consumer-side validation, ACK semantics, and the full wire contract are documented in

../vss-setup-behavior-analytics/references/dynamic-config.md

API作为动态配置更新的生产者。当操作员向

/config

发送POST请求时，API会向

mdx-notification

主题发布一条

upsert

消息，Kafka键为

behavior-analytics-config

。下游的

behavior-analytics

容器会消费该消息并返回ACK。API还处理引导流程——当

behavior-analytics

启动时，它会发布一条

request-config

消息，API则回复包含来自Elasticsearch的最新验证配置的

upsert-all

消息。

消费端验证、ACK语义和完整的通信协议记录在

../vss-setup-behavior-analytics/references/dynamic-config.md

中。

Dynamic calibration

动态校准

The API produces calibration update notifications on

mdx-notification

with Kafka key

calibration

. Supports

upsert-all

(full snapshot),

upsert

(per-sensor merge), and

delete

(per-sensor removal). The downstream

behavior-analytics

container consumes these and applies them to the live calibration.

Consumer-side validation and per-action policy are documented in

../vss-setup-behavior-analytics/references/dynamic-calibration.md

API会在

mdx-notification

主题上发布校准更新通知，Kafka键为

calibration

。支持

upsert-all

（完整快照）、

upsert

（按传感器合并）和

delete

（按传感器移除）操作。下游的

behavior-analytics

容器会消费这些通知并应用到实时校准中。

消费端验证和每个操作的策略记录在

../vss-setup-behavior-analytics/references/dynamic-calibration.md

中。

RTLS / AMR

The API consumes real-time location (

mdx-rtls

) and AMR (

mdx-amr

) messages from Kafka and exposes them via REST endpoints.

API从Kafka消费实时位置（

mdx-rtls

）和AMR（

mdx-amr

）消息，并通过REST端点暴露这些数据。

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 deploy the analytics pipeline (behavior creation, incident detection): hand off to
```
vss-setup-behavior-analytics
```
.
If the user wants to publish a runtime config / calibration update through the REST API: confirm Kafka is reachable, then use the
```
/config
```
or calibration endpoints and point them at the behavior-analytics dynamic-update references for the consumer wire contract.
If the user wants to understand the dynamic config / dynamic calibration wire contract from the consumer (behavior-analytics) side: point them at
```
../vss-setup-behavior-analytics/references/dynamic-config.md
```
and
```
../vss-setup-behavior-analytics/references/dynamic-calibration.md
```
.
If the user wants to query or interact with the REST API endpoints: the endpoint table above and the deploy reference cover what's available. For the full OpenAPI spec, see
```
src/app/specification/openapi.json
```
in the
```
video-analytics-api
```
repo.

如果用户想要"完整栈"（UI/代理/感知）：将其引导至
```
vss-deploy-profile
```
，使用
```
warehouse
```
（或
```
alerts
```
）配置文件。请勿并行运行本技能。
如果用户想要部署分析流水线（行为创建、事件检测）：将其引导至
```
vss-setup-behavior-analytics
```
。
如果用户想要通过REST API发布运行时配置/校准更新：确认Kafka可访问，然后使用
```
/config
```
或校准端点，并引导他们参考behavior-analytics的动态更新文档以了解消费端通信协议。
如果用户想要从消费端（behavior-analytics）了解动态配置/动态校准的通信协议：引导他们参考
```
../vss-setup-behavior-analytics/references/dynamic-config.md
```
和
```
../vss-setup-behavior-analytics/references/dynamic-calibration.md
```
。
如果用户想要查询或与REST API端点交互：上方的端点表和部署参考文档涵盖了可用内容。完整的OpenAPI规范请查看
```
video-analytics-api
```
仓库中的
```
src/app/specification/openapi.json
```
。