构建视频搜索和摘要 (VSS) 智能体

在 Spark 上运行 VSS Blueprint

概述

操作指令

故障排除

基本理念

部署 NVIDIA 的视频搜索和总结 (VSS) AI Blueprint，构建智能视频分析系统，将视觉语言模型、大语言模型和检索增强生成技术相结合。该系统通过视频摘要、问答和实时警报，将原始视频内容转换为可操作的实时见解。您将设置完全本地的 Event Reviewer 部署，或使用远程模型端点进行混合部署。

您将完成的任务

您将在采用 Blackwell 架构的 NVIDIA Spark 硬件上部署 NVIDIA VSS AI Blueprint，并在两种部署场景中进行选择：VSS Event Reviewer (使用 VLM 工作流实现完全本地部署) 或 Standard VSS (使用远程 LLM/ 嵌入端点进行混合部署) 。这包括设置 Alert Bridge、VLM Pipeline、Alert Inspector UI、Video Storage Toolkit 和可选的 DeepStream CV Pipeline，以实现自动视频分析和事件审查。

开始之前需要了解的内容

使用 NVIDIA Docker 容器和容器注册表
设置具有共享网络的 Docker Compose 环境
管理环境变量和身份验证令牌
基本了解视频处理和分析工作流程

预备知识

采用 ARM64 架构和 Blackwell GPU 的 NVIDIA Spark 设备
DGX 操作系统 (建议：7.4.0 或更高版本)
已安装驱动程序版本 580.95.05 或更高版本：nvidia-smi | grep "Driver Version"
已安装 CUDA 版本 13.0： nvcc --version
安装并运行的 Docker：docker --version && docker compose version
NVIDIA 容器工具包
【可选】适用于远程模型端点的 NVIDIA API 密钥 (仅限混合部署)
为视频处理提供足够的存储空间 (在 /tmp/)

辅助文件

VSS Blueprint GitHub 资源库 - 主要代码库和 Docker Compose 配置
VSS 官方文档 - 完整的系统文档

时间和风险

时长：初始设置 30 - 45 分钟，视频处理验证额外时间
风险：
- 容器启动可能需要大量资源且耗时，需要下载大量模型
- 如果共享网络已存在，则网络配置冲突
- 远程 API 端点可能存在速率限制或连接问题 (混合部署)
回滚：使用以下命令停止所有容器 deploy/docker/scripts/dev-profile.sh down
上次更新时间：2026 年 6 月 17 日
- 更新所需的操作系统和驱动程序版本
- 支持带有 Cosmos Reason 2 VLM 的 VSS 3.2.0

第 1 步：验证环境要求

检查您的系统是否满足硬件和软件要求必备软件。

# Verify driver version
nvidia-smi | grep "Driver Version"
# Expected output: Driver Version: 580.95.05 or higher

# Verify CUDA version
nvcc --version
# Expected output: release 13.0

# Verify Docker is running
docker --version && docker compose version

# Verify NGC CLI installation:
ngc --version

第 2 步：配置 Docker

要在不使用 sudo 的情况下轻松管理容器，您必须位于 docker 组。如果您选择跳过此步骤，则需要使用 sudo 运行 Docker 命令。打开新终端并测试 Docker 访问。在终端中，运行：

docker ps

如果您看到权限被拒绝的错误 (例如尝试连接到 Docker 守护程序套接字时权限被拒绝) ，请将您的用户添加到 docker 组，这样您就不需要使用 sudo 运行命令。

sudo usermod -aG docker $USER
newgrp docker

此外，配置 Docker，使其可以使用 NVIDIA 容器运行时。

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

#Run a sample workload to verify the setup
sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

第 3 步：克隆 VSS 存储库

从 NVIDIA 的公共 GitHub 克隆视频搜索和摘要存储库。

注意：如果系统上尚未安装 Git LFS

sudo apt-get install -y git-lfs && git lfs install

# Clone the VSS AI Blueprint repository
git clone https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization.git
cd video-search-and-summarization
git checkout tags/v3.2.0
git lfs install
git lfs pull

第 4 步：运行缓存清理脚本

启动系统缓存清理程序，以优化容器操作期间的内存使用量。

在下面提到的/usr/local/bin/sys-cache-cleaner.sh 中创建缓存清理脚本

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

在后台运行

# In another terminal, start the cache cleaner script.
sudo -b /usr/local/bin/sys-cache-cleaner.sh

注意：

以上操作仅在当前会话中运行缓存清理程序，不会在重启时持续运行。要让缓存清理程序在重启时运行，请改为创建 systemd 服务。要停止后台缓存清理程序，请执行以下操作：

sudo pkill -f sys-cache-cleaner.sh

第 5 步：选择部署场景

根据您的要求选择部署选项：


Deployment Scenario	VLM (Qwen/Qwen3-VL-8B-Instruct)	LLM
Standard VSS (Base)	Local	Remote
Standard VSS (Alert Verification)	Local	Remote
Standard VSS deployment (Real-Time Alerts)	Local	Remote

第 6 步：标准 VSS

标准 VSS (混合部署)

在此混合部署中，我们将使用来自 DGX Spark | NVIDIA 开发者。或者，您可以按照以下步骤中的说明配置自己的托管端点：VSS 远程 LLM 部署指南。

6.1 启动标准 VSS 部署

标准 VSS 部署 (基本) 标准 VSS 部署 (警报验证) 标准 VSS 部署 (实时警报)

使用镜像网站

# Download your model using mirror site
# Note: Do not use port 8000 or 3000
# Example
docker run -it  \
     --gpus all  \
     -p <your_port>:8000 \
     -e NIM_SDK_MAX_PARALLEL_DOWNLOAD_REQUESTS=3 \
     -e NIM_SDK_MAX_PARALLEL_FILE_REQUESTS=3  \
     resource.turingcm.com/qwen/qwen3.5-35b-a3b-spark-nim:latest

# Set NGC CLI API key
# Note: No real NGC credential is needed here; any non-empty value is acceptable.
# Example
export NGC_CLI_API_KEY='dummy'

# Set LLM_ENDPOINT_URL
export LLM_ENDPOINT_URL=http://localhost:<your_port>

# Start Standard VSS (Base)


deploy/docker/scripts/dev-profile.sh up -p base -H DGX-SPARK --use-remote-llm 
--llm-model-type openai --llm <REMOTE LLM MODEL NAME> --vlm <LOCAL VLM MODEL NAME>

# Start Standard VSS (Alert Verification)
deploy/docker/scripts/dev-profile.sh up -p alerts -m verification -H DGX-SPARK --use-remote-llm --llm-model-type openai --llm <REMOTE LLM MODEL NAME> --vlm <LOCAL VLM MODEL NAME>

# Start Standard VSS (Real-Time Alerts)
deploy/docker/scripts/dev-profile.sh up -p alerts -m real-time -H DGX-SPARK --use-remote-llm --llm-model-type openai --llm <REMOTE LLM MODEL NAME> --vlm <LOCAL VLM MODEL NAME>

注意：

在提取容器并初始化服务时，此步骤将需要几分钟时间。VSS 后端需要额外的启动时间。在部署前设置以下环境变量： NGC_CLI_API_KEY - (必填项) NGC API 密钥，用于提取图像和部署 * LLM_ENDPOINT_URL - (使用时必需) --use-remote-llm ) 远程 LLM 的基本 URL NVIDIA_API_KEY - (可选) 适用于需要它的远程 LLM/ VLM 端点 OPENAI_API_KEY - (可选) 适用于需要它的远程 LLM/ VLM 端点 VLM_CUSTOM_WEIGHTS - (可选) 自定义权重目录的绝对路径

将这些附加标志传递给 deploy/docker/scripts/dev-profile.sh 对于远程 LLM 模式：* --use-remote-llm - (必填项) 使用远程 LLM，读取基础 URL LLM_ENDPOINT_URL 在环境中 * --llm - (必填项) 远程 LLM 模型名称 (例如：nvidia/Qwen3-30B-A3B-FP4)。强烈建议用于警报工作流程 (验证和实时)：使用 Qwen/Qwen3-VL-8B-Instruct。省略 --llm 可能会导致脚本使用远程端点返回的任何模型。

运行 deploy/docker/scripts/dev-profile.sh --help 获取受支持参数的完整列表。

使用镜像网站，仍需 NGC CLI API key，映射端口请避开 3000 和 8000

6.2 验证标准 VSS 部署

访问 VSS UI 以确认成功部署。常用 VSS 端点

# Test Agent UI accessibility
# If running locally on your Spark device, use localhost:
curl -I http://localhost:7777
# 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.
# To find your Spark's IP address, run the following command on the Spark terminal:
hostname -I
# Or to get the hostname:
hostname
# Then test accessibility (replace <SPARK_IP_OR_HOSTNAME> with the actual value):
curl -I http://<SPARK_IP_OR_HOSTNAME>:7777

开放 http://localhost:7777 或 http://:7777 在浏览器中访问代理界面。

第 7 步：测试视频处理工作流程

根据您的部署，运行基本测试以验证视频分析工作流是否正常运行。

对于标准 VSS 部署

按照步骤操作单击此处导航至 VSS Agent UI。

访问 VSS Agent 界面 http://localhost:7777
从 NGC 下载样本数据单击此处并上传视频和测试功能
测试标准 VSS 部署 (基础) 单击此处
测试标准 VSS 部署 (警报验证) 单击此处
测试标准 VSS 部署 (实时警报) 单击此处

第 8 步：清理和回滚

完全移除 VSS 部署并释放系统资源关注：

警告：

这将销毁所有已处理的视频数据和分析结果。

# For Standard VSS deployment
deploy/docker/scripts/dev-profile.sh down

第 9 步：后续步骤

部署 VSS 后，您现在可以：

标准 VSS 部署：

在 7777 端口访问完整的 VSS 功能
测试视频和问答功能
配置知识图和图数据库
与现有的视频处理工作流集成

Tab Content


症状	原因	修复
Container fails to start with "pull access denied"	nvcr.io 凭据缺失或不正确	重新运行 docker login nvcr.io 具有有效凭据
Web interfaces not accessible	服务仍在启动或端口冲突	等待 2-3 分钟，检查 docker ps 容器状态
! Container qwen3-vl-8b-instruct Skipped: optional dependency "qwen3-vl-8b-instruct" failed to start ValueError: Free memory ... is less than desired GPU memory utilization	qwen3-vl-8b-instruct 启动的默认 gpu-memory-utilization 为 0.85，会造成 OOM	检查 deploy/docker/services/nim/qwen3-vl-8b-instruct/compose.yml 内容，修改 gpu-memory-utilization 为合适的值

注意：

DGX Spark 采用统一内存架构 (UMA) ，可在 GPU 和 CPU 之间实现动态内存共享。由于许多应用程序仍在更新以利用 UMA，您可能会遇到内存问题，即使在 DGX Spark 的内存容量。如果发生这种情况，请使用以下命令手动刷新缓冲区缓存：

sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches'