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 は、ゼロコピーの GPU バッファー転送に NVIDIA Video Memory Manager（NVMM）を使用します。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 + パーサーを使用します
   • RTSP／ライブソースの場合は、nvstreammux に live-source=1 を、シンクに sync=0 も設定します
   • ローカルパスを URI に変換します：「"file://" + os.path.abspath(path)」

3. メタデータの反復処理：.frame_items と .object_items を使用します（リストではなくイテレーターを返します）

   • これらに len() を決して使用しないでください。数を数えるには反復処理します
   • イテレーターは一度しか消費できません

4. リクエストパッドの構文："sink_%u" テンプレートを使用し、リテラルのパッド名は決して使用しないでください

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

5. シンクのプラットフォーム検出：

   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. tee による分岐または動的ソースを使用する場合、すべてのシンクで async=0 が必要です：状態遷移において重要です

    # tee による分岐または動的ソースを使用する場合、すべてのシンクで async=0 が必須です
    pipeline.add("nveglglessink", "sink", {
        "sync": 0, "qos": 0,
        "async": 0  # 重要 - 状態遷移のデッドロックを防止します
    })
    

    設定されていない場合の症状：パイプラインが PAUSED 状態のままになり、ビデオが表示されません。

11. 組み込みプローブのアタッチ：measure_fps_probe は処理要素（例：nvinfer、nvosdbin）にのみアタッチできます。シンク要素にはアタッチできません。シンクにアタッチすると、RuntimeError: Probe failure が発生します。

12. 動的 ONNX モデルには infer-dims が必要です：ONNX モデルの入力形状が動的な場合（Ultralytics YOLO で dynamic=True を指定してエクスポートした場合や、バッチ／高さ／幅の軸が動的な場合など）、nvinfer の設定に infer-dims=C;H;W を必ず追加してください。指定しないと、TensorRT は動的な次元を -1 として認識し、setDimensions: Error Code 3 で失敗します。一般的な値は次のとおりです。

    • YOLO モデル（入力サイズ 640）：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] — NMS 処理前の生の cx/cy/w/h とクラススコア	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 モデルでは、NvDsInferObjectDetectionInfo を obj{} で値初期化し、rotation_angle = 0 のままにします。単純な NvDsInferObjectDetectionInfo obj; では、フィールドが未初期化のままになります。

14. 仮想環境には pyservicemaker を含める必要があります：pyservicemaker はシステム全体にインストールされていますが、標準の Python 仮想環境からは利用できません。タスクで仮想環境が必要な場合（例：モデルのダウンロード／変換に pip 依存関係が必要な場合）は、仮想環境内に pyservicemaker と pyyaml を必ずインストールしてください。生成するコードと README の仮想環境セットアップには、常に次の内容を含めます。

    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  # other dependencies
    

    不足している場合の症状：仮想環境内でアプリを実行すると、ModuleNotFoundError: No module named 'pyservicemaker' が発生します。

Key Paths (DeepStream 9.0)

• Models: /opt/nvidia/deepstream/deepstream/samples/models/
• Primary Detector: /opt/nvidia/deepstream/deepstream/samples/models/Primary_Detector/resnet18_trafficcamnet_pruned.onnx
• Tracker lib: /opt/nvidia/deepstream/deepstream/lib/libnvds_nvmultiobjecttracker.so
• Kafka lib: /opt/nvidia/deepstream/deepstream/lib/libnvds_kafka_proto.so
• Sample configs: /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	パイプラインを構築する場合：シンプルな再生、複数の推論、カスケード 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_0" ではなく "sink_%u" を使用してください
キューのデータ損失	Process と組み合わせて multiprocessing.Queue を使用してください
設定の解析に失敗	YAML では model: ではなく property: を使用してください
is-classifier の非推奨警告	分類器では is-classifier: 1 の代わりに network-type: 1 を使用してください。検出器ではどちらも省略してください
min-boxes が不明なキーという警告	class-attrs-* セクションでは min-boxes ではなく minBoxes（キャメルケース）を使用してください
セカンダリ GIE が非アクティブ	process-mode: 2 を設定し、operate-on-gie-id を確認してください
Tee／動的ソースが PAUSED のまま停止	すべてのシンク要素で async: 0 を設定してください
RTSP のデータがない／再接続を繰り返す	ffplay で URL をテストし、認証情報を確認してください
RuntimeError: Probe failure	measure_fps_probe はシンク要素にアタッチできません。代わりに 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.obj_label ではなく obj_meta.label を使用してください（C API と Python バインディングで名前が異なります）