deepstream-dev

DeepStream 開発スキル

このスキルを使用するには、以下の references/ ディレクトリに記載されているすべての参照ドキュメントにアクセスできる必要があります。ワークフローを実行する前に、参照ドキュメントが利用可能であることを確認してください。

このスキルが有効な場合、コードを生成する前に、必ず関連する参照ドキュメントを読んでください。記憶に頼らないでください。参照ドキュメントには、正確なプロパティ名、正しい API の使用方法、よくある落とし穴に関する重要な詳細が記載されています。

SDK とアーキテクチャのクイックリファレンス

DeepStream SDK のバージョン要件

• 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 + パーサーを使用します
   • 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"
   

   • WSL2 Ubuntu 24 Docker の場合、このデフォルトの選択を上書きする必要があります。
   • WSL2 + Ubuntu 24 Docker：/proc/version に microsoft または wsl が含まれ、/etc/os-release に VERSION_ID="24.04" がある場合、プロンプトでディスプレイが求められていても、生成されるアプリでディスプレイ用ブランチやディスプレイシンク（nveglglessink、nv3dsink など）を作成してはいけません。この場合は --no-display フラグに頼らないでください。エンコード済みの MP4 出力のみを生成し（nvv4l2h264enc -> h264parse -> mp4mux/qtmux -> filesink）、デフォルトの実行パスで注釈付き動画ファイルを書き出すようにしてください。生成される README.md では、既知の問題によりディスプレイシンクが無効になっているため、WSL2 Ubuntu 24 Docker は MP4 出力のみであることを明記してください。ユーザーが明示的にディスプレイを要求した場合は、インラインコードのコメントと README の注記を追加し、次のように説明してください：Display requested but disabled due to WSL2 Ubuntu 24 Docker limitation — MP4 output generated instead.
   • WSL 以外のターゲット：生成されるアプリや README に WSL 固有の動作や WSL の制限に関する文言を追加しないでください。上記の通常のプラットフォーム別ディスプレイシンク選択を使用してください。

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] — 生の 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+ 形式） 不一致の症状：cluster-mode: 2 を後処理 NMS 済みの [N, 6] 出力とともに使用すると、バウンディングボックスが実際の物体から 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 をインストールしてください。インポートの不足を回避するために、pyservicemaker のパイプラインコードを pyservicemaker を使わないコードに書き換えてはいけません。生成するコードと 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  # その他の依存関係
    

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

主なパス

• モデル：/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	パイプラインの構築：シンプルな再生、複数の推論、カスケード GIE
references/streaming_sources.md	nvurisrcbin でローカルファイル、HTTP MP4、HLS、MPEG-DASH、RTSP ソースを取り込む場合
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 のインストール、コンテナの実行コマンド
references/nvds_msgapi_adapter.md	カスタムプロトコルアダプターの構築：nvds_msgapi

エラーのクイックリファレンス

エラー	解決方法
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 を設定します
WSL2 Ubuntu 24 でディスプレイシンクが要求される	既知のバグがあるため、ディスプレイシンクは使わないでください。filesink で MP4 を書き込み、README に WSL の制限を記載します
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 バインディングでは名前が異なります）