【OpenHarmony】AI引擎模块架构

AI引擎模块架构

源码：https://gitee.com/openharmony/ai_engine

1. 模块概述

1.1 功能与目标

主要功能：
AI引擎模块是OpenHarmony系统提供原生分布式AI能力的核心子系统，实现了统一的AI引擎框架，支持算法能力的快速插件化集成。该模块的主要功能包括：

• 插件管理：提供AI算法插件的生命周期管理和按需部署
• 模块管理：管理AI算法模块的加载、卸载和版本控制
• 通信管理：提供客户端与服务端之间的通信机制
• 算法执行：支持同步和异步的AI算法推理执行
• 资源管理：管理AI模型、数据和计算资源
• 分布式调用：支持跨设备的AI能力调用
• 统一接口：提供适配不同推理框架层级的统一推理接口
• 算法插件：支持ASR（语音识别）、CV（计算机视觉）等算法插件

使用场景：

• 语音识别和唤醒词检测
• 图像分类和目标检测
• 自然语言处理
• 机器学习模型推理
• 分布式AI计算
• 智能设备控制
• 多媒体内容分析

1.2 系统位置

系统架构位置：
AI引擎模块位于OpenHarmony系统的foundation/ai子系统下，是AI业务子系统的核心组件。

模块关系：

• 上层对接：为应用层提供统一的AI能力API
• 下层对接：对接系统能力管理器（SAMGR）、IPC通信等底层服务
• 横向协作：与分布式调度、设备管理、多媒体等模块协作
• 系统集成：集成到系统能力管理器中，提供系统级AI服务

核心模块地位：
该模块是AI子系统的核心模块，承担着统一AI能力接口和算法插件管理的重要职责，是实现分布式AI能力的关键基础设施。

1.3 设计思路与模式

设计思路：

• 插件化架构设计：采用插件化架构，支持算法能力的快速集成和扩展
• 分层架构设计：采用Client-Server分层架构，分离客户端和服务端职责
• 统一接口设计：通过统一的API接口屏蔽不同算法和推理框架的差异
• 异步处理机制：采用异步处理模式，提高系统响应性能
• 资源池管理：采用资源池模式管理计算资源和模型资源
• 分布式设计：支持跨设备的AI能力调用和资源共享

设计模式：

• 工厂模式：ClientFactory用于创建不同类型的客户端
• 单例模式：PluginManager等核心组件采用单例模式
• 策略模式：不同算法插件采用不同的处理策略
• 观察者模式：回调机制支持异步结果通知
• 适配器模式：通信适配器支持不同的通信协议
• 插件模式：算法插件通过IPlugin接口实现统一管理

1.4 系统框图

2. 模块结构

2.1 源文件与头文件

核心接口文件：

AI数据类型：

• interfaces/kits/ai_datatype.h - AI数据类型定义，包含Array模板类
• interfaces/kits/ai_retcode.h - AI错误码定义
• interfaces/kits/ai_callback.h - AI回调接口定义

ASR算法接口：

• interfaces/kits/asr/keyword_spotting/kws_sdk.h - 唤醒词识别SDK接口
• interfaces/kits/asr/keyword_spotting/kws_callback.h - 唤醒词识别回调接口
• interfaces/kits/asr/keyword_spotting/kws_constants.h - 唤醒词识别常量定义
• interfaces/kits/asr/keyword_spotting/kws_retcode.h - 唤醒词识别错误码

CV算法接口：

• interfaces/kits/cv/image_classification/ic_sdk.h - 图像分类SDK接口
• interfaces/kits/cv/image_classification/ic_callback.h - 图像分类回调接口
• interfaces/kits/cv/image_classification/ic_constants.h - 图像分类常量定义
• interfaces/kits/cv/image_classification/ic_retcode.h - 图像分类错误码
• interfaces/kits/cv/ai_image.h - AI图像数据结构

客户端组件：

• services/client/client_executor/include/i_aie_client.inl - AI客户端接口实现
• services/client/client_executor/include/client_factory.h - 客户端工厂类
• services/client/client_executor/include/async_handler.h - 异步处理器
• services/client/communication_adapter/include/sa_client.h - 系统能力客户端适配器

服务端组件：

• services/server/plugin/i_plugin.h - 插件接口定义
• services/server/plugin/i_plugin_callback.h - 插件回调接口
• services/server/plugin_manager/include/plugin_manager.h - 插件管理器
• services/server/server_executor/include/engine_manager.h - 引擎管理器
• services/server/server_executor/include/engine_worker.h - 引擎工作器

公共组件：

• services/common/protocol/struct_definition/aie_info_define.h - AI信息结构定义
• services/common/protocol/retcode_inner/aie_retcode_inner.h - 内部错误码定义
• services/common/utils/log/aie_log.h - AI日志工具
• services/common/platform/threadpool/include/thread_pool.h - 线程池管理

2.2 类、结构体、函数与方法

核心类定义：

Array模板结构体

template<typename T>
struct Array {/* Pointer to the start address of the array */T *data;/* Array size */size_t size;
};

KWSSdk类

class KWSSdk {
public:/*** @brief Defines the constructor for the KWS SDK.*/KWSSdk();/*** @brief Defines the destructor for the KWS SDK.*/virtual ~KWSSdk();/*** @brief Creates a KWS SDK instance.* @return Returns KWS_RETCODE_SUCCESS if the operation is successful;* returns a non-zero error code defined by KWSRetCode otherwise.*/int32_t Create();/*** @brief Synchronously executes the KWS task.* @param input Indicates the input array defined by Array for the KWS task. The element type is int16_t.* @return Returns KWS_RETCODE_SUCCESS if the operation is successful;* returns a non-zero error code defined by KWSRetCode otherwise.*/int32_t SyncExecute(const Array<int16_t> &input);/*** @brief Sets the callback for the KWS task.* @param callback Indicates the callback defined by KWSCallback for implementing the post-processing logic.* @return Returns KWS_RETCODE_SUCCESS if the operation is successful;* returns a non-zero error code defined by KWSRetCode otherwise.*/int32_t SetCallback(const std::shared_ptr<KWSCallback> &callback);/*** @brief Destroys the KWS SDK instance to release the session engaged with the plugin.* @return Returns KWS_RETCODE_SUCCESS if the operation is successful;* returns a non-zero error code defined by KWSRetCode otherwise.*/int32_t Destroy();private:class KWSSdkImpl;std::unique_ptr<KWSSdkImpl> kwsSdkImpl_;
};

IcSdk类

class IcSdk {
public:/*** @brief Defines the constructor for the development tool.*/IcSdk() = default;/*** @brief Defines the destructor for the development tool, release model, and related variables.*/~IcSdk();/*** @brief Establishes a connection from the development tool to the AI server.* @return Returns IC_RETCODE_SUCCESS if the operation is successful;* returns a non-zero error code defined by IcRetCode otherwise.*/int32_t Create();/*** @brief Imports images from the development tool to the image classification model for prediction.* @param picInput Indicates the input BGR image.* @return Returns IC_RETCODE_SUCCESS if the operation is successful;* returns a non-zero error code defined by IcRetCode otherwise.*/int32_t SyncExecute(const IcInput &picInput);/*** @brief Defines the callback function.* @param callback Indicates the specified callback.* @return Returns IC_RETCODE_SUCCESS if the operation is successful;* returns a non-zero error code defined by IcRetCode otherwise.*/int32_t SetCallback(std::shared_ptr<IcCallback> callback);/*** @brief Destroys the loaded model and related resources.* @return Returns IC_RETCODE_SUCCESS if the operation is successful;* returns a non-zero error code defined by IcRetCode otherwise.*/int32_t Destroy();
};

IPlugin接口

class IPlugin {
public:virtual ~IPlugin() = default;virtual const long long GetVersion() const = 0;virtual const char *GetName() const = 0;virtual const char *GetInferMode() const = 0;/*** Algorithmic inference interface for synchronous tasks.* @param [in] request Request task which contains the specific information of the task.* @param [out] response Results of encapsulated algorithmic inference.* @return Returns 0 if the operation is successful, returns a non-zero value otherwise.*/virtual int SyncProcess(IRequest *request, IResponse *&response) = 0;/*** Algorithmic inference interface for asynchronous tasks.* @param [in] request Request task which contains the specific information of the task.* @param [in] callback Callback which is used to return the result of asynchronous inference.* @return Returns 0 if the operation is successful, returns a non-zero value otherwise.*/virtual int AsyncProcess(IRequest *request, IPluginCallback *callback) = 0;/*** Initialize plugin.* @param [in] transactionId Transaction ID.* @param [in] inputInfo Data information needed to initialize plugin.* @param [out] outputInfo The returned data information of initializing plugin.* @return Returns 0 if the operation is successful, returns a non-zero value otherwise.*/virtual int Prepare(long long transactionId, const DataInfo &inputInfo, DataInfo &outputInfo) = 0;/*** Unload model and plugin.* @param [in] isFullUnload Whether to unload completely.* @param [in] transactionId Transaction ID.* @param [in] inputInfo Data information needed to unload model and plugin.* @return Returns 0 if the operation is successful, returns a non-zero value otherwise.*/virtual int Release(bool isFullUnload, long long transactionId, const DataInfo &inputInfo) = 0;/*** Set the configuration parameters of the plugin.* @param [in] optionType The type of setting option.* @param [in] inputInfo Configuration parameter needed to set up the plugin.* @return Returns 0 if the operation is successful, returns a non-zero value otherwise.*/virtual int SetOption(int optionType, const DataInfo &inputInfo) = 0;/*** Get the configuration parameters of plugin.* @param [in] optionType The type of getting option.* @param [in] inputInfo Parameter information for getting options.* @param [out] outputInfo The configuration information of plugin.* @return Returns 0 if the operation is successful, returns a non-zero value otherwise.*/virtual int GetOption(int optionType, const DataInfo &inputInfo, DataInfo &outputInfo) = 0;
};

PluginManager类

class PluginManager : public IPluginManager {FORBID_COPY_AND_ASSIGN(PluginManager);FORBID_CREATE_BY_SELF(PluginManager);
public:static PluginManager *GetInstance();void Destroy() override;int GetPlugin(const std::string &aid, long long version, std::shared_ptr<Plugin> &plugin) override;void UnloadPlugin(const std::string &aid, long long version) override;private:std::shared_ptr<Plugin> FindPlugin(const PluginKey &pluginKey);void AddPlugin(const PluginKey &pluginKey, const std::shared_ptr<Plugin> &pluginValue);void DelPlugin(const PluginKey &pluginKey);void DelPluginByAID(const std::string &aid);int LoadPlugin(const std::string &aid, long long version, std::shared_ptr<Plugin> &plugin);private:static std::mutex instanceLock_;static PluginManager *instance_;private:std::mutex mutex4Interface_;std::mutex mutex_;PluginMap pluginMap_;
};

重要结构体：

PluginKey结构体

struct PluginKey {std::string aid;long long version;PluginKey(const std::string &aid, long long version): aid(aid), version(version){}inline bool operator< (const PluginKey& another) const{if (aid < another.aid) {return true;}if (aid == another.aid && version < another.version) {return true;}return false;}
};

AiRetCode枚举

typedef enum {AI_RETCODE_SUCCESS = 0,                   /** Return code for an operation success */AI_RETCODE_FAILURE = -1,                  /** Return code for an operation failure */AI_RETCODE_INIT_ERROR = 1001,             /** Return code for an initialization error */AI_RETCODE_NULL_PARAM = 1002,             /** Return code for a null parameter error */AI_RETCODE_DUPLICATE_INIT_ERROR = 1004,   /** Return code for a duplicate initialization error */AI_RETCODE_SERIALIZATION_ERROR = 2001,    /** Return code for a serialization error */AI_RETCODE_UNSERIALIZATION_ERROR = 2002,  /** Return code for a deserialization error */AI_RETCODE_PLUGIN_EXECUTION_ERROR = 3001, /** Return code for a plugin execution error */AI_RETCODE_PLUGIN_SESSION_ERROR = 3002,   /** Return code for a plugin session error */
} AiRetCode;

2.3 继承与多态

继承关系：

• PluginManager继承自IPluginManager接口
• 各种算法插件继承自IPlugin接口
• 各种回调类继承自相应的回调接口基类
• 各种SDK类通过组合模式使用实现类

多态设计：

• 通过IPlugin接口实现不同算法插件的统一管理
• 通过回调机制支持多种事件类型的统一处理
• 通过工厂模式实现不同客户端的动态创建
• 通过策略模式实现不同通信协议的处理

2.4 类图

2.5 模块内部依赖框图

3. 模块间交互

3.1 交互描述

与系统模块的交互：

• 系统能力管理器：通过SAMGR模块注册和管理AI服务
• IPC通信：通过IPC模块实现客户端与服务端的通信
• 日志系统：通过Hilog模块记录AI引擎的运行日志
• 工具库：通过utils_base模块使用基础工具函数
• 分布式调度：通过分布式调度模块实现跨设备AI能力调用

外部库依赖：

• 系统框架：SAMGR、IPC等系统框架
• 工具库：utils_base、bounds_checking_function等基础库
• 第三方库：根据具体算法插件可能需要特定的AI推理框架

异步处理机制：

• 使用线程池进行异步任务处理
• 通过回调机制处理异步结果通知
• 支持同步和异步两种执行模式
• 采用事件驱动机制处理插件状态变化

3.2 事件驱动机制

事件类型：

• 插件加载/卸载事件
• 算法执行开始/完成事件
• 客户端连接/断开事件
• 资源分配/释放事件
• 错误和异常事件

事件处理流程：

1. 注册事件监听器
2. 接收系统或插件事件通知
3. 解析事件参数
4. 更新内部状态
5. 通知相关回调
6. 执行相应的处理逻辑

3.3 外部依赖框图

4. 状态机转换图

4.1 状态机模型

AI引擎模块的状态机包含以下主要状态：

服务状态：

• SERVICE_NOT_START - 服务未启动
• SERVICE_RUNNING - 服务运行中
• SERVICE_STOPPING - 服务停止中
• SERVICE_EXIT - 服务已退出

客户端状态：

• CLIENT_UNINITIALIZED - 客户端未初始化
• CLIENT_INITIALIZING - 客户端初始化中
• CLIENT_INITIALIZED - 客户端已初始化
• CLIENT_PREPARING - 客户端准备中
• CLIENT_READY - 客户端就绪
• CLIENT_PROCESSING - 客户端处理中
• CLIENT_ERROR - 客户端错误

插件状态：

• PLUGIN_UNLOADED - 插件未加载
• PLUGIN_LOADING - 插件加载中
• PLUGIN_LOADED - 插件已加载
• PLUGIN_PREPARING - 插件准备中
• PLUGIN_READY - 插件就绪
• PLUGIN_PROCESSING - 插件处理中
• PLUGIN_ERROR - 插件错误

算法执行状态：

• ALGORITHM_IDLE - 算法空闲
• ALGORITHM_PREPARING - 算法准备中
• ALGORITHM_RUNNING - 算法运行中
• ALGORITHM_COMPLETED - 算法完成
• ALGORITHM_ERROR - 算法错误

4.2 状态切换规则

服务启动流程：

1. 服务初始状态为SERVICE_NOT_START
2. 收到启动事件后，进入SERVICE_RUNNING状态
3. 初始化各个子模块和插件管理器
4. 注册到系统能力管理器

客户端状态转换：

1. 客户端初始状态为CLIENT_UNINITIALIZED
2. 调用Create()时，进入CLIENT_INITIALIZING状态
3. 初始化完成后，进入CLIENT_INITIALIZED状态
4. 调用Prepare()时，进入CLIENT_PREPARING状态
5. 准备完成后，进入CLIENT_READY状态
6. 调用SyncExecute()时，进入CLIENT_PROCESSING状态
7. 处理完成后，回到CLIENT_READY状态
8. 发生错误时，进入CLIENT_ERROR状态

插件状态转换：

1. 插件初始状态为PLUGIN_UNLOADED
2. 收到加载请求时，进入PLUGIN_LOADING状态
3. 加载完成后，进入PLUGIN_LOADED状态
4. 调用Prepare()时，进入PLUGIN_PREPARING状态
5. 准备完成后，进入PLUGIN_READY状态
6. 调用SyncProcess()时，进入PLUGIN_PROCESSING状态
7. 处理完成后，回到PLUGIN_READY状态
8. 发生错误时，进入PLUGIN_ERROR状态

算法执行状态转换：

1. 算法初始状态为ALGORITHM_IDLE
2. 收到执行请求时，进入ALGORITHM_PREPARING状态
3. 准备完成后，进入ALGORITHM_RUNNING状态
4. 执行完成后，进入ALGORITHM_COMPLETED状态
5. 发生错误时，进入ALGORITHM_ERROR状态
6. 清理完成后，回到ALGORITHM_IDLE状态

事件触发条件：

• 服务启动/停止事件
• 客户端创建/销毁事件
• 插件加载/卸载事件
• 算法执行请求事件
• 错误和异常事件

4.3 状态机转换图

5. 接口设计

5.1 公共接口

AI客户端接口：

初始化客户端

int AieClientInit(const ConfigInfo &configInfo, ClientInfo &clientInfo,const AlgorithmInfo &algorithmInfo, IServiceDeadCb *cb);

• 功能：初始化AI客户端
• 参数：
  • configInfo - 配置信息
  • clientInfo - 客户端信息（输出参数）
  • algorithmInfo - 算法信息
  • cb - 服务死亡回调
• 返回值：操作结果码
• 异常处理：初始化失败时返回错误码

准备客户端

int AieClientPrepare(const ClientInfo &clientInfo, const AlgorithmInfo &algorithmInfo,const DataInfo &inputInfo, DataInfo &outputInfo, IClientCb *cb);

• 功能：准备AI客户端
• 参数：
  • clientInfo - 客户端信息
  • algorithmInfo - 算法信息
  • inputInfo - 输入数据信息
  • outputInfo - 输出数据信息（输出参数）
  • cb - 客户端回调
• 返回值：操作结果码
• 异常处理：准备失败时返回错误码

同步处理

int AieClientSyncProcess(const ClientInfo &clientInfo, const AlgorithmInfo &algorithmInfo,const DataInfo &inputInfo, DataInfo &outputInfo);

• 功能：同步执行AI算法
• 参数：
  • clientInfo - 客户端信息
  • algorithmInfo - 算法信息
  • inputInfo - 输入数据信息
  • outputInfo - 输出数据信息（输出参数）
• 返回值：操作结果码
• 异常处理：处理失败时返回错误码

异步处理

int AieClientAsyncProcess(const ClientInfo &clientInfo, const AlgorithmInfo &algorithmInfo,const DataInfo &inputInfo);

• 功能：异步执行AI算法
• 参数：
  • clientInfo - 客户端信息
  • algorithmInfo - 算法信息
  • inputInfo - 输入数据信息
• 返回值：操作结果码
• 异常处理：处理失败时返回错误码

销毁客户端

int AieClientDestroy(ClientInfo &clientInfo);

• 功能：销毁AI客户端
• 参数：clientInfo - 客户端信息
• 返回值：操作结果码
• 异常处理：销毁失败时返回错误码

唤醒词识别SDK接口：

创建KWS SDK

int32_t KWSSdk::Create();

• 功能：创建唤醒词识别SDK实例
• 返回值：操作结果码
• 异常处理：创建失败时返回错误码

同步执行

int32_t KWSSdk::SyncExecute(const Array<int16_t> &input);

• 功能：同步执行唤醒词识别
• 参数：input - 输入音频数据
• 返回值：操作结果码
• 异常处理：执行失败时返回错误码

设置回调

int32_t KWSSdk::SetCallback(const std::shared_ptr<KWSCallback> &callback);

• 功能：设置唤醒词识别回调
• 参数：callback - 回调函数
• 返回值：操作结果码
• 异常处理：设置失败时返回错误码

销毁SDK

int32_t KWSSdk::Destroy();

• 功能：销毁唤醒词识别SDK实例
• 返回值：操作结果码
• 异常处理：销毁失败时返回错误码

图像分类SDK接口：

创建IC SDK

int32_t IcSdk::Create();

• 功能：创建图像分类SDK实例
• 返回值：操作结果码
• 异常处理：创建失败时返回错误码

同步执行

int32_t IcSdk::SyncExecute(const IcInput &picInput);

• 功能：同步执行图像分类
• 参数：picInput - 输入图像数据
• 返回值：操作结果码
• 异常处理：执行失败时返回错误码

设置回调

int32_t IcSdk::SetCallback(std::shared_ptr<IcCallback> callback);

• 功能：设置图像分类回调
• 参数：callback - 回调函数
• 返回值：操作结果码
• 异常处理：设置失败时返回错误码

销毁SDK

int32_t IcSdk::Destroy();

• 功能：销毁图像分类SDK实例
• 返回值：操作结果码
• 异常处理：销毁失败时返回错误码

5.2 数据交换接口

IPC接口定义：

• 使用系统能力接口进行跨进程通信
• 支持DataInfo结构体的序列化传输
• 提供异步回调机制

数据格式：

• Array模板类支持各种数据类型的传输
• DataInfo结构体支持二进制数据的传输
• ConfigInfo结构体支持配置信息的传输

5.3 接口调用时序图

6. 总结

AI引擎模块是OpenHarmony系统AI子系统的核心组件，通过插件化架构设计为系统和应用提供统一的AI能力接口。该模块采用Client-Server分层架构，实现了算法能力的快速插件化集成和按需部署。

主要特点：

• 插件化架构设计，支持算法能力的快速集成
• 分层架构设计，职责清晰
• 统一的AI能力接口
• 支持同步和异步执行模式
• 高效的资源管理和生命周期管理
• 支持分布式AI能力调用

技术优势：

• 基于系统能力管理器的服务注册机制
• 完善的错误处理和异常管理
• 支持多种AI算法类型
• 灵活的插件扩展机制
• 高效的异步处理能力

该模块为OpenHarmony系统的AI能力提供了坚实的基础，支持各种AI算法需求，是构建智能应用的重要基础设施。通过插件化设计和统一接口，为开发者提供了灵活、高效、易用的AI开发能力。