使用 DeepStream 9.0 的参考应用

此仓库包含使用 TensorRT 和 DeepStream SDK 9.0 完成视频分析任务的参考应用程序。

快速入门

我们目前提供了三个不同的参考应用：

建议将本项目克隆到 /opt/nvidia/deepstream/deepstream/sources/apps/sample_apps/

若要将项目克隆到上述目录，可能需要超级用户权限。

更多详细信息，请参阅各个项目的 README 文件。

异常检测：README

该项目包含辅助的 dsdirection 插件，用于展示 DeepStream SDK 在异常检测方面的能力。

运行时添加与删除视频源：README

该项目演示了在实时 DeepStream 管道中动态添加和删除视频源的功能。

MaskTracker：README

此示例应用展示了使用 SAM2 实现多目标跟踪与分割的 DeepStream MaskTracker。

单视角 3D 跟踪：README

该示例应用演示了在遮挡情况下，利用 DeepStream 多目标跟踪技术重建世界坐标系下的人体 3D 模型的单视角 3D 跟踪功能。

多视角 3D 跟踪：README

这些示例展示了在 DeepStream 中实现多视角 3D 跟踪的技术，该框架是一个专为大规模校准相机网络设计的分布式实时系统。

并行多模型推理：README

该项目演示了如何使用 DeepStream API 实现多模型的并行推理。

Bodypose 3D 模型推理：README

该示例展示了如何自定义多输入层模型的预处理步骤，以及对 Bodypose 3D 模型后处理部分的定制化操作。

通过 IPC 在管道间共享视频缓冲区：README

本示例演示了如何通过进程间通信（IPC）共享视频缓冲区，以及如何更改输出视频缓冲区。

单解码器支持多个动态源：README

该示例演示了在 DeepStream 管道中使用 nvdsdynamicsrcbin 组件的方法。它有助于构建仅需一个视频解码器即可支持多个动态源的应用程序，从而适应高解码吞吐量的场景。

自定义视频拼接配置：README

本示例展示了如何使用 nvmultistreamtiler 的“custom-tile-config”功能，来自定义批量视频的拼接位置和尺寸。

DeepStream VLLM 插件：README

这是一个基于 GStreamer 的 NVIDIA DeepStream 插件，集成了视觉-语言模型（VLM），利用 VLLM 实现实时视频理解和分析。

Pyservicemaker 参考应用

pyservicemaker_sample_apps 中的应用是额外的示例，展示了如何使用 DeepStream Service Maker 的 Python API，无论是通过流式 API 还是管道 API。有关详细信息，请参阅 Python Service Maker 文档。

旧版 DeepStream 参考示例

由于各种原因，部分旧版示例已不再受支持。这些遗留示例已被移至 /legacy_apps 文件夹中。

DeepStream 9.0 参考应用快速上手指南

本指南旨在帮助开发者快速部署并运行基于 NVIDIA DeepStream SDK 9.0 的视频分析参考应用。这些应用涵盖了异常检测、多目标跟踪、3D 重建及大模型集成等前沿功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 硬件平台：NVIDIA Jetson 系列 (Orin, Xavier, Nano) 或 x86_64 架构搭配 NVIDIA GPU (需支持 TensorRT)。
• 操作系统：Ubuntu 20.04 / 22.04 (x86) 或 JetPack 6.x (Jetson)。
• 核心依赖：
  • 已安装 DeepStream SDK 9.0。
  • 已安装 TensorRT (通常随 DeepStream 自动安装)。
  • 已安装 GStreamer 及相关插件。
  • Python 3.8+ (如需运行 Python Service Maker 示例)。
• 权限要求：需要 sudo 权限以将文件写入系统目录。

注意：本仓库中的部分高级功能（如 SAM2 MaskTracker、VLLM 插件）可能需要额外的模型文件或特定的 CUDA 版本支持，请参考各子项目的具体 README 获取详细依赖说明。

安装步骤

官方推荐将项目克隆至 DeepStream 的标准示例目录下，以便与 SDK 环境完美兼容。

1. 进入目标目录 切换到 DeepStream 源码应用目录：

   cd /opt/nvidia/deepstream/deepstream/sources/apps/sample_apps/
   

2. 克隆参考应用仓库 使用 git 克隆本项目。如果直接克隆速度较慢，可尝试配置 Git 代理或使用国内镜像源加速：

   # 标准克隆命令
   sudo git clone https://github.com/NVIDIA-AI-IOT/deepstream_reference_apps.git
   
   # 若网络受限，可先配置 HTTP 代理后再执行上述命令
   # export http_proxy=http://your-proxy-ip:port
   # export https_proxy=http://your-proxy-ip:port
   

3. 验证安装 进入克隆后的目录，确认包含各个子项目文件夹（如 anomaly, deepstream-masktracker 等）：

   cd deepstream_reference_apps
   ls
   

基本使用

本仓库包含多个独立的参考应用，每个应用针对不同的视频分析场景。以下是运行最基础的异常检测 (Anomaly Detection) 示例的步骤，其他应用的使用逻辑类似（需进入对应子目录查看具体参数）。

示例：运行异常检测应用

该示例展示了如何使用 dsdirection 插件进行光流分析和异常行为检测。

1. 进入项目目录

   cd anomaly
   

2. 编译应用 使用 make 命令编译源代码：

   make
   

3. 运行演示 编译成功后，运行生成的可执行文件。通常需要指定一个输入视频文件或 RTSP 流地址：

   ./deepstream-app -c config_infer.txt
   

   (注：具体的配置文件名和参数请以 anomaly/README.md 中的说明为准，部分示例可能直接运行二进制文件如 ./app_name)

其他热门应用速览

• SAM2 多目标跟踪与分割:

  cd ../deepstream-masktracker
  make
  # 运行命令参考该目录下的 README
  

• 单视图 3D 人体追踪:

  cd ../deepstream-tracker-3d
  make
  

• VLLM 视觉语言模型插件:

  cd ../deepstream-vllm-plugin
  # 需确保已安装 VLLM 及相关 Python 依赖
  

使用 Python Service Maker

如果您倾向于使用 Python API 构建 pipeline，可以参考 pyservicemaker_sample_apps 目录：

cd ../pyservicemaker_sample_apps
python3 <script_name>.py

提示：每个子文件夹内均包含独立的 README.md，其中详细列出了该特定应用所需的模型下载链接、配置文件修改说明及完整的运行命令。建议在执行前优先阅读对应子项目的文档。