deepstream-import-vision-model

导入 DeepStream 视觉模型

此技能启用后，每个阶段开始前都要先阅读相关参考文档。不要依赖记忆——参考文档包含精确的脚本路径、bash 变量约定、日志文件名约定和关键解析规则。

**当前范围：**仅支持目标检测模型。如果在 config.json 中检测到分类、分割或其他架构，立即失败。

模型选择 — 始终提供两个选项

在预检、浏览、下载或创建文件之前，必须恰好提供以下两个选项。不要只用开放式问题询问模型来源来开场。如果用户的请求已明确指定模型，请确认对应选项，而不是重复询问。

1. 默认模型（推荐）

使用经过验证的 Hugging Face RT-DETR 模型：

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

2. 自定义目标检测模型

请用户提供一种受支持的来源：

• Hugging Face 模型 ID（organization/model）或完整模型 URL。
• 包含版本号的 NVIDIA NGC 目录模型 URL。

说明：检查 config.json 后，此技能目前会拒绝分类、分割及其他非检测架构。如果缺少自定义来源或来源不受支持，不要编造或擅自替换模型。

对于试运行，请提供相同的两个选项，并模拟发现、构建、基准测试和报告阶段，不进行浏览、下载、启动 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（Docker Desktop + WSL2 后端，使用 --gpus 时必需）上的运行方式完全相同。每个 shell 的绑定挂载令牌是唯一的系统差异——-v "$PWD":/work（bash）、-v "${PWD}:/work"（PowerShell）、-v "%cd%:/work"（cmd）；完整指南见 references/windows.md。所有 venv/ONNX/引擎/解析器/配置/报告文件都存放在挂载的工作根目录下，并会在临时 --rm 容器之间保留。

预检 — 引导设置 + 验证（通过容器）

1. 一次性引导设置 — 在容器内构建 build/.venv_optimum（torch/onnx/onnxruntime/report 依赖；venv 名称沿用历史名称，已不再使用 optimum）+ 安装 wkhtmltopdf。从工作根目录运行：

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，并在容器内通过 /usr/src/tensorrt/bin/trtexec 调用 trtexec。deepstream-app、 gst-launch-1.0 和 /opt/nvidia/deepstream/… 示例路径都存在于镜像内。 TensorRT 构建和运行时共用同一个镜像，因此没有版本偏差（旧的“在主机上构建”规则试图避免的正是这个问题 — 参见 references/engine-build.md）。 镜像中附带 sample_720p.mp4；仅在需要覆盖时设置 DS_VIDEO。

强制输出结构

在确定 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.1 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 — 始终使用 .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 模型。 步骤 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（步骤 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

运行图表和报告脚本时，确保共享虚拟环境处于激活状态：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 回退，并验证动态 batch
model/inspect-onnx.py	1–5	检查 ONNX 输入/输出形状
model/make-static-batch-onnx.py	4–5	将 batch 维度烘焙到 ONNX 中
model/cleanup.sh	任意	移除暂存目录，保留共享虚拟环境
engine/benchmark-trtexec.sh	4–5	使用标准标志运行 trtexec
deepstream/ds-single-stream.sh	6–7	单流可视化验证（优先使用 NVENC；回退到 theoraenc+oggmux；两者都不可用时跳过）
deepstream/ds-sweep.sh	6–7	两阶段 batch size 扫描
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
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