Doni/OrangePi3588Media

Fork 0

sladro acd3815288

CI / host-build (push) Waiting to run

Details

CI / rk3588-cross-build (push) Waiting to run

Details

性能优化

2026-01-12 15:27:38 +08:00

9.2 KiB

Raw Blame History

PRD ④ 控制端配置窗口（GUI）对接方案（templates/instances-only）

适用版本：V1（2026-01）

范围：仅控制端 GUI/managerd 如何调用设备端 rk3588-agent。

本项目中已在 agent + media-server 实现本文档所需能力。

不包含配置程序（前端/后端）具体 UI 代码实现细节。

1. 目标

让非技术人员通过 GUI 完成：

新增/删除一路摄像头通道（channel）
选择流程模板（转码/YOLO/报警/人脸检测/人脸识别）并配置参数
一键应用配置（写盘 + reload；失败自动 rollback）
人脸库（SQLite face_gallery.db）上传并无需重启立即生效

2. 核心约束（必须遵守）

GUI 只支持 templates/instances 模式：
- 不提供手写 graphs 的编辑。
- 运行态 graphs 只读查看（用于监控/联调）。
人脸数据通过上传整个 SQLite 文件：face_gallery.db。
人脸库默认路径：./models/face_gallery.db。
- 要求部署时 media-server 的工作目录 与 agent.models_dir 关系合理，使该相对路径能找到 agent 上传的 db。
- 推荐：media_server_process.work_dir=<rk3588sys 根目录> 且 agent.models_dir=<work_dir>/models。

3. 鉴权与错误处理

3.1 鉴权

Header：X-RK-Token: <token>
写接口（会写盘/改状态）必须鉴权。
读接口默认可不鉴权；若设备端配置 agent.require_token_for_read=true，则读接口也必须鉴权。

3.2 统一错误返回

成功：2xx，一般为 {"ok":true,...} 或业务 JSON
失败：4xx/5xx，返回 {"error":"..."}

常见 HTTP：

401：unauthorized
400：validation failed / invalid json
404：not found
409：conflict
500：internal error

4. GUI 页面与调用流程

4.1 设备详情页（只读）

设备信息：GET /v1/info
运行态通道摘要：GET /v1/graphs
单通道详情（可选）：GET /v1/graphs/{name}
日志：GET /v1/logs/recent?limit=200

4.2 通道配置页（核心：instances）

4.2.1 初始化

获取 schema（渲染表单）：GET /v1/config/ui/schema
获取当前 state（回显）：GET /v1/config/ui/state

GUI 侧以 instances[] 为“通道列表”。

4.2.2 校验/预览（dry-run）

用户编辑完成后：

POST /v1/config/ui/plan

generated_config：生成出来的 root config（可用于预览/导出）
diff：added/removed/changed（实例级别）

说明：plan 的校验是“基础校验”（必填字段/模板名/实例名唯一）。真正的构图/插件/模型加载等校验发生在 apply → media-server reload 阶段。

4.2.3 应用配置

POST /v1/config/ui/apply

行为：

agent 生成新的 root config（只包含 global/queue/templates/instances）
写盘到 agent.config_path
调用 media-server reload
reload 失败则自动 rollback 并返回 500

4.2.4 回滚（手动）

POST /v1/media-server/rollback

回滚语义：回滚到“上一次成功的源配置”（保留 templates/instances，不会被 expanded 覆盖），便于 GUI 二次编辑。

4.3 人脸库管理页

4.3.1 上传人脸库

PUT /v1/face-gallery
Content-Type：application/octet-stream
Body：SQLite 文件二进制（face_gallery.db）

保存位置：<agent.models_dir>/face_gallery.db

4.3.2 立即生效（无需重启）

POST /v1/face-gallery/reload

行为：

agent 遍历所有 graphs，找到 type==ai_face_recog 的节点
对每个节点下发 runtime config patch：bump gallery.reload_seq
节点收到后会重新加载 SQLite db

5. Agent 对外 API（控制端对接清单）

Base：http://<device_ip>:<agent_port>（默认 9100）

5.1 设备信息

`GET /v1/info`

用于设备列表/详情。

5.2 运行态（只读代理）

`GET /v1/graphs`

`GET /v1/graphs/{name}`

`GET /v1/logs/recent?limit=200`

5.3 配置文件（root config）

`GET /v1/config`

返回 agent.config_path 对应 JSON（用于导出/高级查看）。

`PUT /v1/config`

上传完整 root config JSON（写盘 + reload；失败自动 rollback）。

5.4 语义化配置（GUI 推荐使用）

`GET /v1/config/ui/schema`

返回：可选模板列表 + 字段 schema（类型/默认/必填）。

`GET /v1/config/ui/state`

返回：当前 config 映射到 GUI state（主要是 instances[]）+ 内置模板列表。

`POST /v1/config/ui/plan`

输入 desired state（instances 列表），返回生成 config 与 diff。

`POST /v1/config/ui/apply`

同 plan，但会写盘并 reload（失败自动 rollback）。

5.5 模型管理（可选，但建议 GUI 支持）

`PUT /v1/models/{name}`

上传模型（.rknn），返回可引用的 path。

`GET /v1/models`

列出已上传模型（包含 name/path/sha256/mtime_ms）。

5.6 人脸库

`GET /v1/face-gallery`

返回当前 db 文件信息（exists/size/mtime/path）。

`PUT /v1/face-gallery`

上传 face_gallery.db。

`POST /v1/face-gallery/reload`

让所有 ai_face_recog 节点热加载新 db。

6. `config/ui/*` 的数据结构（控制端直接照此传）

6.1 `POST /v1/config/ui/plan|apply` Request

{
  "global": { },
  "queue": { },
  "instances": [
    {
      "name": "cam1",
      "template": "face_det_recog_rtsp_hls",
      "params": {
        "url": "rtsp://10.0.0.5:8554/cam",
        "fps": 30,
        "src_w": 1280,
        "src_h": 720,

        "det_model_path": "./models/RetinaFace_mobile320.rknn",
        "recog_model_path": "./models/mobilefacenet_arcface.rknn",
        "gallery_path": "./models/face_gallery.db",

        "gop": 60,
        "bitrate_kbps": 2000,
        "rtsp_port": 8555,
        "hls_path": "./web/hls/cam1/index.m3u8"
      }
    }
  ]
}

说明：

global/queue 可省略：agent 会沿用当前 config 中的值。
instances 为全量期望状态：控制端应把当前列表 + 修改后的列表一起提交。
当前实现会生成新的 root config（只包含 global/queue/templates/instances），不会保留 graphs。

6.2 `POST /v1/config/ui/plan|apply` Response

{
  "ok": true,
  "generated_config": { "global":{}, "queue":{}, "templates":{}, "instances":[] },
  "diff": { "added": ["cam1"], "removed": [], "changed": [] },
  "warnings": []
}

7. 内置流程模板与必填参数表

模板名来自 GET /v1/config/ui/schema 的 templates[]。

7.1 `transcode_rtsp_hls`

必填：url
常用：fps,src_w,src_h,gop,bitrate_kbps,rtsp_port,hls_path

7.2 `yolo_rtsp_hls`

必填：url, model_path

7.3 `yolo_alarm_minio`

必填：url, model_path, minio_endpoint, minio_bucket, minio_ak, minio_sk
常用：cooldown_ms（默认 3000）

7.4 `face_det_rtsp_hls`

必填：url, det_model_path

7.5 `face_det_recog_rtsp_hls`

必填：url, det_model_path, recog_model_path
默认：gallery_path=./models/face_gallery.db，thr_accept=0.45，thr_margin=0.05

8. 性能调优参数（可选，建议 GUI 以“高级设置”方式暴露）

8.1 `preprocess`（AI 分支减拷贝 / RGA 并发）

dst_packed：bool，默认 false。
- 说明：当 dst_format 为 rgb/bgr 时，若开启则输出紧凑 packed（stride = width * 3），可避免下游（如 ai_yolo）对齐 stride 导致的逐行 memcpy。
rga_max_inflight：int，默认 0（表示不在配置里覆盖全局值）。
- 说明：RGA 全局并发上限（原先固定为 2）。
- 备注：也可通过环境变量 RK3588_RGA_MAX_INFLIGHT 设置。

8.2 `publish/storage`（一次编码，多处复用）

publish.attach_encoded_meta：bool，默认 true（当 publish 有下游 output_queues 时）。
- 说明：将已编码视频包（含 codec extradata/pts/key）挂在 frame.user_meta，供下游复用（例如报警 clip、storage 复用码流）。
storage.reuse_encoded_meta：bool，默认 true。
- 说明：若收到 EncodedVideoFrameMeta，storage 将直接 remux 写文件（避免再次 MPP 编码）；若未收到则保持原逻辑（MPP 编码录制）。

8.3 推理并发（环境变量，部署侧配置）

RK3588_RKNN_CTX_POOL_SIZE：默认 3。
- 说明：同一模型创建的 RKNN context 数量（多路同模型推理可并发，避免被单 context 串行化）。

9. 人脸库路径对齐建议（避免“上传了但识别不到”）

默认推荐（最省事）：

media-server work_dir：/opt/rk3588sys
agent.models_dir：/opt/rk3588sys/models
ai_face_recog.gallery.path：./models/face_gallery.db

若你们的 work_dir/models_dir 不是这种关系：

控制端在 instances params 里把 gallery_path 设置为绝对路径（例如 /opt/rk3588sys/models/face_gallery.db）。

10. 验收标准

GUI 新增通道 → apply 成功后：GET /v1/graphs 出现该通道；GET /v1/graphs/{name} 能看到节点链路。
删除通道 → apply 成功后 graphs 中消失。
上传 face_gallery.db → POST /v1/face-gallery/reload 后无需重启即可生效。
apply 失败时：自动 rollback，且 rollback 后 config 仍为 templates/instances 源结构。

9.2 KiB Raw Blame History Unescape Escape

PRD ④ 控制端配置窗口（GUI）对接方案（templates/instances-only）

1. 目标

2. 核心约束（必须遵守）

3. 鉴权与错误处理

3.1 鉴权

3.2 统一错误返回

4. GUI 页面与调用流程

4.1 设备详情页（只读）

4.2 通道配置页（核心：instances）

4.2.1 初始化

4.2.2 校验/预览（dry-run）

4.2.3 应用配置

4.2.4 回滚（手动）

4.3 人脸库管理页

4.3.1 上传人脸库

4.3.2 立即生效（无需重启）

5. Agent 对外 API（控制端对接清单）

5.1 设备信息

GET /v1/info

5.2 运行态（只读代理）

GET /v1/graphs

GET /v1/graphs/{name}

GET /v1/logs/recent?limit=200

5.3 配置文件（root config）

GET /v1/config

PUT /v1/config

5.4 语义化配置（GUI 推荐使用）

GET /v1/config/ui/schema

GET /v1/config/ui/state

POST /v1/config/ui/plan

POST /v1/config/ui/apply

5.5 模型管理（可选，但建议 GUI 支持）

PUT /v1/models/{name}

GET /v1/models