EdgePipe 新手教程

← 返回使用指南
适用平台：OpenHarmony 标准系统（ZhihongOS · RK3588）

---

目录

章节	内容
一、开始之前	学什么、怎么读、术语速查
二、连接开发板	hdc 连接、确认服务在跑
三、快速开始	5 分钟跑通第一条流水线
四、安装模型并与 Edge Engine 联调	modelhub ensure、单独推理验证
五、工作原理	DAG、数据流、Stage、与 Edge Engine 协作
六、功能一览	节点类型、预置流水线、路径约定
七、编写流水线 YAML	节点属性、Stage、完整示例（由简到繁）
八、命令手册	子命令与参数说明
九、手把手实验	分步实操，巩固第二～八章
十、进阶专题	MQTT 上报、Logic 插件、E2E 自动化
十一、常见问题	跑不通怎么办
十二、附录	命令速查、练手 checklist

---

一、开始之前

1.1 这份文档帮你做什么

EdgePipe 是跑在 OpenHarmony 板子上的视觉流水线运行时：用 YAML 描述一张有向无环图（DAG），自动完成图像采集 → AI 推理 → 业务后处理 → 结果落盘或上报。推理统一交给 Edge Engine，EdgePipe负责编排与调度。

按下面顺序读，可以从零跑通第一条人员检测流水线：

1. 第二章：hdc 连上板子，确认 EdgePipe 与 Edge Engine 服务在运行
2. 第三章：安装模型、校验并运行预置 YAML，约 5 分钟看到标注图
3. 第四章：理解模型如何从 EdgeHub 安装、如何单独验证推理
4. 第五章：理解 DAG、FramePacket、Stage 后处理链——读懂前几章在干什么
5. 第七章：学会自己写 YAML，从 4 节点最简流水线逐步扩展到区域告警
6. 第八章：需要查某个子命令或参数时当字典用
7. 第九章：动手做 7 组实验，巩固全部功能

第三章跑通后，就可以边做边回头看第五、七章；不必一次读完。

1.2 你需要准备

项目	说明
开发板	RK3588 开发板，已烧录 ZhihongOS
宿主机	已安装 hdc，能 hdc shell 进板子
网络（可选）	从 EdgeHub 在线装模型时需要访问 zhihongos.cn
前置知识	建议先完成 Edge Engine 新手教程 第三章（首次推理）
基础命令	会复制粘贴 Shell；JSON 输出看得懂字段名更好

1.3 CLI 用法

官方命令是 edgepipe；模型安装与单独推理用 edgeengine：

edgepipe --version
edgepipe schema pipeline.run
edgeengine --format json modelhub ensure global/people_count_yolov10 --version v1.1

环境	标识	说明
宿主机	【宿主机】	hdc shell 等
板端	【板端】	先 hdc shell，再执行 edgepipe / edgeengine

脚本解析 JSON 时推荐加 --format json。

1.4 术语速查

术语	含义
流水线 / Pipeline	由 YAML 定义的视觉处理 DAG
节点 / Node	DAG 中的一个处理单元（Streamer、Algorithm、Logic、Sink 等）
Stage	Logic 节点内的后处理步骤（过滤、跟踪、区域检测等）
FramePacket	节点间传递的数据包（图像 + 检测结果 + metadata）
model_name	ModelHub 模型标识，如 global/people_count_yolov10

| dry-run | 只校验不执行；成功时退出码为 10（正常，非错误） |

---

二、连接开发板

ZhihongOS 开机后 edge_pipe_service与 edge_engine_service随系统自动启动，一般无需手动 service_control start。本章确认你能连上板子、两个服务在线，再进入第三章跑第一条流水线。

2.1 硬件要求

项目	说明
开发板	RK3588 开发板（含 NPU）
系统	ZhihongOS 6.1.0
CLI	edgepipe v0.1.0

2.2 连接开发板

# 【宿主机】列出已连接设备
hdc list targets

# 进入板端 shell
hdc shell

连接成功后，提示符类似 #。后续标注 【板端】 的命令均在此 shell 中执行。

2.3 确认服务已运行

# 【板端】EdgePipe 状态（推荐）
edgepipe --format json service status

# Edge Engine 状态（推理依赖）
edgeengine --format json service status

命令	期望
edgepipe service status	"ok": true, "running": false
edgeengine service status	"available": true

仅在第十一章遇到异常时，才考虑 service_control restart edge_pipe_service 或 edge_engine_service。

2.4 第一步验证

edgepipe --version
edgepipe --format json service status
edgepipe schema pipeline.run

命令	期望
--version	0.1.0 (schema 1)
service status	"ok": true

注意：裸跑 edgepipe schema（不带子路径）可能崩溃，请始终使用 edgepipe schema pipeline.run 等子路径。

---

三、快速开始

目标：5 分钟内完成「确认服务 → 安装模型 → 校验 YAML → 运行流水线 → 看到标注图」。

3.1 一键流程

# 【板端】

# 步骤 1：确认服务可用
edgepipe --format json service status
edgeengine --format json service status

# 步骤 2：确认 CLI 版本
edgepipe --version

# 步骤 3：确保模型已安装（不存在则自动从 EdgeHub 下载）
edgeengine --format json modelhub ensure global/people_count_yolov10 --version v1.1

# 步骤 4：校验预置流水线（不执行推理）
edgepipe --format json pipeline validate \
  /system/etc/edge_pipe/pipelines/person_detect_yolov10_cloud.yaml

# 步骤 5：干跑预览（可选，成功退出码为 10）
edgepipe --format json pipeline run \
  /system/etc/edge_pipe/pipelines/person_detect_yolov10_cloud.yaml --dry-run

# 步骤 6：正式运行
edgepipe --format json pipeline run \
  /system/etc/edge_pipe/pipelines/person_detect_yolov10_cloud.yaml

# 步骤 7：查看输出标注图
ls -la /data/service/el1/public/edge_pipe/output/yolov10_cloud/

3.2 期望结果摘要

步骤	关键字段	期望值
service status	ok	true
modelhub ensure	message	installed 或 already_installed
pipeline validate	valid	true
pipeline run --dry-run	退出码	10（正常，非错误）
pipeline run	running	true
输出目录	文件	含标注 JPG

3.3 这条流水线在做什么？

节点链：cam0 → detect → logic → image_out

节点	类型	作用
cam0	edge.image_streamer	读取 bus.jpg
detect	edge.detection	YOLOv10 + RKNN 推理
logic	edge.logic	过滤 person + NMS + 画框
image_out	edge.sink.image_file	保存标注图到 output

3.4 快速开始常见问题

现象	快速处理
edgepipe service status 退出码 3	按 2.3 节确认；仍异常见第十一章
valid: false	检查 YAML 路径；见 8.4 节
dry-run 退出码 10	正常，不是错误
无输出图像	确认步骤 6 成功；检查 output 目录权限
推理失败	先按第四章单独测 edgeengine model infer

---

四、安装模型并与 Edge Engine 联调

EdgePipe 的推理节点通过 Edge Engine 完成 AI 计算。跑流水线前，建议先在本章确认模型已安装且单独推理可用——这样出问题时能快速区分是 Edge Engine 还是 EdgePipe 的问题。

4.1 安装模型

# 从 EdgeHub 下载并安装（与 Edge Engine 教程相同）
edgeengine --format json modelhub ensure global/people_count_yolov10 --version v1.1

# 查看已安装模型
edgeengine --format json modelhub list

4.2 单独验证推理（绕过 EdgePipe）

edgeengine --format json model infer global/people_count_yolov10 --engine rknn \
  --input /system/etc/edge_pipe/fixtures/images/bus.jpg

期望：detection_count > 0，含 person、bus 等类别。

4.3 预览 model_name 解析路径

YAML 中使用 model_name: global/people_count_yolov10 时，Edge Engine 会解析为实际 .rknn 文件：

edgeengine --format json model resolve global/people_count_yolov10 --engine rknn

记录返回的 model_path，便于排障时对照。

4.4 鉴权与网络（可选）

从 EdgeHub 在线安装需要网络可达及有效 Token，配置方式与 Edge Engine 教程 2.5 节相同：

param get persist.ai_engine.edgehub.url
param set persist.ai_engine.edgehub.token "your-token-here"

---

五、工作原理

读完第二～四章动手操作后，本章说明 EdgePipe 各组件如何协作。需要查 YAML 节点属性时，直接看第七章。

5.1 整体架构

EdgePipe 分三层：

层级	组件	职责
客户端	edgepipe CLI、业务 SDK	校验、运行、停止流水线
服务	edge_pipe_service	托管流水线生命周期、多线程调度
运行时	Streamer / Algorithm / Logic / Sink / Report	按 DAG 处理每一帧

推理不发生在 EdgePipe 内部：AlgorithmNode 经 Binder IPC 调用 Edge Engine。

5.2 一次流水线怎么走

1. 编译：校验节点类型、拓扑、Stage 顺序，实例化 C++ 节点并建立队列
2. 运行：Streamer 推帧 → Algorithm 推理 → Logic 过滤/标注 → Sink/Report 输出
3. 返回：CLI 获得 running: true 等状态 JSON

5.3 流水线 = DAG

YAML 中 nodes 是节点，links 是有向边。编译器检查：无环、Source 无入边、Sink/Report 无出边、Logic 至少有 1 个上游。

5.4 FramePacket 数据流

节点间通过 FramePacket 传递数据：

字段	写入者	内容
frame	Streamer	BGR 图像
meta	Streamer	帧序号、时间戳
detections	Algorithm	检测框
metadata	Logic	告警、计数等业务键值
perf	Algorithm	推理耗时

5.5 Stage 后处理链

edge.logic 内 stages 按数组顺序执行，再经 annotators 在图像上绘制标注：

confidence_filter → class_filter → nms → byte_track → polygon_zone

推荐顺序与每个 Stage 的属性详见 7.4 节。

5.6 队列与背压

config.runtime 控制节点间队列行为：

参数	说明	场景
blocking_mode: false	队列满时丢旧帧	实时视频
blocking_mode: true	队列满时阻塞上游	不能丢帧
queue_capacity	每条边最大帧数	默认 8

5.7 与其他服务的关系

服务	关系
edge_engine	核心依赖，所有推理经 Edge Engine
EdgeHub	经 edgeengine modelhub ensure 下载模型
edgecomputer	检测结果可经 MQTT 上报到 JetLinks
edgeclaw / edgemcp	无直接集成，可分别调用

---

六、功能一览

模块	CLI / 入口	作用
Pipeline	edgepipe pipeline	校验、运行、导出 DAG
Service	edgepipe service	查询/停止当前流水线
Schema	edgepipe schema	命令参数自省
推理（依赖）	edgeengine model	模型安装与单独推理

6.1 节点类型速览

YAML type	角色	说明
edge.image_streamer / edge.video_streamer	数据源	读图/视频，DAG 起点
edge.detection / edge.classification	推理	调用 Edge Engine
edge.logic	后处理	Stage 链 + 标注器
edge.logic.condition 等	专用 Logic	告警、统计、ROI
edge.fanout	路由	一分多扇出
edge.sink.*	同步终端	落盘、stdout
edge.report.*	异步终端	HTTP/MQTT 上报

各节点完整属性见 第七章。

6.2 预置流水线

路径：/system/etc/edge_pipe/pipelines/

文件	说明	推荐
person_detect_yolov10_cloud.yaml	YOLOv10 行人检测	主推
person_detect_yolov8_video.yaml	YOLOv8 视频示例	需单独装 v8 模型
video_verify/T4_multi_async.yaml	多路异步验证	进阶

测试图片：/system/etc/edge_pipe/fixtures/images/bus.jpg

6.3 板端路径约定

用途	路径
运行数据根	/data/service/el1/public/edge_pipe
图像输出	.../output/
上报文件	.../report/
预置 YAML	/system/etc/edge_pipe/pipelines/
模型仓库	/data/edge_engine/models/
内联 YAML 临时目录	.../data/tmp

---

七、编写流水线 YAML

读完第三～五章动手操作后，本章教你自己写 YAML。建议按 7.1 → 7.8 顺序阅读，示例由简到繁。需要查节点属性时当字典用。

7.1 文档顶层结构

version: "1.0"          # 文档版本（可选，建议填写）

metadata:               # 人类可读信息，不参与运行时
  name: my_pipeline
  description: 示例流水线

config:                 # 全局配置
  runtime:
    blocking_mode: false
    queue_capacity: 8
    log_level: info
  paths:
    output_dir: /data/service/el1/public/edge_pipe/output
    # cmask: /system/etc/edge_pipe/shared.cmask.yaml  # 共享配置，供 @cmask.xxx 引用

polygon:                # 可选，供 @polygon.xxx 引用
  work_area:
    - [100, 80]
    - [500, 80]
    - [500, 400]
    - [100, 400]

nodes:                  # 节点列表（必填）
  - name: cam0
    type: edge.image_streamer
    params: { ... }

links:                  # 连线（必填）
  - "cam0 > detect > sink"

顶层字段	必填	含义
version	否	流水线文档版本，用于未来兼容性
metadata	否	名称与描述，仅作标注
config.runtime	否	全局队列与日志策略
config.paths	否	共享路径与 cmask 配置
polygon	否	文档级多边形定义
nodes	是	DAG 节点数组
links	是	节点间有向边

预置 YAML 使用 name 作为节点标识，params 作为配置块。编译器同时支持 id / config 写法，新流水线建议统一为 name + params。

---

7.2 数据源节点（Streamer）

数据源是 DAG 的起点，无入边，主动读取图像或视频帧并推入下游。

edge.image_streamer — 图片流

属性	类型	默认值	含义
source	string	—	图片路径。支持单文件、目录、通配符（*.jpg）
process_frame_interval	int	0	跳帧间隔。0 = 每帧都处理；2 = 每 3 帧处理 1 帧
loop	bool	false	读完是否从头循环
loop_num	int	0	循环次数上限。0 = 无限循环（配合 loop: true）
motion_detect	bool	false	是否启用运动检测，仅在有变化时推帧
motion_threshold	int	—	运动检测像素差阈值
motion_min_changed_pixels	int	—	触发运动的最小变化像素数
motion_min_changed_ratio	float	—	触发运动的最小变化比例
motion_downscale_width	int	—	运动检测时下采样宽度（加速）

source 路径解析规则：

• 绝对路径：直接使用
• 相对路径：优先在预置 fixtures 目录查找，如 fixtures/images/bus.jpg 对应 /system/etc/edge_pipe/fixtures/images/bus.jpg

- name: cam0
  type: edge.image_streamer
  params:
    source: fixtures/images/bus.jpg
    process_frame_interval: 0
    loop: true
    loop_num: 1000

edge.video_streamer — 视频流

属性	类型	默认值	含义
source	string	—	视频文件路径（mp4、avi 等）
process_frame_interval	int	0	跳帧间隔
loop	bool	false	播完后是否循环

- name: cam0
  type: edge.video_streamer
  params:
    source: /data/test/demo.mp4
    loop: false
    process_frame_interval: 1    # 每隔 1 帧处理一次，降低负载

---

7.3 推理节点（Algorithm）

推理节点从上游接收 FramePacket，调用 Edge Engine 完成 AI 推理，将结果写入 detections 或 classifications。

三种 type 等价关系：

type	默认任务	说明
edge.algorithm	通用	基类，需配合 algorithm_id
edge.detection	目标检测	常用，默认 algorithm_id 为 yolov8
edge.classification	图像分类	常用，默认 algorithm_id 为 mobilenet

核心属性

属性	类型	必填	含义
algorithm_id	string	是	算法族标识，决定推理插件路由
model_name	string	二选一	平台模式：ModelHub 标识，如 global/people_count_yolov10
model_version	string	否	固定版本，如 v1.1；省略时取 EdgeHub 最新版
model_path	string	二选一	路径模式：直接指定 .rknn / .onnx 文件
engine	string	否	推理后端：rknn / onnx / auto
mode	string	否	primary（整图推理）或 secondary（对上游检测框裁剪后分类）
num_threads	int	否	推理线程数，RK3588 上常用 4–6
infer_batch	bool	否	是否启用批推理

model_name 与 model_path 互斥，不可同时出现。

推理阈值（meta_override）

属性	含义
meta_override.confidence_threshold	模型输出置信度阈值，低于此值的框在推理阶段即被过滤
meta_override.nms_threshold	非极大值抑制 IoU 阈值
meta_override.class_names	覆盖类别名列表（逗号分隔）

Secondary 模式（两阶段检测 + 分类）

属性	含义
max_secondary_boxes	每帧最多处理的检测框数量
secondary_class_names	仅对指定类别框做裁剪推理，如 person
crop.mode	裁剪模式
crop.expand_ratio	裁剪框外扩比例，避免裁切过紧
crop.clip_to_frame	是否将裁剪区域限制在图像边界内
result_attach.field_status	分类结果 status 字段写入 detection.data 的键名
result_attach.field_score	分类分数写入 detection.data 的键名
ok_labels / ng_labels	二分类 OK/NG 标签名

支持的 algorithm_id

ID	任务
yolov3, yolov5, yolov7, yolov8, yolov10, yolov11	目标检测
cnn, mobilenet, mobilenetv2, resnet, vgg	图像分类

model_name 模式示例（推荐生产环境）

- name: detect
  type: edge.detection
  params:
    algorithm_id: yolov10
    model_name: global/people_count_yolov10
    model_version: v1.1
    engine: rknn
    mode: primary
    num_threads: 6
    meta_override.confidence_threshold: 0.45
    meta_override.nms_threshold: 0.45

运行前需执行：edgeengine modelhub ensure global/people_count_yolov10 --version v1.1

model_path 模式示例（本地调试）

- name: detect
  type: edge.detection
  params:
    algorithm_id: yolov10
    model_path: /data/edge_engine/models/global/people_count_yolov10/v1.1/rk3588/yolov10n_fp16.rknn
    engine: rknn

---

7.4 Logic 节点与 Stage 后处理链

edge.logic 是业务后处理的核心节点。它包含两部分：

1. stages：按顺序执行的检测框过滤、跟踪、区域分析等
2. annotators：在图像上绘制可视化标注

- name: logic
  type: edge.logic
  params:
    class_names: person,car,bus       # 可选，全局类别名提示
    stages:
      - type: confidence_filter
        threshold: 0.45
      - type: class_filter
        class_names: person
      - type: nms
        iou_threshold: 0.45
    annotators:
      - type: label
        thickness: 2
        color_lookup: class

Stage 一览

stage type	功能	关键属性	属性含义
coordinate_restore	坐标还原	—	将检测框坐标还原到原始分辨率（上游有缩放时使用）
confidence_filter	置信度过滤	threshold (float)	丢弃置信度低于阈值的检测框
class_filter	类别过滤	class_names (string)	逗号分隔的类别名白名单，仅保留匹配的框
		class_ids (string)	逗号分隔的类别 ID 白名单，与 class_names 二选一
area_filter	面积过滤	min_area (float)	框面积下限（像素²）
		max_area (float)	框面积上限
nms	非极大值抑制	iou_threshold (float)	IoU 超过此值的重叠框被抑制，默认 0.45
		class_agnostic (bool)	true = 跨类别 NMS；false = 按类别分别 NMS
max_detections	数量限制	max (int)	每帧最多保留的检测框数，默认 128
softmax	Softmax 归一化	—	对分类分数做 softmax（分类任务）
top_k	Top-K 筛选	k (int)	仅保留分数最高的 K 个结果
byte_track	多目标跟踪	—	为每个检测框分配 tracker_id，后续 line_zone 依赖此 stage
polygon_zone	多边形区域	polygon (string)	顶点坐标 x1,y1;x2,y2;...，或用 @polygon.work_area 引用
line_zone	越线计数	start (string)	线段起点 x,y
		end (string)	线段终点 x,y
		—	必须在 byte_track 之后，输出 line_in_count / line_out_count 到 metadata
detection_smoother	检测平滑	length (int)	滑动窗口长度，减少框抖动
output_encode	输出编码	—	将结果编码为统一输出格式

Stage 顺序约束

编译器会校验部分 Stage 的先后顺序：

• line_zone 之前必须有 byte_track（需要 tracker_id）
• polygon_zone 通常放在过滤类 Stage（confidence_filter、class_filter、nms）之后

推荐典型顺序：

confidence_filter → class_filter → nms → byte_track → polygon_zone / line_zone

Stage 详细示例

置信度 + 类别 + NMS 过滤（最常用）：

stages:
  - type: confidence_filter
    threshold: 0.5
  - type: class_filter
    class_names: person
  - type: nms
    iou_threshold: 0.45
    class_agnostic: false

区域入侵检测：

polygon:
  danger_zone:
    - [200, 150]
    - [600, 150]
    - [600, 450]
    - [200, 450]

# 在 logic 节点中：
stages:
  - type: confidence_filter
    threshold: 0.4
  - type: byte_track
  - type: polygon_zone
    polygon: "@polygon.danger_zone"

polygon_zone 会将区域内目标数写入 metadata.zone_count，可用于后续告警。

越线计数：

stages:
  - type: confidence_filter
    threshold: 0.4
  - type: byte_track          # 必须先跟踪
  - type: line_zone
    start: "100,300"
    end: "700,300"

输出 metadata.line_in_count（进入计数）与 metadata.line_out_count（离开计数）。

Annotators（可视化标注器）

Annotators 在 stages 处理完成后执行，修改 frame 图像用于展示或落盘。

type	功能	关键属性	属性含义
box_v2	绘制检测框	thickness (int)	边框线宽（像素）
		color_lookup (string)	颜色策略：class = 按类别着色
label	绘制类别标签	thickness (int)	文字背景框线宽
		color_lookup (string)	颜色策略
trace	绘制跟踪轨迹	—	显示 byte_track 产生的运动轨迹
polygon_zone_annotator	绘制多边形区域	zone_ref (string)	引用 stage 中注册的区域名
line_zone_annotator	绘制计数线	zone_ref (string)	引用 line_zone 区域

annotators:
  - type: box_v2
    thickness: 2
    color_lookup: class
  - type: label
    thickness: 2
    color_lookup: class
  - type: trace
  - type: polygon_zone_annotator
    zone_ref: danger_zone

---

7.5 专用 Logic 节点

除通用 edge.logic 外，系统提供几种语义化的专用 Logic 节点，适合特定业务场景。

edge.logic.condition — 条件告警

当检测条件满足时，在 metadata 中设置告警标志。

属性	含义
min_count	检测框数量下限
max_count	检测框数量上限
min_confidence	最低置信度要求
required_class_names	必须出现的类别（逗号分隔）
alert_metadata_key	告警键名，默认 alert
set_alert_on_match	匹配时是否设置 metadata[alert_metadata_key]=true

- name: alert_logic
  type: edge.logic.condition
  params:
    required_class_names: person
    min_count: 1
    min_confidence: 0.6
    alert_metadata_key: alert
    set_alert_on_match: true

输出：metadata.condition_match、metadata.condition_count，匹配时 metadata.alert=true。

edge.logic.statistics — 统计聚合

属性	含义
output_key	统计 JSON 写入 metadata 的键名，默认 statistics
count_by_class	是否按类别计数
count_by_tracker	是否按 tracker_id 计数

edge.logic.aggregate — NG/OK 汇总

适用于质检场景：汇总 secondary 分类的 OK/NG 结果。

属性	含义
source_field	汇总字段名，默认 status
ok_value / ng_value	OK 与 NG 的枚举值
output_summary_key	摘要 JSON 键名
alert_on_ng	出现 NG 时设置 alert
include_boxes	摘要是否包含框信息
dedupe_by	去重字段，如 tracker_id
alert_cooldown_sec	告警冷却时间（秒），避免重复告警

edge.logic.roi — ROI 区域过滤

属性	含义
mode	inside（保留区域内）或 outside（保留区域外）
polygon	ROI 多边形顶点

就地过滤 detections，输出 metadata.zone_count、metadata.roi_mode。

edge.logic.plugin — 动态插件

属性	含义
plugin_path	逻辑插件 .so 路径

插件须导出 edge_pipe_logic_plugin_entry()，参考 extension/ai/edge_pipe/plugins/sample_alert_plugin.cpp。

---

7.6 路由节点（Fanout）

edge.fanout 将同一帧透传到多个下游，实现一分多。编译器要求出度 ≥ 2。

- name: split
  type: edge.fanout

links:
  - "logic > split"
  - from: split
    to: [image_out, json_out, mqtt_out]

---

7.7 Sink 节点（同步终端）

Sink 是 DAG 的终点，接收帧后同步落盘或输出，不再向下游传递。

type	功能	关键属性	属性含义
edge.sink.image_file	保存标注图	directory	输出目录
		format	图片格式：jpg、png
		jpeg_quality	JPEG 压缩质量 1–100
		keep_latest_only	true = 只保留最新一帧（覆盖写）
edge.sink.json_file	JSONL 落盘	path / output_path	输出文件路径
		include_frame_image	是否将图像 base64 写入 JSON
edge.sink.video_file	写视频	path	输出视频路径
		fps	帧率
		fourcc	编码四字符码，如 mp4v
edge.sink.stdout	控制台摘要	verbose	是否输出详细信息
edge.sink.null	丢弃	—	性能测试时丢弃输出
edge.sink.callback	回调注册	callback_id	注册的回调 ID

- name: image_out
  type: edge.sink.image_file
  params:
    directory: /data/service/el1/public/edge_pipe/output/demo
    format: jpg
    jpeg_quality: 90
    keep_latest_only: true

---

7.8 Report 节点（异步终端）

Report 与 Sink 的区别：在独立 IO 线程中执行网络/文件上报，不阻塞推理主路径。支持重试退避。

公共属性

属性	含义
report_mode	every_frame（每帧上报）/ on_alert（仅告警帧）/ on_metadata_key（指定键触发）
alert_metadata_key	告警 metadata 键名，默认 alert
include_summary_only	仅序列化摘要字段
summary_keys	逗号分隔的摘要键列表
retry.max_attempts	最大重试次数，默认 3
retry.backoff_ms	重试退避毫秒，默认 500

edge.report.mqtt

属性	含义
broker	MQTT Broker 地址，支持 tcp://host
port	端口（也可用 URL 内端口或环境变量）
topic	发布主题
client_id	客户端 ID
username / password	认证凭据，支持 ${ENV}
qos	0 / 1 / 2
retain	是否保留消息

MQTT 端口优先级：URL 内端口 > YAML port > 环境变量 EDGE_PIPE_MQTT_PORT > 系统参数 persist.edge_pipe.mqtt.port（默认 1883）

edge.report.http

属性	含义
url	POST 目标 URL
method	HTTP 方法，默认 POST
timeout_ms	请求超时
headers.*	自定义请求头

edge.report.file

属性	含义
path	本地文件路径

- name: mqtt_out
  type: edge.report.mqtt
  params:
    broker: zhihongos.cn
    port: 1883
    topic: edge/pipe/alerts
    username: ${MQTT_USER}
    password: ${MQTT_PASS}
    report_mode: on_alert
    alert_metadata_key: alert

---

7.9 完整示例（由简到繁）

以下示例由简到繁，展示如何组合上述节点与 Stage。

示例 A：最简检测 + 落盘（4 节点）

适合第一次编写 YAML：

version: "1.0"
metadata:
  name: minimal_detect
  description: 最简人员检测流水线

nodes:
  - name: cam0
    type: edge.image_streamer
    params:
      source: fixtures/images/bus.jpg
      loop: false

  - name: detect
    type: edge.detection
    params:
      algorithm_id: yolov10
      model_name: global/people_count_yolov10
      engine: rknn

  - name: logic
    type: edge.logic
    params:
      stages:
        - type: confidence_filter
          threshold: 0.4
      annotators:
        - type: label
          thickness: 2
          color_lookup: class

  - name: out
    type: edge.sink.image_file
    params:
      directory: /data/service/el1/public/edge_pipe/output/minimal
      format: jpg

links:
  - "cam0 > detect > logic > out"

编写步骤：

1. 定义 nodes：数据源 → 推理 → 后处理 → 落盘
2. 用 links 串联："cam0 > detect > logic > out"
3. edgepipe pipeline validate my.yaml 校验
4. 确保模型已 modelhub ensure
5. edgepipe pipeline run my.yaml

示例 B：过滤 + NMS + 仅保留 person

在示例 A 的 logic 中扩展 stages：

  - name: logic
    type: edge.logic
    params:
      stages:
        - type: confidence_filter
          threshold: 0.45
        - type: class_filter
          class_names: person
        - type: nms
          iou_threshold: 0.45
      annotators:
        - type: box_v2
          thickness: 2
          color_lookup: class
        - type: label
          thickness: 2
          color_lookup: class

示例 C：区域入侵 + 告警 + 双路输出

version: "1.0"

polygon:
  work_area:
    - [100, 80]
    - [500, 80]
    - [500, 400]
    - [100, 400]

nodes:
  - name: cam0
    type: edge.image_streamer
    params:
      source: fixtures/images/bus.jpg
      loop: true
      loop_num: 100

  - name: detect
    type: edge.detection
    params:
      algorithm_id: yolov10
      model_name: global/people_count_yolov10
      engine: rknn
      meta_override.confidence_threshold: 0.45

  - name: logic
    type: edge.logic
    params:
      stages:
        - type: confidence_filter
          threshold: 0.45
        - type: class_filter
          class_names: person
        - type: byte_track
        - type: polygon_zone
          polygon: "@polygon.work_area"
      annotators:
        - type: box_v2
          thickness: 2
          color_lookup: class
        - type: polygon_zone_annotator
          zone_ref: work_area

  - name: alert
    type: edge.logic.condition
    params:
      required_class_names: person
      min_count: 1
      set_alert_on_match: true

  - name: split
    type: edge.fanout

  - name: image_out
    type: edge.sink.image_file
    params:
      directory: /data/service/el1/public/edge_pipe/output/zone_demo
      format: jpg

  - name: json_out
    type: edge.sink.json_file
    params:
      path: /data/service/el1/public/edge_pipe/report/zone_events.jsonl

links:
  - "cam0 > detect > logic > alert > split"
  - from: split
    to: [image_out, json_out]

示例 D：两阶段检测 + 分类

  - name: detect
    type: edge.detection
    params:
      algorithm_id: yolov8
      model_name: global/people_count_yolov8
      engine: rknn
      mode: primary

  - name: classify
    type: edge.classification
    params:
      algorithm_id: mobilenet
      model_name: global/quality_classifier
      engine: rknn
      mode: secondary
      secondary_class_names: person
      max_secondary_boxes: 8
      crop.expand_ratio: 0.1

links 中需串联：cam0 > detect > classify > logic > ...

---

八、命令手册

需要查某个子命令或参数时，直接看本章。所有子命令支持 --format json，便于脚本集成。

8.1 命令树总览

edgepipe
├── pipeline
│   ├── run <path>           [--content-file] [--dry-run] [--wait]
│   ├── validate <path>      [--content-file]
│   ├── graph <path>         [--content-file]
│   ├── run-local <path>     # 进程内运行，不经服务 IPC
│   ├── validate-local <path>
│   └── graph-local <path>
├── service
│   ├── status
│   └── stop                 [--dry-run]
└── schema [command-path]    # 建议带子路径，如 pipeline.run

# 遗留扁平别名（兼容旧脚本）
edgepipe run / validate / graph / status / stop

8.2 全局选项

选项	简写	说明	使用场景
--version	-V	打印 CLI 版本与 schema 版本	确认工具链版本
--format auto|json|table	—	输出格式	脚本中固定使用 json
--yes / --no-interactive	—	跳过交互确认	自动化脚本、CI
--quiet	—	减少 stderr 日志	减少噪音
--verbose	—	增加 stderr 日志	排障时查看详细日志
--help	-h	打印帮助	查看子命令用法

环境变量：

变量	作用
EDGE_PIPE_FORMAT	默认输出格式（等价于 --format）
EDGE_PIPE_NO_TUI	禁用 TUI 交互
NO_COLOR	禁用彩色输出

优先级：CLI 参数 > 环境变量 > 默认值。

8.3 退出码

码	名称	含义	脚本处理建议
0	Ok	成功	正常继续
1	General	一般错误（校验失败、IPC 错误、推理失败等）	读取 JSON message 排障
2	Usage	命令用法错误（参数缺失、路径无效等）	检查命令拼写与 --help
3	NotFound	服务不可用	检查服务是否运行，service_control restart
5	Conflict	已有流水线在运行	先 service stop 或等待当前流水线结束
10	DryRunOk	dry-run 成功	正常，非错误；脚本中应视为成功

脚本中处理 dry-run 的推荐写法：

edgepipe --format json pipeline run foo.yaml --dry-run
code=$?
if [ $code -eq 0 ] || [ $code -eq 10 ]; then
  echo "校验通过"
else
  echo "失败，退出码: $code"
  exit $code
fi

---

8.4 pipeline validate

用途：校验 YAML 语法、节点类型、拓扑连通性、Stage 顺序约束。不执行推理，不检查模型是否已安装。

edgepipe --format json pipeline validate <yaml路径>
edgepipe --format json pipeline validate my.yaml --content-file /path/to/inline.yaml

参数	必填	说明
path	是	YAML 文件路径。相对路径优先在 /system/etc/edge_pipe/pipelines/ 查找
--content-file	否	从指定文件读取 YAML 内容作为内联流水线，忽略 path 磁盘内容

成功输出：

{"command":"pipeline.validate","ok":true,"pipeline":"/path/to.yaml","valid":true}

失败输出：ok:false，message 描述具体错误（如未知节点类型、Logic 无上游、links 引用不存在的节点名）。

典型场景：

• 编写 YAML 后第一时间校验，快速发现拓扑错误
• CI 流水线中作为静态检查步骤
• 修改 Stage 顺序后确认编译器接受

---

8.5 pipeline run

用途：经 edge_pipe_service 加载并运行流水线。默认启动后立即返回（异步）；加 --wait 则阻塞至流水线结束。

edgepipe --format json pipeline run <yaml路径> [--dry-run] [--wait] [--content-file <file>]

参数	必填	说明
path	是	YAML 文件路径
--dry-run	否	仅校验不执行。成功时退出码 10，JSON 含 "dry_run":true
--wait	否	阻塞直到流水线运行完毕再返回
--content-file	否	内联 YAML 内容文件，适合管道传入或临时配置

成功输出（正式运行）：

{"command":"pipeline.run","ok":true,"pipeline":"/path/to.yaml","running":true}

冲突输出（已有流水线在跑）：

{
  "error": "pipeline_running",
  "message": "a pipeline is already running",
  "ok": false,
  "retryable": false,
  "suggestion": "Run 'edgepipe service stop' before starting another pipeline"
}

退出码：5。

执行流程（服务内部）：

1. 解析 YAML 路径（支持相对路径、内联内容落盘到 tmp）
2. ValidatePipeline — 拓扑与参数校验
3. GraphCompiler 编译 DAG
4. EdgeLauncher 启动各节点 worker 线程
5. Streamer 推帧 → Algorithm 推理 → Logic 后处理 → Sink/Report 输出

注意：edge_pipe_service 同一时刻只允许一条流水线运行。启动新流水线前须停止当前流水线。

---

8.6 pipeline graph

用途：将 YAML 编译为 Graphviz DOT 格式的 DAG 图，用于文档配图、架构评审或可视化调试。

edgepipe --format json pipeline graph <yaml路径>

成功时 JSON 的 graph 字段包含 DOT 文本，例如：

digraph pipeline {
  "cam0" [label="cam0\nedge.image_streamer"];
  "detect" [label="detect\nedge.detection"];
  "logic" [label="logic\nedge.logic"];
  "image_out" [label="image_out\nedge.sink.image_file"];
  "cam0" -> "detect";
  "detect" -> "logic";
  "logic" -> "image_out";
}

在 PC 上渲染为 PNG：

# 板端导出后通过 hdc 拉到 PC
hdc file recv /data/local/tmp/pipeline.dot ./pipeline.dot
dot -Tpng pipeline.dot -o pipeline.png

---

8.7 pipeline run-local / validate-local / graph-local

用途：在 CLI 进程内直接编译运行，不经服务 IPC。适合开发阶段快速迭代 YAML，但无法测试服务生命周期与并发冲突。

edgepipe pipeline validate-local my.yaml
edgepipe pipeline run-local my.yaml
edgepipe pipeline graph-local my.yaml

对比项	pipeline run	pipeline run-local
经 edge_pipe_service	是	否
测试并发冲突	是	否
推理调用 Edge Engine	是	是（若 SDK 可用）
适用场景	生产运行、板端运维	本地开发、YAML 调试

---

8.8 service status

用途：查询 edge_pipe_service 当前状态，包括是否有流水线在运行及正在运行的 YAML 路径。

edgepipe --format json service status

字段	说明
ok	IPC 调用是否成功
running	是否有流水线在运行
pipeline	当前运行的 YAML 路径（空闲时为空字符串）

空闲示例：

{"command":"service.status","ok":true,"pipeline":"","running":false}

运行中示例：

{"command":"service.status","ok":true,"pipeline":"/system/etc/edge_pipe/pipelines/person_detect_yolov10_cloud.yaml","running":true}

---

8.9 service stop

用途：停止当前正在运行的流水线。

edgepipe --format json service stop
edgepipe --format json service stop --dry-run

参数	说明
--dry-run	仅预览将停止哪条流水线，不真正停止；退出码 10

不带 --dry-run：调用 StopPipeline()，应真正停止流水线。

带 --dry-run：返回 would_stop 预览信息，流水线继续运行。

若 stop 后 running 仍为 true，可强制复位：

service_control restart edge_pipe_service

---

8.10 schema

用途：CLI 命令自省，输出子命令的参数、标志与描述。不需要连接 edge_pipe_service，可在服务未启动时使用。

edgepipe schema pipeline.run
edgepipe schema pipeline.validate
edgepipe schema pipeline.graph
edgepipe schema service.status
edgepipe schema service.stop

示例输出（pipeline.run）：

{
  "args": [
    {"description": "Pipeline YAML path", "name": "path", "required": true, "type": "string"}
  ],
  "description": "Run a pipeline YAML",
  "flags": [
    {"description": "Preview side effects without executing", "name": "dry-run", "type": "bool"},
    {"description": "Inline YAML from file", "name": "content-file", "type": "string"}
  ],
  "path": "pipeline.run"
}

裸跑 edgepipe schema（不带子路径）可能因 UTF-8 编码问题崩溃，请始终指定子路径。

8.11 错误 JSON 格式

失败时 stdout 统一输出：

{
  "ok": false,
  "error": "service_unavailable",
  "message": "详细错误描述",
  "suggestion": "建议的修复命令",
  "retryable": true
}

字段	说明
error	机器可读错误码
message	人类可读描述
suggestion	建议的下一步操作
retryable	是否可重试

---

九、手把手实验

完成第二～八章后，用本章 7 组实验巩固所学。建议先在宿主机 hdc shell 进入板端，按顺序逐步完成。

实验	主题	耗时	前置依赖
0	实验准备	1 分钟	板端已开机、可 hdc shell
1	确认服务与 CLI	2 分钟	实验 0
2	校验预置 YAML	3 分钟	实验 1
3	干跑与导出 DAG	3 分钟	实验 2
4	模型下载与 Edge Engine 联调	5–10 分钟	实验 3、板端可访问 EdgeHub
5	正式运行与输出检查	3 分钟	实验 4
6	冲突检测与停止	3 分钟	实验 5（流水线仍在运行）
7	完整自动化脚本	5 分钟	实验 1–6 均通过

---

9.0 实验准备

目标：确认开发环境就绪，无需手动启动服务（系统初始化时已自动拉起 edge_engine_service 与 edge_pipe_service）。

步骤：

1. 在宿主机连接开发板：

hdc list targets
hdc shell

2. 确认已进入板端 shell（提示符通常为 # 或 $）。

预期结果：hdc shell 无报错，可执行 edgepipe、edgeengine 等命令。

若失败：检查 USB/网络连接、hdc 驱动与设备授权。

---

9.1 确认服务与 CLI

目标：验证 EdgePipe CLI 可用，且 edge_pipe_service 与 Edge Engine 均已由系统启动并就绪。

步骤：

1. 查看 CLI 版本，确认工具链已安装：

edgepipe --version

2. 通过 IPC 查询 EdgePipe 服务状态（比 ps 更可靠）：

edgepipe --format json service status

3. （可选）用进程列表双重确认两个服务进程存在：

ps -ef | grep -E 'edge_pipe_service|edge_engine_service' | grep -v grep

预期结果：

检查项	期望值
edgepipe --version	0.1.0 (schema 1)
service status 中 ok	true
running	false（尚无流水线在跑）
pipeline	空字符串 ""
ps 输出	可见 edge_pipe_service 与 edge_engine_service 进程

若失败：

• 退出码 3 或 service_unavailable：执行 service_control restart edge_engine_service 与 service_control restart edge_pipe_service 后重试。
• 找不到 edgepipe 命令：确认镜像已刷入含 EdgePipe 组件的版本。

---

9.2 校验预置 YAML

目标：学习使用 pipeline validate 做静态检查——验证 YAML 语法、节点类型与 DAG 拓扑是否正确，不执行推理、不消耗 NPU。

背景：编写或修改流水线后，应第一时间 validate，可在模型未安装时就发现拓扑错误。

步骤：

1. 校验主推 YOLOv10 流水线：

edgepipe --format json pipeline validate \
  /system/etc/edge_pipe/pipelines/person_detect_yolov10_cloud.yaml

2. 校验 YOLOv8 视频流水线（对比不同节点类型）：

edgepipe --format json pipeline validate \
  /system/etc/edge_pipe/pipelines/person_detect_yolov8_video.yaml

预期结果：

{"command":"pipeline.validate","ok":true,"pipeline":"...","valid":true}

两条 YAML 均应 "valid":true。YOLOv8 使用 edge.video_streamer，节点链与 YOLOv10 的 edge.image_streamer 不同，但均可通过拓扑校验。

注意：validate 不检查模型是否已安装。YOLOv8 YAML 校验通过后，正式运行仍需单独 modelhub ensure global/people_count_yolov8。

若失败：阅读 JSON 中 message 字段，常见原因包括 links 引用了不存在的节点名、edge.logic 缺少上游、Stage 顺序违反约束（如 line_zone 前无 byte_track）。

---

9.3 干跑与导出 DAG

目标：

• 使用 --dry-run 在不真正执行推理的前提下，确认服务能接受该 YAML 并走完编译流程；
• 使用 pipeline graph 导出 DAG 结构，直观理解节点连接关系。

步骤：

1. 对 YOLOv10 流水线执行干跑：

edgepipe --format json pipeline run \
  /system/etc/edge_pipe/pipelines/person_detect_yolov10_cloud.yaml --dry-run
echo "exit code: $?"

2. 导出 Graphviz DOT 格式的 DAG 图：

edgepipe --format json pipeline graph \
  /system/etc/edge_pipe/pipelines/person_detect_yolov10_cloud.yaml

预期结果：

检查项	期望值
dry-run JSON 中 valid	true
dry-run JSON 中 dry_run	true
退出码	10（DryRunOk，表示成功，不是错误）
graph JSON 中 graph	含 cam0 → detect → logic → image_out 四条边

DAG 节点对应关系：

cam0 (edge.image_streamer) → detect (edge.detection) → logic (edge.logic) → image_out (edge.sink.image_file)

若失败：dry-run 退出码 1 表示编译或校验失败；退出码 3 表示服务不可用（回到实验 1）。

---

9.4 模型下载与 Edge Engine 联调

目标：在跑 EdgePipe 流水线之前，先通过 Edge Engine 独立验证模型已正确安装且推理可用。这是排障的关键分层：推理问题应先在这一层解决，再测流水线。

前置条件：板端可访问 EdgeHub（需网络）；若离线环境，需提前将模型包拷贝到 /data/edge_engine/models/。

步骤：

1. 从 EdgeHub 下载并安装 YOLOv10 模型到 ModelHub：

edgeengine --format json modelhub ensure global/people_count_yolov10 --version v1.1

首次安装时 message 为 installed；已安装时为 already_installed。记录 install_path 字段。

2. 列出本地已安装模型，确认目录存在：

edgeengine --format json modelhub list

3. 单独推理验证（绕过 EdgePipe，直接调用 Edge Engine）：

edgeengine --format json model infer global/people_count_yolov10 --engine rknn \
  --input /system/etc/edge_pipe/fixtures/images/bus.jpg

4. 预览 model_name 在板端解析到的实际 .rknn 路径（与 YAML 中 model_name 模式对应）：

edgeengine --format json model resolve global/people_count_yolov10 --engine rknn

预期结果：

步骤	关键字段	期望值
ensure	ok	true
ensure	install_path	/data/edge_engine/models/global/people_count_yolov10/v1.1
infer	detection_count	> 0（bus.jpg 通常检出 person、bus 等）
infer	engine	rknn
resolve	model_path	指向 .../rk3588/yolov10n_fp16.rknn
resolve	platform	rk3588

若失败：

• ensure 网络超时：检查 DNS 与 EdgeHub 连通性，或离线拷贝模型。
• infer 失败但 ensure 成功：检查 NPU 驱动、hilog | grep edge_engine。
• 此步未通过时，不要继续实验 5，否则无法区分是 Edge Engine 还是 EdgePipe 的问题。

---

9.5 正式运行与输出检查

目标：经 edge_pipe_service 正式启动 YOLOv10 人员检测流水线，并在输出目录中确认标注图像已生成。

前置条件：实验 4 中 edgeengine model infer 已成功。

步骤：

1. 启动流水线（默认异步，命令立即返回）：

edgepipe --format json pipeline run \
  /system/etc/edge_pipe/pipelines/person_detect_yolov10_cloud.yaml

2. 确认服务状态变为运行中：

edgepipe --format json service status

3. 等待数秒后，检查输出目录中的标注图：

ls -la /data/service/el1/public/edge_pipe/output/yolov10_cloud/

预置 YAML 中 image_streamer 设置了 loop: true、loop_num: 1000，流水线会持续处理帧；sink 设置了 keep_latest_only: true，目录中通常只保留最新一张标注 JPG。

预期结果：

检查项	期望值
run JSON 中 ok	true
run JSON 中 running	true
status 中 pipeline	指向 person_detect_yolov10_cloud.yaml
输出目录	存在 .jpg 文件，图像上有人体检测框标注

流水线本帧做了什么（对应 YAML 节点链）：

1. cam0：读取 /system/etc/edge_pipe/fixtures/images/bus.jpg
2. detect：YOLOv10 RKNN 推理，输出检测框
3. logic：confidence_filter → class_filter(person) → nms → label 标注
4. image_out：保存到 output/yolov10_cloud/

若失败：退出码 1 时查看 hilog | grep -E 'edge_pipe|AlgorithmNode'；无输出图像时检查 sink 的 directory 路径与 /data 写权限。

---

9.6 冲突检测与停止

目标：理解 edge_pipe_service 同一时刻只允许一条流水线运行的限制，练习冲突检测与服务停止操作。

前置条件：实验 5 的流水线仍在运行（service status 中 running: true）。若已停止，请先重新执行实验 5 的步骤 1。

步骤：

1. 在流水线未停止的情况下，再次尝试启动同一条 YAML：

edgepipe --format json pipeline run \
  /system/etc/edge_pipe/pipelines/person_detect_yolov10_cloud.yaml
echo "exit code: $?"

2. 停止当前流水线：

edgepipe --format json service stop

3. 再次查询状态，确认已停止：

edgepipe --format json service status

预期结果：

步骤	检查项	期望值
重复 run	退出码	5（Conflict）
重复 run	JSON error	pipeline_running
stop 后 status	running	false
stop 后 status	pipeline	""

若 stop 后 running 仍为 true：执行 service_control restart edge_pipe_service 强制复位，然后重新从实验 1 确认服务状态。

---

9.7 完整自动化脚本

目标：将实验 1–6 的关键步骤合并为一份可重复执行的 Bash 脚本，适合 CI、回归测试或交付验收。

步骤：

1. 在板端创建脚本文件（或通过 hdc shell 粘贴执行）：

#!/bin/bash
set -e

echo "=== [1/6] 确认服务 ==="
edgepipe --format json service status | grep -q '"ok":true'
edgepipe --version

echo "=== [2/6] 安装模型 ==="
edgeengine --format json modelhub ensure global/people_count_yolov10 --version v1.1

echo "=== [3/6] 单独验证推理 ==="
edgeengine --format json model infer global/people_count_yolov10 --engine rknn \
  --input /system/etc/edge_pipe/fixtures/images/bus.jpg

echo "=== [4/6] 干跑校验 ==="
edgepipe --format json pipeline run \
  /system/etc/edge_pipe/pipelines/person_detect_yolov10_cloud.yaml --dry-run
test $? -eq 10

echo "=== [5/6] 正式运行 ==="
edgepipe --format json pipeline run \
  /system/etc/edge_pipe/pipelines/person_detect_yolov10_cloud.yaml

echo "=== [6/6] 检查输出 ==="
ls /data/service/el1/public/edge_pipe/output/yolov10_cloud/

echo "=== 全部通过 ==="

2. 赋予执行权限并运行：

chmod +x /data/local/tmp/edgepipe_e2e.sh
/data/local/tmp/edgepipe_e2e.sh

预期结果：脚本逐步打印 [1/6] 至 [6/6]，最终以 全部通过 结束，退出码 0。

扩展练习（可选）：

• 在脚本末尾加入 edgepipe service stop 与冲突检测（实验 6）
• 将 pipeline graph 输出重定向到文件，在 PC 上用 Graphviz 渲染
• 修改 YAML 中 logic.stages，观察输出图像变化（参考第七章）

---

十、进阶专题

掌握第三～九章后，本章介绍生产环境常用能力：模型指定方式、MQTT 上报、自定义 Logic 插件与自动化测试。

10.1 model_name 与 model_path

模式	字段	适用场景	依赖
平台模式	model_name + model_version	生产环境、EdgeHub 统一管理	edgeengine modelhub ensure
路径模式	model_path	本地测试、临时模型	文件存在于板端

model_name 格式：<namespace>/<model_short_name>，如 global/people_count_yolov10。

内部解析为 modelhub://global/people_count_yolov10/v1.1 URI，由 Edge Engine ModelHub 定位实际 .rknn 文件。

10.2 MQTT 上报

- name: mqtt_report
  type: edge.report.mqtt
  params:
    broker: zhihongos.cn
    port: 1883
    topic: edge/pipe/alerts
    username: ${MQTT_USER}
    password: ${MQTT_PASS}
    report_mode: on_alert

export MQTT_USER=admin
export MQTT_PASS=admin
edgepipe pipeline run alert_pipeline.yaml

可与 JetLinks（edgecomputer 接入的同一 MQTT Broker）联动。

10.3 逻辑插件开发

- name: alert_logic
  type: edge.logic.plugin
  params:
    plugin_path: /system/lib64/edge_pipe/plugins/libsample_alert_plugin.z.so

编译部署：

./build.sh --product-name rk3588 --build-target edge_pipe

10.4 板端 E2E 自动化

# 【宿主机】
bash extension/ai/edge_pipe/test/run_pipelines_board_e2e.sh

---

十一、常见问题

11.1 诊断流程图

11.2 退出码速查

退出码	场景	处理
0	成功	—
1	校验失败、推理错误	查看 JSON message / hilog
2	命令用法错误	edgepipe --help
3	服务不可用	service_control restart edge_pipe_service
5	流水线已在运行	先 stop 或重启服务
10	dry-run 成功	正常，非错误

11.3 常见问题速查

现象	可能原因	解决方案
service status 退出码 3	服务未运行	service_control restart edge_pipe_service
valid: false	YAML 拓扑或节点类型错误	见 8.4 节；对照第七章
dry-run 退出码 10	正常	脚本中视为成功
退出码 5	已有流水线在跑	edgepipe service stop 或重启服务
model not found	模型未安装	第四章 modelhub ensure
infer 失败但 ensure 成功	NPU/驱动问题	hilog | grep edge_engine
无输出图像	sink 路径或权限	检查 output/ 目录与 YAML directory
schema 崩溃	UTF-8 异常	使用 edgepipe schema pipeline.run
YOLOv8 validate 通过 run 失败	未装 v8 模型	modelhub ensure global/people_count_yolov8
MQTT 连接失败	broker/端口/网络	见 7.8 节端口优先级

Q1：edgepipe pipeline run 退出码 3

原因：edge_pipe_service 未运行或 IPC 连接失败。

解决：

service_control restart edge_engine_service
service_control restart edge_pipe_service
edgepipe --format json service status

Q2：退出码 5 — pipeline_running

解决：

edgepipe --format json service stop
# 若仍 running:true：
service_control restart edge_pipe_service

Q3：model not found / 推理失败

解决：

edgeengine --format json modelhub list
edgeengine --format json modelhub ensure global/people_count_yolov10 --version v1.1
edgeengine --format json model infer global/people_count_yolov10 --engine rknn \
  --input /system/etc/edge_pipe/fixtures/images/bus.jpg

先确认 Edge Engine 单独推理 OK，再跑 EdgePipe。

Q4：edgepipe schema 崩溃

解决：使用子路径 edgepipe schema pipeline.run，不要使用裸 edgepipe schema。

Q5：dry-run 退出码 10 是否失败？

不是失败。脚本中应将 0 和 10 均视为成功。

Q6：YOLOv8 YAML validate 通过但 run 失败

原因：validate 只检查拓扑，不检查模型是否安装。

解决：

edgeengine --format json modelhub ensure global/people_count_yolov8 --version v1.0

Q7：MQTT 连接失败

检查顺序：YAML broker/port → 环境变量 EDGE_PIPE_MQTT_PORT → param get persist.edge_pipe.mqtt.port → 网络连通。

Q8：无输出图像

ls -la /data/service/el1/public/edge_pipe/output/
# 检查 YAML 中 sink directory 路径与写权限

Q9：Stage 顺序报错

确认 line_zone 之前有 byte_track；检查 class_filter 的 class_names 拼写是否与模型类别一致。

Q10：调试建议 — run-local

edgepipe pipeline validate-local my.yaml
edgepipe pipeline run-local my.yaml

11.4 日志与进一步诊断

hilog -T EdgePipe
hilog | grep -E 'edge_pipe|EdgeLauncher|AlgorithmNode'

---

十二、附录

附录 A：命令速查表

场景	命令
查看版本	edgepipe --version
服务状态	edgepipe --format json service status
命令自省	edgepipe schema pipeline.run
校验 YAML	edgepipe --format json pipeline validate <yaml>
干跑预览	edgepipe --format json pipeline run <yaml> --dry-run
正式运行	edgepipe --format json pipeline run <yaml>
导出 DAG	edgepipe --format json pipeline graph <yaml>
停止流水线	edgepipe --format json service stop
本地调试	edgepipe pipeline run-local <yaml>
安装模型	edgeengine --format json modelhub ensure <name> --version v1.1
验证推理	edgeengine --format json model infer <name> --engine rknn --input <img>
重启服务	service_control restart edge_pipe_service

附录 B：person_detect_yolov10_cloud.yaml 全文

version: "1.0"

metadata:
  name: person_detect_yolov10_cloud
  description: YOLOv10 行人检测 — ModelHub 云端下载 + RKNN 推理

config:
  runtime:
    blocking_mode: false
    queue_capacity: 4
    log_level: info

nodes:
  - name: cam0
    type: edge.image_streamer
    params:
      source: fixtures/images/bus.jpg
      process_frame_interval: 0
      loop: true
      loop_num: 1000

  - name: detect
    type: edge.detection
    params:
      algorithm_id: yolov10
      model_name: global/people_count_yolov10
      engine: rknn
      mode: primary
      num_threads: 6
      meta_override.confidence_threshold: 0.45
      meta_override.nms_threshold: 0.45

  - name: logic
    type: edge.logic
    params:
      stages:
        - type: confidence_filter
          threshold: 0.45
        - type: class_filter
          class_names: person
        - type: nms
          iou_threshold: 0.45
      annotators:
        - type: label
          thickness: 2
          color_lookup: class

  - name: image_out
    type: edge.sink.image_file
    params:
      directory: /data/service/el1/public/edge_pipe/output/yolov10_cloud
      format: jpg
      jpeg_quality: 90
      keep_latest_only: true

links:
  - "cam0 > detect > logic > image_out"

附录 C：练手 checklist

题号	练习	验证命令
1	确认服务与 CLI	edgepipe --version + service status
2	schema 自省	edgepipe schema pipeline.validate
3	校验预置 YOLOv10 YAML	edgepipe pipeline validate .../person_detect_yolov10_cloud.yaml
4	干跑并确认退出码 10	edgepipe pipeline run ... --dry-run; echo $?
5	安装模型	edgeengine modelhub ensure global/people_count_yolov10 --version v1.1
6	单独验证推理	edgeengine model infer ... --engine rknn --input .../bus.jpg
7	编写最简 4 节点 YAML 并 validate	参考第七章 7.9 示例 A
8	正式运行并查看输出	edgepipe pipeline run ... + ls output/yolov10_cloud/
9	导出 DAG 图	edgepipe pipeline graph ...
10	体验冲突检测	连续两次 pipeline run，观察退出码 5

结业测验（宿主机）：

bash extension/documents/scripts/training_quiz.sh

附录 D：五服务教程体系导航

顺序	服务	本地教程	角色	依赖
1	EdgeComputer	edgecomputer.md	JetLinks 网关	—
2	EdgeMCP	edgemcp.md	MCP 设备桥	EdgeComputer
3	EdgeClaw	edgeclaw.md	AI 管家	EdgeComputer + EdgeMCP
4	Edge Engine	edgeengine.md	推理运行时	Edge Engine
5	EdgePipe	edgepipe.md（本文）	视觉流水线	Edge Engine

文档	路径
使用指南总览	/training/
架构设计（开发者）	extension/ai/edge_pipe/docs/ARCHITECTURE.md
模型标识设计	extension/ai/edge_pipe/docs/MODEL_IDENTIFIER_REFACTOR_DESIGN.md

附录 E：文档修订记录

日期	说明
2026-09-03	对齐 Edge Engine 教程结构：先实操后原理；十二章节编号；手把手实验分步说明
2026-09-02	按统一结构重写；主推 YOLOv10 + modelhub ensure 联调
2026-09-01	初版章节式手册