⚡

VSS行为分析服务独立部署Skill vss-setup-behavior-analytics

本技能用于单独部署VSS行为分析服务，支持选择入口点、配置源和可选标定，并可在运行时通过消息代理对已运行容器进行动态配置和动态标定更新，而无需重启。关键词：VSS行为分析, 独立部署, 动态配置, 动态标定, NVIDIA AI Blueprint, 视频行为分析, Kafka, 标定, 空间AI。

视频智能服务(VSS) 0 次安装 2 次浏览 更新于 9/6/2026
名称 vss-setup-behavior-analytics
描述 用于独立部署 vss-behavior-analytics 服务（入口点、配置源、可选标定）。不用于完整仓库部署。
开源协议 Apache-2.0

metadata: author: “NVIDIA 视频搜索与摘要团队” version: “3.2.0” github-url: “https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization” tags: “nvidia blueprint operational deployment behavior-analytics”

目的

部署行为分析服务独立，使用用户选择的入口点、配置和标定。

说明

遵循下面的路由表和分步工作流。每个以 工作流、快速开始 或 流程 结尾的部分都应从上到下执行。详细参考资料见 references/。

示例

完整的端到端示例保存在 evals/ 下（每个 *.json 清单包含一个可运行场景）。运行 Tier-3 评估以重放它们：

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

一个最小的独立启动如下所示：

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。

限制

  • 需要匹配的 VSS 配置文件/微服务已部署并且调用方可访问。
  • NGC 托管的模型和 NIM 可能受到速率限制、GPU 内存要求和许可证限制。
  • 并发、GPU 内存和存储限制取决于主机硬件和配置文件的 compose 文件。

故障排除

  • 错误：REST 调用返回连接被拒绝。原因：目标微服务未运行。解决方案：探测 /docs 或 /health；通过 vss-deploy-profile 或匹配的 vss-deploy-* 技能重新部署。
  • 错误：从 NGC 拉取时返回 HTTP 401/403。原因：缺少/过期 NGC_CLI_API_KEY。解决方案：docker login nvcr.io 并在重试前重新导出密钥。
  • 错误：容器内存溢出或模型加载失败。原因：所选配置文件的 GPU 内存不足。解决方案：切换到较小变体或通过 docker compose down 释放 GPU。

VSS 设置行为分析 — 独立部署

部署 仅 vss-behavior-analytics 容器（来自上游 behavior-analytics 仓库的空间 AI 分析流水线），而不是完整仓库蓝图堆栈的一部分。

完整的操作手册 — 入口点表、配置源选项、标定类型、动态更新接口契约、故障排除 — 位于 references/deploy-behavior-analytics-service.md。本 SKILL.md 仅处理路由和先决条件。

使用时机

  • “部署行为分析” / “独立运行行为分析”
  • “我只想运行分析，不想运行整个堆栈”
  • “将入口点更改为 fusion_search / dev_example / analytics 3D / mv3dt”
  • “使用我自己的行为分析配置 / 标定 JSON”
  • “将行为分析指向 warehouse-3d（或 mv3dt）配置，而不启动仓库配置文件的其余部分”
  • “向正在运行的行为分析进行动态配置 / 动态标定”

先决条件

  1. 仓库检出，$VSS_APPS_DIR 指向 <repo>/deploy/docker/。服务 compose 的卷绑定需要它。
  2. NGC 凭据 — 设置 $NGC_CLI_API_KEY，以便 docker 可以拉取镜像。请参阅 references/ngc-api-key-registry-login.md。
  3. Docker 运行时 — Docker Engine 28.3.3 与 Docker Compose 插件 v2.39.1+。使用 docker --version 和 docker compose version 验证。
  4. 可选代理（Kafka / Redis Streams / MQTT）。容器没有代理也能正常启动 — Kafka 客户端有界重试，然后应用退出，restart: always 会循环重启容器。docker ps 将显示 Restarting (N)，直到代理可达。有代理后，通过 mdx-notification 的动态配置 / 动态标定变为可用。
  5. 可选的磁盘上的配置 / 标定文件，如果用户自带文件。

如果任何必需先决条件失败，请先提出差距，然后再继续。

工作流

向用户提供 references/deploy-behavior-analytics-service.md，并按其顺序指导他们完成步骤：

  1. 选择入口点（analytics 2D / 3D / mv3dt, dev_example, fusion_search）。
  2. 选择配置 — 配置文件自带的或自定义的。
  3. 选择标定 — 可选；配置文件自带的或自定义的；否则应用等待动态标定通知。
  4. 确定代理是否可达；如果可达，将它们指向动态更新流程。

compose 文件编辑、YAML 差异、部署 + 验证命令和故障排除表都位于该参考中 — 不要在此处重复。

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

一旦容器启动 并且代理可达，两个运行时更新流程可用 — 均无需重新部署：

动态配置

向 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>（启动回复），或直接发布者 upsert 的源类型字面量（kafka / redis / mqtt）。

消息体：{"status": ..., "config": <patch>, "error": ...}。

监听器在信封层验证每条消息（拒绝未知键、缺少配置、格式错误的 status/error），并在逐负载层验证（拒绝禁止的节、错误的项形状）。成功的 upsert 会持久化到磁盘，应用于每个 worker，并通过主题发送 ACK 回复。

完整接口契约 + ack 语义：references/dynamic-config.md。

动态标定

向同一主题发布，使用 Kafka 键 calibration 和头信息：

  • event.type: upsert-all（完整快照） | upsert（逐传感器合并） | delete（逐传感器删除）
  • timestamp: ISO-8601 UTC (YYYY-MM-DDTHH:MM:SS.fffZ)。

消息体：JSON 传感器列表（以及 upsert-all 的 ROI / 绊网 / 单应矩阵）。

监听器在持久化之前根据内置 AJV 模式进行验证。模式违规记录 calibration schema violation 警告并被丢弃 — 之前加载的好标定仍然保留。

完整接口契约 + 每操作验证策略：references/dynamic-calibration.md。

两个流程完全位于代理上 — 生产者可以是 video-analytics-api、您自己的脚本或任何镜像线形状的 Kafka 客户端。它们是容器运行后更改配置的推荐方式，因此操作员不必重新部署。

路由规则

bump:1