Developer Docs · Edge Runtime

端侧运行时与模型部署

模型不是拷进板子就能跑的文件，它是系统的一部分：有固定目录、有权限、有双槽、有健康检查。本页写清运行时组件、模型产物与校验阈值，上板失败时按最后一节的表逐条排查。

适用版本hy-rt v2.4.1 · hy-tc v2.3.0 · 驱动包 2.4.0

适用板型HY-Edge X1（NPU-v2）· HY-Gateway G3 · HY-MCU M55

最近更新2026-09-05 · 对应 hy-rt v2.4.1

反馈入口contact@huayuniot.com.cn · 1 个工作日

Components · 运行时组成

四个常驻组件，各有明确职责

排障时先确认是哪一层的问题：驱动没起来、运行时没起来，还是应用没接上。看端口与 systemd 状态最快。

组件	职责	资源占用	对外接口	状态检查
`hy-npu-daemon`	NPU 固件加载、上下文与时间片调度	常驻约 12 MB	本地 unix socket	`systemctl status hy-npu-daemon`
`hy-rt`	模型加载、推理服务、批处理	cgroup 上限 256 MB	TCP 5100（本机/内网）	`hy-rt --version`、`hy-rt status`
`hy-profiler`	逐算子延迟、NPU 利用率、DDR 带宽采集	按需启动	命令行	`hy-profiler --duration 10s`
`hy-ota-agent`	模型与固件升级、断点续传、双槽切换	常驻约 8 MB	出方向 443	`hy-ota-agent status`

端口约定：5100 只监听内网与回环地址，默认不暴露到公网；需要跨网调用时通过网关的反向代理统一出入口，不要在设备上直接开放端口。

Artifacts · 目录与产物约定

路径固定、权限固定、台账固定

Rootfs 出厂时已预置目录与权限，应用不需要关心路径细节，但排障与升级依赖这套约定。

board — 目录结构出厂预置

/data/models/
├─ current -> a/                 # 原子软链，切换点
├─ a/  yolov8n_npu-v2.hyb
│      yolov8n.json
├─ b/  （上一版本，回退用）
└─ manifest.json                 # 版本台账

/data/samples/                   # 校验用样例
/data/hy/collect/                # 采集配置
/data/hy/logs/                   # 运行日志（滚动 7 天）

# 权限与标记
# /data/models  hy_npu:hy_npu 770
# SELinux 标记   hy_model_t

manifest.json 里记什么

/data/models/manifest.json版本台账

{
  "active": "a",
  "entries": [
    {
      "slot": "a",
      "name": "yolov8n_npu-v2.hyb",
      "sha256": "9f21c4...17ae",
      "target": "npu-v2",
      "input": [1, 3, 640, 640],
      "quant": "int8-per-channel",
      "pipeline_id": "pl_20260905_0417",
      "published_at": "2026-09-05T11:02:19Z"
    }
  ]
}

双槽规则：升级只写非活跃槽，写完校验通过再切 current 软链；软链切换是原子操作，回退耗时 <1 s，不需要重启设备，也不会丢正在处理的请求。

Pipeline · 五段产物与校验

每一段都有文件名和校验方式

与模型工具链五段一一对应。每段可单独执行，也可用 pipeline run 串联；失败可回退到上一段，产物按哈希缓存。

阶段	产物	校验方式	通过阈值
01 量化 Quantize	`model_int8.onnx` + `quant_report.html`	校准集逐层 SNR，报告标红层	mAP 损失 <1%；无塌陷层（余弦 <0.95）
02 编译 Compile	`<name>_<target>.hyb` + `perf.json`	算子融合数与内存规划对比	融合后算子数下降；内存复用生效
03 仿真 Simulate	`sim_report.json`	数值余弦 + 时序估算（不上板）	余弦均值 >0.985、SNR >28 dB
04 在环 HIL	`hil_report.json` + 逐帧日志	真机 profiler 与仿真对齐	mAP 差 <0.008；p50 <4 ms（X1）
05 OTA	`ota_<ver>_diff.bin` + 发布单	签名校验 + 灰度批次到达率	到达率 ≥99.5%；失败自动回滚

host — 逐段执行可断点续跑

# 01 量化（PTQ，500 张校准集，逐通道）
huayun quantize \
  --model yolov8n.onnx --calib coco_calib_500/ \
  --precision int8 --metric kl --per-channel --export-report
#  → yolov8n_int8.onnx + quant_report.html

# 02 编译到 NPU-v2
huayun compile \
  --model yolov8n_int8.onnx --target npu-v2 --opt O2 \
  --memory-plan reuse --dump-perf
#  → yolov8n_npu-v2.hyb + perf.json

# 03 主机侧仿真（不上板）
huayun simulate --artifact yolov8n_npu-v2.hyb \
  --samples val_200/ --mode numeric+timing

host — 在环与一键流水线真机

# 04 在环真测并落盘到设备
huayun hil run \
  --artifact yolov8n_npu-v2.hyb \
  --device npu-v2@192.168.1.10 \
  --samples val_200/ --profile --deploy
#  HIL p50 3.18ms  p95 3.42ms  NPU 87%  DDR 1.2GB/s
#  mAP Δ -0.002 vs 仿真   HIL 通过 184/200

# 一键串联（等价于上面四段）
huayun pipeline run \
  --model yolov8n.onnx --calib coco_calib_500/ \
  --target npu-v2 --board hy-edge-x1 \
  --hil auto --ota-diff --from v2.3.0

版本不匹配时：hy-rt 低于 2.4.1 无法加载 2.3.0 以上 hy-tc 编译的 .hyb（报 unsupported artifact version）。先升运行时再升模型；反过来会出现「模型推上去了、设备不认」的回退。

Run as Service · 常驻服务

用 systemd 管起来，别用脚本拉起

推理进程要开机自启、失败重试、内存封顶。unit 文件里这三项都写清楚，现场重启就不用人工介入。

/etc/systemd/system/hy-rt.service出厂预置

[Unit]
Description=HuaXin Model Runtime
After=hy-npu-daemon.service network.target
Requires=hy-npu-daemon.service

[Service]
Type=simple
User=hy_npu
Group=hy_npu
ExecStartPre=/usr/bin/hy-npu-test --quick
ExecStart=/usr/bin/hy-rt serve \
  --model /data/models/yolov8n_npu-v2.hyb \
  --config /data/models/yolov8n.json \
  --port 5100 --workers 2
Restart=on-failure
RestartSec=3
MemoryMax=256M

[Install]
WantedBy=multi-user.target

board — 调用与观测应用侧

# 单帧推理（排障用）
hy-rt run --model /data/models/yolov8n_npu-v2.hyb \
  --input /data/samples/bus.jpg --dump result.json
jq '.latency_ms, .boxes[:1]' result.json

# HTTP 调用（长驻服务）
curl -sS -X POST http://127.0.0.1:5100/v1/models/yolov8n/infer \
  -H "Content-Type: application/json" \
  -d '{"input":"/data/samples/bus.jpg"}'

# 资源与健康
hy-rt status
systemctl show hy-rt -p MemoryCurrent
cat /proc/meminfo | head -3

资源项	建议值	说明
单进程内存上限	256 MB	推理期峰值实测 <50 MB（YOLOv8n，1 路 640×640）
`/data` 预留	≥ 2 × 最大模型体积	保证双槽 + 一份升级包同时存在
工作线程	2（4 核 A55）	再多会与采集进程争抢 CPU
双缓冲	开启	NPU 与 CPU 异构重叠，实测延迟再降约 12%
模型并发	≤ 2 个模型	NPU 时间片调度，超过后单帧延迟线性上升

Acceptance · 验收阈值

仿真对齐在环，在环对齐阈值

这四项是模型能不能上产线的判定标准。任一项不达标，先回溯量化，不要直接调调度参数掩盖精度问题。

工位上双屏显示一条曲线与样本图集，一位工程师用笔指向曲线、另一位在旁指向同一屏，桌面上是通着电并带散热片的开发板和叠放的打印样本页 — 量化复核现场：逐层误差曲线与校准样本一一对照，标红层回退 FP16。

指标	阈值	典型实测（YOLOv8n INT8）
余弦相似度（均值）	> 0.985	0.992
SNR	> 28 dB	31.4 dB
mAP 差（在环 − 量化）	< 0.008	−0.002
单帧延迟 p50（X1 / NPU-v2）	< 4 ms	3.18 ms
单帧延迟 p95	< 5 ms	3.42 ms
推理进程内存峰值	< 50 MB	41 MB

调优顺序：先量化（敏感层回退 FP16、校准集补难例），再编译（--opt O3、开启 Winograd），最后调度（双缓冲、异构重叠）。顺序颠倒会出现精度与性能互相掩盖，回归时无法定位。

Failure Handling · 失败处置

上板失败按这张表逐条排

从驱动到模型，现象与命令一一对应。每条都给出先执行哪条命令，避免一上来就重新编译整个流水线。

现象	根因	先执行	处置
报 `ENODEV`	NPU 驱动未载入或电源域未开	`dmesg \| grep hy_npu`	`hy-pm npu on`；确认 `CONFIG_HY_NPU=m`
`unsupported artifact version`	运行时版本低于编译工具链	`hy-rt --version`	把 hy-rt 升到 ≥2.4.1 后重推模型
`signature mismatch`	模型文件被改动或未签名	`hy-rt verify --model *.hyb`	重新出包并保留 SHA256 记录
首帧延迟明显高于仿真	未预热、DDR 带宽被采集进程占用	`hy-rt bench --warmup 3`	开启双缓冲；采集周期错峰
推理结果整体偏移	输入预处理（归一化/尺寸）与训练不一致	`jq .input` 比对 manifest	按元信息修正预处理，不调量化参数
偶发结果为空	后处理阈值过高或输入全黑	`hy-profiler --duration 10s`	回灌异常帧：`huayun hil replay --case fail_07.jpg`

运维、OTA 与 SLA灰度批次、失败码与回滚流程 BSP 移植与适配驱动与运行时的分层升级边界 版本与兼容性说明BSP / 运行时 / 工具链的最低搭配版本

本文档由平台研发组维护，最近复核 2026-09-05。精度或性能与本文阈值不一致时，请附 quant_report.html、hil_report.json 与 hy-profiler 导出文件发至 contact@huayuniot.com.cn。

2026-09-05：新增 unsupported artifact version 与运行时版本的对应关系。
2026-08-21：补充双槽软链切换与 manifest 字段说明。