deepstream-import-vision-model

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

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

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

パイプラインの概要

ステップ	フェーズ	リファレンス	内容
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 のベンチマークレポート

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

事前チェック

開始前に実行してください：

# 1. GPU and drivers
nvidia-smi

# 2. TensorRT version match (must match between builder and DS runtime)
trtexec 2>&1 | head -3
dpkg -l | grep libnvinfer-bin

# 3. Shared Python venv — create once, reuse across all models
mkdir -p build
VENV=build/.venv_optimum
if [ ! -x "$VENV/bin/python3" ]; then
  python3 -m venv "$VENV"
  "$VENV/bin/pip" install --upgrade pip -q
  "$VENV/bin/pip" install "optimum[exporters]>=1.20,<2.0" "torch<2.12" \
    transformers onnxruntime matplotlib numpy markdown -q
fi

# 4. System tools
which wkhtmltopdf || apt-get install -y wkhtmltopdf
which mediainfo    || apt-get install -y mediainfo
which deepstream-app  # required for KITTI dump (Step 6g) and benchmark perf-measurement (Step 7c); shipped with DeepStream SDK

# 5. Sample video — only check default path when user has not provided a custom DS_VIDEO
if [ -z "$DS_VIDEO" ]; then
  [ -f /opt/nvidia/deepstream/deepstream/samples/streams/sample_720p.mp4 ] || \
    echo "WARNING: sample_720p.mp4 not found. Install DeepStream samples or set DS_VIDEO=/path/to/your.mp4"
fi

必須の出力構成

MODEL_NAME が確定したら（ステップ 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. エンジンの命名 — 常に {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.0 の OBB サポートに必要です。obj; のみでは rotation_angle が初期化されず、傾いたバウンディングボックスが発生します。
5. KITTI 検証ゲート — KITTI のフレーム数が 0、または検出率が 90% 未満の場合、ステップ 7 に進まないでください。
6. 共有 venv — すべてのモデルで build/.venv_optimum を再利用してください。モデルごとの venv は作成しないでください。
7. trtexec --noDataTransfers — GPU のみで計算することで、DeepStream の GPU 間データフローに一致させます。
8. レポートの HTML+PDF — 必ず 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 環境変数またはスクリプト引数で指定）。

パイプラインの所要時間

各ステップをラップしてください：

STEP_START=$(date +%s.%N)
# ... step commands ...
STEP_END=$(date +%s.%N)
STEP_DURATION=$(echo "$STEP_END - $STEP_START" | bc)
echo "[Step N] completed in ${STEP_DURATION}s"

PIPELINE_START（ステップ 1 の前）と PIPELINE_END（ステップ 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

スクリプト

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	optimum-cli を使用して SafeTensors → ONNX をエクスポート
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 ファイルが 0 件	gie-kitti-output-dir は nvinfer に読み取られません — 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）	dynamo エクスポート経路を使用するか、onnxsim を実行してください — references/engine-build.md を参照
検出数が 0 件	net-scale-factor が間違っています — references/pipeline-run.md のモデルファミリー表を確認してください
No module named 'pyservicemaker'	venv にインストールしてください：pip install /opt/nvidia/deepstream/.../pyservicemaker*.whl