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 帧数为零或检测率低于 90%，请勿继续执行步骤 7。
6. 共享 venv——所有模型都复用 build/.venv_optimum。绝不要为每个模型单独创建 venv。
7. trtexec --noDataTransfers——仅 GPU 计算与 DeepStream 的 GPU 到 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	两阶段批次大小扫描
deepstream/benchmark-ds.sh	6–7	固定流数 DS 基准测试
deepstream/ds-kitti-dump.sh	6–7	通过 deepstream-app 导出 KITTI 检测结果
deepstream/ds-perf-run.sh	7	步骤 7c 双次运行基准测试——使用 enable-perf-measurement=1 封装 deepstream-app，写入固定名称的日志，供报告解析器使用
deepstream/extract-frame.sh	6–7	从输出视频中提取样例帧（.mp4 NVENC 路径或 .ogv theoraenc 备用方案）
report/generate-benchmark-charts.py	8	生成 5 张基准测试 PNG 图表
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	使用 M 后缀而非 MiB——例如 --memPoolSize=workspace:32768M
DETR 的 ForeignNode 构建失败	使用 dynamo 导出路径或运行 onnxsim——参见 references/engine-build.md
检测结果为零	net-scale-factor 错误——检查 references/pipeline-run.md 中的模型系列表
No module named 'pyservicemaker'	安装到 venv 中：pip install /opt/nvidia/deepstream/.../pyservicemaker*.whl