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 新增测试用例
- 在
testcases/下新建tc_NN_<描述>.py - 参照现有用例,定义
TESTCASE字典并调用run_testcase(TESTCASE) - 如需新模型文件,放入
models/x5/或models/s100/ - 在
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() 函数执行步骤:
- 设置任务状态为运行中
- 挂载 JuiceFS 文件系统(最多 5 个挂载点)
- 执行 Docker 容器推理(强制要求 docker_image)
- 清理挂载点(无论成败都执行,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. 注意事项
-
多板水平扩展:系统设计为多块完全等价的板子同时运行,通过 RabbitMQ round-robin 分发机制实现负载均衡
-
Docker 强制模式:推理任务必须指定
docker_image,系统不支持原生可执行程序模式 -
Token 安全:
backend/private.py包含敏感 token,不提交到版本控制 -
平台不兼容:RDK X5(bayese)和 RDK S100(nashem)的 BPU 指令集不兼容,模型格式不同(
.binvs.hbm) -
消费者隔离:测试时建议使用独立的 RabbitMQ 配置,避免与其他消费者争抢任务
-
挂载点清理:任务无论成功或失败,都会尝试卸载挂载点。
_safe_umount()最多重试 3 次,包括强制卸载和 lazy unmount -
日志位置:
- Supervisor stdout:
/tmp/worker_infer_consumer_stdout.log - Supervisor stderr:
/tmp/worker_infer_consumer_stderr.log - 应用日志:
backend/tasks/logs/app.log
- Supervisor stdout: