sarman/dgx-spark-playbooks
1
0
Fork 0
mirror of https://github.com/NVIDIA/dgx-spark-playbooks.git synced 2026-04-27 12:23:51 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

chore: Regenerate all playbooks

Browse Source
This commit is contained in:
GitLab CI 2026-03-25 13:12:33 +00:00
parent 8abb849008
commit abe821e699
1 changed files with 88 additions and 217 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

305
nvidia/vss/README.md
View File

@ -42,7 +42,6 @@ You will deploy NVIDIA's VSS AI Blueprint on NVIDIA Spark hardware with Blackwel
## Ancillary files ## Ancillary files
- [VSS Blueprint GitHub Repository](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization) - Main codebase and Docker Compose configurations - [VSS Blueprint GitHub Repository](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization) - Main codebase and Docker Compose configurations
- [Sample CV Detection Pipeline](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/tree/main/examples/cv-event-detector) - Reference CV pipeline for event reviewer workflow
- [VSS Official Documentation](https://docs.nvidia.com/vss/latest/index.html) - Complete system documentation - [VSS Official Documentation](https://docs.nvidia.com/vss/latest/index.html) - Complete system documentation
## Time & risk ## Time & risk
@ -52,7 +51,7 @@ You will deploy NVIDIA's VSS AI Blueprint on NVIDIA Spark hardware with Blackwel
* Container startup can be resource-intensive and time-consuming with large model downloads * Container startup can be resource-intensive and time-consuming with large model downloads
* Network configuration conflicts if shared network already exists * Network configuration conflicts if shared network already exists
* Remote API endpoints may have rate limits or connectivity issues (hybrid deployment) * Remote API endpoints may have rate limits or connectivity issues (hybrid deployment)
* **Rollback:** Stop all containers with `docker compose down`, remove shared network with `docker network rm vss-shared-network`, and clean up temporary media directories. * **Rollback:** Stop all containers with `scripts/dev-profile.sh down`
* **Last Updated:** 3/16/2026 * **Last Updated:** 3/16/2026
* Update required OS and Driver versions * Update required OS and Driver versions
* Support for VSS 3.1.0 with Cosmos Reason 2 VLM * Support for VSS 3.1.0 with Cosmos Reason 2 VLM
@ -61,7 +60,7 @@ You will deploy NVIDIA's VSS AI Blueprint on NVIDIA Spark hardware with Blackwel
## Step 1. Verify environment requirements ## Step 1. Verify environment requirements
Check that your system meets the hardware and software prerequisites. Check that your system meets the hardware and software [prerequisites](https://docs.nvidia.com/vss/latest/prerequisites.html).
```bash ```bash
## Verify driver version ## Verify driver version
@ -117,25 +116,47 @@ cd video-search-and-summarization
Start the system cache cleaner to optimize memory usage during container operations. Start the system cache cleaner to optimize memory usage during container operations.
Create the cache cleaner script at /usr/local/bin/sys-cache-cleaner.sh mentioned below
```bash
sudo tee /usr/local/bin/sys-cache-cleaner.sh << 'EOF'
#!/bin/bash
## Exit immediately if any command fails
set -e
## Disable hugepages
echo "disable vm/nr_hugepage"
echo 0 | tee /proc/sys/vm/nr_hugepages
## Notify that the cache cleaner is running
echo "Starting cache cleaner - Running"
echo "Press Ctrl + C to stop"
## Repeatedly sync and drop caches every 3 seconds
while true; do
sync && echo 3 | tee /proc/sys/vm/drop_caches > /dev/null
sleep 3
done
EOF
sudo chmod +x /usr/local/bin/sys-cache-cleaner.sh
```
Running in the background
```bash ```bash
## In another terminal, start the cache cleaner script. ## In another terminal, start the cache cleaner script.
## Alternatively, append " &" to the end of the command to run it in the background. sudo -b /usr/local/bin/sys-cache-cleaner.sh
sudo sh deploy/scripts/sys_cache_cleaner.sh
``` ```
## Step 5. Set up Docker shared network > [!NOTE]
+> The above runs the cache cleaner in the current session only; it does not persist across reboots. To have the cache cleaner run across reboots, create a systemd service instead.
+>
+> To stop the background cache cleaner:
+> ```bash
+> sudo pkill -f sys-cache-cleaner.sh
+> ```
Create a Docker network that will be shared between VSS services and CV pipeline containers.
```bash ## Step 5. Authenticate with NVIDIA Container Registry
## Create shared network (may require sudo depending on Docker configuration)
docker network create vss-shared-network
```
> [!WARNING]
> If the network already exists, you may see an error. Remove it first with `docker network rm vss-shared-network` if needed.
## Step 6. Authenticate with NVIDIA Container Registry
Log in to NVIDIA's container registry using your [NGC API Key](https://org.ngc.nvidia.com/setup/api-keys). Log in to NVIDIA's container registry using your [NGC API Key](https://org.ngc.nvidia.com/setup/api-keys).
@ -149,194 +170,71 @@ docker login nvcr.io
## Password: <PASTE_NGC_API_KEY_HERE> ## Password: <PASTE_NGC_API_KEY_HERE>
``` ```
## Step 7. Choose deployment scenario ## Step 6. Choose deployment scenario
Choose between two deployment options based on your requirements: Choose between two deployment options based on your requirements:
| Deployment Scenario | VLM (Cosmos-Reason2-8B)| LLM (Llama 3.1) | Embedding / Reranker | CV Pipeline | | Deployment Scenario | VLM (Cosmos-Reason2-8B)| LLM |
|---------------------- |------------------------|-------------------------------|----------------------|--------------| |-------------------------------------------|------------------------|-------------------------------|
| VSS Event Reviewer | Local | Not Used | Not Used | Local | | Standard VSS (Base) | Local | Remote |
| Standard VSS | Local | Remote (70B) or Local (8B) | Remote / Local | Optional | | Standard VSS (Alert Verification) | Local | Remote |
| Standard VSS deployment (Real-Time Alerts)| Local | Remote |
Proceed with **Option A** for Event Reviewer or **Option B** for Standard VSS.
## Step 8. Option A ## Step 7. Standard VSS
**[VSS Event Reviewer](https://docs.nvidia.com/vss/latest/content/vss_event_reviewer.html) (Completely Local)** **[Standard VSS](https://docs.nvidia.com/vss/latest/#architecture-overview) (Hybrid Deployment)**
**8.1 Navigate to Event Reviewer directory** In this hybrid deployment, we would use NIMs from [build.nvidia.com](https://build.nvidia.com/). Alternatively, you can configure your own hosted endpoints by following the instructions in the [VSS remote LLM deployment guide](https://docs.nvidia.com/vss/latest/vss-agent/configure-llm.html).
Change to the directory containing the Event Reviewer Docker Compose configuration.
```bash **7.1 Get NVIDIA API Key**
cd deploy/docker/event_reviewer/
```
**8.2 Configure NGC API Key and HF Token**
Update the environment file with your NGC API Key and HF Token. You can do this by editing the `.env` file directly, or by running the following commands:
> [!NOTE]
> To deploy the default VLM (**Cosmos-Reason2 8B**) from Hugging Face, you must accept the model’s terms and conditions on the Hugging Face model page before downloads will work.
```bash
## Edit the .env file and update NGC_API_KEY
echo "NGC_API_KEY=<YOUR_NGC_API_KEY>" >> .env
echo "HF_TOKEN=<YOUR_HF_TOKEN>" >> .env # To download Cosmos-Reason2-8B VLM
```
**8.3 (Optional) Remove the VST volume data**
When upgrading from older versions of VSS, remove the VST volume data
```bash
rm -rf vst/vst_volume/*
```
**8.4 Start VSS Event Reviewer services**
Launch the complete VSS Event Reviewer stack including Alert Bridge, VLM Pipeline, Alert Inspector UI, and Video Storage Toolkit.
```bash
## DGX Spark tuning: improves Q&A responsiveness/behavior for the Event Reviewer workflow
export VLM_DEFAULT_NUM_FRAMES_PER_CHUNK=8
## Start VSS Event Reviewer with ARM64 and SBSA optimizations
IS_SBSA=1 ALERT_REVIEW_MEDIA_BASE_DIR=/tmp/alert-media-dir docker compose up
```
> [!NOTE]
> This step will take several minutes as containers are pulled and services initialize. The VSS backend requires additional startup time. Proceed to the next step in a new terminal in the meantime.
**8.5 Navigate to CV Event Detector directory**
In a new terminal session, navigate to the computer vision event detector configuration.
```bash
cd video-search-and-summarization/examples/cv-event-detector
```
**8.6 Start DeepStream CV pipeline**
Launch the DeepStream computer vision pipeline and CV UI services.
```bash
## Start CV pipeline with ARM64 and SBSA optimizations
IS_SBSA=1 ALERT_REVIEW_MEDIA_BASE_DIR=/tmp/alert-media-dir docker compose up
```
**8.7 Wait for service initialization**
Allow time for all containers to fully initialize before accessing the user interfaces.
```bash
## Monitor container status
docker ps
## Verify all containers show "Up" status and VSS backend logs (vss-engine:2.4.1-sbsa) show ready state "Uvicorn running on http://0.0.0.0:7860"
## In total, there should be 8 containers:
## nvcr.io/nvidia/blueprint/nv-cv-event-detector-ui:2.4.1
## nvcr.io/nvidia/blueprint/nv-cv-event-detector:2.4.0-sbsa
## nginx:alpine
## nvcr.io/nvidia/blueprint/vss-alert-inspector-ui:2.4.1
## nvcr.io/nvidia/blueprint/alert-bridge:0.19.0-multiarch
## nvcr.io/nvidia/blueprint/vss-engine:2.4.1-sbsa
## nvcr.io/nvidia/blueprint/vst-storage:2.1.0-25.11.1.1
## redis/redis-stack-server:7.2.0-v9
```
**8.8 Validate Event Reviewer deployment**
Access the web interfaces to confirm successful deployment and functionality.
```bash
## Test CV UI accessibility (default: localhost)
curl -I http://localhost:7862
## Expected: HTTP 200 response
## Test Alert Inspector UI accessibility (default: localhost)
curl -I http://localhost:7860
## Expected: HTTP 200 response
## If you are running your Spark in Remote or Accessory mode, replace 'localhost' with the IP address or hostname of your Spark device.
## To find your Spark's IP address, run the following command on the Spark system:
hostname -I
## Or to get the hostname:
hostname
## Then use the IP/hostname in place of 'localhost', for example:
## curl -I http://<SPARK_IP_OR_HOSTNAME>:7862
```
Open these URLs in your browser:
- `http://localhost:7862` - CV UI to launch and monitor CV pipeline
- `http://localhost:7860` - Alert Inspector UI to view clips and review VLM results
> [!NOTE]
> You may now proceed to step 10.
## Step 9. Option B
**[Standard VSS](https://docs.nvidia.com/vss/latest/content/architecture.html) (Hybrid Deployment)**
In this hybrid deployment, we would use NIMs from [build.nvidia.com](https://build.nvidia.com/). Alternatively, you can configure your own hosted endpoints by following the instructions in the [VSS remote deployment guide](https://docs.nvidia.com/vss/latest/content/installation-remote-docker-compose.html).
> [!NOTE]
> Fully local deployment using smaller LLM (Llama 3.1 8B) is also possible.
> To set up a fully local VSS deployment, follow the [instructions in the VSS documentation](https://docs.nvidia.com/vss/latest/content/vss_dep_docker_compose_arm.html#local-deployment-single-gpu-dgx-spark).
**9.1 Get NVIDIA API Key**
- Log in to https://build.nvidia.com/explore/discover. - Log in to https://build.nvidia.com/explore/discover.
- Search for **Get API Key** on the page and click on it. - Search for **Get API Key** on the page and click on it.
**9.2 Navigate to remote LLM deployment directory**
**7.2 Launch Standard VSS deployment**
[Standard VSS deployment (Base)](https://docs.nvidia.com/vss/latest/quickstart.html#deploy)
[Standard VSS deployment (Alert Verification)](https://docs.nvidia.com/vss/latest/agent-workflow-alert-verification.html)
[Standard VSS deployment (Real-Time Alerts)](https://docs.nvidia.com/vss/latest/agent-workflow-rt-alert.html#real-time-alert-workflow)
```bash ```bash
cd deploy/docker/remote_llm_deployment/ ## Start Standard VSS (Base)
``` export NGC_CLI_API_KEY='your_ngc_api_key'
export LLM_ENDPOINT_URL=https://your-llm-endpoint.com
scripts/dev-profile.sh up -p base -H DGX-SPARK --use-remote-llm
**9.3 Configure environment variables** ## Start Standard VSS (Alert Verification)
export NGC_CLI_API_KEY='your_ngc_api_key'
export LLM_ENDPOINT_URL=https://your-llm-endpoint.com
scripts/dev-profile.sh up -p alerts -m verification -H DGX-SPARK --use-remote-llm
Update the environment file with your API keys and deployment preferences. You can do this by editing the `.env` file directly, or by running the following commands: ## Start Standard VSS (Real-Time Alerts)
export NGC_CLI_API_KEY='your_ngc_api_key'
> [!NOTE] export LLM_ENDPOINT_URL=https://your-llm-endpoint.com
> To deploy the default VLM (**Cosmos-Reason2 8B**) from Hugging Face, you must accept the model’s terms and conditions on the Hugging Face model page before downloads will work. scripts/dev-profile.sh up -p alerts -m real-time -H DGX-SPARK --use-remote-llm
```bash
## Edit .env file with required keys
echo "NVIDIA_API_KEY=<YOUR_NVIDIA_API_KEY>" >> .env
echo "NGC_API_KEY=<YOUR_NGC_API_KEY>" >> .env
echo "HF_TOKEN=<YOUR_HF_TOKEN>" >> .env # To download Cosmos-Reason2-8B VLM
echo "DISABLE_CV_PIPELINE=true" >> .env # Set to false to enable CV
echo "INSTALL_PROPRIETARY_CODECS=false" >> .env # Set to true to enable CV
```
**9.4 Review model configuration**
Verify that the config.yaml file contains the correct remote endpoints. For NIMs, it should be set to `https://integrate.api.nvidia.com/v1 `.
```bash
## Check model server endpoints in config.yaml
cat config.yaml | grep -A 10 "model"
```
**9.5 Launch Standard VSS deployment**
```bash
## Start Standard VSS with hybrid deployment
IS_SBSA=1 docker compose up
``` ```
> [!NOTE] > [!NOTE]
> This step will take several minutes as containers are pulled and services initialize. The VSS backend requires additional startup time. > This step will take several minutes as containers are pulled and services initialize. The VSS backend requires additional startup time.
> The following the environment variable needs to be set first before any deployment:
> • NGC_CLI_API_KEY — (required) for vss deployment
> • LLM_ENDPOINT_URL — (required) when --use-remote-llm is passed, used as LLM base URL
> • NVIDIA_API_KEY — (optional) used for accessing remote LLM/VLM endpoints
> • OPENAI_API_KEY — (optional) used for accessing remote LLM/VLM endpoints
> • VLM_CUSTOM_WEIGHTS — (optional) absolute path to custom weights dir
**9.7 Validate Standard VSS deployment** **7.3 Validate Standard VSS deployment**
Access the VSS UI to confirm successful deployment. Access the VSS UI to confirm successful deployment.
[Common VSS Endpoints](https://docs.nvidia.com/vss/latest/agent-workflow-alert-verification.html#service-endpoints)
```bash ```bash
## Test VSS UI accessibility ## Test Agent UI accessibility
## If running locally on your Spark device, use localhost: ## If running locally on your Spark device, use localhost:
curl -I http://localhost:9100 curl -I http://localhost:3000
## Expected: HTTP 200 response ## Expected: HTTP 200 response
## If your Spark is running in Remote/Accessory mode, replace 'localhost' with the IP address or hostname of your Spark device. ## If your Spark is running in Remote/Accessory mode, replace 'localhost' with the IP address or hostname of your Spark device.
@ -345,65 +243,40 @@ hostname -I
## Or to get the hostname: ## Or to get the hostname:
hostname hostname
## Then test accessibility (replace <SPARK_IP_OR_HOSTNAME> with the actual value): ## Then test accessibility (replace <SPARK_IP_OR_HOSTNAME> with the actual value):
curl -I http://<SPARK_IP_OR_HOSTNAME>:9100 curl -I http://<SPARK_IP_OR_HOSTNAME>:3000
``` ```
Open `http://localhost:9100` in your browser to access the VSS interface. Open `http://localhost:3000` or `http://<SPARK_IP_OR_HOSTNAME>:3000` in your browser to access the Agent interface.
## Step 10. Test video processing workflow ## Step 8. Test video processing workflow
Run a basic test to verify the video analysis pipeline is functioning based on your deployment. The UI comes with a few example videos pre-populated for uploading and testing Run a basic test to verify the video analysis pipeline is functioning based on your deployment. The UI comes with a few example videos pre-populated for uploading and testing
**For Event Reviewer deployment**
Follow the steps [here](https://docs.nvidia.com/vss/latest/content/vss_event_reviewer.html#vss-alert-inspector-ui) to access and use the Event Reviewer workflow.
- Access CV UI at `http://localhost:7862` to upload and process videos
- Monitor results in Alert Inspector UI at `http://localhost:7860`
**For Standard VSS deployment** **For Standard VSS deployment**
Follow the steps [here](https://docs.nvidia.com/vss/latest/content/ui_app.html) to navigate VSS UI - File Summarization, Q&A, and Alerts. Follow the steps [here](https://docs.nvidia.com/vss/latest/quickstart.html#deploy) to navigate VSS Agent UI.
- Access VSS interface at `http://localhost:9100` - Access VSS Agent interface at `http://localhost:3000`
- Upload videos and test summarization features - Download the sample data from NGC [here](https://docs.nvidia.com/vss/latest/quickstart.html#download-sample-data-from-ngc) and upload videos and test features [here](https://docs.nvidia.com/vss/latest/quickstart.html#download-sample-data-from-ngc)
## Step 11. Cleanup and rollback ## Step 9. Cleanup and rollback
To completely remove the VSS deployment and free up system resources: To completely remove the VSS deployment and free up system resources [Follow](https://docs.nvidia.com/vss/latest/quickstart.html#step-5-teardown-the-agent):
> [!WARNING] > [!WARNING]
> This will destroy all processed video data and analysis results. > This will destroy all processed video data and analysis results.
```bash ```bash
## For Event Reviewer deployment
cd deploy/docker/event_reviewer/
IS_SBSA=1 ALERT_REVIEW_MEDIA_BASE_DIR=/tmp/alert-media-dir docker compose down
cd ../../examples/cv-event-detector/
IS_SBSA=1 ALERT_REVIEW_MEDIA_BASE_DIR=/tmp/alert-media-dir docker compose down
## For Standard VSS deployment ## For Standard VSS deployment
cd deploy/docker/remote_llm_deployment/ scripts/dev-profile.sh down
IS_SBSA=1 docker compose down
## Remove shared network (if using Event Reviewer)
docker network rm vss-shared-network
## Clean up temporary media files and stop cache cleaner
rm -rf /tmp/alert-media-dir
sudo pkill -f sys_cache_cleaner.sh
``` ```
## Step 12. Next steps ## Step 10. Next steps
With VSS deployed, you can now: With VSS deployed, you can now:
**Event Reviewer deployment:**
- Upload video files through the CV UI at port 7862
- Monitor automated event detection and reviewing
- Review analysis results in the Alert Inspector UI at port 7860
- Configure custom event detection rules and thresholds
**Standard VSS deployment:** **Standard VSS deployment:**
- Access full VSS capabilities at port 9100 - Access full VSS capabilities at port 3000
- Test video summarization and Q&A features - Test video summarization and Q&A features
- Configure knowledge graphs and graph databases - Configure knowledge graphs and graph databases
- Integrate with existing video processing workflows - Integrate with existing video processing workflows
@ -413,8 +286,6 @@ With VSS deployed, you can now:
| Symptom | Cause | Fix | | Symptom | Cause | Fix |
|---------|--------|-----| |---------|--------|-----|
| Container fails to start with "pull access denied" | Missing or incorrect nvcr.io credentials | Re-run `docker login nvcr.io` with valid credentials | | Container fails to start with "pull access denied" | Missing or incorrect nvcr.io credentials | Re-run `docker login nvcr.io` with valid credentials |
| Network creation fails | Existing network with same name | Run `docker network rm vss-shared-network` then recreate |
| Services fail to communicate | Incorrect environment variables | Verify `IS_SBSA=1` are set correctly |
| Web interfaces not accessible | Services still starting or port conflicts | Wait 2-3 minutes, check `docker ps` for container status | | Web interfaces not accessible | Services still starting or port conflicts | Wait 2-3 minutes, check `docker ps` for container status |
> [!NOTE] > [!NOTE]