dlstreamer-coding-agent

DL Streamer コーディングエージェント

既存のサンプルアプリから抽出した設計パターンを組み合わせて、新しい DL Streamer 動画分析アプリケーション（Python、C、C++、または GStreamer コマンドライン）を構築します。

ファイルの解決

このスキルでは、スキルフォルダー外のファイルを参照するために、リポジトリルートからの相対パスを使用します（例：docs/user-guide/elements/、samples/gstreamer/python/hello_dlstreamer/）。リポジトリ全体をクローンした場合、リポジトリルートはこのスキルファイルの3階層上にあります。スキルファイルのみをコピーした場合は、https://github.com/open-edge-platform/dlstreamer を指します。

使用するタイミング

• ユーザーがビジョン AI パイプラインを自然言語で説明する場合
• ユーザーが DL Streamer を基盤とする新しい Python サンプルアプリケーションを作成したい場合
• ユーザーが DL Streamer を基盤とする新しい C または C++ サンプルアプリケーションを作成したい場合
• ユーザーが DL Streamer の要素を使用する新しい GStreamer コマンドラインを作成したい場合
• ユーザーが複数の既存サンプルの要素を組み合わせたい場合（例：検出＋VLM＋録画）
• ユーザーが Python または C++ でカスタム分析ロジックやカスタム GStreamer 要素を追加する必要がある場合

アイデアを得るには、プロンプトの例を参照してください。

新しいサンプルアプリのディレクトリ構成

<new_sample_app_name>
├── <app_name>.py or .sh        # Main application (Python or shell script)
├── export_models.py or .sh     # Model download and export script
├── requirements.txt            # Python dependencies for the application
├── export_requirements.txt     # Python dependencies for model export scripts
├── README.md                   # Setup and usage instructions
├── plugins/                    # Only if custom GStreamer elements are needed
│   ├── python/
│   │   └── <element>.py
│   └── c/
│       └── <element>.c
├── config/                     # Only if config files are needed
│   └── *.txt / *.json
├── models/                     # Created at runtime (cached model exports)
├── videos/                     # Created at runtime (cached video downloads)
└── results/                    # Created at runtime (output files)

手順

実行の概要

ステップ 0（要件の確認）の後、独立して実行できる時間のかかるタスクをすべて非同期ターミナルで並行して開始し、完了を待つ間に推論を要する作業を進めます。 順序に迷った場合は、開始前に、必ず各ステップに記載された前提条件の完了を待ってください。以下の依存関係図が唯一の基準です。

Step 0 (gather requirements — interactive)
  │
  ├──► Step 1  (Docker pull — async) ───────────────────────────────────────┐
  ├──► Step 2a (export scripts + uv pip install — async) ──► Step 2c (export)──┤
  ├──► Step 2b (video download — async) ────────────────────────────────────┤───► Step 5 (run & validate)
  └──► Step 3  (design pipeline — reasoning) ──► Step 4 (generate app) ─────┘

並列化のルール：

• ステップ 1、2a、2b、3 は完全に独立しているため、ステップ 0 の直後にすべて開始します
• ステップ 2c（モデルのエクスポート）は、ステップ 2a（uv pip install）の完了後に実行します
• ステップ 4（アプリの生成）は、ステップ 3（パイプライン設計）の完了後に実行します
• ステップ 5（実行と検証）は、ステップ 1、2c、4 のすべての完了後に実行します

自律実行時の安全ルール：

• パッケージのインストール、外部コンテンツのダウンロード、またはファイルの変更・削除を伴うコマンドを実行する前に、実行するコマンド全体を提示し、チャットでユーザーの明示的な確認を求めます。
• 未加工のユーザー入力をシェルコマンドに埋め込まないでください。検証済みの許可リストと固定の引数テンプレートを使用します。
• ユーザーがより広い範囲を明示的に承認しない限り、ファイル操作はサンプルアプリケーションのディレクトリ内に限定します。

参照資料の確認

各参照資料は、重複して読み込まないよう、主に1つのステップで使用します。

参照資料	主なステップ	目的
要件確認の質問票	ステップ 0	ユーザープロンプトに情報が不足している場合に尋ねる詳細な質問
モデルの準備	ステップ 2	AI モデルを OpenVINO IR 形式で準備する
パイプラインの構築	ステップ 3	要素の選択、パイプラインのルール、一般的なパターン
サンプルインデックス	ステップ 3	コードを生成する前に調査する既存のサンプル
設計パターン	ステップ 3	Python アプリケーションの構成、パターン、コーディング規約
デバッグのヒント	ステップ 5	Docker でのテスト、よくある注意点、検証チェックリスト

---

クイックパス（パターンテーブルとの照合）

完全な手順に進む前に、ユーザーのプロンプトが 一般的なパイプラインパターンの表の行に直接該当するか確認します。 該当する行が見つかった場合：

1. 該当する行からステップ 0 の項目を事前入力します
2. 必須項目が不足している場合、または該当する行から推測されている場合は、事前入力した値をユーザーに提示して確認を求めます（情報がまだ不足している場合を除き、完全な 要件確認アンケートは省略します）
3. 必須項目がすべてユーザーから明示的に提供されている場合（推測されたものではない場合）、要件項目の確認は省略しますが、ステップ 1～2 のコマンドを実行する前に、引き続きユーザーから明示的な承認を得ます
4. ユーザーが確認（または変更）した後、確認済みの選択に必要な設計パターン、リファレンスのセクション、モデル準備のセクションのみを読みます
5. ステップ 1～5 に進みます

ステップ 0 — 要件の収集

ユーザーのプロンプトから以下を抽出します。

必要な情報	確認する内容	未指定の場合のデフォルト
ビデオ入力	ファイルパス、HTTP URL（ダウンロード用）、または RTSP URI	—（確認が必要）
AI モデル	モデル名／URLとタスク（検出、分類、VLM、OCR など）	—（確認が必要）
対象ハードウェア	Intel プラットフォーム、利用可能なアクセラレーター（GPU／NPU／CPU）	Not sure / detect at runtime
出力形式	注釈付きビデオ、JSON、JPEG スナップショット、表示ウィンドウ	All of the above
アプリケーションの種類	Python アプリ、C/C++ アプリ、または GStreamer コマンドライン	既存のアプリケーションを変換する指示がある場合は、元のアプリケーションのファイル拡張子を調べて種類を判断します。アプリケーションの種類は、入力アプリケーションのプログラミング言語と一致させる必要があります（C/C++ → C/C++、Python → Python、シェル → GStreamer コマンドライン）
Docker イメージ	DL Streamer の Docker タグ	intel/dlstreamer:latest（このタグは最新の Ubuntu 24 イメージとして扱われます）

アプリケーションの種類の上書き： ユーザーのプロンプトに

「bash script」、「shell script」、「gst-launch」、「command line」などの明示的な指定がある場合は、デフォルトにかかわらず、アプリケーションの種類を GStreamer command lineに設定します。Python applicationをデフォルトにするのは、プロンプトに希望の指定がなく、変換対象の元のアプリケーションもない場合に限ります。

ユーザーのプロンプトに必須情報がすべて明示されている場合（ビデオ入力とモデル名が推測ではなく明示されている場合）は、ステップ 1 に直接進みます。

必須情報が不足している場合、またはクイックパスで推測した場合（ユーザーが明示していない場合）は、続行する前に、事前入力した値を必ず提示し、確認または変更を求めてください。利用可能であれば対話型質問ツール（例：VS Code Copilot の vscode_askQuestions）を使用し、そうでなければチャットに値を列挙してください。デフォルトを黙って適用して確認を省略してはいけません。

ユーザーが NPU を要求しているものの、選択したモデルまたは要素が NPU 推論に対応していない場合は、その旨をユーザーに伝え、GPU または CPU への切り替えを提案します。

ステップ 1 — Docker イメージの取得（非同期）

ステップ 0 の完了直後に、非同期ターミナルで Docker イメージの取得を開始します。

常に利用可能な最新のイメージを取得してください 取得前にローカルキャッシュのイメージを再利用してはいけません。

docker pull intel/dlstreamer:latest

docker pullが失敗した場合（たとえば、イメージが見つからない、またはネットワークエラーの場合）は、その旨をユーザーに伝え、再試行する前に Docker のログイン状態とネットワーク接続を確認するよう提案します。

ステップ 2 — モデルとビデオの準備（非同期）

2a — エクスポートスクリプトを作成し、venv の作成と uv pip install を開始する

要求されたモデル（または類似モデル）が、DL Streamer に同梱されているモデルエクスポーターに含まれているか確認します。

モデルエクスポーター	主なモデル	パス
download_other_models.py	Hugging Face や Ultralytics 以外の、選定済みヘルパーモデル	scripts/download_models/download_other_models.py
download_hf_models.py	VLM モデルや Transformer ベースの検出／分類モデル（RTDETR、CLIP、ViT）を含む HuggingFace モデル	scripts/download_models/download_hf_models.py
download_ultralytics_models.py	Ultralytics YOLO モデル専用のモデルダウンローダー	scripts/download_models/download_ultralytics_models.py
download_timm_models.py	Hugging Face でホストされている TIMM 画像分類モデル	scripts/download_models/download_timm_models.py

モデルが見つかった場合は、そのダウンロード手順を取り出し、アプリケーションディレクトリにローカルの export_models.py を作成します。 モデルが一覧にない場合は、エクスポート手順についてモデル準備リファレンスを確認してから、モデルエクスポートテンプレートを使って新しいスクリプトを作成します。

モデルエクスポートスクリプトに追加の Python パッケージ（HuggingFace transformers、Ultralytics、optimum-cli など）が必要な場合は、エクスポート要件テンプレートを使って export_requirements.txt ファイルを作成します。export_requirements.txt にコメントを追加し、どのモデルエクスポートスクリプトが特定のパッケージを必要とするかを示します。モデル準備リファレンス → 要件に記載されている正確な固定バージョンを使用してください。

重要 — CPU 専用 PyTorch： export_requirements.txt の最初の行は、次の内容にする必要があります。 --extra-index-url https://download.pytorch.org/whl/cpu （ultralytics や nncf など、torch に依存するパッケージより前に記述します）。これがないと、モデルのエクスポートに不要な数 GB の GPU ライブラリが uv によってダウンロードされます。 完全なテンプレートについては、モデル準備リファレンス → 要件を参照してください。

前提条件 — uv のインストール： uv が利用できない場合は、先にインストールしてください。 curl -LsSf https://astral.sh/uv/install.sh | sh

両方のファイルを作成したら、非同期ターミナルで venv の作成と uv pip install を開始します。

# Run in async mode — do NOT wait for completion
uv venv .<app_name>-export-venv && \
source .<app_name>-export-venv/bin/activate && \
uv pip install -r export_requirements.txt

2b — 動画をローカルディレクトリにダウンロードする

ユーザーから動画入力用の HTTP URL が提供された場合は、今すぐダウンロードします。

mkdir -p videos && curl -L -o videos/<video_name>.mp4 \
    -H "Referer: https://www.pexels.com/" \
    -H "User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36" \
    "<DIRECT_VIDEO_URL>"

アプリケーション自体で動画をダウンロードしてはいけません。ローカルファイルまたは RTSP URI を指す --input のみを受け付けます。ダウンロード手順は README に記載してください。

Pexels のページ URL → 直接ファイル URL： Pexels のページ URL （https://www.pexels.com/video/<slug>-<ID>/）は、直接ダウンロードできるリンクではありません。 curl -s でページを取得し、HTML 内で videos.pexels.com/video-files/ リンクを検索して、実際の .mp4 URL を取得してください。 解像度や FPS を推測してはいけません。動画ごとに異なります。 スクレイピングに失敗した場合は、ユーザーに直接 URL を尋ねてください。

Git LFS に関する警告： edge-ai-resources の動画は、動画データではなく HTML を返すことがあります。次のコマンドで確認してください：file videos/sample.mp4 | grep -q "ISO Media"。 テスト動画のデフォルトには、Pexels の直接 URL を優先してください。

uv pip install と docker pull がバックグラウンドで実行されている間に、ステップ 3 に進みます。

2c — モデルをエクスポートする（uv pip install の完了後）

エクスポートを実行する前に、ステップ 2a の非同期ターミナルが正常に完了したことを確認してください。 インストールに失敗した場合は、原因を調査して再実行してから続行します。

確認できたら、モデルエクスポートを実行します。

source .<app_name>-export-venv/bin/activate
python3 export_models.py  # or bash export_models.sh

モデルエクスポートに失敗した場合は、コマンド出力で一般的な原因（未対応のアーキテクチャ、RAM 不足、モデルの重みの不足）を確認し、推奨される修正方法とともにエラーを報告してから再試行してください。

Step 3 — パイプラインの設計

ユーザーの要件を満たす DL Streamer パイプラインを設計します。このステップでは、要素の選択とアプリケーションの構成を扱います。

3a — 要素を選択してパイプライン文字列を組み立てる

Pipeline Construction Referenceを使用して、パイプラインの各段階（ソース、デコード、推論、メタデータ、シンク）に必要な要素を特定します。参照先のPipeline Design Rulesに従ってください。

一般的なユースケースでは、ユースケース → テンプレート／パターンの対応表を使用して、すぐにファイルの生成に進みます。

複雑なケースでは、関連するリファレンス実装をSample Indexで確認し、ユーザーのユースケースに合った具体的なサンプルを読んでください。

DeepStream からの変換

DeepStream アプリケーションを変換する場合は、次の追加ルールに従ってください。

1. ソースパイプラインの要素を一覧にします。 まず、DeepStream パイプラインに含まれるすべての要素を特定します。
2. Converting Guide（docs/user-guide/dev_guide/converting_deepstream_to_dlstreamer.md）を使用して、各要素を1 対 1 で対応付けます。
3. Common Pipeline Patterns の表または Sample Index を使用して、DL Streamer の要素を接続します。
4. ソースパイプラインにない要素を追加しないでください。 変換後のパイプラインの各要素は、一覧に記載された要素のいずれかに対応している必要があります。

3b — アプリケーションの構成を選択する

CLI アプリケーションの場合、3a で作成したパイプライン文字列が成果物となります。gst-launch-1.0のシェルスクリプトでラップしてください。

Python アプリケーションの場合は、Pattern Selection Tableを使用して、ユーザーの説明を1つ以上の設計パターンに対応付けます。

1. パイプラインの構築方法を選択します。Pattern 1: Pipeline Coreを参照してください。
2. 必要に応じて、コールバック／プローブを追加します。
3. ユーザーがインライン分析を必要とする場合は、カスタム Python 要素を追加します。まず、既存の GStreamer 要素でそのロジックを処理できるかどうかを確認してください。できない場合は、Pattern 7 のConventionsに従ってください。
4. 引数の解析を接続します。
5. パイプラインのイベントループを追加します。Pattern 2: Pipeline Event Loopを参照してください。

ステップ 4 — アプリケーションの生成

このドキュメントの冒頭で定義したディレクトリ構成に従って、すべてのアプリケーションファイルを生成します。

言語ごとの生成：

C/C++ アプリケーション： アプリケーションテンプレートを基本のひな形として使用します。コーディング規約とアプリケーション構成については、デザインパターンリファレンスを参照してください。

• Python アプリケーション：アプリケーションテンプレートを基本のひな形として使用します。コーディング規約とアプリケーション構成については、デザインパターンリファレンスを参照してください。

すべての言語で：

• README テンプレートを使用して、以下の説明に従い、すべての {{PLACEHOLDERS}} を置き換えて README.md を生成します。

  プレースホルダー	生成する内容
  {{APP_TITLE}}	アプリケーションの短いタイトル
  {{APP_DESCRIPTION}}	アプリケーションの機能と主な用途を説明する2〜3文
  {{DLSTREAMER_CODING_AGENT_PROMPT}}	Markdown の引用ブロック（> ）で囲んだ、ユーザーの最初のプロンプトの全文。言い換えたり要約したりしないでください。
  {{APP_VISUALIZATION}}	任意のスクリーンショット行：。スクリーンショットがない場合は、この行全体を省略します。
  {{DETAILED_DESCRIPTION}}	詳細な説明：モデル名、ハードウェア要件、想定される出力。入力動画が一般公開されているソース（例：Pexels）の場合は、This sample uses a video from <link> by <author>. を追加します。
  {{NUMBERED_STEPS}}	パイプラインの各段階を示す番号付きリスト。例：1. **Detects** objects using gvadetect
  {{PIPELINE_DIAGRAM}}	Mermaid 図。直線的なパイプラインには graph LR を使用します。tee／複数分岐にはサブグラフを使用します（例については smart_nvr と vlm_self_checkout を参照）。
  {{PIPELINE_ELEMENTS_LIST}}	GStreamer／DL Streamer の各エレメントとその役割を示す任意の箇条書きリスト。パイプラインが単純な場合は省略します。
  {{VIDEO_DOWNLOAD_INSTRUCTIONS}}	テスト動画を videos/ にダウンロードする curl コマンド。一般公開されている動画を使用しない場合は、### Download Video の見出しとこのプレースホルダー全体を省略します。
  {{ADVANCED_USAGE}}	デフォルト以外の CLI オプションを示す任意の2つ目の使用方法ブロック。不要な場合は省略します。
  {{HOW_IT_WORKS_SECTIONS}}	パイプラインの主要な各段階またはカスタムエレメントについて、関連するコードスニペットを含む ### STEP N サブセクションを1つずつ記述します。
  {{CONFIGURATION_FILES_SECTION}}	任意の ## Configuration Files テーブル（ファイル名＋用途）。使用しない場合は、このセクションを省略します。
  {{CLI_ARGUMENTS_TABLE}}	CLI 引数ごとに1行を記載するテーブル：フラグ名、デフォルト値、説明。
  {{OUTPUT_FILES_LIST}}	results/ に生成される出力ファイルの箇条書きリスト。

• アプリケーションに Python パッケージが必要な場合は、requirements.txt に記載します。OpenVINO Python ランタイムが必要な場合は、DL Streamer とともにインストールされている OpenVINO ランタイムと同じバージョンに固定します。

ステップ 5 — 実行、デバッグ、検証

Docker で実行

docker run --init --rm \
    -u "$(id -u):$(id -g)" \
    -e PYTHONUNBUFFERED=1 \
    -v "$(pwd)":/app -w /app \
    --device /dev/dri \
    --group-add $(stat -c "%g" /dev/dri/render*) \
    --device /dev/accel \
    --group-add $(stat -c "%g" /dev/accel/accel*) \
    intel/dlstreamer:latest \
    python3 <app_name>.py

自律実行 — ユーザーの確認を待たないでください。 非同期モードで起動し、完了するまで15〜30秒ごとに get_terminal_output をポーリングします。 ユーザーへの質問は、判断が必要な場合（例：OOM 後のデバイス変更）に限ります。 これは、実行時間の長いすべてのコマンド（docker run、docker pull、uv pip install、モデルのエクスポート）に適用されます。

検証： 出力がユーザーの期待する結果と一致していることを確認します。よくある問題については、デバッグのヒントと検証チェックリストを使用してください。連続入力または長い入力の場合は、EOS を送信して処理を完了します。

タスク後 — コーディングエージェントの分析結果を報告する

アプリケーションの検証が完了したら、検証結果と同じ応答内ですぐに分析テーブルを報告してください。

アプリケーションが動作したら、時間の指標を報告してください。

1. AI の推論時間 — プロンプトの理解、パイプラインの設計、コードの作成
2. 環境のセットアップ時間 — uv pip install の実行、モデルのエクスポート、Docker イメージのプルの待ち時間
3. デバッグと検証の時間 — アプリケーションの実行、出力の確認、問題の修正
4. ユーザーの待ち時間 — ユーザーの入力または確認を待つ時間
5. 合計アクティビティ時間（各フェーズは重複する場合があるため、合計は各フェーズの合計と一致しません）

例

手順の参考資料や実践例については、プロンプトの例を参照してください。