deepstream-dev

DeepStream 开发技能

启用此技能时，始终先阅读相关参考文档，再生成代码。不要依赖记忆——参考文档包含有关准确属性名称、正确 API 用法和常见问题的关键细节。

SDK 和架构速查

DeepStream SDK 9.0 版本要求

• GStreamer：1.24.2
• NVIDIA Driver：590+
• CUDA：13.1
• TensorRT：10.14.1.48
• 平台：Ubuntu 24.04（x86_64 和 ARM64/Jetson）

典型管道流程

Source → Stream Muxer → Inference → [Tracker] → OSD → Renderer

[方括号] 中的组件为可选项——仅在用户明确要求时添加。

阶段	作用	关键元素	是否必需？
源	从文件、RTSP、摄像头输入	nvurisrcbin（首选）、nvmultiurisrcbin、filesrc	是
流复用器	将多个流组成批次以供推理	nvstreammux	是
推理	执行 TensorRT 模型	nvinfer、nvinferserver	是
跟踪器	跨帧进行多目标跟踪	nvtracker	仅在用户要求时
OSD	绘制边界框、标签和叠加层	nvosdbin	是（用于可视化）
渲染器	显示或保存输出	nveglglessink、nv3dsink、filesink	是

内存模型

DeepStream 使用 NVIDIA Video Memory Manager（NVMM）实现 GPU 缓冲区的零拷贝传输。Caps 字符串使用 memory:NVMM 表示 GPU 内存（例如，video/x-raw(memory:NVMM), format=NV12）。

关键规则

1. 仅添加用户要求的组件：不要添加用户未要求的管道元素。

   • 跟踪器（nvtracker）：仅在用户明确要求跟踪或跨帧对象 ID 时添加
   • 二级 GIE：仅在用户要求分类或属性提取时添加
   • 分析（nvdsanalytics）：仅在用户要求越线检测、ROI 计数等功能时添加
   • 消息代理（nvmsgbroker/nvmsgconv）：仅在用户要求 Kafka/云端消息传递时添加
   • 如有疑问，请构建最小可用管道，由用户提出后续添加需求

2. 源默认使用 nvurisrcbin：当用户提到“摄像头”“流”“视频”或提供文件路径时：

   • 始终使用 nvurisrcbin——它能透明地处理 RTSP、HTTP 和本地文件（file://）
   • 仅当用户明确需要原始文件源控制时，才使用 filesrc + qtdemux + parser
   • 对于 RTSP/实时源，还要在 nvstreammux 上设置 live-source=1，并在 sink 上设置 sync=0
   • 将本地路径转换为 URI："file://" + os.path.abspath(path)

3. 元数据迭代：使用 .frame_items 和 .object_items（返回迭代器，而非列表）

   • 绝不要对它们使用 len()——通过迭代进行计数
   • 迭代器只能被遍历一次

4. 请求 Pad 语法：使用 "sink_%u" 模板，绝不要使用字面 Pad 名称

   pipeline.link(("decoder", "mux"), ("", "sink_%u"))  # CORRECT
   # pipeline.link(("decoder", "mux"), ("", "sink_0"))  # WRONG - will fail
   

5. Sink 的平台检测：

   import platform
   sink_type = "nv3dsink" if platform.processor() == "aarch64" else "nveglglessink"
   

6. 缓冲区克隆：异步处理时始终克隆缓冲区

   tensor = buffer.extract(0).clone()  # CRITICAL
   

7. 队列类型：

   • queue.Queue → 与 threading.Thread 配合使用
   • multiprocessing.Queue → 与 multiprocessing.Process 配合使用
   • 使用错误的类型会导致数据静默丢失！

8. nvinfer 配置格式：

   • YAML：使用 property: 部分（而非 model:），并采用 key: value 格式，冒号后加空格
   • INI：使用 [property] 部分，并采用 key=value 格式
   • 部分名称必须为 property

9. nvmsgbroker 是一个 SINK：不能连接下游元素——使用 tee 拆分管道

10. 所有 SINK 在 Tee 拆分或动态源场景中都需要设置 async=0：这对状态转换至关重要

    # 使用 tee 拆分或动态源时，所有 SINK 都必须设置 async=0
    pipeline.add("nveglglessink", "sink", {
        "sync": 0, "qos": 0,
        "async": 0  # 至关重要——可防止状态转换死锁
    })
    

    缺少此设置时的症状：管道停留在 PAUSED 状态，没有视频显示。

11. 内置探针的附加位置：measure_fps_probe 只能附加到处理元素（例如 nvinfer、nvosdbin），不能附加到 sink 元素。附加到 sink 会引发 RuntimeError: Probe failure。

12. 动态 ONNX 模型需要设置 infer-dims：当 ONNX 模型具有动态输入形状时（例如使用 Ultralytics YOLO 的 dynamic=True 导出，或具有动态 batch/height/width 轴），必须在 nvinfer 配置中添加 infer-dims=C;H;W。否则，TensorRT 会将动态维度识别为 -1，并因 setDimensions: Error Code 3 失败。常见取值：

    • 输入尺寸为 640 的 YOLO 模型：infer-dims=3;640;640
    • 输入尺寸为 416 的模型：infer-dims=3;416;416
    • 输入尺寸为 1280 的模型：infer-dims=3;1280;1280

13. Ultralytics YOLO 的输出格式取决于模型代际——较新的模型（v10+/v26+）输出经过 NMS 后的结果；较旧的模型（v8/v11）输出未经 NMS 的原始张量。自定义解析器和 cluster-mode 必须与实际输出匹配：

模型代际	输出张量形状	字段	cluster-mode
v8 / v11	[batch, 84, 8400]	[features(4+80), anchors] — 原始 cx/cy/w/h + 类别分数，未经过 NMS	2（NMS）
v10 / v26+	[batch, 300, 6]	[max_det, (x1,y1,x2,y2,conf,cls)] — 已经过 NMS，坐标为像素坐标	4（无）

如何在运行时识别：在自定义解析器中记录 inferDims.d[0] 和 inferDims.d[1]。

• d={84, 8400} → 未经过 NMS（v8/v11 风格）
• d={300, 6} → 已经过 NMS（v10/v26+ 风格）

不匹配的表现：如果对经过 NMS 的 [N, 6] 输出使用 cluster-mode: 2，边界框会相对于实际物体偏移 45° 或 135°（DeepStream 的 NMS 会错误地重新处理已经最终确定的坐标）。 如果看到倾斜或旋转的边界框，也请检查 references/nvinfer_config.md 中关于 OBB / rotation_angle 的说明：对于非 OBB 模型，应使用 obj{} 对 NvDsInferObjectDetectionInfo 进行值初始化，并保持 rotation_angle = 0；普通的 NvDsInferObjectDetectionInfo obj; 会导致字段未初始化。

14. 虚拟环境必须包含 pyservicemaker：pyservicemaker 已安装在系统范围内，但无法从标准 Python 虚拟环境中访问。当任务需要 venv（例如需要用于模型下载/转换的 pip 依赖）时，务必在 venv 内安装 pyservicemaker 和 pyyaml。生成代码和 README 中的 venv 设置必须始终包含：

    python3 -m venv venv
    source venv/bin/activate
    pip install /opt/nvidia/deepstream/deepstream/service-maker/python/pyservicemaker*.whl pyyaml
    pip install -r requirements.txt  # 其他依赖
    

    缺少依赖时的表现：在 venv 中运行应用时出现 ModuleNotFoundError: No module named 'pyservicemaker'。

Key Paths (DeepStream 9.0)

• 模型：/opt/nvidia/deepstream/deepstream/samples/models/
• 主检测器：/opt/nvidia/deepstream/deepstream/samples/models/Primary_Detector/resnet18_trafficcamnet_pruned.onnx
• 跟踪器库：/opt/nvidia/deepstream/deepstream/lib/libnvds_nvmultiobjecttracker.so
• Kafka 库：/opt/nvidia/deepstream/deepstream/lib/libnvds_kafka_proto.so
• 示例配置：/opt/nvidia/deepstream/deepstream/samples/configs/deepstream-app/

参考文档

重要：请务必阅读这些文档以获取完整详情。切勿凭记忆生成代码。

文档	使用场景
references/gstreamer_plugins.md	查询插件属性，列出所有属性
references/service_maker_api.md	使用 Pipeline/Flow API、访问元数据、探针、EventMessageUserMetadata
references/use_cases_pipelines.md	构建 Pipeline：简单播放、多重推理、级联 GIE
references/kafka_messaging.md	Kafka/消息代理设置、nvmsgconv/nvmsgbroker 配置、msg2p-newapi
references/best_practices.md	设计模式、常见问题、反模式
references/buffer_apis.md	BufferProvider/Feeder（注入）、BufferRetriever/Receiver（提取）
references/media_extractor_advanced.md	MediaExtractor、MediaChunk、FrameSampler
references/utilities_config.md	PerfMonitor、EngineFileMonitor、SourceConfig、SensorInfo、SmartRecordConfig
references/nvinfer_config.md	nvinfer 配置文件格式、所有参数
references/tracker_config.md	nvtracker 配置、NvDCF/IOU/DeepSORT/NvSORT
references/troubleshooting.md	错误消息和解决方案
references/rest_api_dynamic.md	REST API、动态添加/移除源、nvmultiurisrcbin
references/metamux_config.md	nvdsmetamux 配置、并行多模型推理、元数据合并、源 ID 筛选
references/docker_containers.md	Docker 镜像、Dockerfile 示例、pyservicemaker 安装、容器运行命令

常见错误速查

错误	解决方案
iterator has no len()	遍历计数，不要使用 len()
pad template not found	使用 "sink_%u"，而不是 "sink_0"
队列数据丢失	将 multiprocessing.Queue 与 Process 配合使用
配置解析失败	在 YAML 中使用 property:，而不是 model:
is-classifier 弃用警告	对分类器使用 network-type: 1，而不是 is-classifier: 1；对检测器省略这两项
min-boxes 未知键警告	在 class-attrs-* 部分中使用驼峰命名的 minBoxes，而不是 min-boxes
Secondary GIE 未激活	设置 process-mode: 2，检查 operate-on-gie-id
Tee/动态源卡在 PAUSED 状态	对所有 sink 元素设置 async: 0
RTSP 无数据/正在重新连接	使用 ffplay 测试 URL，检查凭据
RuntimeError: Probe failure	measure_fps_probe 无法附加到 sink 元素；请改用 nvinfer 或 nvosdbin
setDimensions 维度为负数 / 引擎构建失败	为动态 ONNX 模型添加 infer-dims=C;H;W（例如，infer-dims=3;640;640）
venv 中出现 No module named 'pyservicemaker'	在 venv 中运行 pip install /opt/nvidia/deepstream/deepstream/service-maker/python/pyservicemaker*.whl pyyaml
AttributeError: object has no attribute 'obj_label'	在 pyservicemaker 中使用 obj_meta.label，而不是 obj_meta.obj_label（C API 名称与 Python 绑定不同）