dlstreamer-coding-agent

DL Streamer 编码 Agent

通过组合从现有示例应用中提取的设计模式，构建新的 DL Streamer 视频分析应用（Python、C、C++ 或 GStreamer 命令行）。

文件路径解析

此技能使用相对于仓库根目录的路径来引用技能文件夹之外的文件（例如，docs/user-guide/elements/、samples/gstreamer/python/hello_dlstreamer/）。完整克隆仓库时，仓库根目录位于此技能文件上方三级目录；如果只复制了技能文件，则仓库根目录指向 https://github.com/open-edge-platform/dlstreamer。

适用场景

• 用户用自然语言描述视觉 AI 流水线
• 用户想要创建基于 DL Streamer 的新 Python 示例应用
• 用户想要创建基于 DL Streamer 的新 C 或 C++ 示例应用
• 用户想要使用 DL Streamer 元素创建新的 GStreamer 命令行
• 用户想要组合多个现有示例中的元素（例如，检测 + VLM + 录制）
• 用户需要在 Python 或 C++ 中添加自定义分析逻辑或自定义 GStreamer 元素

请参阅示例提示词获取灵感。

新示例应用的目录布局

<new_sample_app_name>
├── <app_name>.py or .sh        # Main application (Python or shell script)
├── export_models.py or .sh     # Model download and export script
├── requirements.txt            # Python dependencies for the application
├── export_requirements.txt     # Python dependencies for model export scripts
├── README.md                   # Setup and usage instructions
├── plugins/                    # Only if custom GStreamer elements are needed
│   ├── python/
│   │   └── <element>.py
│   └── c/
│       └── <element>.c
├── config/                     # Only if config files are needed
│   └── *.txt / *.json
├── models/                     # Created at runtime (cached model exports)
├── videos/                     # Created at runtime (cached video downloads)
└── results/                    # Created at runtime (output files)

流程

执行概览

完成步骤 0（需求收集）后，通过异步终端并行启动所有相互独立的长时间运行任务，然后在它们运行期间继续进行需要深入推理的工作。 如果不确定执行顺序，务必先等待某个步骤列出的前置条件完成，再开始该步骤——下方的依赖关系图是唯一的事实来源。

Step 0 (gather requirements — interactive)
  │
  ├──► Step 1  (Docker pull — async) ───────────────────────────────────────┐
  ├──► Step 2a (export scripts + uv pip install — async) ──► Step 2c (export)──┤
  ├──► Step 2b (video download — async) ────────────────────────────────────┤───► Step 5 (run & validate)
  └──► Step 3  (design pipeline — reasoning) ──► Step 4 (generate app) ─────┘

并行执行规则：

• 步骤 1、2a、2b 和 3 完全独立——步骤 0 完成后立即全部启动
• 步骤 2c（模型导出）依赖步骤 2a（uv pip install）完成
• 步骤 4（生成应用）依赖步骤 3（流水线设计）完成
• 步骤 5（运行并验证）依赖步骤 1、2c 和 4 全部完成

自主执行的安全规则：

• 运行任何用于安装软件包、下载外部内容或修改/删除文件的命令前，先展示完整命令，并在聊天中请求用户明确确认。
• 切勿将未经处理的用户输入插入 Shell 命令。请使用经过验证的允许列表和固定参数模板。
• 除非用户明确批准扩大操作范围，否则文件操作仅限于示例应用目录。

参考资料查找

每份参考文档仅用于一个主要步骤，以避免重复读取：

参考资料	主要步骤	用途
需求调查问卷	步骤 0	用户提示不完整时要提出的详细问题
模型准备	步骤 2	准备 OpenVINO IR 格式的 AI 模型
流水线构建	步骤 3	元素选择、流水线规则和常见模式
示例索引	步骤 3	生成代码前要研究的现有示例
设计模式	步骤 3	Python 应用结构、模式和编码规范
调试提示	步骤 5	Docker 测试、常见注意事项和验证清单

---

快速路径（模式表匹配）

在继续完整流程之前，检查用户的提示词是否直接对应 常见流水线模式表中的某一行。 如果找到匹配项：

1. 根据匹配行预填步骤 0 的字段
2. 如果有任何必填字段缺失，或是根据匹配行推断得出，请向用户展示预填值以供确认（除非信息仍有缺失，否则跳过完整的 需求问卷）
3. 如果用户明确提供了所有必填字段（而非推断得出），则跳过需求字段确认，但在步骤 1–2 中运行任何命令之前，仍须请求用户明确批准
4. 用户确认（或修改）后，只阅读确认选择所需的设计模式、参考章节和模型准备章节
5. 继续步骤 1–5

步骤 0 — 收集需求

从用户的提示词中提取以下信息：

必填信息	查找内容	缺失时的默认值
视频输入	文件路径、HTTP URL（用于下载）或 RTSP URI	—（必须询问）
AI 模型	模型名称／URL 和任务（检测、分类、VLM、OCR，…）	—（必须询问）
目标硬件	Intel 平台、可用加速器（GPU／NPU／CPU）	Not sure / detect at runtime
输出格式	带标注的视频、JSON、JPEG 快照、显示窗口	All of the above
应用类型	Python 应用、C/C++ 应用或 GStreamer 命令行	当提示词提及要转换的现有应用时，通过检查源应用的文件扩展名来确定应用类型。应用类型必须与输入应用的编程语言相符（C/C++ → C/C++，Python → Python，shell → GStreamer 命令行）
Docker 镜像	DL Streamer Docker 标签	intel/dlstreamer:latest（此标签视为最新的 Ubuntu 24 镜像）

应用类型覆盖规则： 如果用户的提示词中包含

“bash script”、“shell script”、“gst-launch”或“command line”等明确表述，请将应用类型 设为 GStreamer command line，无论默认值为何。只有在提示词未表明偏好，且没有要转换的源应用时，才默认设为 Python application。

如果用户的提示词明确提供了所有必填信息（明确写出视频输入和模型名称， 而非推断得出），则直接继续步骤 1。

如果有任何必填信息缺失，或是通过快速路径推断得出（用户未明确说明）， 则必须展示预填值，并在继续之前请用户确认或修改。如果有交互式提问工具可用 （例如 VS Code Copilot 中的 vscode_askQuestions），请使用该工具； 否则就在聊天中直接列出这些值。不要默默采用默认值并跳过确认。

如果用户要求使用 NPU，但所选模型或元素不支持 NPU 推理，请告知用户，并建议改用 GPU 或 CPU。

步骤 1 — 拉取 Docker 镜像（异步）

步骤 0 完成后，立即在异步终端中启动 Docker 镜像拉取。

始终拉取最新可用镜像 不要在未先拉取镜像的情况下重复使用本地缓存的镜像。

docker pull intel/dlstreamer:latest

如果 docker pull 失败（例如镜像不存在或网络错误），请告知用户，并建议检查 Docker 登录状态和网络连接后重试。

步骤 2 — 准备模型和视频

2a — 创建导出脚本并启动 venv 和 uv pip install

检查 DL Streamer 随附的模型导出器中是否包含所需模型（或类似模型）。

模型导出器	常见模型	路径
download_other_models.py	Hugging Face 和 Ultralytics 之外的精选辅助模型	scripts/download_models/download_other_models.py
download_hf_models.py	HuggingFace 模型，包括 VLM 模型和基于 Transformer 的检测／分类模型（RTDETR、CLIP、ViT）	scripts/download_models/download_hf_models.py
download_ultralytics_models.py	专用于 Ultralytics YOLO 模型的下载器	scripts/download_models/download_ultralytics_models.py
download_timm_models.py	托管在 Hugging Face 上的 TIMM 图像分类模型	scripts/download_models/download_timm_models.py

如果找到模型，提取其下载配置，并在应用目录中创建本地 export_models.py。 如果未列出该模型，请查看 模型准备参考 中的导出说明，然后使用 模型导出模板 编写新脚本。

如果模型导出脚本需要其他 Python 包（例如 HuggingFace transformers、Ultralytics、optimum-cli 等），请使用 导出依赖模板 创建 export_requirements.txt 文件。在 export_requirements.txt 中添加注释，指出哪个模型导出脚本需要特定的软件包。使用 模型准备参考 → 依赖项 中精确固定的版本。

重要 — 仅使用 CPU 的 PyTorch： export_requirements.txt 的第一行必须是 --extra-index-url https://download.pytorch.org/whl/cpu （放在任何依赖 torch 的软件包（如 ultralytics 或 nncf）之前）。否则，uv 会拉取模型导出不需要的数 GB GPU 库。 完整模板请参阅模型准备参考 → 依赖项。

前置条件 — 已安装 uv： 如果尚未安装 uv，请先安装： curl -LsSf https://astral.sh/uv/install.sh | sh

写好这两个文件后，在异步终端中启动 venv 创建和 uv pip install：

# Run in async mode — do NOT wait for completion
uv venv .<app_name>-export-venv && \
source .<app_name>-export-venv/bin/activate && \
uv pip install -r export_requirements.txt

2b — 将视频下载到本地目录

如果用户提供了视频输入的 HTTP URL，请立即下载：

mkdir -p videos && curl -L -o videos/<video_name>.mp4 \
    -H "Referer: https://www.pexels.com/" \
    -H "User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36" \
    "<DIRECT_VIDEO_URL>"

应用本身不应下载视频——它只接受指向本地文件或 RTSP URI 的 --input。请在 README 中说明下载步骤。

Pexels 页面 URL → 直接文件 URL： Pexels 页面 URL （https://www.pexels.com/video/<slug>-<ID>/）不是直接下载链接。 使用 curl -s 抓取页面，并在 HTML 中搜索 videos.pexels.com/video-files/ 链接，以获取实际的 .mp4 URL。 不要猜测分辨率或 FPS——不同视频各不相同。 如果抓取失败，请向用户索要直接 URL。

Git LFS 警告： 来自 edge-ai-resources 的视频可能返回 HTML，而非视频数据。验证方法：file videos/sample.mp4 | grep -q "ISO Media"。 默认测试视频优先使用 Pexels 直接 URL。

在 uv pip install 和 docker pull 于后台运行时，继续执行步骤 3。

2c — 运行模型导出（在 uv pip install 完成后）

运行导出前，请确认步骤 2a 中的异步终端已成功完成。 如果安装失败，请先诊断并重新运行，再继续。

确认后，运行模型导出：

source .<app_name>-export-venv/bin/activate
python3 export_models.py  # or bash export_models.sh

如果模型导出失败，请检查命令输出中的常见原因（不支持的架构、RAM 不足、缺少模型权重），报告错误并提供建议的修复方法，然后重试。

步骤 3 — 设计流水线

设计一个满足用户需求的 DL Streamer 流水线。本步骤涵盖元素选择和应用结构。

3a — 选择元素并组装流水线字符串

使用 流水线构建参考 为每个流水线阶段（源、解码、推理、元数据、接收端）确定所需元素。遵循该参考中的流水线设计规则。

对于常见用例，直接根据用例 → 模板/模式映射表生成文件。

对于复杂情况，请查阅示例索引寻找相关参考实现，然后阅读与用户用例相符的具体示例。

从 DeepStream 转换

转换 DeepStream 应用时，请遵循以下附加规则：

1. 清点源流水线。 首先识别 DeepStream 流水线中的所有元素。
2. 使用 docs/user-guide/dev_guide/converting_deepstream_to_dlstreamer.md 中的转换指南，逐一映射每个元素。
3. 使用常见流水线模式表或示例索引连接 DL Streamer 元素。
4. 不要添加源流水线中不存在的元素。 转换后流水线中的每个元素都必须能追溯到清单。

3b — 选择应用结构

对于 CLI 应用，3a 中的流水线字符串就是交付内容 — 将其封装在 gst-launch-1.0 shell 脚本中。

对于 Python 应用，根据用户的描述，使用模式选择表映射到一个或多个设计模式：

1. 选择流水线构建方法 — 参见模式 1：流水线核心
2. 按需添加回调/探针
3. 如果用户需要内联分析，则添加自定义 Python 元素 — 首先检查现有 GStreamer 元素是否能处理该逻辑。如果不能，请遵循模式 7 下的约定。
4. 配置参数解析
5. 添加流水线事件循环 — 参见模式 2：流水线事件循环

第 4 步 — 生成应用程序

按照本文档开头定义的目录布局生成所有应用程序文件。

按语言生成：

C/C++ 应用程序：使用 应用程序模板 作为起始骨架。阅读设计模式参考，了解编码规范和应用程序结构。

• Python 应用程序：使用 应用程序模板 作为起始骨架。阅读设计模式参考，了解编码规范和应用程序结构。

适用于所有语言：

• 使用 README 模板 生成 README.md，并按照下方说明替换所有 {{PLACEHOLDERS}}：

  占位符	生成内容
  {{APP_TITLE}}	应用程序的简短标题
  {{APP_DESCRIPTION}}	用 2–3 句话说明应用程序的功能及其主要用例
  {{DLSTREAMER_CODING_AGENT_PROMPT}}	用 Markdown 引用块（> ）包裹的初始用户提示词原文。不要改述或概括。
  {{APP_VISUALIZATION}}	可选的屏幕截图行：。如果没有可用的屏幕截图，则完全省略此行。
  {{DETAILED_DESCRIPTION}}	扩展说明：模型名称、硬件要求、预期输出。如果输入视频来自公开来源（例如 Pexels），则添加：This sample uses a video from <link> by <author>.
  {{NUMBERED_STEPS}}	流水线阶段的编号列表，例如 1. **Detects** objects using gvadetect
  {{PIPELINE_DIAGRAM}}	Mermaid 图表。线性流水线使用 graph LR；对于 tee／多分支，使用子图（示例见 smart_nvr 和 vlm_self_checkout）。
  {{PIPELINE_ELEMENTS_LIST}}	可选的 GStreamer／DL Streamer 元素及其作用的项目符号列表。如果流水线很简单，则省略。
  {{VIDEO_DOWNLOAD_INSTRUCTIONS}}	将测试视频下载到 videos/ 的 curl 命令。如果未使用公开视频，则省略外层的 ### Download Video 标题和此占位符。
  {{ADVANCED_USAGE}}	可选的第二个用法代码块，展示非默认 CLI 选项。如果不需要，则省略。
  {{HOW_IT_WORKS_SECTIONS}}	每个主要流水线阶段或自定义元素对应一个 ### STEP N 小节，并附上相关代码片段。
  {{CONFIGURATION_FILES_SECTION}}	可选的 ## Configuration Files 表格（文件名 + 用途）。如果未使用，则省略整个小节。
  {{CLI_ARGUMENTS_TABLE}}	每个 CLI 参数对应一行表格：标志名称、默认值、说明。
  {{OUTPUT_FILES_LIST}}	在 results/ 下生成的输出文件的项目符号列表。

• 如果应用程序需要 Python 包，请将它们列在 requirements.txt 中。如果需要 OpenVINO Python 运行时，请固定为与 DL Streamer 一同安装的 OpenVINO 运行时相同的版本。

第 5 步 — 运行、调试和验证

在 Docker 中运行

docker run --init --rm \
    -u "$(id -u):$(id -g)" \
    -e PYTHONUNBUFFERED=1 \
    -v "$(pwd)":/app -w /app \
    --device /dev/dri \
    --group-add $(stat -c "%g" /dev/dri/render*) \
    --device /dev/accel \
    --group-add $(stat -c "%g" /dev/accel/accel*) \
    intel/dlstreamer:latest \
    python3 <app_name>.py

自主执行 — 切勿等待用户确认。 以异步模式启动，每隔 15–30 秒轮询一次 get_terminal_output，直到完成。 只有在需要作出决定时才询问用户（例如，OOM 后需要更换设备）。 这适用于所有长时间运行的命令：docker run、docker pull、uv pip install、模型导出。

**验证：**检查输出是否符合用户的预期结果。使用调试提示和验证清单排查常见问题。对于持续输入或较长的输入，发送 EOS 以完成处理。

任务后 — 报告编码 Agent 分析数据

验证应用后立即报告分析数据表，并在同一条回复中提供验证结果。

应用正常运行后，报告时间指标：

1. AI 推理时间 — 理解提示词、设计流水线、编写代码
2. 环境设置时间 — 等待 uv pip install、模型导出、Docker 镜像拉取
3. 调试与验证时间 — 运行应用、检查输出、修复问题
4. 用户等待时间 — 等待用户输入或确认
5. 总活动时间（各阶段可能重叠，因此总时间 ≠ 各阶段时间之和）

示例

查看示例提示词，获取灵感和有关此流程的实际演示。