2026-09-10 15:11:34 +08:00
2026-09-10 15:11:34 +08:00
2026-09-10 15:11:34 +08:00
2026-09-10 15:11:34 +08:00
2026-09-10 15:11:34 +08:00
2026-09-10 15:11:34 +08:00
2026-09-10 15:11:34 +08:00
2026-09-10 15:11:34 +08:00
2026-09-10 15:11:34 +08:00

onboard_inference — 板端推理调度系统

基于 RabbitMQ 消息队列的板端(边缘设备)AI 模型推理调度系统。通过消息队列接收推理任务,动态挂载 JuiceFS 文件系统获取数据,仅支持 Docker 容器方式执行推理,并将结果回调给上游系统。

专为 RDK X5(bayese)和 RDK S100(nashem)ARM64 平台设计。


1. 项目概述

1.1 解决什么问题

在边缘设备(如 RDK X5、S100)上运行 AI 推理任务时,面临以下挑战:

  • 推理任务由云端统一下发,需要一种可靠的通信机制
  • 模型文件和输入数据存储在分布式文件系统(JuiceFS)中,需要动态挂载使用
  • 推理通过 Docker 容器方式执行,保证环境隔离和一致性
  • 多块板子需要协同工作,共享任务队列,实现水平扩展

本系统完美解决以上问题。

1.2 核心特性

特性 说明
消息队列驱动 基于 RabbitMQ 实现任务的接收和结果的回调
多板水平扩展 多块板子共同消费同一队列,RabbitMQ round-robin 自动负载均衡
动态 JuiceFS 挂载 任务执行前自动挂载所需路径,执行后自动卸载
Docker 容器执行 推理任务强制使用 Docker 容器,保证环境一致性
多租户隔离 通过 token + subdir 实现多租户数据隔离
Supervisor 守护 进程异常退出后自动重启,保证服务持续运行
完整链路测试 提供端到端测试用例,覆盖从数据上传到结果验证全流程

1.3 平台兼容性

平台 芯片代号 模型格式 推理镜像
RDK X5 bayese .bin ccr-29eug8s3-pub.cnc.bj.baidubce.com/public/hrt_perf_bayese:v1.24.5
RDK S100 nashem .hbm ccr-29eug8s3-pub.cnc.bj.baidubce.com/public/hrt_perf_nashem:v3.7.3

重要: 消费者集群必须同构。X5 和 S100 的 BPU 指令集不兼容,模型格式不同(.bin vs .hbm),不能混用。


2. 系统架构

2.1 架构图

上游系统(任务发布方)
        │
        │  发布推理任务消息(JSON)
        ▼
  RabbitMQ Exchange  (onboard.exchange.dev)
        │
        │  routing_key: onboard.infer.task.dev
        ▼
  任务队列 (onboard.infer.task.dev)
        │
        ▼
  worker_infer_consumer.py  ← supervisord 守护
        │
        ├─ 步骤1  解析任务参数
        ├─ 步骤2  挂载 JuiceFS(juicefs-private)
        ├─ 步骤3  执行 Docker 容器推理
        └─ 步骤4  卸载挂载点(finally 块,无论成败都执行)
                │
                ▼
        回调队列 (onboard.infer.result.*)
                │
                ▼
        上游系统(结果接收方)

2.2 多板水平扩展

本系统设计为在多块完全等价的板子上同时运行。每块板子上部署一个 worker_infer_consumer 进程,所有板子共同消费同一个 RabbitMQ 任务队列。

上游系统
   │
   │  发布推理任务
   ▼
RabbitMQ 任务队列
   │
   ├──► 板子 A  worker_infer_consumer
   ├──► 板子 B  worker_infer_consumer
   ├──► 板子 C  worker_infer_consumer
   └──► 板子 N  worker_infer_consumer

RabbitMQ 的 round-robin 分发机制(prefetch_count=1)天然保证负载均衡:每块板子同一时刻只处理一条任务,空闲的板子自动接取下一条,无需任何额外的调度逻辑。新增板子只需部署相同的服务并连接同一个 MQ,即可线性扩展吞吐量。


3. 项目结构

onboard_inference/
├── backend/                         # 后端核心代码
│   ├── config/
│   │   └── config.py               # 配置管理,根据 APP_ENV 加载 .env 文件
│   ├── tasks/
│   │   ├── worker_infer_consumer.py  # RabbitMQ 消费者入口(长驻进程)
│   │   └── onboard_inference_task.py # 推理任务核心逻辑
│   ├── utils/
│   │   ├── rabbitmq.py             # RabbitMQ 同步客户端封装
│   │   ├── juicefs_utils.py       # JuiceFS 挂载/卸载管理
│   │   ├── docker_utils.py         # Docker 容器执行封装
│   │   └── logger.py               # 日志配置(JSON 结构化日志)
│   ├── private.py                  # JuiceFS token(敏感信息,不提交版本控制)
│   ├── requirements.txt            # Python 依赖
│   └── requirements.lock           # 锁定版本依赖
├── deploy/
│   └── config/supervisor/
│       └── onboard_worker_dev.conf # Supervisor 守护进程配置
├── scripts/                        # 运维脚本
│   ├── jfs-install.sh              # 安装商业版 juicefs-private
│   ├── jfs-workspace.sh            # JuiceFS 挂载/卸载/文件增删改查
│   ├── test-jfs.sh                # 完整链路测试
│   ├── check-dev-env.sh            # 环境检查与清理
│   ├── install_env_by_uv.sh        # 使用 uv 安装 Python 依赖
│   └── docker-image-cleanup.sh     # 清理过期 Docker 镜像
├── testcases/                      # 端到端测试用例
│   ├── TESTCASES.md               # 测试用例详细说明
│   ├── run_all.sh                 # 批量运行入口
│   ├── tc_01_x5_single_perf.py    # X5 单任务性能基准
│   ├── tc_02_x5_multi_model_perf.py # X5 单任务多模型批量
│   ├── tc_03_s100_single_perf.py  # S100 单任务性能基准
│   ├── tc_04_x5_burst.py         # X5 高爆发并发压测
│   └── tc_05_s100_burst.py        # S100 高爆发并发压测
└── .env.board_dev                  # 配置:云上 RabbitMQ + 云上 JuiceFS

4. 快速开始

4.1 环境要求

依赖 说明
Python 3.8+ 运行后端代码
RabbitMQ 消息代理(云服务或本地 Docker 自建)
juicefs-private JuiceFS 商业版客户端
Docker 容器执行模式必需,Daemon 必须运行
conda 环境 conda activate on_board_inference

4.2 安装 Python 依赖

# 使用 uv 安装(推荐)
bash scripts/install_env_by_uv.sh

# 或使用 pip
pip install -r backend/requirements.txt

4.3 安装 JuiceFS

# 安装商业版 juicefs-private(需要 root)
sudo bash scripts/jfs-install.sh

# 验证安装
juicefs-private -h

4.4 准备 RabbitMQ

选择以下一种方式:

方式一:本地自建(一键搞定)

sudo bash scripts/rabbitmq-setup.sh

脚本自动检测并处理:

  • 容器已运行 → 跳过
  • 容器已停止 → 自动启动
  • 容器不存在 → 自动创建
  • 所有步骤幂等,第二次执行秒完成

方式二:使用云上服务 直接在 .env.board_dev 中填入对应的 RABBITMQ_URI 地址,无需额外操作。

4.5 启动消费者

# 连接云上 MQ(生产/联调用)
APP_ENV=board_dev python3 backend/tasks/worker_infer_consumer.py

4.6 运行测试验证

# Docker 模式(使用真实镜像)
DOCKER_IMAGE=ccr-29eug8s3-pub.cnc.bj.baidubce.com/public/hrt_perf_bayese:v1.24.5 \
bash scripts/test-jfs.sh

5. 配置文件说明

5.1 环境配置

项目配置文件通过 APP_ENV 环境变量指定:

配置文件 用途 RabbitMQ JuiceFS
.env.board_dev 云上环境(生产/联调) 云上服务地址 商业版

切换配置:

APP_ENV=board_dev python3 backend/tasks/worker_infer_consumer.py

5.2 配置文件内容

.env.board_dev(云上生产环境)

APP_NAME=onboard_inference
APP_ENV=board_dev
RABBITMQ_URI=amqp://rock:rock123!@120.48.111.89:5672/%2f?heartbeat=600
RABBITMQ_EXCHANGE_NAME=onboard.exchange.dev
RABBITMQ_TASK_QUEUE_NAME=onboard.infer.task.dev
RABBITMQ_TASK_ROUTING_KEY=onboard.infer.task.dev
DEBUG=False
LOG_LEVEL=INFO

5.3 私有配置

backend/private.py 包含 JuiceFS 商业版 token(不提交到版本控制):

juicefs_private_token_str = "f48eca3cbd1693d73233295ed8711b261bde8e0a"

所有脚本通过 Python 导入读取 token,不会打印到任何日志或输出。


6. JuiceFS 使用详解

6.1 安装

sudo bash scripts/jfs-install.sh

从地瓜私有源下载商业版 juicefs-private 客户端。

6.2 JuiceFS 操作工具

scripts/jfs-workspace.sh 是统一的 JuiceFS 操作工具:

挂载

# 挂载子目录到本地路径
bash scripts/jfs-workspace.sh mount /mnt/hostpath/dcloud/dataset/ dcloud/dataset/

# 挂载测试专用目录(测试完清理即可)
bash scripts/jfs-workspace.sh mount /mnt/hostpath/dcloud/test/wuchao_test dcloud/test/wuchao_test

卸载

bash scripts/jfs-workspace.sh umount /mnt/hostpath/dcloud/test/wuchao_test

查看挂载状态

bash scripts/jfs-workspace.sh status

文件操作

bash scripts/jfs-workspace.sh ls     dcloud/test/wuchao_test          # 列出目录
bash scripts/jfs-workspace.sh mkdir  dcloud/test/wuchao_test/task-001  # 创建目录
bash scripts/jfs-workspace.sh put    ./task.json dcloud/test/wuchao_test/task-001/input/task.json  # 上传文件
bash scripts/jfs-workspace.sh get    dcloud/test/wuchao_test/task-001/output/result.json ./result.json  # 下载文件
bash scripts/jfs-workspace.sh cat    dcloud/test/wuchao_test/task-001/output/result.json  # 查看文件内容
bash scripts/jfs-workspace.sh rm     dcloud/test/wuchao_test/task-001  # 删除文件或目录

6.3 环境变量(可选)

变量 默认值 说明
JFS_BUCKET dev-01-dcloudfs 桶名
JFS_CACHE_SIZE 102400(mount)/ 1024(文件操作) 缓存大小(MB)
JFS_MAX_UPLOADS 20(mount)/ 4(文件操作) 最大并发上传数

7. 消息协议

7.1 任务消息格式

推理任务强制使用 Docker 容器模式,消息中必须包含 docker_image 字段:

{
  "task_id": "hrt-perf-001",
  "task_params": {
    "inference_task_id":         "hrt-perf-001",
    "public_juicefs_token":      "<JuiceFS token>",
    "juicefs_s3_bucket_name":    "dev-01-dcloudfs",
    "inference_task_type":       1,
    "storage_dataset_path":      "dcloud/dataset/",
    "storage_train_infer_path":  "dcloud/train-infer/",
    "storage_infer_path_input":  "dcloud/train-infer/infer/<task_id>/onboardinferdataset/",
    "storage_infer_path_output": "dcloud/train-infer/infer/<task_id>/onboardinferresult/",
    "storage_infer_exec_path":   "dcloud/train-infer/infer/<task_id>/onboardinferdataset/",
    "workspace_path":            "/mnt/hostpath/",
    "workspace_input_path":      "/workspace/input/",
    "workspace_output_path":     "/workspace/output/",
    "workspace_infer_exec_path": "/workspace/<task_id>",
    "docker_image":        "ccr-29eug8s3-pub.cnc.bj.baidubce.com/public/hrt_perf_bayese:v1.24.5",
    "docker_command":      [],
    "docker_env":          {"TASK_ID": "hrt-perf-001"},
    "docker_timeout":      3600,
    "docker_pull_timeout": 600
  },
  "callback_routing_key": "onboard.infer.result.hrt-perf-001"
}

7.2 Docker 字段说明

字段 必填 默认值 说明
docker_image 是 — 镜像地址,推理任务必须指定
docker_command 否 [] 覆盖容器启动命令;[] 表示使用镜像自带 entrypoint
docker_env 否 {} 注入容器的额外环境变量
docker_mounts 否 [] 额外挂载,格式:[{"host":"/h","container":"/c","read_only":true}]
docker_privileged 否 true 特权模式,访问 BPU 硬件必须开启
docker_network 否 host 网络模式
docker_timeout 否 3600 容器最长运行秒数
docker_pull_timeout 否 600 pull 超时秒数

Docker 模式自动挂载(无需配置):

workspace_input_path      → /workspace/input   (只读)
workspace_output_path     → /workspace/output
workspace_infer_exec_path → /workspace/exec
/opt/hobot                → /opt/hobot          (只读,存在才挂)
/usr/hobot                → /usr/hobot          (只读,存在才挂)
/opt/tros                 → /opt/tros           (只读,存在才挂)
/lib/aarch64-linux-gnu    → /host_lib/aarch64-linux-gnu (只读,存在才挂)

7.3 结果回调消息

// 成功
{"task_id": "xxx", "result": {"status": "success", "error": null}}

// 失败
{"task_id": "xxx", "result": {"status": "failed", "error": "错误描述"}}

7.4 消息确认策略

情况 操作
推理成功且回调成功 basic_ack,消息永久删除
推理失败 basic_nack(requeue=False),消息丢弃
回调发布失败 basic_nack(requeue=True),消息重新入队

7.5 inference_task_type 枚举值

值 任务类型
1 detection(目标检测)
2 classification(图像分类)
3 segmentation(语义分割)
4 depth_estimation(深度估计)

8. 测试指南

8.1 测试用例列表

用例 平台 并发 说明
tc_01_x5_single_perf.py X5 1 X5 单任务性能基准(YOLOv8n 640×640)
tc_02_x5_multi_model_perf.py X5 1 X5 单任务多模型批量
tc_03_s100_single_perf.py S100 1 S100 单任务性能基准(YOLO11n 640×640)
tc_04_x5_burst.py X5 8 X5 高爆发并发压测
tc_05_s100_burst.py S100 8 S100 高爆发并发压测

8.2 运行测试

推荐:使用本地 MQ 隔离测试

# 启动本地 MQ(如果还没起)
docker run -d --name rabbitmq-demo --hostname rabbitmq-demo \
    -p 5672:5672 -p 15672:15672 rabbitmq:3-management

# 启动消费者(连接本地 MQ)
APP_ENV=board_dev_all_local python3 backend/tasks/worker_infer_consumer.py

# 运行测试(另一个终端)
APP_ENV=board_dev_all_local python3 testcases/tc_01_x5_single_perf.py

运行单个用例

# X5 单任务
APP_ENV=board_dev_all_local python3 testcases/tc_01_x5_single_perf.py

# S100 单任务
APP_ENV=board_dev_all_local python3 testcases/tc_03_s100_single_perf.py

# X5 高爆发(默认 8 条并发)
APP_ENV=board_dev_all_local python3 testcases/tc_04_x5_burst.py

# X5 高爆发(自定义并发数)
BURST_COUNT=4 APP_ENV=board_dev_all_local python3 testcases/tc_04_x5_burst.py

批量运行

# 运行所有用例
APP_ENV=board_dev_all_local bash testcases/run_all.sh

# 只运行 X5 相关用例
APP_ENV=board_dev_all_local bash testcases/run_all.sh tc_01 tc_02 tc_04

# 只运行 S100 相关用例
APP_ENV=board_dev_all_local bash testcases/run_all.sh tc_03 tc_05

8.3 完整链路测试脚本

# Docker 模式(使用真实镜像)
DOCKER_IMAGE=ccr-29eug8s3-pub.cnc.bj.baidubce.com/public/hrt_perf_bayese:v1.24.5 \
TIMEOUT=600 \
bash scripts/test-jfs.sh

# 使用真实测试数据
TEST_DATA_DIR=/path/to/example_fs_bayese \
DOCKER_IMAGE=ccr-29eug8s3-pub.cnc.bj.baidubce.com/public/hrt_perf_bayese:v1.24.5 \
bash scripts/test-jfs.sh

8.4 测试执行流程

对每条任务:
  1. 上传模型文件 + task.json 到 JuiceFS
     dcloud/test/wuchao_test/<task_id>/onboardinferdataset/

  2. 发布 MQ 消息(包含 JuiceFS 路径、docker_image、token)

  3. 等待 MQ 回调(轮询 onboard.infer.result.dev 队列)

  4. 从 JuiceFS 读取 result.json 验证推理输出
     dcloud/test/wuchao_test/<task_id>/onboardinferresult/result.json

  5. 清理 JuiceFS 测试数据

  6. 打印汇总报告

9. 部署指南

9.1 Supervisor 部署

使用 Supervisor 守护进程管理消费者进程:

# 首次启动
supervisord -c deploy/config/supervisor/onboard_worker_dev.conf

# 热重载配置
supervisorctl -c deploy/config/supervisor/onboard_worker_dev.conf reread
supervisorctl -c deploy/config/supervisor/onboard_worker_dev.conf update

# 查看状态
supervisorctl -c deploy/config/supervisor/onboard_worker_dev.conf status

9.2 Supervisor 配置说明

deploy/config/supervisor/onboard_worker_dev.conf 定义了两个 program:

Program 说明
worker_infer_consumer_board_dev 主消费者进程,自动重启
docker_image_cleanup_board_dev Docker 镜像定时清理,每天凌晨 3 点执行

9.3 部署注意事项

  • 每块板子上执行相同的部署步骤
  • 所有板子连接同一个 RabbitMQ 即可加入集群

10. 运维脚本

脚本 功能
scripts/jfs-install.sh 安装商业版 juicefs-private(需要 root)
scripts/jfs-workspace.sh JuiceFS 统一操作工具:挂载、卸载、文件增删改查
scripts/test-jfs.sh 完整链路测试
scripts/check-dev-env.sh 环境检查与清理
scripts/install_env_by_uv.sh 使用 uv 安装 Python 依赖
scripts/docker-image-cleanup.sh 清理超过 7×24 小时未使用的 Docker 镜像

10.1 环境检查

# 只检查
bash scripts/check-dev-env.sh

# 检查 + 清理(杀进程、卸载挂载、清空队列)
bash scripts/check-dev-env.sh --clean

10.2 Docker 镜像清理

# 预览(不实际删除)
DRY_RUN=true bash scripts/docker-image-cleanup.sh

# 执行清理
bash scripts/docker-image-cleanup.sh

# 自定义过期时间(48 小时)
EXPIRE_HOURS=48 bash scripts/docker-image-cleanup.sh

配合 crontab 每天凌晨 3 点自动触发:

# crontab -e
0 3 * * * supervisorctl -c /home/sunrise/Project/onboard_inference/deploy/config/supervisor/onboard_worker_dev.conf start docker_image_cleanup_board_dev

11. 二次开发指南

11.1 新增测试用例

  1. 在 testcases/ 下新建 tc_NN_<描述>.py
  2. 参照现有用例,定义 TESTCASE 字典并调用 run_testcase(TESTCASE)
  3. 如需新模型文件,放入 models/x5/ 或 models/s100/
  4. 在 TESTCASES.md 补充说明

11.2 新增任务类型

修改 backend/tasks/onboard_inference_task.py 中的 TASK_TYPE_MAP:

TASK_TYPE_MAP = {
    1: "detection",
    2: "classification",
    3: "segmentation",
    4: "depth_estimation",
    5: "your_new_task_type"  # 新增
}

11.3 修改 Docker 执行逻辑

参考 backend/utils/docker_utils.py 中的 run_docker_inference() 函数,可以修改 Docker 执行细节(如挂载策略、环境变量等)。


12. 核心模块说明

12.1 配置模块 (backend/config/config.py)

  • 使用 pydantic-settings + python-dotenv 管理配置
  • 根据 APP_ENV 环境变量加载对应的 .env 文件
  • 主要配置项:RabbitMQ 连接信息、日志配置、飞书通知

12.2 RabbitMQ 客户端 (backend/utils/rabbitmq.py)

  • 基于 pika 库的同步阻塞式 RabbitMQ 客户端
  • 提供方法:connect(), close(), publish(), consume(), declare_queue(), declare_exchange(), bind_queue()
  • 内部有简单的重连机制

12.3 JuiceFS 管理 (backend/utils/juicefs_utils.py)

  • JuiceFSManager 类:提供完整的 JuiceFS 生命周期管理
  • 使用商业版 juicefs-private 命令,通过 token + bucket_name 挂载
  • 便捷函数:mount_juicefs(), umount_juicefs(), is_juicefs_mounted()

12.4 Docker 执行 (backend/utils/docker_utils.py)

  • image_version_matches(): 检查本地镜像与 registry 版本是否一致
  • pull_image(): 智能 pull(版本匹配则跳过)
  • run_container(): 运行容器并等待完成
  • run_docker_inference(): 完整 docker 推理流程
  • 自动挂载宿主机系统路径

12.5 推理任务核心 (backend/tasks/onboard_inference_task.py)

onboard_model_inference() 函数执行步骤:

  1. 设置任务状态为运行中
  2. 挂载 JuiceFS 文件系统(最多 5 个挂载点)
  3. 执行 Docker 容器推理(强制要求 docker_image)
  4. 清理挂载点(无论成败都执行,finally 块)

12.6 RabbitMQ 消费者 (backend/tasks/worker_infer_consumer.py)

  • handle_infer_task(): 消息处理回调
  • start_consume_once(): 启动一次消费循环
  • main(): 长期运行入口,网络抖动时自动重连
  • 使用 prefetch_count=1 确保单消费者同时只处理一条消息

13. 依赖说明

13.1 Python 依赖

包 版本 用途
pika 1.3.2 RabbitMQ Python 客户端
pydantic 2.4.2 数据校验与配置模型
pydantic-settings 2.0.3 基于环境变量的配置管理
python-dotenv 1.0.0 加载 .env 文件
docker ≥7.1.0 Docker SDK,容器执行模式使用
supervisor 4.3.0 进程守护管理
python-json-logger 2.0.7 JSON 结构化日志
fastapi 0.103.2 Web 框架(用于 logger)
uvicorn 0.23.2 ASGI 服务器
httpx 0.24.1 HTTP 客户端
requests 2.32.5 HTTP 库

13.2 外部依赖

依赖 说明
RabbitMQ 消息代理,自建或云服务均可
juicefs-private JuiceFS 商业版客户端
Docker Docker 容器执行模式必须,需要 daemon 运行

14. 注意事项

  1. 多板水平扩展:系统设计为多块完全等价的板子同时运行,通过 RabbitMQ round-robin 分发机制实现负载均衡

  2. Docker 强制模式:推理任务必须指定 docker_image,系统不支持原生可执行程序模式

  3. Token 安全:backend/private.py 包含敏感 token,不提交到版本控制

  4. 平台不兼容:RDK X5(bayese)和 RDK S100(nashem)的 BPU 指令集不兼容,模型格式不同(.bin vs .hbm)

  5. 消费者隔离:测试时建议使用独立的 RabbitMQ 配置,避免与其他消费者争抢任务

  6. 挂载点清理:任务无论成功或失败,都会尝试卸载挂载点。_safe_umount() 最多重试 3 次,包括强制卸载和 lazy unmount

  7. 日志位置:

    • Supervisor stdout: /tmp/worker_infer_consumer_stdout.log
    • Supervisor stderr: /tmp/worker_infer_consumer_stderr.log
    • 应用日志: backend/tasks/logs/app.log
Description
No description provided
Readme 2.5 MiB
Languages
Python 73.9%
Shell 26.1%