# deepstream_python_apps

**Repository Path**: ai-agents/deepstream_python_apps

## Basic Information

- **Project Name**: deepstream_python_apps
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 1
- **Created**: 2026-03-05
- **Last Updated**: 2026-03-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeepStream Python 应用程序

此仓库包含 [DeepStream SDK](https://developer.nvidia.com/deepstream-sdk) 的 Python 绑定和示例应用程序。

支持的 SDK 版本：8.0

<b>此版本仅支持 Ubuntu 24.04，适用于 DeepStreamSDK 8.0，Python 3.12 和 [gst-python](3rdparty/gst-python/) 1.24.1！</b>

绑定源代码及构建说明可在 [bindings](bindings) 中找到！PyDS 1.2.0+ 适用于 DeepStream 7.1+，使用了更新的 PyPA 构建系统以支持 pip 24.2+，后者弃用了 setup.py 命令行。我们提供了一个[指南](bindings/BINDINGSGUIDE.md)用于贡献绑定，以及另一个[指南](bindings/CUSTOMUSERMETAGUIDE.md)用于高级用例，例如为自定义数据结构编写绑定。

请在 [DeepStream SDK 论坛](https://devtalk.nvidia.com/default/board/209) 上报告任何问题或错误。这使得 DeepStream 社区能够在一个中心位置找到帮助。

<b>注意：</b> Python 3.12 需要虚拟环境来安装和导入 pip 包：
```
sudo apt install python3-venv

# 为 pyds 创建虚拟环境
python3 -m venv pyds
# （适用于 Spark - 错误修复）
python3 -m venv --system-site-packages pyds
# 激活环境
source ./pyds/bin/activate
```

<b>注意：</b> 不支持 numpy 2.x。如果您安装了 numpy 2.x，请通过运行以下命令降级：
```
pip3 install --force-reinstall numpy==1.26.0
```

<b>注意：</b> deepstream-segmask 和 deepstream-segmentation 应用程序目前不受 DeepStream 8.0 支持，因为分段和 ssd 模型已被移除。

<b>注意：</b> deepstream-ssd-parser 应用程序不受支持，因为 ssd 模型已被弃用。ssd-parser 应用程序已被移除。

<b>DeepStream dockers 注意事项：</b> 如果您通过运行 user_deepstream_python_apps_install.sh 脚本安装了 PyDS，请确保您也运行了 <b>user_additional_install.sh 脚本</b>。

- [DeepStream Python 应用程序](#deepstream-python-apps)
  - [安装设置](#安装设置)
  - [Python 绑定](#python-绑定)
    - [Python 绑定破坏性 API 变更](#python-绑定破坏性-api-变更)
  - [示例应用程序](#示例应用程序)

## 安装设置
在系统上安装 DeepStreamSDK 先决条件和 DeepStreamSDK 后，导航到 <DS_ROOT>/sources/ 目录（即 /opt/nvidia/deepstream/deepstream/sources/），在这里 git clone deepstream_python_apps 仓库。

最新的绑定可以从 [发布页面](../../releases) 安装。
如果需要，您也可以按照 [bindings readme](bindings/README.md) 中的说明从源代码构建绑定。

<a name="metadata_bindings"></a>
## Python 绑定

DeepStream 管道可以使用 Gst Python（GStreamer 框架的 Python 绑定）来构建。为了访问 DeepStream 元数据，
此仓库提供了 Python [绑定](bindings)。此模块使用 [Pybind11](https://github.com/pybind/pybind11) 生成。

<p align="center">
<img src=".python-app-pipeline.png" alt="bindings pipeline" height="600px"/>
</p>

这些绑定支持 Python 接口访问元数据结构和函数。此接口的使用在 [使用指南](HOWTO.md) 中有文档说明，并在示例应用程序中进行了演示。

### Python 绑定破坏性 API 变更
函数 alloc_nvds_event_msg_meta() 的绑定现在需要一个 NvDsUserMeta 指针，NvDsEventMsgMeta 与之关联。请参考 [deepstream-test4](apps/deepstream-test4) 和 [bindschema.cpp](bindings/src/bindschema.cpp)。

<a name="sample_applications"></a>
## 示例应用程序

此处提供的示例应用程序演示了如何使用 Python 处理 DeepStream 管道。
示例应用程序需要 [元数据绑定](#metadata_bindings) 才能工作。

要运行示例应用程序或编写自己的应用程序，请参阅 [使用指南](HOWTO.md)

<p align="center">
<img src=".test3-app.png" alt="deepstream python app screenshot" height="400px"/>
</p>

我们目前提供以下示例应用程序：
* [deepstream-test1](apps/deepstream-test1) -- 4类目标检测管道，还演示了对新 nvstreammux 的支持
* [deepstream-test2](apps/deepstream-test2) -- 4类目标检测、跟踪和属性分类管道
* [deepstream-test3](apps/deepstream-test3) -- 执行4类目标检测的多流管道，还支持 triton 推理服务器、无显示模式、文件循环和静默模式
* [deepstream-test4](apps/deepstream-test4) -- 用于将分析结果发送到云端的 msgbroker
* [deepstream-imagedata-multistream](apps/deepstream-imagedata-multistream) -- 可访问图像缓冲区的多流管道
* [deepstream-test1-usbcam](apps/deepstream-test1-usbcam) -- 使用 USB 摄像头输入的 deepstream-test1 管道
* [deepstream-test1-rtsp-out](apps/deepstream-test1-rtsp-out) -- 带 RTSP 输出的 deepstream-test1 管道，演示添加软件编码器选项以支持 Jetson Orin Nano
* [deepstream-opticalflow](apps/deepstream-opticalflow) -- 光流和可视化管道，流向量以 NumPy 数组返回
* [deepstream-segmentation](apps/deepstream-segmentation) -- 分段和可视化管道，分段掩码以 NumPy 数组返回
* [deepstream-nvdsanalytics](apps/deepstream-nvdsanalytics) -- 带分析插件的多流管道
* [runtime_source_add_delete](apps/runtime_source_add_delete) -- 在运行时添加/删除源流
* [deepstream-imagedata-multistream-redaction](apps/deepstream-imagedata-multistream-redaction) -- 带人脸检测和编辑的多流管道 **注意** 现在使用本地 sink 而不是 rtsp 输出
* [deepstream-rtsp-in-rtsp-out](apps/deepstream-rtsp-in-rtsp-out) -- 带 RTSP 输入/输出的多流管道 - 有命令行选项 "--rtsp-ts" 用于配置 RTSP 源附加时间戳而不是 streammux
* [deepstream-preprocess-test](apps/deepstream-preprocess-test) -- 使用 nvdspreprocess 插件和自定义 ROI 的多流管道
* [deepstream-demux-multi-in-multi-out](apps/deepstream-demux-multi-in-multi-out) -- 使用 nvstreamdemux 插件生成独立缓冲区输出的多流管道
* [deepstream-imagedata-multistream-cupy](apps/deepstream-imagedata-multistream-cupy) -- 在多流源中从 GPU 访问图像数据缓冲区作为 CuPy 数组 - 仅限 x86
* [deepstream-segmask](apps/deepstream-segmask) -- 从 NvOSD_MaskParams 访问和解释分段掩码信息
* [deepstream-custom-binding-test](apps/deepstream-custom-binding-test) -- 演示 NvDsUserMeta 用于附加自定义数据结构的用法 - 另请参阅 [自定义用户元数据指南](bindings/CUSTOMUSERMETAGUIDE.md)


详细的应用程序信息在 [apps](apps) 下的每个应用程序子目录中提供。