Edge Engine 新手教程

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

章节	内容
一、开始之前	学什么、怎么读这份文档
二、连接开发板	hdc 连接、确认服务在跑
三、快速开始	5 分钟完成首次推理
四、从 EdgeHub 安装模型	浏览市场、在线安装
五、工作原理	ModelHub、推理管道、组件协作
六、功能一览	模块与能力速览
七、命令手册	子命令与参数说明
八、进阶专题	edge_pipe 联调、ASR、插件开发
九、常见问题	装不上、推不动怎么办
十、附录	命令速查、练手 checklist

一、开始之前

1.1 这份文档帮你做什么

Edge Engine 是跑在 OpenHarmony 板子上的端侧 AI 推理引擎：从 EdgeHub 安装模型包，在板端做目标检测、图像分类、语音识别等，RK3588 上可走 NPU 加速。

按下面顺序读，可以从零完成首次推理：

第二章：hdc 连上板子，确认 Edge Engine 服务在运行
第三章：安装模型、对测试图推理，约 5 分钟跑通
第四章：从 EdgeHub 浏览、安装更多模型
第五章：理解 ModelHub、推理管道、EdgeHub 如何配合——读懂前几章在干什么
第七章：需要查某个子命令或参数时当字典用

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

1.2 你需要准备

项目	说明
开发板	RK3588 开发板，已烧录 ZhihongOS
宿主机	已安装 `hdc`，能 `hdc shell` 进板子
网络（可选）	从 EdgeHub 在线装模型时需要访问 `zhihongos.cn`
基础命令	会复制粘贴 Shell；JSON 输出看得懂字段名更好

1.3 CLI 用法

官方命令是 edgeengine：

bash

edgeengine --version
edgeengine schema
edgeengine schema model.infer

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

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

1.4 术语速查

术语	含义
ModelHub	板端模型仓库：安装、列表、卸载
EdgeHub	云端模型市场
manifest	模型包内的推理管道定义
model_name	完整标识，如 `global/people_count_yolov10`
engine	推理后端：`rknn`（NPU）或 `onnx`（CPU）

二、连接开发板

ZhihongOS 开机后 Edge Engine 随系统自动启动，一般无需手动 service_control start。本章确认你能连上板子、服务在线，再进入第三章做首次推理。

2.1 硬件要求

项目	说明
开发板	RK3588 开发板（含 NPU）
系统	ZhihongOS 6.1.0
CLI	`edgeengine` v1.0.0

2.2 连接开发板

bash

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

# 进入板端 shell
hdc shell

连接成功后，提示符类似：

后续标注 【板端】 的命令均在此 shell 中执行。

2.3 确认 Edge Engine 服务已运行

进入板端后执行：

bash

edgeengine --format json service status

"available": true 即表示服务正常。仅在第九章遇到异常时，才考虑 service_control restart edge_engine_service。

2.4 第一步验证

bash

edgeengine --version
edgeengine --format json service status
edgeengine schema

命令	期望
`--version`	`1.0.0 (schema 1)`
`service status`	`"available": true`

2.5 EdgeHub 网络与鉴权（可选）

从 EdgeHub 在线安装模型需要网络可达及有效 Token：

bash

# 查看当前 EdgeHub URL 配置
param get persist.ai_engine.edgehub.url

# 设置 Token（若 EdgeHub 需要鉴权）
param set persist.ai_engine.edgehub.token "your-token-here"

三、快速开始

目标：5 分钟内完成「确认服务 → 安装模型 → 推理 bus.jpg → 看到 5 个检测框」。

3.1 一键流程

bash

# 【板端】

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

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

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

# 步骤 4：对 bus.jpg 执行推理
edgeengine --format json model infer global/people_count_yolov10 \
  --engine rknn \
  --input /system/etc/edge_pipe/fixtures/images/bus.jpg

3.2 期望结果摘要

步骤	关键字段	期望值
`--version`	文本	`1.0.0 (schema 1)`
`service status`	`available`	`true`
`modelhub ensure`	`message`	`installed` 或 `already_installed`
`model infer`	`detection_count`	`5`
`model infer`	`class_name`	`person`（4 个）、`bus`（1 个）

3.3 推理结果说明

json

{
  "command": "model.infer",
  "data": {
    "detection_count": 5,
    "detections": [
      { "class_id": 0, "class_name": "person", "confidence": 0.526, "x1": 0, "y1": 551, "x2": 59, "y2": 874 },
      { "class_id": 5, "class_name": "bus",  "confidence": 0.941, "x1": 8,  "y1": 231, "x2": 802, "y2": 739 },
      { "class_id": 0, "class_name": "person", "confidence": 0.908, "x1": 219, "y1": 406, "x2": 344, "y2": 863 },
      { "class_id": 0, "class_name": "person", "confidence": 0.901, "x1": 49,  "y1": 396, "x2": 246, "y2": 905 },
      { "class_id": 0, "class_name": "person", "confidence": 0.825, "x1": 671, "y1": 394, "x2": 810, "y2": 875 }
    ],
    "engine": "rknn",
    "model_name": "global/people_count_yolov10"
  },
  "ok": true
}

坐标说明：x1, y1, x2, y2 为原图像素坐标，左上角 (x1,y1)，右下角 (x2,y2)。

3.4 快速开始常见问题

现象	快速处理
`available: false`	先按 2.3 节确认；仍异常见第九章
`ensure_failed` + HTTP 错误	检查网络与 EdgeHub Token
`detection_count: 0`	确认 `--input` 图片路径正确且可读
推理很慢（>5s）	首次推理含模型加载，可用 `model load` 预加载

四、从 EdgeHub 安装模型

4.1 浏览模型市场

EdgeHub 提供浏览器访问的模型市场：

默认地址：https://zhihongos.cn/edgehub
可浏览模型、查看版本、获取安装命令

EdgeHub 首页

4.2 在线安装流程

bash

# 1. 查看本地候选（通常为空）
edgeengine modelhub packages

# 2. 在线安装
edgeengine --format json modelhub install global/people_count_yolov10 --version v1.1

# 3. 验证 info + infer
edgeengine --format json modelhub info 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

4.3 鉴权失败处理

若返回 HTTP 401：

bash

param set persist.ai_engine.edgehub.token "your-valid-token"

五、工作原理

读完第二～四章动手操作后，本章说明 Edge Engine 各组件如何协作。需要查命令参数时，直接看第七章。

5.1 整体架构

Edge Engine 分三层：

层级	组件	职责
客户端	`edgeengine` 命令、edge_pipe、业务 SDK	发起推理请求
服务	ModelHub、插件管理、资源监控	调度模型、路由算法、管理本地仓库
插件	CV / ASR 算法插件	执行预处理、NPU/CPU 推理、后处理

客户端与服务之间通过系统 IPC 通信；edge_pipe 等业务模块用同样方式调用。

5.2 一次推理怎么走

准备：根据 model_name、版本、engine（rknn / onnx）找到对应模型包
推理：按 manifest 定义的预处理 → 推理 → 后处理依次执行
返回：输出结构化 JSON（如检测框、分类结果、ASR 文本）

5.3 推理管道（manifest）

每个模型包带有 manifest，描述从输入到输出的处理步骤，例如：

图像预处理：颜色转换、缩放填充
推理：RKNN（NPU）或 ONNX（CPU）
后处理：解码检测框、过滤低置信度结果、坐标还原到原图

不同算法（YOLO、MobileNet 等）manifest 不同，安装后可用 model manifest 查看。

5.4 ModelHub 与 EdgeHub

EdgeHub：云端模型市场，提供 zip 包下载
ModelHub：板端本地仓库，负责安装、索引、供推理时查找

在线安装走 EdgeHub；已安装模型即使断网也可推理。EdgeHub 地址与 Token 通过 param 配置（见 2.5 节）。

5.5 模型标识

字段	示例	说明
namespace	`global`	命名空间
name	`people_count_yolov10`	模型名
model_name	`global/people_count_yolov10`	命令中使用的完整标识
version	`v1.1`	版本号
algorithm_id	`yolov10`	算法类型，决定加载哪个插件
engine	`rknn` / `onnx`	推理后端：NPU 或 CPU

在 RK3588 上优先使用 rknn 以启用 NPU 加速。

5.6 与其他服务的关系

服务	与 Edge Engine 的关系
edge_pipe	主要调用方，流水线节点经 SDK 发起推理
EdgeHub	模型包下载来源
EdgeClaw	可通过 Skill 间接使用推理能力
EdgeComputer / EdgeMCP	无直接依赖，可并行部署

六、功能一览

模块	CLI 入口	作用
ModelHub	`modelhub`	从 EdgeHub 或本地 zip 安装、列出、卸载模型
Model	`model`	单次推理、预加载、查看 manifest
Service	`service status`	查看服务是否可用
Metrics	`metrics get`	NPU/CPU/内存等资源采样
Schema	`schema`	查询子命令与参数（建议用子路径，见第九章）

支持的 CV 算法包括 YOLOv10 检测、MobileNet/ResNet 分类等；部分镜像可选 Whisper 语音识别。算法由插件按 algorithm_id 路由。

七、命令手册

7.1 命令树总览

edgeengine
├── [全局选项]
├── modelhub
│   ├── install <model_name> [--version <ver>] [--namespace <ns>]
│   ├── ensure <model_name> [--version <ver>] [--namespace <ns>]
│   ├── list [--namespace <ns>]
│   ├── uninstall <model_name> [--version <ver>]
│   ├── info <model_name> [--version <ver>]
│   └── packages [--namespace <ns>]
├── model
│   ├── infer <model_name> [--engine <eng>] [--input <path>] [--version <ver>]
│   ├── manifest <model_name> [--version <ver>]
│   ├── resolve <model_name> [--version <ver>] [--engine <eng>]
│   ├── load <model_name> [--version <ver>]
│   └── unload                          # 注意：不带模型名参数
├── service
│   └── status
├── metrics
│   └── get
└── schema [path]

7.2 全局选项

全局选项可放在命令任意位置（推荐放在子命令前）。

选项	简写	类型	默认值	说明
`--format`	—	`auto\|json\|table`	`auto`	输出格式；脚本建议固定 `json`
`--quiet`	—	flag	false	减少日志输出
`--verbose`	—	flag	false	增加调试日志
`--version`	`-V`	flag	—	打印 CLI 版本并退出
`--help`	`-h`	flag	—	打印帮助

示例：

bash

# 以下两种写法等价
edgeengine --format json modelhub list
edgeengine modelhub list --format json

--version 示例输出：

1.0.0 (schema 1)

7.3 `service status`

查询 edge_engine_service 是否可用。

bash

edgeengine --format json service status

响应字段	类型	说明
`available`	bool	服务是否可用

7.4 `modelhub` 子命令

7.4.1 `modelhub install`

从 EdgeHub 或本地 zip 安装指定模型。

bash

edgeengine --format json modelhub install <model_name> [--version <ver>] [--namespace <ns>]

参数	必填	说明
`<model_name>`	是	格式 `namespace/name` 或仅 `name`（配合 `--namespace`）
`--version`	否	版本号，如 `v1.1`；省略则安装最新
`--namespace`	否	当 model_name 不含 `/` 时指定命名空间，默认 `global`

行为：若已存在同版本，通常返回错误或跳过（取决于实现版本）。

7.4.2 `modelhub ensure`（推荐）

幂等操作：模型不存在则安装，已存在则直接返回成功。

bash

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

响应字段	说明
`message`	`installed`（新安装）或 `already_installed`（已存在）
`algorithm`	如 `yolov10`
`install_path`	本地安装目录
`platforms`	支持的平台列表，如 `["generic","rk3588"]`

首次安装示例：

json

{
  "command": "modelhub.ensure",
  "data": {
    "algorithm": "yolov10",
    "install_path": "/data/edge_engine/models/global/people_count_yolov10/v1.1",
    "message": "installed",
    "model_name": "global/people_count_yolov10",
    "name": "people_count_yolov10",
    "namespace": "global",
    "platforms": ["generic", "rk3588"],
    "version": "v1.1"
  },
  "ok": true
}

再次执行示例（full_eval）：

json

{
  "data": {
    "message": "already_installed",
    "state": "installed"
  },
  "ok": true
}

7.4.3 `modelhub list`

列出本地已安装模型。

bash

edgeengine --format json modelhub list
# 或
edgeengine modelhub list --format json

示例输出：

json

{
  "command": "modelhub.list",
  "data": {
    "count": 1,
    "models": [
      {
        "algorithm": "yolov10",
        "install_path": "/data/edge_engine/models/global/people_count_yolov10/v1.1",
        "model_name": "global/people_count_yolov10",
        "state": "installed",
        "version": "v1.1"
      }
    ]
  },
  "ok": true
}

7.4.4 `modelhub info`

查看单个模型详情。

bash

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

参数	必填	说明
`<model_name>`	是	`namespace/name`
`--version`	否	省略则返回最新已安装版本

7.4.5 `modelhub uninstall`

卸载本地模型包。

bash

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

卸载后 modelhub list 的 count 应减少，磁盘上对应目录被删除。

7.4.6 `modelhub packages`

扫描本地 zip 候选包（不访问 EdgeHub）。

bash

edgeengine modelhub packages

示例输出（无本地 zip 时）：

json

{
  "command": "modelhub.packages",
  "data": { "count": 0, "packages": [] },
  "ok": true
}

7.5 `model` 子命令

7.5.1 `model infer`

对单张图片（或音频）执行推理。

bash

edgeengine --format json model infer <model_name> \
  --engine rknn \
  --input <file_path> \
  [--version <ver>]

参数	必填	说明
`<model_name>`	是	`global/people_count_yolov10`
`--engine`	建议	`rknn`（NPU）或 `onnx`（CPU）；RK3588 推荐 rknn
`--input`	是	输入文件绝对路径
`--version`	否	模型版本，默认使用已安装最新版

检测任务响应字段：

字段	说明
`detection_count`	检测框数量
`detections[]`	数组，每项含 class_id、class_name、confidence、x1/y1/x2/y2
`engine`	实际使用的后端
`output_image`	可视化输出路径（若启用）

7.5.2 `model manifest`

打印平台 manifest 内容（推理管道定义）。

bash

edgeengine model manifest global/people_count_yolov10 --version v1.1

返回的 data.manifest 为转义后的 JSON 字符串，包含 pre_stages、decoder_stages、post_stages 等。

7.5.3 `model resolve`

按 engine 解析模型文件路径，不执行推理。

bash

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

示例输出：

json

{
  "command": "model.resolve",
  "data": {
    "algorithm_id": "yolov10",
    "backend": "rknn",
    "manifest_path": "/data/edge_engine/models/global/people_count_yolov10/v1.1/rk3588/manifest.json",
    "model_path": "/data/edge_engine/models/global/people_count_yolov10/v1.1/rk3588/yolov10n_fp16.rknn",
    "package_root": "/data/edge_engine/models/global/people_count_yolov10/v1.1",
    "platform": "rk3588",
    "version": "v1.1"
  },
  "ok": true
}

7.5.4 `model load`

预加载模型到服务内存，适合流水线高频推理场景。

bash

edgeengine model load global/people_count_yolov10 --version v1.1

示例输出：

json

{
  "command": "model.load",
  "data": {
    "algorithm": "yolov10",
    "engine": "auto",
    "model_name": "global/people_count_yolov10"
  },
  "ok": true
}

7.5.5 `model unload`

释放当前预加载的模型会话。

bash

# ✅ 正确用法（不带模型名）
edgeengine model unload

# ❌ 错误用法（v1.0.0 已知问题，会报错）
edgeengine model unload global/people_count_yolov10

错误示例：

The following argument was not expected: global/people_count_yolov10
Run with --help for more information.

这是 v1.0.0 的已知 CLI 参数解析问题：unload 子命令不接受位置参数。请始终使用无参的 edgeengine model unload。

7.6 `metrics get`

获取服务资源快照。

bash

edgeengine --format json metrics get

空闲时示例（tutorial_cases）：

json

{
  "command": "metrics.get",
  "data": {
    "active_sessions": 0,
    "cpu_usage_percent": 0.0,
    "disk_available_mb": 51662,
    "last_infer_latency_ms": 0.0,
    "npu_present": true,
    "npu_utilization_percent": 0.0,
    "npu_cores": [
      { "core_id": 0, "utilization_percent": 0.0 },
      { "core_id": 1, "utilization_percent": 0.0 },
      { "core_id": 2, "utilization_percent": 0.0 }
    ],
    "process_rss_mb": 17,
    "source": "edge_engine_service"
  },
  "ok": true
}

推理后示例（full_eval，NPU 有负载）：

json

{
  "data": {
    "npu_utilization_percent": 5.0,
    "process_rss_mb": 350,
    "last_infer_latency_ms": 0.0
  }
}

7.7 `schema`

输出命令树 JSON schema，供自省与文档生成。

bash

# ⚠️ 裸跑可能崩溃（UTF-8 异常）
edgeengine schema

# ✅ 推荐使用子路径
edgeengine schema model.infer
edgeengine schema modelhub.ensure
edgeengine schema service.status

裸跑异常：

libc++abi: terminating due to uncaught exception of type nlohmann::json_abi_v3_11_3::detail::type_error: [json.exception.type_error.316] invalid UTF-8 byte at index 24: 0x89

原因：完整 schema 输出中混入了二进制或非 UTF-8 字符（如 0x89 PNG 魔数），导致 JSON 解析器崩溃。子路径查询仅返回对应命令的 schema，可规避此问题。

八、进阶专题

8.2 与 edge_pipe 联调

edge_pipe 是 Edge Engine 最主要的调用方，通过 CvBackendSdk 经 IPC 推理。

8.2.1 联调架构

8.2.2 联调步骤

bash

# 1. 确认 Edge Engine、edge_pipe 服务已运行（系统开机自启）
edgeengine --format json service status

# 2. 确保模型
edgeengine --format json modelhub ensure global/people_count_yolov10 --version v1.1

# 3. 运行 edge_pipe 流水线
edgepipe pipeline run /system/etc/edge_pipe/pipelines/person_detect_yolov10_cloud.yaml

8.2.3 YAML 中的模型引用

yaml

- id: detect1
  type: edge.algorithm
  config:
    algorithm_id: yolov10
    model_name: global/people_count_yolov10
    model_version: v1.1
    engine: rknn

字段	说明
`algorithm_id`	必须与 manifest 中一致
`model_name`	`namespace/name` 格式
`model_version`	如 `v1.1`
`engine`	`rknn` 或 `onnx`

8.3 ONNX 后端对比实验

RK3588 上也可使用 generic 平台的 ONNX 模型（CPU 推理，无需 NPU）：

bash

# 解析 ONNX 路径
edgeengine model resolve global/people_count_yolov10 --engine onnx --format json

# CPU 推理（较慢，适合无 NPU 环境验证）
edgeengine --format json model infer global/people_count_yolov10 \
  --engine onnx \
  --input /system/etc/edge_pipe/fixtures/images/bus.jpg

对比项	rknn	onnx
硬件	NPU	CPU
典型延迟	~百毫秒级	秒级
平台目录	`rk3588/`	`generic/`
模型文件	`.rknn`	`.ort`

8.4 Whisper ASR 语音识别

8.4.1 原理

8.4.2 预置资源路径

资源	路径
Encoder RKNN	`/system/etc/edge_engine/whisper/whisper_encoder_base_20s.rknn`
英文词表	`/system/etc/edge_engine/whisper/vocab_en.txt`
中文词表	`/system/etc/edge_engine/whisper/vocab_zh.txt`
Mel 滤波器	`/system/etc/edge_engine/whisper/mel_filters.bin`

8.4.3 使用示例

bash

# 若 EdgeHub 提供 whisper 包
edgeengine --format json modelhub ensure global/whisper_base --version v1.0 2>/dev/null || true

# 推理（需 16kHz mono WAV）
edgeengine --format json model infer global/whisper_base \
  --engine rknn \
  --input /data/test/sample.wav

期望响应含 text 字段。

注意事项：

部分镜像未编入 whisper 插件，model infer 可能报插件不存在
输入建议：16 kHz、单声道、最长约 20 秒
CV 与 ASR 共用 model infer 接口，由 manifest 的 algorithm_id 区分

8.5 插件开发入门

8.5.1 IPlugin 接口

插件须实现 IPlugin（services/server/plugin/i_plugin.h）：

方法	说明
`GetName()`	插件名称
`Prepare()`	加载模型、分配资源
`SyncProcess()`	同步推理
`AsyncProcess()`	异步推理（可选）
`Release()`	释放资源

8.5.2 开发步骤

在 services/server/plugin/cv/ 或 asr/ 下创建插件目录
实现 IPlugin + 导出工厂函数
编写 {platform}/manifest.json 定义推理管道
在 BUILD.gn 中注册插件 target
编译：./build.sh --build-target edge_engine

参考实现：

CV：services/server/plugin/cv/yolov8/
ASR：services/server/plugin/asr/whisper/

8.5.3 与 ModelHub 集成

模型包 manifest 声明 algorithm_id → ModelHub 安装后 → PluginManager 按 ID 路由到对应 .so。

8.6 SDK 编程接入（libai_client）

除 CLI 外，应用可通过 libai_client SDK 直接 IPC 调用，生命周期与 3.2 节一致：

cpp

// 伪代码示意
AieClientInit();
Prepare(modelInfo);
SyncProcess(inputBuffer);
Release();
Destroy();

edge_pipe 的 CvBackendSdk 即基于此封装，业务应用可通过 SDK 接入。

8.7 性能优化建议

场景	建议
流水线高频推理	启动前 `model load`，结束後 `model unload`
降低首帧延迟	服务启动后预热一次 `model infer`
磁盘不足	`modelhub uninstall` 清理旧版本
监控瓶颈	对比 `metrics get` 的 `last_infer_latency_ms` 与 NPU 利用率
批量图片	复用 load 会话，避免每张图重新加载

九、常见问题

9.1 诊断流程图

9.2 常见问题速查

现象	可能原因	解决方案
`available: false`	服务未正常运行	按 2.3 节确认；见第九章，必要时 `service_control restart edge_engine_service`
`model not found`	未安装模型	`edgeengine modelhub ensure global/people_count_yolov10 --version v1.1`
`ensure_failed` + HTTP 错误	网络或 EdgeHub 不可达	检查网络、`persist.ai_engine.edgehub.url`
EdgeHub 401	Token 未配置或过期	`param set persist.ai_engine.edgehub.token "..."`
`engine rknn failed`	平台目录缺失	`model resolve` 确认 `rk3588/manifest.json` 存在
`detection_count: 0`	输入路径错误或图片损坏	`ls -l <input_path>`
`unload` 报 unexpected argument	v1.0.0 已知问题	使用 `edgeengine model unload`（不带模型名）
`edgeengine schema` 崩溃	UTF-8 解析异常	改用 `edgeengine schema model.infer` 等子路径
推理极慢	使用 onnx 或未预加载	改用 `--engine rknn`，或先 `model load`
NPU 利用率始终 0	空闲或驱动未上报	推理时再采样 `metrics get`

9.3 已知问题（v1.0.0）

ID	问题	规避方法	状态
K-001	`model unload <name>` 不接受模型名参数	使用 `edgeengine model unload`	已知
K-002	`edgeengine schema` 裸跑 UTF-8 异常退出	使用 `edgeengine schema <subpath>`	已知
K-003	`modelhub list` 部分字段 `name`/`namespace` 为空	以 `model_name` 为准	已知
K-004	`people_count_yolov8` v1.0 在 EdgeHub 不可用	使用 `people_count_yolov10` v1.1	预期行为

9.4 日志与进一步诊断

bash

# 查看服务进程
ps -ef | grep edge_engine_service

# 查看模型目录
ls -la /data/edge_engine/models/
cat /data/edge_engine/models/.registry.json

# 查看插件配置
cat /system/etc/edge_engine_plugin.ini

# 确认测试图存在
ls -l /system/etc/edge_pipe/fixtures/images/bus.jpg

# EdgeHub 配置
param get persist.ai_engine.edgehub.url
param get persist.ai_engine.edgehub.token
cat /data/edge_engine/edgehub.conf 2>/dev/null

9.5 重置 ModelHub（慎用）

bash

# 停止服务
service_control stop edge_engine_service

# 备份后清空（会删除所有已安装模型）
mv /data/edge_engine/models /data/edge_engine/models.bak.$(date +%s)
mkdir -p /data/edge_engine/models

# 重启并重新 ensure
service_control start edge_engine_service
edgeengine --format json modelhub ensure global/people_count_yolov10 --version v1.1

十、附录

附录 A：命令速查表

场景	命令
查看版本	`edgeengine --version`
服务状态	`edgeengine --format json service status`
安装/确保模型	`edgeengine --format json modelhub ensure global/people_count_yolov10 --version v1.1`
列出模型	`edgeengine --format json modelhub list`
模型详情	`edgeengine --format json modelhub info global/people_count_yolov10 --version v1.1`
解析路径	`edgeengine model resolve global/people_count_yolov10 --engine rknn --format json`
图片推理	`edgeengine --format json model infer global/people_count_yolov10 --engine rknn --input /system/etc/edge_pipe/fixtures/images/bus.jpg`
预加载	`edgeengine model load global/people_count_yolov10 --version v1.1`
卸载会话	`edgeengine model unload`
资源监控	`edgeengine --format json metrics get`
命令 schema	`edgeengine schema model.infer`

附录 B：练手 checklist

步骤	做什么	怎么确认
1	`hdc shell` 连板子	`edgeengine --version` 有输出
2	确认服务就绪	`service status` → `available: true`
3	安装模型	`modelhub ensure global/people_count_yolov10 -v v1.1` 成功
4	图片推理	`model infer` + bus.jpg → `detection_count: 5`
5	列出模型	`modelhub list` → `count >= 1`
6	预加载与卸载	`model load` 后 `model unload` 无报错
7	edge_pipe 联调（可选）	流水线跑通人员检测

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

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

文档	路径
使用指南总览	/training/

附录 D：JSON 响应通用格式

成功时 ok 为 true，data 为业务字段；失败时 ok 为 false，含 error 与 message。

Edge Engine 新手教程 ​

目录 ​

一、开始之前 ​

1.1 这份文档帮你做什么 ​

1.2 你需要准备 ​

1.3 CLI 用法 ​

1.4 术语速查 ​

二、连接开发板 ​

2.1 硬件要求 ​

2.2 连接开发板 ​

2.3 确认 Edge Engine 服务已运行 ​

2.4 第一步验证 ​

2.5 EdgeHub 网络与鉴权（可选） ​

三、快速开始 ​

3.1 一键流程 ​

3.2 期望结果摘要 ​

3.3 推理结果说明 ​

3.4 快速开始常见问题 ​

四、从 EdgeHub 安装模型 ​

4.1 浏览模型市场 ​

4.2 在线安装流程 ​

4.3 鉴权失败处理 ​

五、工作原理 ​

5.1 整体架构 ​

5.2 一次推理怎么走 ​

5.3 推理管道（manifest） ​

5.4 ModelHub 与 EdgeHub ​

5.5 模型标识 ​

5.6 与其他服务的关系 ​

六、功能一览 ​

七、命令手册 ​

7.1 命令树总览 ​

7.2 全局选项 ​

7.3 service status ​

7.4 modelhub 子命令 ​

7.4.1 modelhub install ​

7.4.2 modelhub ensure（推荐） ​

7.4.3 modelhub list ​

7.4.4 modelhub info ​

7.4.5 modelhub uninstall ​

7.4.6 modelhub packages ​

7.5 model 子命令 ​

7.5.1 model infer ​

7.5.2 model manifest ​

7.5.3 model resolve ​

7.5.4 model load ​

7.5.5 model unload ​

7.6 metrics get ​

7.7 schema ​

八、进阶专题 ​

8.2 与 edge_pipe 联调 ​

8.2.1 联调架构 ​

8.2.2 联调步骤 ​

8.2.3 YAML 中的模型引用 ​

8.3 ONNX 后端对比实验 ​

8.4 Whisper ASR 语音识别 ​

8.4.1 原理 ​

8.4.2 预置资源路径 ​

8.4.3 使用示例 ​

8.5 插件开发入门 ​

8.5.1 IPlugin 接口 ​

8.5.2 开发步骤 ​

8.5.3 与 ModelHub 集成 ​

8.6 SDK 编程接入（libai_client） ​

8.7 性能优化建议 ​

九、常见问题 ​

9.1 诊断流程图 ​

9.2 常见问题速查 ​

9.3 已知问题（v1.0.0） ​

9.4 日志与进一步诊断 ​

9.5 重置 ModelHub（慎用） ​

十、附录 ​

附录 A：命令速查表 ​

附录 B：练手 checklist ​

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

附录 D：JSON 响应通用格式 ​

Edge Engine 新手教程

目录

一、开始之前

1.1 这份文档帮你做什么

1.2 你需要准备

1.3 CLI 用法

1.4 术语速查

二、连接开发板

2.1 硬件要求

2.2 连接开发板

2.3 确认 Edge Engine 服务已运行

2.4 第一步验证

2.5 EdgeHub 网络与鉴权（可选）

三、快速开始

3.1 一键流程

3.2 期望结果摘要

3.3 推理结果说明

3.4 快速开始常见问题

四、从 EdgeHub 安装模型

4.1 浏览模型市场

4.2 在线安装流程

4.3 鉴权失败处理

五、工作原理

5.1 整体架构

5.2 一次推理怎么走

5.3 推理管道（manifest）

5.4 ModelHub 与 EdgeHub

5.5 模型标识

5.6 与其他服务的关系

六、功能一览

七、命令手册

7.1 命令树总览

7.2 全局选项

7.3 `service status`

7.4 `modelhub` 子命令

7.4.1 `modelhub install`

7.4.2 `modelhub ensure`（推荐）

7.4.3 `modelhub list`

7.4.4 `modelhub info`

7.4.5 `modelhub uninstall`

7.4.6 `modelhub packages`

7.5 `model` 子命令

7.5.1 `model infer`

7.5.2 `model manifest`

7.5.3 `model resolve`

7.5.4 `model load`

7.5.5 `model unload`

7.6 `metrics get`

7.7 `schema`

八、进阶专题

8.2 与 edge_pipe 联调

8.2.1 联调架构

8.2.2 联调步骤

8.2.3 YAML 中的模型引用

8.3 ONNX 后端对比实验

8.4 Whisper ASR 语音识别

8.4.1 原理

8.4.2 预置资源路径

8.4.3 使用示例

8.5 插件开发入门

8.5.1 IPlugin 接口

8.5.2 开发步骤

8.5.3 与 ModelHub 集成

8.6 SDK 编程接入（libai_client）

8.7 性能优化建议

九、常见问题

9.1 诊断流程图

9.2 常见问题速查

9.3 已知问题（v1.0.0）

9.4 日志与进一步诊断

9.5 重置 ModelHub（慎用）

十、附录

附录 A：命令速查表

附录 B：练手 checklist

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

附录 D：JSON 响应通用格式