3. 环境搭建与配置

DeepStream 是 NVIDIA 推出的流式分析框架，其本质是一条由 GStreamer 插件串联起来的硬件加速流水线。在开始编写车流检测逻辑之前，必须先完成底层运行时的安装与验证。本章将围绕 CUDA、TensorRT、GStreamer 与 DeepStream SDK 的版本匹配关系、安装顺序、环境变量配置以及基本运行验证展开，帮助您建立一个可复现、可排障的深度学习推理开发环境。

DeepStream 开发环境依赖关系与验证链路 NVIDIA GPU + Driver Jetson / dGPU (x86_64) CUDA Toolkit 并行计算基础库 TensorRT 推理优化引擎 GStreamer 多媒体流框架 DeepStream SDK GStreamer 插件 + 元数据管理 + 推理/跟踪/计数模块 验证工具链 deepstream-app / gst-inspect-1.0 / nvidia-smi RTSP 输出 / 屏幕显示 / 元数据回调 常见排障点 • 版本不匹配 • 环境变量缺失 • 权限/驱动问题 • 插件未注册

上图展示了 DeepStream 运行时的核心依赖栈。硬件驱动位于最底层，CUDA 提供通用并行计算能力，TensorRT 负责将训练好的模型优化为推理引擎，GStreamer 则承担视频流的解码、缩放、渲染等多媒体任务。DeepStream 将上述组件封装为统一的 GStreamer 插件，对外提供 nvinfer、nvtracker、nvvideoconvert 等元素。理解这条链路，有助于在后续安装和排障时快速定位问题所在。

3.1 版本匹配与安装前检查

DeepStream 对底层依赖的版本有严格要求，不同版本的 SDK 对应不同的 CUDA、TensorRT 和 GStreamer 版本。安装前务必查阅 NVIDIA 官方文档中的 Release Notes 或 Compatibility Matrix。以 DeepStream 6.4 为例，其典型依赖为 CUDA 12.1、TensorRT 8.6、GStreamer 1.20，并要求 GPU 驱动版本不低于 530.30.02。

DeepStream 版本CUDA 版本TensorRT 版本GStreamer 版本适用平台
6.412.18.61.20Jetson / x86_64
6.311.88.51.20Jetson / x86_64
6.211.88.51.20Jetson / x86_64
6.111.78.41.20Jetson / x86_64

在开始安装之前，建议执行以下检查命令，确认硬件和驱动状态：

# 检查 GPU 是否被系统识别
lspci | grep -i nvidia

# 查看当前驱动版本（需与 CUDA 版本兼容）
nvidia-smi

# 检查系统架构（x86_64 或 aarch64）
uname -m

# 查看操作系统版本（Ubuntu 20.04 / 22.04 等）
cat /etc/os-release

如果 nvidia-smi 无法运行，说明驱动未安装或未正确加载。此时需要先安装 NVIDIA 驱动，再继续后续步骤。对于 Jetson 平台，驱动通常已预置在 JetPack 中，只需确认 JetPack 版本与 DeepStream 匹配即可。

风险提示： 切勿在已有 CUDA 环境的系统上直接覆盖安装不同版本的 CUDA，这可能导致系统级库冲突。建议使用 apt 包管理器或 NVIDIA 官方提供的 .deb / .run 安装包，并严格遵循官方安装顺序。

3.2 安装 CUDA 与 TensorRT

CUDA 的安装方式主要有两种：网络安装和本地安装。网络安装适用于网络状况良好的环境，本地安装则适合离线部署。以 Ubuntu 22.04 + CUDA 12.1 为例，推荐使用 NVIDIA 官方 apt 仓库进行安装：

# 添加 NVIDIA 官方仓库
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update

# 安装 CUDA 12.1（包含驱动）
sudo apt install cuda-12-1

# 设置环境变量
echo 'export PATH=/usr/local/cuda-12.1/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

# 验证安装
nvcc --version

TensorRT 的安装同样推荐使用 apt 仓库方式。安装完成后，需要验证 TensorRT 的 Python 绑定和 C++ 库是否可用：

# 安装 TensorRT 8.6
sudo apt install tensorrt-8.6.1

# 验证 Python 绑定
python3 -c "import tensorrt as trt; print(trt.__version__)"

# 验证 C++ 库
dpkg -l | grep TensorRT
经验提醒： 在 Jetson 平台上，CUDA 和 TensorRT 已随 JetPack 预装，无需手动安装。但需要注意，JetPack 的版本决定了 DeepStream 的可用版本。例如 JetPack 5.1 对应 CUDA 11.4 和 TensorRT 8.5，此时应选择 DeepStream 6.3 而非 6.4。

3.3 安装 GStreamer 与 DeepStream SDK

GStreamer 是 DeepStream 的运行时基础。在 Ubuntu 上，可以通过 apt 直接安装：

# 安装 GStreamer 核心库和常用插件
sudo apt install libgstreamer1.0-0 gstreamer1.0-tools gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly

# 安装开发头文件（编译自定义插件时需要）
sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev

DeepStream SDK 的安装包可以从 NVIDIA 官网下载，分为 .deb 和 .run 两种格式。对于 x86_64 平台，推荐使用 .deb 包：

# 下载 DeepStream 6.4 deb 包后执行
sudo apt install ./deepstream-6.4_6.4.0-1_amd64.deb

# 安装完成后，设置环境变量
echo 'export DS_PATH=/opt/nvidia/deepstream/deepstream-6.4' >> ~/.bashrc
echo 'export PATH=$DS_PATH/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=$DS_PATH/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

安装完成后，可以通过以下命令验证 DeepStream 是否安装成功：

# 查看 DeepStream 版本
deepstream-app --version

# 列出所有 DeepStream 相关插件
gst-inspect-1.0 | grep nv

# 检查 nvinfer 插件是否可用
gst-inspect-1.0 nvinfer

3.4 验证基本运行：从视频文件到屏幕输出

环境配置完成后，最直接的验证方式是运行 DeepStream 自带的示例应用。官方提供了多种测试视频和配置文件，位于 $DS_PATH/samples 目录下。以下命令演示了如何运行一个基本的物体检测流水线：

# 进入示例目录
cd $DS_PATH/samples/configs/deepstream-app

# 运行检测示例（使用 config_infer_primary.txt 配置）
deepstream-app -c config_infer_primary.txt

如果一切正常，您将看到一个视频窗口，其中检测到的物体被矩形框标记，并显示类别和置信度。此时按 Ctrl+C 终止程序，终端会输出性能统计信息，包括 FPS、推理耗时、解码耗时等关键指标。

对于无显示器的服务器环境，可以使用 fakesink 作为输出端，仅验证流水线是否正常流转：

# 使用 fakesink 替代显示输出
gst-launch-1.0 filesrc location=/opt/nvidia/deepstream/deepstream-6.4/samples/streams/sample_720p.h264 ! qtdemux ! h264parse ! nvv4l2decoder ! nvinfer config-file-path=/opt/nvidia/deepstream/deepstream-6.4/samples/configs/deepstream-app/config_infer_primary.txt ! nvvideoconvert ! fakesink
案例拆解： 某智能交通项目组在部署 DeepStream 时，遇到 nvinfer 插件初始化失败的问题。错误日志显示 Cannot create TensorRT engine。排查过程如下：
  1. 首先检查 TensorRT 版本，确认与 DeepStream 要求一致（8.6.1）。
  2. 检查模型文件路径，发现 config_infer_primary.txt 中引用的 resnet10.caffemodel 不存在，原因是未设置 DS_PATH 环境变量。
  3. 修正环境变量后，重新运行，仍然报错。进一步检查发现，模型文件权限不足，当前用户无法读取。
  4. 使用 chmod +r 修改权限后，问题解决。

此案例说明，环境变量和文件权限是 DeepStream 部署中最常见的两个坑。建议在安装完成后，立即验证 echo $DS_PATH 和 ls -l $DS_PATH/samples/models 是否正常。

3.5 常见误区与总结复盘

在环境搭建过程中，以下误区需要特别注意：

  • 误区一： 认为 CUDA 版本越高越好。实际上，DeepStream 对 CUDA 版本有严格限制，版本不匹配会导致编译错误或运行时崩溃。
  • 误区二： 忽略 GStreamer 插件版本。DeepStream 依赖特定版本的 GStreamer 插件，如果系统自带版本过新或过旧，可能导致插件加载失败。
  • 误区三： 在 Jetson 上手动安装 CUDA。Jetson 的 CUDA 由 JetPack 统一管理，手动安装会破坏系统完整性。
  • 误区四： 忘记设置环境变量。每次打开新终端时，~/.bashrc 中的环境变量才会生效，如果使用 sudo 执行命令，环境变量可能丢失。

总结复盘时，建议建立一份环境检查清单，每次部署新机器时按顺序执行：

  1. 确认 GPU 驱动可用（nvidia-smi）。
  2. 确认 CUDA 版本（nvcc --version）。
  3. 确认 TensorRT 版本（python3 -c "import tensorrt; print(tensorrt.__version__)"）。
  4. 确认 GStreamer 版本（gst-launch-1.0 --version）。
  5. 确认 DeepStream 版本（deepstream-app --version）。
  6. 运行官方示例验证完整链路。

通过以上步骤，您可以确保开发环境处于健康状态，为后续的车流检测、跟踪与计数开发打下坚实基础。在实际项目中，建议将环境配置过程写成自动化脚本，以便快速复现和迁移。

← 上一章 📖 返回目录 下一章 →