vss-setup-behavior-analytics
Use to deploy the vss-behavior-analytics service standalone (entrypoint, config-source, optional calibration). Not for the full warehouse deploy.
- License 许可
- Apache-2.0
- 最近更新
- 2026-07-18
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- vss-setup-behavior-analytics
- license
- Apache-2.0
- metadata
- { "tags": "nvidia blueprint operational deployment behavior-analytics", "author": "NVIDIA Video Search and Summarization team", "version": "3.2.0", "github-url": "https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization" }
- description
- Use to deploy the vss-behavior-analytics service standalone (entrypoint, config-source, optional calibration). Not for the full warehouse deploy.
03 SKILL.md 正文
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/.
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:
nv-base validate skills/vss-setup-behavior-analytics --agent-eval
A minimal standalone bring-up looks like:
cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
docker compose -f services/analytics/behavior-analytics/compose.yml up -d vss-behavior-analytics-base
Follow references/deploy-behavior-analytics-service.md for the full
workflow (entrypoint pick, config source, dynamic updates).
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.
Troubleshooting
- Error: REST call returns connection refused. Cause: target microservice not running. Solution: probe
/docsor/health; redeploy viavss-deploy-profileor the matchingvss-deploy-*skill. - Error: HTTP 401/403 from NGC pulls. Cause: missing/expired
NGC_CLI_API_KEY. Solution:docker login nvcr.ioand 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.
VSS Setup Behavior Analytics — Standalone
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.
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"
Prerequisites
- Repo checkout with
$VSS_APPS_DIRpointing at<repo>/deploy/docker/. Required by the service compose's volume binds. - NGC credentials —
$NGC_CLI_API_KEYset so docker can pull the image. Seereferences/ngc-api-key-registry-login.md. - Docker runtime — Docker Engine 28.3.3 with Docker Compose plugin v2.39.1+. Verify with
docker --versionanddocker 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: alwayscycles the container. Status will showRestarting (N)indocker psuntil a broker is reachable. With a broker, dynamic config / dynamic calibration overmdx-notificationbecome 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.
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.
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|ackreference-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.
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.
Routing rules
- If the user wants "the full stack" (UI / agent / perception): hand off to
vss-deploy-profilewith profilewarehouse(oralerts). 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. 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, orreferences/dynamic-calibration.mdbefore editing the JSON.
bump:1
04 同仓库更多 Skills
arxiv-search
Search arXiv physics, math, and computer science preprints using natural language queries. Powered by Valyu semantic search.
arxiv-search
Search arXiv physics, math, and computer science preprints using natural language queries. Powered by Valyu semantic search.
working-with-legacy-code
Safely change and test untested codebases using Feathers' "Working Effectively with Legacy Code". Use when the user mentions "legacy code", "no tests", "untested codebase", "how do I test this", "seams", "characterization tests", "golden master", "sprout method", "afraid to change this code", "monster method", "dependency breaking", or "inherited a messy codebase". Also trigger when changing code without tests safely, getting a class under test when constructors, statics, or singletons block it, adding features to tangled modules, or planning incremental test coverage for an old codebase. Covers the legacy-code change algorithm, seams, characterization tests, sprout/wrap, and dependency-breaking techniques. For refactoring code that already has tests, see refactoring-patterns. For day-to-day code quality, see clean-code.
working-with-legacy-code
Safely change and test untested codebases using Feathers' "Working Effectively with Legacy Code". Use when the user mentions "legacy code", "no tests", "untested codebase", "how do I test this", "seams", "characterization tests", "golden master", "sprout method", "afraid to change this code", "monster method", "dependency breaking", or "inherited a messy codebase". Also trigger when changing code without tests safely, getting a class under test when constructors, statics, or singletons block it, adding features to tangled modules, or planning incremental test coverage for an old codebase. Covers the legacy-code change algorithm, seams, characterization tests, sprout/wrap, and dependency-breaking techniques. For refactoring code that already has tests, see refactoring-patterns. For day-to-day code quality, see clean-code.
web-typography
Select, pair, and implement typefaces for web projects. Use when the user mentions "font pairing", "which typeface", "line height", "responsive typography", "web font loading", "type hierarchy", "variable fonts", "FOUT/FOIT", "typographic scale", or "the text is hard to read". Also trigger when choosing between system fonts and web fonts, optimizing font-loading performance, or designing readable long-form content. Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.
web-typography
Select, pair, and implement typefaces for web projects. Use when the user mentions "font pairing", "which typeface", "line height", "responsive typography", "web font loading", "type hierarchy", "variable fonts", "FOUT/FOIT", "typographic scale", or "the text is hard to read". Also trigger when choosing between system fonts and web fonts, optimizing font-loading performance, or designing readable long-form content. Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.