Back to Skills

vss-deploy-video-embedding

Use this skill when deploying, operating, or integrating the VSS 3.2 GA RT-Embed Video Embedding microservice. Covers Docker Compose bring-up, GPU and storage prerequisites, the `/v1` REST API (file uploads, text and video embeddings, live RTSP streams, health and metrics), Redis/Kafka/OTel integration, common failure modes, and teardown.

2,759stars321forksUpdated 8/1/2026

Security Assessment

Safe(92/100)
Security Score92/100

About vss-deploy-video-embedding

This skill is an operational playbook for deploying, running, and integrating NVIDIA's VSS 3.2 GA RT-Embed Video Embedding microservice (Compose service `rtvi-embed`, container `vss-rtvi-embed`). It solves the problem of standing up the Cosmos-Embed1-448p embedding service correctly from a Docker Compose file, covering the GPU driver / NVIDIA Container Toolkit prerequisites, NGC registry login, environment-variable configuration, persistent model caches, and the long (20-minute) first-boot health grace period so that agents can bring the service up reliably instead of guessing at setup.

Once running, it documents the `/v1` REST API for generating text and video embeddings from uploaded files, HTTP/S3/file/data URLs, or live RTSP streams, plus health (`GET /v1/ready`) and metrics endpoints. It maps every host-side environment variable to its in-container name (image/tag, GPU device selection, RTSP reconnection tuning, OpenTelemetry, Kafka topics, Hugging Face and NGC cache volumes) and explains how to wire the service alongside Redis, Kafka, and OpenTelemetry. It also includes triage guidance for readiness, model-download, GPU, and stream-reconnection failures, plus clean teardown.

The target users are DevOps engineers, MLOps practitioners, and AI agents operating the NVIDIA Video Search and Summarization blueprint who need a repeatable standalone bring-up. Notably, the skill is security-conscious: it forbids interactive `sudo` prompts, prefers `sudo -n`, and explicitly refuses `chmod 777` / world-writable workarounds, stopping instead with the exact command a host owner must run.

FAQ

What service does this deploy?

The VSS 3.2 GA RT-Embed Video Embedding microservice (Compose service `rtvi-embed`, image `nvcr.io/nvidia/vss-core/vss-rt-embed`, default tag 3.2.1), which serves the Cosmos-Embed1-448p model for text and video embeddings.

What are the prerequisites?

An NVIDIA driver plus the NVIDIA Container Toolkit with the default runtime set to `nvidia`, a recent Docker Engine and Compose plugin, a completed `docker login nvcr.io` with a valid NGC API key, the required host variables (RTVI_EMBED_PORT, VSS_DATA_DIR, NGC_API_KEY, optionally HF_TOKEN), and multi-GB free disk for the model caches.

What inputs can it embed?

Text, an uploaded file, an HTTP/S3/file/data URL, or a live RTSP stream, all via the `/v1` REST API.

Why does first startup take so long?

The healthcheck allows a 1200-second (20-minute) startup grace period on first boot because the Cosmos-Embed1 weights must download; setting HF_TOKEN is recommended to avoid Hugging Face 429 rate-limit errors during that download.

Is this for a full VSS deployment?

No. This targets the standalone RT-Embed deployment; it explicitly says not to use `/vss-deploy-profile` or `scripts/dev-profile.sh` for the standalone path, though it can be wired into a wider VSS deployment with Redis, Kafka, and OpenTelemetry.

All Files

12 files
evals/evals.json1.5 KB
View
BENCHMARK.md3.8 KB
View
references/environment.md6.2 KB
View
references/troubleshooting.md8.6 KB
View
evals/standalone_deploy.json4.0 KB
View
references/README.md1.5 KB
View
SKILL.md14.3 KB
View
references/deploy-vss-deploy-video-embedding.md11.1 KB
View
references/rest-api.md12.6 KB
View
skill.oms.sig6.2 KB
View
references/integrate-vss-deploy-video-embedding.md16.3 KB
View
skill-card.md4.2 KB
View

Install vss-deploy-video-embedding

Download and extract the skill files to your .claude/skills/ directory.

Quick Setup:

  1. Copy the skill folder to .claude/skills/
  2. Claude will automatically detect and use the skill

Repository

nvidia/skills