跳到主要内容

System Architecture

NE503 AIPC（AI IPC）平台是一个面向边缘 AI 计算的完整软件栈，采用四层分层架构设计，支持多 SoC 平台（Hailo-15 / RKxxx / Jetson）通过硬件抽象层实现平滑迁移。本文档详细介绍平台各层架构、核心服务与数据流。

1. 四层架构总览​

层级职责技术
应用容器层第三方 AI 应用、模型推理管线Python/Go/C++，容器化运行
平台服务层摄像头管理、AI 推理、容器管理、事件分发、设备控制、API 网关、设备发现Go 微服务 + C++ 守护进程
硬件抽象层统一硬件接口，解耦平台服务与 SoCC/C++ 函数指针表（Ops），DMA-BUF 零拷贝
硬件层SoC、NPU、ISP、传感器、MCUHailo-15H（当前）、RKxxx / Jetson（可扩展）

2. 平台服务层​

平台服务层包含多个微服务，通过 gRPC over Unix Domain Socket 进行内部通信。

2.1 服务总览​

服务语言监听地址职责
ai-runtimeC++unix:///run/aipc/ai-runtime.sockAI 模型管理与推理调度，NPU 资源分配，GenAI 流式推理
app-managerGounix:///run/aipc/app-manager.sock容器应用生命周期管理（安装/启动/停止/卸载），基于 containerd
event-busGounix:///run/aipc/event-bus.sock + TCP 127.0.0.1:50053发布/订阅消息总线，MQTT 风格通配符匹配
device-controlGounix:///run/aipc/device-control.sock硬件外设控制（灯光/PTZ/镜头/GPIO），MCU UART 通信
device-discoveryGounix:///run/aipc/device-discovery.sock网络设备发现（CT-Disc 协议），设备注册与状态管理
platform-apiGo:8080HTTP/RESTful API 网关，代理所有后端 gRPC 服务
camera-daemonC++unix:///run/aipc/camera.sock（FD 发布）+ unix:///run/aipc/camera-control.sock（gRPC 控制）+ /run/aipc/shm/（SHM）视频采集、双通道帧分发（FD/SHM）、编码、RTSP 流媒体

2.2 gRPC API 定义​

平台通过 Protocol Buffers 文件定义所有 gRPC 接口：

Proto 文件服务说明
inference.protoAI 推理模型注册/推理/流式推理/GenAI 会话管理
app.proto容器管理应用安装/生命周期 + 容器/镜像/资源管理
event.proto事件总线发布/订阅，MQTT 风格通配符，主题统计
device.proto设备控制灯光/PTZ/镜头（含 AF0832）/GPIO/环境/告警/RS485
camera.proto摄像头管理视频采集管道、RTSP 流媒体、OSD 叠加
lens_hal.proto镜头控制device.proto 镜头部分的 HAL 桥接实现
discovery.proto设备发现CT-Disc 协议设备发现、监听与扫描

各 proto 的完整操作列表见对应的服务参考文档。

3. 硬件抽象层（HAL）​

3.1 HAL 接口总览​

HAL 头文件按组件子目录组织，位于 hal_v2/include/：

目录覆盖功能
media/视频采集、编码（H.264/H.265）、OSD 叠加、ISP、音频、Profile 管理
model/模型推理、后处理（NMS）、GenAI（LLM/VLM）、可视化绘制、CLIP 文本编码
dsp/裁剪、缩放、格式转换、隐私遮罩、防抖
peripheral/MCU 通信、GPIO/传感器；设备层含 LED、镜头、告警、RS485、RTC、OTA 等
common/公共枚举/错误码、HalFrameBuffer 帧缓冲、基础类型、日志

各服务消费的具体子接口（如 HalInferenceOps、HalPostprocessOps 等）详见对应的服务参考文档。

3.2 核心数据结构：HalFrameBuffer​

HalFrameBuffer 是平台的核心帧数据载体，用于在视频采集、AI 推理、编码等模块间传递帧数据。

数据封装：

  • 图像元数据：宽高、像素格式、时间戳

  • 内存描述：DMA-BUF fd、虚拟地址、stride/size

  • 私有数据：通过 priv 指针透传平台特定信息

  • 内存模式：支持 DMA-BUF（零拷贝）和 CPU Memory 两种。视频→AI→编码全链路共享同一 DMA-BUF，无需内存拷贝。

  • 生命周期：通过引用计数管理（hal_frame_buffer_ref / hal_frame_buffer_release）。

完整结构体定义见 GitHub 仓库 hal_v2/include/common/ 目录。

3.3 多平台支持​

当前实现：Hailo-15（完整）+ Stub（完整桩实现，无硬件开发用）。RKxxx 和 Jetson 可通过实现对应的 HAL 接口扩展支持。

4. Web 控制台​

Web 控制台基于 React 19 + TypeScript + Vite 构建，提供设备管理、视频监控、AI 模型管理、应用管理、系统监控等功能。

技术栈组件
框架React 19 + TypeScript
构建Vite
状态管理Zustand
数据获取TanStack Query
UI 组件shadcn/ui + Radix
测试Vitest

Web 控制台通过 REST API 和 WebSocket 与 platform-api 通信，实时推送 AI 推理结果和设备事件。

访问地址：http://<设备IP>:8080。

5. 关键技术特性​

5.1 零拷贝优化​

核心机制：

  • HalFrameBuffer 通过 dma_fds[] 传递 DMA-BUF 文件描述符，视频→AI→编码全程零拷贝
  • 引用计数管理帧生命周期（hal_frame_buffer_ref / hal_frame_buffer_release）
  • AI Runtime 与 Camera Daemon 之间通过 SCM_RIGHTS 传递 FD（无需内存拷贝）

5.2 事件驱动架构​

Event Bus 采用发布/订阅模式，支持 MQTT 风格通配符匹配：

模式说明示例
精确匹配完全匹配主题名app/myapp/status
* 单级通配匹配一个层级app/*/status
** 多级通配匹配多个层级model/**/detections

所有服务产生的推理结果、容器事件、设备事件均通过 Event Bus 分发，第三方应用通过 SDK 的 EventClient 订阅感兴趣的主题。

5.3 容器化应用平台​

  • 基于 containerd 运行时，OCI 标准镜像部署
  • 多容器支持（Main + Sub），插件化依赖解析
  • 健康检查系统（Command / HTTP / TCP，指数退避策略）
  • 自动重启（故障时 backoff 策略）

6. 系统配置​

平台使用 YAML 配置文件管理所有服务参数，配置文件位于 configs/ 目录：

配置文件服务核心配置项
platform-api.yamlplatform-api服务器端口、认证密钥、日志级别
platform/app-manager.yamlapp-managercontainerd 连接、安全策略、资源限制
platform/event-bus.yamlevent-busSocket 路径、TCP 监听、主题 ACL
platform/device-control.yamldevice-controlMCU UART 设备、镜头参数、自动化规则
platform/camera-daemon.yamlcamera-daemon视频采集、编码参数、RTSP 配置
platform/discovery.yamldevice-discoveryCT-Disc 协议参数
ai/ai-runtime.yamlai-runtimeHAL 库路径、模型仓库、调度器、自动推理管道
preload.yamlpack-factory工厂预装（预装模型与应用）
security/seccomp-default.json安全默认 Seccomp 系统调用白名单

安装位置：/opt/aipc/（二进制 bin/、配置 etc/）。

7. 相关文档​