deepstream-generate-pipeline

DeepStream 流水线构建器

通过交互式问卷收集流水线需求，然后使用独立的 BM25 检索后端并通过结构元数据增强（对 270 多条经过验证的流水线进行相似度搜索，无需外部依赖），为 NVIDIA DeepStream SDK 生成可直接运行的 gst-launch-1.0 流水线。

前置条件

• Python： 3.8+（仅使用标准库，无需安装 pip 包）
• DeepStream SDK： 安装在 /opt/nvidia/deepstream/deepstream/（用于通过 gst-inspect-1.0 进行验证和元素检查）
• GStreamer： PATH 中包含 gst-launch-1.0 和 gst-inspect-1.0（随 DeepStream 安装）
• 平台： x86 dGPU（T4、A100、L40、RTX 等）或 aarch64 — Jetson（Orin、Xavier、Nano）/ SBSA（Grace、GH200）

使用示例

# Fully specified — skips most questions
detect and track on 4 rtsp streams and display on jetson

# Partially specified — asks remaining questions
give me a pipeline to infer on an image

# Minimal — asks all 7 questions
build a pipeline

支持的配置

参数	选项
输入	本地视频（.mp4/.h264/.h265）、本地图像（.jpg/.png）、RTSP 流、USB 摄像头、测试图案
推理	无、主推理（nvinfer）、主推理+辅助推理、使用预处理器、Triton（nvinferserver）
跟踪器	无、NvDCF、IOU、NvSORT、DeepSORT
接收端	显示（dGPU/Jetson）、保存（JPG/PNG/MP4/H264）、RTSP 输出、fakesink
平台	x86 dGPU（T4、A100、L40、RTX 等）或 aarch64 — Jetson（Orin、Xavier、Nano）/ SBSA（Grace、GH200）
其他功能	缩放、旋转/翻转、裁剪、颜色格式转换

脚本

脚本	用途
scripts/generate_pipeline.py	BM25 检索引擎 — 对 data/data.csv 中的流水线评分并排序。支持 --format {json,compact,summary}（默认 json）
scripts/validate_pipeline.py	四阶段验证器：语法、元素、属性、实时解析。支持 --format {json,summary}（默认 json）
scripts/lint_data.py	流水线 CSV 的数据质量检查工具（使用 --fix 自动修复）

工作流

第 1 步 — 收集流水线需求

执行此步骤前，必须先 Read references/requirement-extraction.md。 其中包含查询推断表、复合需求提取示例、完整的 AskUserQuestion 问题库（含默认选项优先排序约定）、自动 OSD 和其他功能/翻转方法规则，以及此步骤所需的动态问题精简示例。请严格遵照执行。

操作顺序：

1. 根据查询推断所有可推断的信息，使用 references/requirement-extraction.md 中的推断表。目标是识别用户已经指定了 7 个参数中的哪些（输入源、源数量、推理、跟踪器、接收端、平台、其他功能）。
2. 通过 AskUserQuestion 在一次调用中询问用户未知的信息。 不要默默地为跟踪器/接收端/平台/其他功能设置默认值——这些都是应由用户明确选择的选项（显示还是保存、不使用跟踪器还是使用 NvDCF、x86 dGPU 还是 aarch64 Jetson/SBSA 等）。只跳过查询中已明确的问题。
3. 在提问前向用户复述推断出的参数，让用户了解你已提取的信息。例如：“根据你的查询，我了解到：3 个 mp4 视频，主推理。还需要确认几个细节：”

按照 references/requirement-extraction.md 中的推断表、问题库以及 OSD/其他功能规则，决定要询问哪些问题以及如何放置转换元素，然后继续第 2 步。

第 2 步 — 构建自然语言查询

根据用户的回答，构造一个描述性查询字符串。请遵循以下模式：

Please provide a GStreamer pipeline that [operation] on [num_sources] [input_type] [input_detail] [tracker_detail] and [output_action] [platform_detail]

构造查询示例：

用户选择	构造的查询
本地视频，1 个源，主检测器，无跟踪器，显示，dGPU	"请提供一个 GStreamer 管道，对单个 mp4 视频执行主推理并显示输出"
RTSP，4 个源，主推理 + 次级推理，NvDCF，保存为 MP4，dGPU	"请提供一个 GStreamer 管道，使用 NvDCF 跟踪器对 4 路 RTSP 流执行主推理和次级推理，并将输出保存为 MP4 文件"
本地视频，2 个源，主推理并使用预处理器，IOU，显示，Jetson	"请提供一个 GStreamer 管道，在使用 IOU 跟踪器对 2 路 mp4 流执行主推理之前进行预处理，并在 Jetson 上显示输出"
本地图像，1 个源，无推理，无跟踪器，保存文件，dGPU，顺时针旋转 90°	"请提供一个 GStreamer 管道，在处理单张 jpg 图像之前顺时针旋转 90°，并将其保存到文件"
本地视频，3 个源，主检测器，NvDCF，保存为 MP4，dGPU，旋转 180°	"请提供一个 GStreamer 管道，在使用 NvDCF 跟踪器执行主推理之前将 3 个 mp4 视频旋转 180°，并将输出保存为 MP4 文件"

第 3 步 — 运行管道生成脚本

使用构造的查询和用户参数执行后端脚本：

python3 <skill-path>/scripts/generate_pipeline.py \
  --query "<constructed_query>" \
  --source-type "<Local video file|Local image file|RTSP stream|USB camera|Test pattern>" \
  --num-sources <N> \
  --inference "<None|primary|primary+secondary|primary+preprocess|primary+secondary+preprocess|primary-triton|primary+secondary-triton>" \
  --tracker "<none|NvDCF|IOU|NvSORT|DeepSORT>" \
  --sink "<display|display-jetson|save-jpg|save-png|save-mp4|save-h264|rtsp-out|fakesink>" \
  --platform "<dGPU|Jetson|SBSA>" \
  --extras "<none|resize|rotate|crop|color-convert|osd>" \
  --format compact

始终传入 --format compact。 compact 模式仅返回置信度和排名最高的检索管道（约 25 行），而不会在聊天中输出全部 10 条检索结果（约 150 行 JSON）。json 模式（向后兼容时的默认模式）仅在直接调试检索器时有用。此外还有一种 summary 模式（单行易读文本），供非 Claude 调用方使用。

该脚本将（零外部依赖——纯 Python 标准库）：

1. 加载管道数据集（270 多个经验证的 DeepStream 管道）
2. 提取每个管道的结构元数据（平台、源类型、接收端类型、推理模式、跟踪器、流数量）
3. 使用 BM25（按文档长度归一化）进行评分，并对查询和文档执行领域专用同义词扩展
4. 应用结构加权——提高与用户的平台／源／接收端／推理相匹配的结果的权重，并降低不匹配结果的权重
5. 以 JSON 格式返回排名最高的 K 个结果，并根据最高分数在 confidence 字段中标注置信度（high／medium／low）
6. Claude 使用这些检索到的示例以及下方的组装规则来构建最终管道

当 confidence 为 low 时，应更多地依赖下方的组装规则，而不是检索到的示例。

步骤 4 — 验证管线

提交前，运行验证脚本以检查语法错误、未知元素和链接问题：

python3 <skill-path>/scripts/validate_pipeline.py "<assembled_pipeline>" --format summary

始终传入 --format summary。 Summary 会打印单行状态（例如 valid · 11 elements · 0 warnings · live-parse skipped (multi-stream)），只有存在错误或警告时，才会在下方缩进显示。默认的 json 模式会输出约 40 行结构化内容，仅适用于程序化调用者。

验证器会执行 4 项检查：

1. 语法检查 — 检查引号不匹配、管道段为空、缺少源或接收端
2. 元素检查 — 通过 gst-inspect-1.0 验证每个元素是否存在
3. 属性检查 — 验证 DeepStream 元素的已知属性
4. 实时解析检查 — 使用 gst-launch-1.0 本身构建管线图（以 fakesrc/fakesink 替换），检查链接错误和 pad 不匹配。多流管线会自动跳过此项检查（这类管线包含命名 pad 引用，例如 m.sink_0），因为 fakesrc 无法通过命名 pad 协商 caps。

如果验证失败（"valid": false），请修复错误并重新验证后再提交。验证重试最多 2 次——如果修复 2 次后管线仍未通过验证，请按原样提交（其余检查已覆盖语法、元素、属性和结构正确性）。如果只有警告，请提交管线，但要向用户说明这些警告。

步骤 5 — 提交管线

5.1 — 输出格式（唯一接受的格式）

你的回复必须严格包含以下 5 个区块，并按此顺序排列：

1. 单行状态徽章（验证状态 + 置信度）
2. 包含完整 gst-launch-1.0 -e … 命令的单个 bash 代码块，使用具体的绝对路径，且命令必须在一行内（不得使用 \ 续行、shell 变量或 shell 包装器）
3. 按阶段分组的明细表
4. 建议项目符号列表
5. （仅当前置检查失败时）在状态徽章上方添加一行 ⚠，说明缺少哪个默认路径

这是此步骤唯一接受的输出形式。references/output-format.md 中的 5.3 节模板是必须逐字遵循的模板。

5.2 — 前置检查（撰写回复前运行）

对管线将引用的默认路径（示例视频、PGIE 配置、跟踪器库/配置）运行一次 Bash ls。根据结果确定是否要在徽章中标记 ⚠ default path not found: <path>，并将对应的 “Use your own …” 建议移到首位。

ls /opt/nvidia/deepstream/deepstream/samples/streams/sample_1080p_h264.mp4 \
   /opt/nvidia/deepstream/deepstream/samples/configs/deepstream-app/config_infer_primary.txt \
   2>&1

5.3 / 5.4 — 完整示例与禁止的反模式

撰写回复前，必须 Read references/output-format.md。 其中包含必须严格遵循的 5.3 节字面模板，以及 5.4 节中禁止的输出形式示例（heredoc 包装器、shell 变量间接引用、\ 续行、单独的 “Run it” 行、将内容 Write 到脚本）。请遵循 5.3 节的格式；绝不可使用 5.4 节中的任何形式。

5.5 — 发送前自检

发送回复前，在心里逐项确认。若有任何一项不符合，请重写回复。

• 管线必须在单个 ```bash 代码块内，且严格保持一行。
• 管线以 gst-launch-1.0 -e 开头，且只包含绝对路径字面量（例如 /opt/nvidia/deepstream/...）——不得包含 $VAR、${VAR:-default}、cat >、EOF 或 \ 续行。
• 回复不得包含以下任何内容：cat > /tmp/pipeline.sh、bash /tmp/pipeline.sh、<<'EOF'、${VAR:-。
• 回复不得调用 Write 工具。（将内容保存到文件只能作为建议项目提供，不能作为实际操作。）
• 明细表必须按阶段分组（Source / Mux / Inference / Tracking / Composition / Render — 根据管线的实际阶段调整名称，例如，为文件接收端添加 Encode/Mux 行）。
• “Save it to a script?” 一行必须出现在建议列表中，绝不可作为主要操作。

5.6 — 预检失败变体

如果第 5.2 节中的 ls 报告缺少一个或多个默认路径，请在状态徽章上方添加一行 ⚠，并将匹配的“使用你自己的 …”建议移到最前面：

⚠ default path not found: `/opt/nvidia/deepstream/deepstream/samples/streams/sample_1080p_h264.mp4` — substitute your own video path before running
✓ Validated · 11 elements · 0 warnings · confidence: HIGH

```bash
gst-launch-1.0 -e filesrc location=/opt/nvidia/deepstream/deepstream/samples/streams/sample_1080p_h264.mp4 ! …
```

[breakdown + suggestions as in Section 5.3, with the "Use your own video" suggestion bumped to the top]

关于长度： 5–8 路流式管道写在一行时会很长。这是正确且符合预期的——聊天客户端会如实呈现 bash 代码块，复制时也能正确还原。长 ≠ 拆分。

Step 6 — 提供优化选项

呈现管道后，询问用户是否要调整内容：

要我修改什么吗？例如：

• 更改流数量
• 添加/移除跟踪器或辅助推理
• 切换显示输出和文件输出
• 更改平台（x86 dGPU / aarch64 Jetson / SBSA）

如果用户要求更改，请使用更新后的参数返回步骤 2——不要重新询问全部 7 个问题。只询问发生变化的具体参数，或者在变更明确时直接应用。

Step 6.5 — 可选：将管道保存到脚本

仅当用户明确提出要求时才执行此步骤（例如 “保存它”、“保存到 pipeline.sh”、“写入文件”、“放到 ~/run.sh”）。不要主动创建文件——步骤 5 始终会在聊天中显示具体管道，方便直接复制粘贴；保存只是后续提供的便利选项。

1. 文件名： 如果用户只说 “保存它”，默认使用 /tmp/pipeline.sh。否则使用用户指定的确切路径（例如 ~/run.sh、scripts/demo.sh）。

2. 文件内容： 两行——shebang 加上聊天中显示的同一条单行管道（具体绝对路径，不使用 shell 变量）。确保二者一致——用户从文件运行的内容必须与直接复制粘贴的内容逐字节相同。

   #!/usr/bin/env bash
   gst-launch-1.0 -e filesrc location=/opt/nvidia/deepstream/deepstream/samples/streams/sample_1080p_h264.mp4 ! qtdemux ! h264parse ! nvv4l2decoder ! m.sink_0 … ! nvdsosd ! nveglglessink
   

   使用 Write 工具创建文件。

3. 向用户确认并提供运行命令：

   已保存到 <path>。运行命令：

   bash <path>
   

---

管道组装规则

如果脚本不可用或执行失败，请按照 references/assembly-rules.md 中的规则组装管道。这些规则涵盖源元素、多流模式、推理链、跟踪器配置、接收端元素和额外操作，也可用于验证脚本输出。

---

错误处理

失败	原因	恢复方式
generate_pipeline.py 返回 confidence: low	查询与数据集中的任何管道都不够匹配	依照此技能中的组装规则，而不是检索到的示例
validate_pipeline.py 报告未知元素	未安装 GStreamer/DeepStream，或不在 PATH 中	安装 DeepStream SDK；确认 gst-inspect-1.0 nvinfer 可以正常运行
重试 2 次后验证仍失败	元素组合异常或链接问题	保留管道原样并附上警告——语法/元素/属性检查仍已通过
在 <skill-path>/scripts/ 中找不到脚本	技能安装不正确或路径配置有误	确认技能目录已符号链接到 .claude/skills/ 或 .cursor/skills/

测试

运行测试套件，验证检索质量和验证器的正确性：

python3 -m unittest discover -s <skill-path>/tests -v

测试套件包括：

• 单元测试，用于 BM25 检索器（分词器、同义词扩展、元数据提取、评分）
• 单元测试，用于验证器（语法、结构、属性、命名焊盘检查）
• 黄金回归测试——20 多组“查询→预期结果”配对，确保检索质量不会退化
• 数据质量检查器——检查 CSV 中的重复项、语法问题和结构错误：

python3 <skill-path>/scripts/lint_data.py          # report issues
python3 <skill-path>/scripts/lint_data.py --fix     # auto-fix and overwrite

---

安全性、局限性与说明

安全态势、已知局限性和运行说明记录在 references/security-and-limitations.md 中。如果需要了解子进程安全性、输入验证、平台/SDK 要求、多流试运行注意事项，或样例路径/配置文件相关提醒，请阅读该文件。