vss-setup-behavior-analytics

用途

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

说明

遵循以下路由表和分步工作流。以 workflow、quick start 或 flow 结尾的各节都应从上到下执行。详细参考资料请见 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 仅介绍路由和前置条件。

适用场景

• “部署行为分析” / “独立运行 behavior-analytics”
• “我只想运行分析，不需要完整技术栈”
• “将入口点改为 fusion_search / dev_example / analytics 3D / mv3dt”
• “使用我自己的 behavior-analytics 配置 / 校准 JSON”
• “让 behavior-analytics 使用 warehouse-3d（或 mv3dt）配置，但不启动仓库配置文件的其他部分”
• “向正在运行的 behavior-analytics 动态加载配置 / 校准”

前置条件

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 key 为 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": ...}。

监听器会在信封层验证每条消息（拒绝未知键、缺少 config、格式错误的 status/error），并在每个负载层进行验证（拒绝禁用的部分、格式错误的条目）。成功的 upsert 会持久化到磁盘、应用于每个工作线程，并通过主题返回 ACK。

完整的消息线协议 + ACK 语义：references/dynamic-config.md。

动态标定

向同一主题发布消息，Kafka key 为 calibration，并带上以下标头：

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

消息体：JSON 传感器列表（upsert-all 还包含 ROI / tripwires / homographies）。

监听器会先根据 vendored AJV schema 进行验证，再持久化。违反 schema 的消息会记录 calibration schema violation 警告并丢弃——之前有效的标定会继续加载。

完整的消息线协议 + 各操作的验证策略：references/dynamic-calibration.md。

这两种流程完全通过代理运行——生产者可以是 video-analytics-api、你自己的脚本，或任何遵循相同消息线格式的 Kafka 客户端。它们是容器运行后更改配置的推荐方式，无需操作员重新部署。

路由规则

• 如果用户想要“完整技术栈”（UI / Agent / 感知）：将其转交给 vss-deploy-profile，并使用配置文件 warehouse（或 alerts）。请勿并行运行此技能。
• 如果用户想要向正在运行的容器发布运行时配置 / 标定更新：引导他们阅读动态更新部分。两种流程都需要代理可访问。
• 如果用户描述了希望验证的行为分析行为变更（新事件类型、新 ROI 规则、新传感器）：请在编辑 JSON 前引导他们查看 references/configuration.md、references/dynamic-config.md 或 references/dynamic-calibration.md。

bump:1