deepstream-import-vision-model

DeepStream ビジョンモデルのインポート

このスキルが有効な場合は、各フェーズを開始する前に、該当するリファレンスドキュメントを必ず読んでください。記憶に頼らないでください。リファレンスドキュメントには、正確なスクリプトのパス、bash 変数の規則、ログファイル名の取り決め、重要な解析ルールが記載されています。

**現在の対象範囲：**物体検出モデルのみです。config.json で分類、セグメンテーション、またはその他のアーキテクチャが検出された場合は、即座に処理を中止してください。

モデルの選択 — 常に2つの選択肢を提示する

プリフライト、ブラウジング、ダウンロード、ファイル作成の前に、必ず次の2つの選択肢だけを提示してください。自由回答形式でモデルのソースを尋ねるだけの形で始めないでください。ユーザーの依頼からモデルがすでに明確に選ばれている場合は、重複して尋ねず、該当する選択肢を確認してください。

1. デフォルトモデル（推奨）

検証済みの Hugging Face RT-DETR モデルを使用します。

model_id: PekingU/rtdetr_r50vd
source: huggingface
task: object-detection
precision_preference: fp16

2. カスタム物体検出モデル

対応しているソースを1つ尋ねてください。

• Hugging Face のモデル ID（organization/model）または完全なモデル URL。
• バージョンを含む NVIDIA NGC カタログのモデル URL。

このスキルでは現在、config.json の検査後に、分類、セグメンテーション、その他の物体検出以外のアーキテクチャを拒否することを説明してください。カスタムソースが指定されていない場合や、対応していない場合に、モデルを捏造したり、黙って別のモデルに置き換えたりしないでください。

ドライランでも同じ2つの選択肢を提示し、ブラウジング、ダウンロード、Docker の起動、ファイルの書き込み、プロセスの開始を行わずに、検出、ビルド、ベンチマーク、レポートの各段階をシミュレーションしてください。

パイプラインの概要

ステップ	フェーズ	リファレンス	内容
1–3	モデル取得	references/model-acquire.md	HF/NGC をブラウジングし、形式を検出して、ONNX をダウンロードするか SafeTensors をエクスポートします
4–5	エンジンビルド	references/engine-build.md	動的 TRT エンジンをビルドし、trtexec を BS=1 および BS=MAX_BS で実行します
6–7	DS パイプライン	references/pipeline-run.md	カスタム bbox パーサー、nvinfer 設定、単一ストリームおよびマルチストリームのベンチマークを実行します
8	レポート	references/report-generation.md	5つのグラフ、HTML、PDF のベンチマークレポートを作成します

各ステップで確認のために中断せず、パイプライン全体を自律的に実行してください。

すべて Docker 内で実行（ホストへのパッケージインストール不要）

すべてのステップは DeepStream コンテナ内で実行されます。 ホストに必要なのは Docker と NVIDIA ドライバーだけです。ホスト側の python/venv/torch/trtexec/make/wkhtmltopdf は不要です。Linux とWindows（--gpus に必要な Docker Desktop + WSL2 バックエンド）のどちらでも同様に動作します。シェルごとに異なるのはバインドマウントのトークンだけです。bash では -v "$PWD":/work、PowerShell では -v "${PWD}:/work"、cmd では -v "%cd%:/work" を使用します。詳細なガイドは references/windows.md を参照してください。venv/ONNX/エンジン/パーサー/設定/レポートのすべての成果物はマウントされた作業ルート内に保存され、破棄される --rm コンテナ間でも保持されます。

事前確認 — ブートストラップと検証（コンテナ経由）

1. 初回のみのブートストラップ — すべてコンテナ内で、build/.venv_optimum（torch／onnx／onnxruntime／レポート用依存関係）をビルドし、wkhtmltopdf をインストールします（venv 名は歴史的なもので、optimum は現在使用していません）。作業ルートから実行します：

docker run --rm -it --gpus all --shm-size=16g -v "$PWD":/work -w /work \
  --entrypoint bash nvcr.io/nvidia/deepstream:9.1-triton-multiarch \
  .claude/skills/deepstream-import-vision-model/setup.sh

2. 事前確認 — GPU、venv、trtexec をコンテナ経由で実行します（コンテナモードは自動検出されます）：

docker run --rm --gpus all -v "$PWD":/work -w /work \
  --entrypoint bash nvcr.io/nvidia/deepstream:9.1-triton-multiarch \
  .claude/skills/deepstream-import-vision-model/scripts/preflight.sh   # proceed only on PASS

以降のすべてのフェーズも同じ方法で実行します — モデルのコマンドを docker run … --entrypoint bash … -lc '<commands>' 経由で実行します（または .claude/skills/deepstream-import-vision-model/scripts/dsrun.sh ラッパーを使います： bash .claude/skills/deepstream-import-vision-model/scripts/dsrun.sh '<in-container command>'）。 コンテナ内では PY=build/.venv_optimum/bin/python を使い、trtexec は /usr/src/tensorrt/bin/trtexec にあります。deepstream-app、gst-launch-1.0、および /opt/nvidia/deepstream/… のサンプルパスは、すべてイメージ内にあります。 TensorRT のビルドと実行は同じイメージを使うため、バージョンの不一致はありません（以前の「ホスト上でビルドする」ルールが避けようとしていた問題です。references/engine-build.md を参照してください）。 sample_720p.mp4 はイメージに含まれています。変更する場合に限り、DS_VIDEO を設定してください。

必須の出力構成

MODEL_NAME が分かったら（Step 1）、一度だけ作成します。ファイルをフラットに配置してはいけません。

models/{model_name}/
  model/           <- ONNX file(s)
  parser/          <- .cpp, Makefile, .so
  config/          <- nvinfer config, ds-app config, labels.txt
  scripts/         <- run helper scripts
  benchmarks/
    engines/       <- _dynamic_b{MAX_BS}.engine, timing.cache, build logs
    b1/            <- trtexec BS=1 log
    b{MAX_BS}/     <- trtexec BS=MAX_BS log
    ds/            <- DS benchmark logs
  reports/         <- benchmark_report.md, .html, .pdf, benchmark_data.json
    charts/        <- chart_*.png (5 charts)
  samples/         <- output .mp4 or .ogv (theoraenc fallback), test frames
    kitti_output/  <- KITTI detection .txt files

mkdir -p models/$MODEL_NAME/{model,parser,config,scripts,benchmarks/engines,benchmarks/ds,reports/charts,samples/kitti_output}

重要なルール

1. Engine の命名 — 常に {model}_dynamic_b{MAX_BS}.engine とします。model_dynamic.engine のような、バッチサイズを含まない名前は禁止です。
2. batch_size == num_streams — DS の実行では、batch-size とストリーム数を常に同じにします。
3. ログファイル名は固定 — trtexec_b1.log、trtexec_b${MAX_BS}.log、ds_s${N}_run1.log、ds_s${N}_run2.log とします。タイムスタンプは付けません。レポート生成では正確なパスを読み込みます。
4. パーサーのゼロ初期化 — 常に NvDsInferObjectDetectionInfo obj = {}; とします。DS 9.1 の OBB サポートに必須です。obj; のままでは rotation_angle が未初期化となり、バウンディングボックスが傾きます。
5. KITTI 検証ゲート — KITTI のフレーム数が 0、または検出率が 90% 未満の場合、Step 7 に進んではいけません。
6. 共有 venv — すべてのモデルで build/.venv_optimum を再利用します。モデルごとの venv は作成しません。
7. trtexec --noDataTransfers — GPU のみで計算することで、DeepStream の GPU 間データフローに一致させます。
8. レポートの HTML+PDF — 常に .claude/skills/deepstream-import-vision-model/scripts/report/md-to-html-pdf.py を使います。独自の HTML ジェネレーターを作成したり、wkhtmltopdf を直接呼び出したりしてはいけません。
9. 物体検出のみ — 何かをビルドする前に config.json で物体検出以外のアーキテクチャを拒否します。
10. エンコーダーのフォールバック（必須） — x264enc と openh264enc は禁止です。NVENC を利用できないシステムでは、theoraenc + oggmux を使います（LGPL。gst-plugins-base に含まれ、出力形式は .ogv です）。theoraenc／oggmux がない場合は、動画を作成せず（DS_SINGLE_STREAM_MODE=skipped）、使用したモードを報告します：nvv4l2h264enc／theoraenc-fallback／skipped。
11. 動画ソース（必須） — デフォルトでは常に sample_720p.mp4（1280×720）を使います。sample_1080p_h264.mp4 やその他のファイルに、自動で置き換えてはいけません。異なる動画を使えるのは、ユーザーがパスを明示的に指定した場合のみです（DS_VIDEO 環境変数またはスクリプト引数を使用）。

例

デフォルトモデルをエンドツーエンドで実行する場合。 ブートストラップは一度だけ実行し、その後パイプライン全体を実行します：

docker run --rm -it --gpus all --shm-size=16g -v "$PWD":/work -w /work \
  --entrypoint bash nvcr.io/nvidia/deepstream:9.1-triton-multiarch \
  .claude/skills/deepstream-import-vision-model/setup.sh
# then: "Use deepstream-import-vision-model to run PekingU/rtdetr_r50vd"

公開済み ONNX がない SafeTensors モデルの場合。 Step 2b で先にエクスポートします。ラッパーはグラフを生成したバックエンドを報告し、バッチ次元が固定されている場合は明確にエラーを出して終了します：

bash .claude/skills/deepstream-import-vision-model/scripts/model/safetensors-to-onnx.sh \
  models/$MODEL_NAME/hf_model models/$MODEL_NAME/onnx_export/
#   [export] backend=dynamo
#   [export] dynamo produced a static batch dimension; trying the next backend
#   [export] backend=legacy-torchscript
#   [export] pixel_values shape=['batch', 3, 640, 640]

Hub のリビジョンを固定して再現可能なビルドにします。エクスポーターのフラグはそのまま渡されます：

bash .claude/skills/deepstream-import-vision-model/scripts/model/safetensors-to-onnx.sh \
  PekingU/rtdetr_r50vd models/rtdetr/onnx_export --revision <commit-sha> --opset 18

パイプラインの所要時間

各ステップをラップします：

STEP_START=$(date +%s.%N)
# ... step commands ...
STEP_END=$(date +%s.%N)
STEP_DURATION=$(python3 -c "print(round($STEP_END - $STEP_START, 2))")   # bc is not in the container; python3 always is
echo "[Step N] completed in ${STEP_DURATION}s"

PIPELINE_START（Step 1 の前）と PIPELINE_END（Step 8 の後）を記録します。すべての所要時間をベンチマークレポートに記載してください。

レポート出力（必須 — 3形式すべて）

1. benchmark_report.md — Markdown ソース（必須の12セクション）
2. benchmark_report.html — スタイル付きHTML（グラフはBase64でインライン化し、ローカルファイルへのアクセスなし）
3. benchmark_report_{model_name}.pdf — md-to-html-pdf.py 経由で作成します。HTML出力内の data:image/png の出現数を数えて、グラフが埋め込まれていることを確認してください。grep -o 'data:image/png' benchmark_report.html | wc -l の結果は5になる必要があります。

グラフとレポートのスクリプトは、共有venvを有効にして実行してください：source build/.venv_optimum/bin/activate。

参照ドキュメント

重要：各フェーズの開始前に、該当する参照ドキュメントを読んでください。記憶を頼りにコードを生成しないでください。

ドキュメント	使用するタイミング
references/model-acquire.md	手順1～3：HF/NGC URLの解析、形式の検出、ONNXのダウンロード、SafeTensorsのエクスポート、ラベルの抽出
references/engine-build.md	手順4～5：trtexecによるエンジンのビルド、ベンチマーク、PEAK_GPU_STREAMSの導出、反復的なスケーリング
references/pipeline-run.md	手順6～7：カスタムbboxパーサー、nvinfer設定、単一ストリームの検証、KITTIダンプ、マルチストリームのベンチマーク
references/report-generation.md	手順8：benchmark_data.json、5つのグラフ、12セクションのMarkdownレポート、HTML＋PDF

スクリプト

install.sh によって .claude/skills/deepstream-import-vision-model/scripts/ にインストールされます。

スクリプト	フェーズ	目的
model/hf-list-files.sh	1～3	HuggingFaceリポジトリのファイル一覧を表示
model/hf-download-config.sh	1～3	HFからconfig.jsonをダウンロード
model/ngc-list-files.sh	1～3	NGCモデルのファイル一覧を表示
model/ngc-download.sh	1～3	NGCモデルのアーカイブをダウンロード
model/safetensors-to-onnx.sh	1～3	torch.onnx.export 経由でSafeTensorsをONNXにエクスポートするラッパー
model/safetensors_to_onnx.py	1～3	エクスポーター — dynamoバックエンド、TorchScriptフォールバック、動的バッチの検証
model/inspect-onnx.py	1～5	ONNXの入力／出力形状を検査
model/make-static-batch-onnx.py	4～5	ONNXにバッチ次元を固定
model/cleanup.sh	任意	ステージングディレクトリを削除し、共有venvは保持
engine/benchmark-trtexec.sh	4～5	標準フラグを指定してtrtexecを実行
deepstream/ds-single-stream.sh	6～7	単一ストリームの視覚的検証（NVENCを優先し、利用できない場合はtheoraenc＋oggmuxにフォールバック。どちらも利用できない場合はスキップ）
deepstream/ds-sweep.sh	6～7	2フェーズのバッチサイズスイープ
deepstream/benchmark-ds.sh	6～7	ストリーム数を固定したDSベンチマーク
deepstream/ds-kitti-dump.sh	6～7	deepstream-app経由でKITTI検出結果をダンプ
deepstream/ds-perf-run.sh	7	手順7cの2回実行ベンチマーク — enable-perf-measurement=1 を指定して deepstream-app をラップし、レポートパーサー用の固定名ログを出力
deepstream/extract-frame.sh	6～7	出力動画からサンプルフレームを抽出（.mp4 のNVENC経路、または .ogv のtheoraencフォールバック）
report/generate-benchmark-charts.py	8	ベンチマーク用PNGグラフを5つ生成
report/md-to-html-pdf.py	8	Markdown → スタイル付きHTML → PDF（ベンチマークレポートの標準パス）
report/md-to-pdf.sh	任意	pandoc/pdflatex経由でMarkdownをPDFに変換 — 設計ドキュメントと参照資料のみを対象とし、ベンチマークレポートには使用しません（ベンチマークレポートには md-to-html-pdf.py を使用してください）
report/report-style.css	8	HTMLレポート用CSS
report/render-mermaid-for-pdf.py	8	Mermaid図をPNGに変換
report/mermaid-puppeteer.json	8	Mermaid用の検証済みPuppeteer設定（サンドボックス化、非root）
report/mermaid-puppeteer-root.json	8	Mermaid用の検証済みPuppeteer設定（rootで実行する場合に使用）

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

エラー	解決方法
境界ボックスが傾いている／斜めになっている	パーサーの構造体がゼロ初期化されていません — NvDsInferObjectDetectionInfo obj = {}; を使用してください
KITTI ファイルが生成されない	nvinfer は gie-kitti-output-dir を読み込みません — ds-kitti-dump.sh（deepstream-app をラップ）を使用してください
DS を実行するたびにエンジンが再構築される	model-engine-file のパスが間違っています — config/ ディレクトリからの相対パスを確認してください
setDimensions の次元が負になる	動的 ONNX モデルの場合は、nvinfer の設定に infer-dims=3;H;W を追加してください
--memPoolSize のワークスペースが 0.03 MiB	MiB ではなく M サフィックスを使用してください — 例：--memPoolSize=workspace:32768M
ForeignNode のビルド失敗（DETR）	onnxsim を実行してください — references/engine-build.md を参照してください。どちらのエクスポートバックエンドでも、TRT 10.16 では再現していません
ONNX に静的なバッチ次元がある	どちらのエクスポートバックエンドでも特殊化されています — references/model-acquire.md の注意事項を参照してください
検出結果がゼロ	net-scale-factor が間違っています — references/pipeline-run.md のモデルファミリー表を確認してください
No module named 'pyservicemaker'	venv にインストールしてください：pip install /opt/nvidia/deepstream/.../pyservicemaker*.whl