
名称	deepstream-import-vision-model
描述	> 使用此技能将任何来自HuggingFace或NVIDIA NGC的视觉模型导入NVIDIA DeepStream管道，实现端到端自动化：ONNX下载、SafeTensors导出、TRT引擎构建、自定义nvinfer边界框解析器、多流基准测试和PDF报告。仅支持目标检测模型。
开源协议	CC-BY-4.0 AND Apache-2.0 metadata:
作者	NVIDIA CORPORATION
版本	1.2.2

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和驱动
nvidia-smi

# 2. TensorRT版本匹配（builder和DS运行时之间必须匹配）
trtexec 2>&1 | head -3
dpkg -l | grep libnvinfer-bin

# 3. 共享Python虚拟环境 — 创建一次，可在所有模型间重用
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. 系统工具
which wkhtmltopdf || apt-get install -y wkhtmltopdf
which mediainfo    || apt-get install -y mediainfo
which deepstream-app  # KITTI转储（步骤6g）和基准测试性能测量（步骤7c）需要；随DeepStream SDK提供

# 5. 示例视频 — 当用户没有提供自定义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文件
  parser/          <- .cpp, Makefile, .so
  config/          <- nvinfer配置、ds-app配置、labels.txt
  scripts/         <- 运行辅助脚本
  benchmarks/
    engines/       <- _dynamic_b{MAX_BS}.engine、timing.cache、构建日志
    b1/            <- trtexec BS=1日志
    b{MAX_BS}/     <- trtexec BS=MAX_BS日志
    ds/            <- DS基准测试日志
  reports/         <- benchmark_report.md、.html、.pdf、benchmark_data.json
    charts/        <- chart_*.png（5个图表）
  samples/         <- 输出.mp4或.ogv（theoraenc回退）、测试帧
    kitti_output/  <- KITTI检测.txt文件

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

关键规则

引擎命名 — 始终为 {model}_dynamic_b{MAX_BS}.engine。绝不能是裸的 model_dynamic.engine。
batch_size == num_streams — 在DS运行中，batch-size和流数量始终相等。
日志文件名固定 — trtexec_b1.log、trtexec_b${MAX_BS}.log、ds_s${N}_run1.log、ds_s${N}_run2.log。无时间戳。报告生成读取精确路径。
解析器零初始化 — 始终 NvDsInferObjectDetectionInfo obj = {};。DeepStream OBB支持需要；裸 obj; 会让 rotation_angle 未初始化，导致倾斜的边界框。
KITTI验证门 — 如果KITTI帧数为零或检测率<90%，不要进入步骤7。
共享虚拟环境 — build/.venv_optimum 可在所有模型间重用。绝不创建每模型虚拟环境。
trtexec --noDataTransfers — 纯GPU计算与DeepStream的GPU到GPU数据流匹配。
报告HTML+PDF — 始终使用 skills/deepstream-import-vision-model/scripts/report/md-to-html-pdf.py。绝不编写自定义HTML生成器或直接调用 wkhtmltopdf。
仅目标检测 — 在构建任何内容之前，从 config.json 拒绝非检测架构。
编码器回退（强制） — 禁止 x264enc 和 openh264enc。在无NVENC的系统上，使用 theoraenc + oggmux（LGPL；随gst-plugins-base提供；输出为 .ogv）。如果 theoraenc/oggmux 不存在，跳过视频创建（DS_SINGLE_STREAM_MODE=skipped）。报告使用了哪种模式：nvv4l2h264enc / theoraenc-fallback / skipped。
视频源（强制） — 默认始终是 sample_720p.mp4 (1280×720)。绝不自主替换为 sample_1080p_h264.mp4 或任何其他文件。仅在用户明确提供路径时（通过 DS_VIDEO 环境变量或脚本参数）使用不同视频。

管道计时

包裹每个步骤：

STEP_START=$(date +%s.%N)
# ... 步骤命令 ...
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种格式）

benchmark_report.md — Markdown源（12个必需章节）
benchmark_report.html — 样式化HTML（图表base64内联，无本地文件访问）
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

脚本

位于 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	任意	删除暂存目录，保留共享虚拟环境
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两次运行基准测试 — 包装 deepstream-app，带 enable-perf-measurement=1，为报告解析器写入固定名称日志
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	任意	Markdown → PDF（通过pandoc/pdflatex） — 仅用于设计文档和参考，不用于基准报告（那些用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	经过审查的Puppeteer配置（沙箱；非root）
report/mermaid-puppeteer-root.json	8	经过审查的Puppeteer配置（以root运行时使用）

快速错误参考

错误	修复
倾斜/对角线边界框	解析器结构未零初始化 — 使用 NvDsInferObjectDetectionInfo obj = {};
零KITTI文件	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	使用 M 后缀而不是 MiB — 例如 --memPoolSize=workspace:32768M
ForeignNode构建失败（DETR）	使用dynamo导出路径或运行 onnxsim — 见references/engine-build.md
零检测	错误的 net-scale-factor — 检查references/pipeline-run.md中的模型族表
No module named ‘pyservicemaker’	安装到虚拟环境：pip install /opt/nvidia/deepstream/…/pyservicemaker*.whl