deepstream-generate-pipeline

DeepStream パイプラインビルダー

インタラクティブな質問票でパイプラインの要件を収集し、スタンドアロンの BM25 検索バックエンドを使用してパイプラインを組み立てることで、NVIDIA DeepStream SDK 用のすぐに実行できる gst-launch-1.0 パイプラインを生成します。構造メタデータによるブーストにも対応しています（外部依存関係なしで、検証済みパイプライン 270 件以上を対象に類似度検索を実行します）。

前提条件

• Python： 3.8 以降（標準ライブラリのみ — pip パッケージは不要）
• DeepStream SDK： /opt/nvidia/deepstream/deepstream/ にインストール済み（gst-inspect-1.0 による検証とエレメントの確認に使用）
• GStreamer： gst-launch-1.0 と gst-inspect-1.0 が PATH に設定済み（DeepStream とともにインストール）
• プラットフォーム： x86 dGPU（T4、A100、L40、RTX など）または aarch64 — Jetson（Orin、Xavier、Nano）／SBSA（Grace、GH200）

使用例

# Fully specified — skips most questions
detect and track on 4 rtsp streams and display on jetson

# Partially specified — asks remaining questions
give me a pipeline to infer on an image

# Minimal — asks all 7 questions
build a pipeline

対応構成

パラメーター	選択肢
入力	ローカル動画（.mp4/.h264/.h265）、ローカル画像（.jpg/.png）、RTSP ストリーム、USB カメラ、テストパターン
推論	なし、プライマリ（nvinfer）、プライマリ＋セカンダリ、プリプロセッサー使用、Triton（nvinferserver）
トラッカー	なし、NvDCF、IOU、NvSORT、DeepSORT
シンク	表示（dGPU/Jetson）、保存（JPG/PNG/MP4/H264）、RTSP 出力、fakesink
プラットフォーム	x86 dGPU（T4、A100、L40、RTX など）または aarch64 — Jetson（Orin、Xavier、Nano）／SBSA（Grace、GH200）
追加機能	リサイズ、回転／反転、クロップ、色形式変換

スクリプト

スクリプト	用途
scripts/generate_pipeline.py	BM25 検索エンジン — data/data.csv 内のパイプラインをスコア付けして順位付けします。--format {json,compact,summary} に対応します（デフォルトは json）
scripts/validate_pipeline.py	4 段階のバリデーター：構文、エレメント、プロパティ、ライブパース。--format {json,summary} に対応します（デフォルトは json）
scripts/lint_data.py	パイプライン CSV のデータ品質リンター（自動修正するには --fix を指定）

ワークフロー

ステップ 1 — パイプライン要件の収集

このステップを行う前に、必ず references/requirement-extraction.md を Read してください。 ここには、クエリ推論テーブル、複合要件の抽出例、AskUserQuestion の質問バンク全体（デフォルトを先頭に置く順序の規約を含む）、OSD と追加機能／反転方式の自動設定ルール、およびこのステップで使用する動的な質問削減の例が記載されています。記載内容を厳密に適用してください。

操作手順：

1. クエリから推測できる情報をすべて推測します。 references/requirement-extraction.md の推論テーブルを使用してください。目標は、7 つのパラメーター（入力ソース、ソース数、推論、トラッカー、シンク、プラットフォーム、追加機能）のうち、ユーザーがすでに指定しているものを特定することです。
2. 不明な点を AskUserQuestion で 1 回の呼び出しでユーザーに尋ねます。 トラッカー／シンク／プラットフォーム／追加機能を黙ってデフォルト設定しないでください。これらはユーザーが明示的に選ぶべき項目です（表示か保存か、トラッカーなしと NvDCF のどちらか、x86 dGPU と aarch64 Jetson／SBSA のどちらかなど）。クエリから回答が明らかな質問だけを省略してください。
3. 質問を呼び出す前置きで、推測したパラメーターをユーザーに伝えます。 これにより、すでに抽出した情報をユーザーが確認できます。例：「クエリから、mp4 動画 3 本とプライマリ推論だと判断しました。あといくつか確認させてください。」

どの質問をするか、変換エレメントをどこに配置するかを決める際は、 references/requirement-extraction.md の推論テーブル、質問バンク、OSD／追加機能のルールに従ってから、ステップ 2 に進んでください。

ステップ 2 — 自然言語クエリを作成する

ユーザーの回答から、説明的なクエリ文字列を 1 つ作成します。次のパターンに従ってください。

Please provide a GStreamer pipeline that [operation] on [num_sources] [input_type] [input_detail] [tracker_detail] and [output_action] [platform_detail]

作成したクエリの例：

ユーザーの選択	作成したクエリ
ローカル動画、1 ソース、プライマリ検出器、トラッカーなし、表示、dGPU	"Please provide a GStreamer pipeline that performs primary inference on a single mp4 video and displays the output"
RTSP、4 ソース、プライマリ＋セカンダリ、NvDCF、MP4 に保存、dGPU	"Please provide a GStreamer pipeline that performs primary and secondary inference with NvDCF tracker on 4 RTSP streams and saves output to MP4 file"
ローカル動画、2 ソース、プリプロセッサ付きプライマリ、IOU、表示、Jetson	"Please provide a GStreamer pipeline that performs preprocessing before primary inference with IOU tracker on 2 mp4 streams and displays the output on Jetson"
ローカル画像、1 ソース、なし、トラッカーなし、ファイルに保存、dGPU、時計回りに 90° 回転	"Please provide a GStreamer pipeline that rotates a single jpg image 90° clockwise before processing and saves it to a file"
ローカル動画、3 ソース、プライマリ検出器、NvDCF、MP4 に保存、dGPU、180° 回転	"Please provide a GStreamer pipeline that rotates 3 mp4 videos 180° before primary inference with NvDCF tracker and saves output to MP4 file"

ステップ 3 — パイプライン生成スクリプトを実行する

作成したクエリとユーザーパラメーターを使って、バックエンドスクリプトを実行します。

python3 <skill-path>/scripts/generate_pipeline.py \
  --query "<constructed_query>" \
  --source-type "<Local video file|Local image file|RTSP stream|USB camera|Test pattern>" \
  --num-sources <N> \
  --inference "<None|primary|primary+secondary|primary+preprocess|primary+secondary+preprocess|primary-triton|primary+secondary-triton>" \
  --tracker "<none|NvDCF|IOU|NvSORT|DeepSORT>" \
  --sink "<display|display-jetson|save-jpg|save-png|save-mp4|save-h264|rtsp-out|fakesink>" \
  --platform "<dGPU|Jetson|SBSA>" \
  --extras "<none|resize|rotate|crop|color-convert|osd>" \
  --format compact

必ず --format compact を渡してください。 compact モードでは、チャットに 10 件すべての検索結果を約 150 行の JSON として出力する代わりに、信頼度と検索上位のパイプラインのみ（約 25 行）を返します。json モード（後方互換性のためのデフォルト）は、リトリーバーを直接デバッグする場合にのみ便利です。Claude 以外の呼び出し元向けに、summary モード（人が読める 1 行）もあります。

スクリプトは、外部依存関係を使わず、Python の標準ライブラリのみで次の処理を行います。

1. パイプラインのデータセット（検証済みの DeepStream パイプライン 270 件以上）を読み込みます
2. 各パイプラインから構造メタデータ（プラットフォーム、ソースタイプ、シンクタイプ、推論モード、トラッカー、ストリーム数）を抽出します
3. BM25（文書長で正規化）と、クエリと文書の両方に対するドメイン固有の同義語拡張を使ってスコアを算出します
4. 構造的なブーストを適用します。ユーザーのプラットフォーム、ソース、シンク、推論に一致する結果のスコアを上げ、一致しない結果のスコアを下げます
5. 信頼度（high／medium／low）を最上位スコアに基づいて示す confidence フィールドを含め、上位 K 件の結果を JSON で返します
6. Claude は、取得した例と以下の組み立てルールを使って、最終的なパイプラインを作成します

confidence が low の場合は、取得した例よりも以下の組み立てルールを重視してください。

ステップ 4 — パイプラインを検証する

提示する前に、検証スクリプトを実行し、構文エラー、不明な要素、リンクの問題を確認します。

python3 <skill-path>/scripts/validate_pipeline.py "<assembled_pipeline>" --format summary

必ず --format summary を指定してください。 summary はステータスを1行で表示します（例：valid · 11 elements · 0 warnings · live-parse skipped (multi-stream)）。エラーや警告がある場合にのみ、その下にインデントして表示されます。デフォルトの json モードでは構造化された出力が約40行表示されるため、プログラムから呼び出す場合にのみ便利です。

バリデーターは4つのチェックを実行します。

1. 構文チェック — 引用符の不整合、空のパイプセグメント、ソース／シンクの不足
2. 要素チェック — gst-inspect-1.0 を使って各要素の存在を確認
3. プロパティチェック — DeepStream 要素の既知のプロパティを検証
4. ライブ解析チェック — gst-launch-1.0 自体を使い、パイプラインのグラフを構築します（fakesrc/fakesink に置き換えます）。これにより、リンクエラーやパッドの不一致を検出します。名前付きパッド参照（m.sink_0 など）を含むマルチストリームパイプラインでは、fakesrc が名前付きパッド経由で caps をネゴシエートできないため、自動的にスキップされます。

検証に失敗した場合（"valid": false）、エラーを修正し、提示する前に再検証してください。検証の再試行は最大2回までにしてください。2回修正してもパイプラインが失敗する場合は、そのまま提示してください（残りのチェックで構文、要素、プロパティ、構造上の妥当性はすでに確認されています）。警告のみの場合は、パイプラインを提示し、警告があることをユーザーに伝えてください。

ステップ 5 — パイプラインを提示する

5.1 — 出力形式（受け入れられる唯一の形式）

回答は、次の順序で必ず5つのブロックだけにしてください。

1. 1行のステータスバッジ（検証結果＋信頼度）
2. 完全な gst-launch-1.0 -e … コマンドを含む単一の bash コードブロック。具体的な絶対パスを使い、1行に記述します（\ による継続、シェル変数、シェルラッパーは不可）
3. ステージごとにまとめた内訳テーブル
4. 提案の箇条書き
5. （事前チェックに失敗した場合のみ）ステータスバッジの上に、見つからないデフォルトパスを示す ⚠ 行

このステップで受け入れられる出力形式は、これだけです。references/output-format.md の Section 5.3 のテンプレートがそのまま使用するテンプレートです。一致させてください。

5.2 — 事前チェック（回答を作成する前に実行）

パイプラインが参照するデフォルトパス（サンプル動画、PGIE 設定、トラッカーのライブラリ／設定）を対象に、Bash の ls を1回実行します。その結果に応じて、バッジに ⚠ default path not found: <path> を付けるかどうかを判断し、対応する「独自の … を使用する」提案をリストの先頭に移動します。

ls /opt/nvidia/deepstream/deepstream/samples/streams/sample_1080p_h264.mp4 \
   /opt/nvidia/deepstream/deepstream/samples/configs/deepstream-app/config_infer_primary.txt \
   2>&1

5.3 / 5.4 — 作成例と禁止されているアンチパターン

回答を作成する前に、必ず Read references/output-format.md を実行してください。 このファイルには、出力が完全に一致させる必要がある Section 5.3 のテンプレートと、禁止されている出力形式（heredoc ラッパー、シェル変数を介した間接参照、\ による行継続、余計な「Run it」行、スクリプトへの Write）をまとめた Section 5.4 の一覧が記載されています。Section 5.3 に合わせ、Section 5.4 の形式は絶対に出力しないでください。

5.5 — 回答を送信する前のセルフチェック

返信を出力する前に、各項目を頭の中で確認してください。1つでも満たしていない場合は、回答を書き直してください。

• パイプラインは、単一の ```bash コードブロック内で正確に1行になっています。
• パイプラインは gst-launch-1.0 -e で始まり、文字列として記述された絶対パス（例：/opt/nvidia/deepstream/...）のみを含みます。$VAR、${VAR:-default}、cat >、EOF、\ による行継続は含みません。
• 回答に次のいずれも含まれていません：cat > /tmp/pipeline.sh、bash /tmp/pipeline.sh、<<'EOF'、${VAR:-。
• Write ツールを呼び出していません。（ファイルへの保存は実行する操作ではなく、提案の箇条書きとして提示します。）
• 内訳テーブルはステージごとにまとめています（Source / Mux / Inference / Tracking / Composition / Render。パイプラインの実際のステージに合わせて調整し、ファイルシンクの場合は Encode/Mux 行を追加するなどしてください）。
• 「スクリプトに保存しますか？」という行は「提案」のリスト内にあります。主要な操作として提示してはいけません。

5.6 — 起動前の失敗時のパターン

セクション 5.2 の ls でデフォルトパスが 1 つ以上見つからなかった場合は、ステータスバッジの上に ⚠ の行を追加し、該当する「独自の…を使用する」提案を先頭に移動します。

⚠ default path not found: `/opt/nvidia/deepstream/deepstream/samples/streams/sample_1080p_h264.mp4` — substitute your own video path before running
✓ Validated · 11 elements · 0 warnings · confidence: HIGH

```bash
gst-launch-1.0 -e filesrc location=/opt/nvidia/deepstream/deepstream/samples/streams/sample_1080p_h264.mp4 ! …
```

[breakdown + suggestions as in Section 5.3, with the "Use your own video" suggestion bumped to the top]

長さについて： 5～8 個のストリームパイプラインを 1 行にすると長くなりますが、これは意図したとおりです。チャットクライアントは bash コードブロックを正確に表示し、コピーした内容も正確に再現されます。長いことは、分割する理由にはなりません。

Step 6 — 調整の提案

パイプラインを提示した後、変更したい点があるかユーザーに尋ねます。

何か変更しますか？ たとえば：

• ストリーム数の変更
• トラッカーまたはセカンダリ推論の追加／削除
• 画面出力とファイル出力の切り替え
• プラットフォームの変更（x86 dGPU／aarch64 Jetson／SBSA）

ユーザーが変更を希望した場合は、パラメーターを更新して Step 2 に戻ります。7 つの質問をすべて再度尋ねてはいけません。変更された特定のパラメーターについてのみ尋ねるか、内容が明確であればそのまま変更を適用します。

Step 6.5 — オプション：パイプラインをスクリプトに保存する

ユーザーが明示的に要求した場合（例：「保存して」、「pipeline.sh に保存して」、「ファイルに書き込んで」、「~/run.sh に入れて」）にのみ、このステップを実行します。先回りしてファイルを作成してはいけません。Step 5 では常に、チャット上にそのままコピーして貼り付けられる具体的なパイプラインを表示します。保存は、後から利用できる便利な機能です。

1. ファイル名： ユーザーが単に 「保存して」 と言った場合は、デフォルトで /tmp/pipeline.sh を使用します。それ以外の場合は、ユーザーが指定した正確なパス（例：~/run.sh、scripts/demo.sh）を使用します。

2. ファイルの内容： 2 行にします。シバンと、チャットに表示したものと同じ 1 行のパイプライン（具体的な絶対パスを使用し、シェル変数は使用しません）。内容が一致するようにします。ファイルから実行する内容は、コピーして貼り付けられる内容と 1 ビットも違わないようにします。

   #!/usr/bin/env bash
   gst-launch-1.0 -e filesrc location=/opt/nvidia/deepstream/deepstream/samples/streams/sample_1080p_h264.mp4 ! qtdemux ! h264parse ! nvv4l2decoder ! m.sink_0 … ! nvdsosd ! nveglglessink
   

   Write ツールを使用してファイルを作成します。

3. ユーザーへの確認 と実行コマンド：

   <path> に保存しました。次のコマンドで実行できます：

   bash <path>
   

---

パイプラインの組み立てルール

スクリプトが利用できない場合、または失敗した場合は、references/assembly-rules.md のルールに従ってパイプラインを組み立てます。これらのルールでは、ソース要素、複数ストリームのパターン、推論チェーン、トラッカー設定、シンク要素、および追加操作を扱います。また、スクリプトの出力を検証する際にも使用します。

---

エラー処理

失敗	原因	対応
generate_pipeline.py が confidence: low を返す	クエリがデータセット内のどのパイプラインとも十分に一致しない	取得した例ではなく、このスキルの組み立てルールに従います
validate_pipeline.py が不明な要素を報告する	GStreamer／DeepStream がインストールされていない、または PATH に含まれていない	DeepStream SDK をインストールし、gst-inspect-1.0 nvinfer が動作することを確認します
2 回再試行しても検証に失敗する	珍しい要素の組み合わせ、またはリンクの問題	警告を添えて、そのままパイプラインを提示します。構文、要素、プロパティのチェックには合格しています
<skill-path>/scripts/ にスクリプトが見つからない	スキルが正しくインストールされていない、またはパスの設定が誤っている	スキルディレクトリが .claude/skills/ または .cursor/skills/ にシンボリックリンクされていることを確認します

テスト

テストスイートを実行して、取得品質とバリデーターの正しさを確認します。

python3 -m unittest discover -s <skill-path>/tests -v

テストスイートには、次のものが含まれます。

• ユニットテスト：BM25 リトリーバー（トークナイザー、同義語の展開、メタデータ抽出、スコアリング）
• ユニットテスト：バリデーター（構文、構造、プロパティ、名前付きパッドのチェック）
• ゴールデン回帰テスト — 取得品質の低下を防ぐ、20 件以上のクエリ→期待結果のペア
• データ品質リンター — CSV の重複、構文上の問題、構造上のバグをチェックします。

python3 <skill-path>/scripts/lint_data.py          # report issues
python3 <skill-path>/scripts/lint_data.py --fix     # auto-fix and overwrite

---

セキュリティ、制限事項、注意事項

セキュリティの考え方、既知の制限事項、運用上の注意点については、references/security-and-limitations.md に記載されています。サブプロセスの安全性、入力検証、プラットフォーム／SDK の要件、複数ストリームのドライランに関する注意点、サンプルパス／設定ファイルについて詳しく知りたい場合は、このファイルを読んでください。