ai

AI模块提供模型加载、构建、推理等能力，支持从文件路径或内存缓冲区加载模型，管理上下文及张量数据，执行推理并获取结果。

头文件清单

#include <middleware/utils/ai.h>

接口清单

接口名称	功能简述
OH_AI_InitFromFile	从配置文件路径初始化AI模块
OH_AI_Init	从配置文件缓冲区初始化AI模块
OH_AI_Deinit	去初始化AI模块
OH_AI_ContextCreate	创建上下文对象
OH_AI_ContextDestroy	销毁上下文对象
OH_AI_ModelCreate	创建模型对象
OH_AI_ModelBuildFromFile	从模型文件路径加载并构建模型
OH_AI_ModelBuild	从模型文件缓冲区加载并构建模型
OH_AI_ModelBuildFromName	依据模型名称构建模型
OH_AI_ModelDestroy	销毁模型对象
OH_AI_ModelGetInputs	获取模型的所有输入张量句柄
OH_AI_ModelGetOutputs	获取模型的所有输出张量句柄
OH_AI_ModelPredict	执行模型推理
OH_AI_TensorGetDataSize	获取张量的数据大小
OH_AI_TensorGetShape	获取张量的形状
OH_AI_TensorGetElementNum	获取张量中元素的个数
OH_AI_TensorGetDataType	获取张量的数据类型
OH_AI_TensorGetMutableData	获取张量的数据指针
OH_AI_GetErrorCode	获取详细错误码

Functions

OH_AI_InitFromFile

OH_AI_Status OH_AI_InitFromFile(char* config_file_path)

功能说明

从配置文件路径初始化AI模块，读取指定路径的配置文件完成模块初始化
配置文件路径必须有效且指向合法的AI模块配置文件

前置条件

调用时序约束：AI模块未被初始化，否则可能返回失败状态

入参

名称	参数类型	详细说明	约束取值范围
config_file_path	char*	定义配置文件的路径	非 NULL，指向有效配置文件路径字符串

返回值

返回值	文字含义	触发场景
OH_AI_STATUS_SUCCESS(0)	初始化成功	配置文件路径合法，AI模块初始化完成
OH_AI_STATUS_FAILED(1)	初始化失败	配置文件路径无效或初始化过程异常

OH_AI_Init

OH_AI_Status OH_AI_Init(void* config_data, size_t data_size)

功能说明

从配置文件缓冲区初始化AI模块，直接读取内存中的配置数据完成初始化
适用于配置数据已加载到内存的场景，无需通过文件路径访问

前置条件

调用时序约束：AI模块未被初始化，否则可能返回失败状态

入参

名称	参数类型	详细说明	约束取值范围
config_data	void*	定义从配置文件读取的缓冲区	非 NULL，指向有效配置数据缓冲区
data_size	size_t	定义配置文件缓冲区的字节数	大于 0

返回值

返回值	文字含义	触发场景
OH_AI_STATUS_SUCCESS(0)	初始化成功	配置数据合法，AI模块初始化完成
OH_AI_STATUS_FAILED(1)	初始化失败	配置数据无效或初始化过程异常

OH_AI_Deinit

OH_AI_Status OH_AI_Deinit(void)

功能说明

去初始化AI模块，释放模块占用的资源
去初始化后模型推理等相关接口将不可用，需重新初始化后方可使用

前置条件

调用时序约束：已通过 OH_AI_Init 或 OH_AI_InitFromFile 完成初始化

返回值

返回值	文字含义	触发场景
OH_AI_STATUS_SUCCESS(0)	去初始化成功	模块已初始化，资源释放成功
OH_AI_STATUS_FAILED(1)	去初始化失败	模块未初始化或去初始化过程异常

OH_AI_ContextCreate

OH_AI_ContextHandle OH_AI_ContextCreate(void)

功能说明

创建一个上下文对象，用于在模型执行期间存储配置选项
上下文对象需在模型构建时传入，控制模型执行行为
上下文对象的生命周期由 OH_AI_ContextDestroy 管理释放

返回值

返回值	文字含义	触发场景
非 NULL	上下文对象句柄	创建成功
NULL	创建失败	内存不足或系统资源不可用

OH_AI_ContextDestroy

void OH_AI_ContextDestroy(OH_AI_ContextHandle* context)

功能说明

销毁上下文对象，释放上下文占用的资源
传入上下文对象句柄的指针，销毁后句柄被置空
不可对同一上下文句柄重复销毁

入参

名称	参数类型	详细说明	约束取值范围
context	OH_AI_ContextHandle*	上下文对象指针	非 NULL，指向有效的上下文对象句柄

OH_AI_ModelCreate

OH_AI_ModelHandle OH_AI_ModelCreate(void)

功能说明

创建一个模型对象，后续通过构建接口加载模型数据
作为模型构建接口的前置步骤，构建后方可执行推理
模型对象的生命周期由 OH_AI_ModelDestroy 管理释放

返回值

返回值	文字含义	触发场景
非 NULL	模型对象句柄	创建成功
NULL	创建失败	内存不足或系统资源不可用

OH_AI_ModelBuildFromFile

OH_AI_Status OH_AI_ModelBuildFromFile(OH_AI_ModelHandle model, const char* model_path, const OH_AI_ContextHandle model_context)

功能说明

从模型文件路径加载并构建模型，使其可以在设备上运行

前置条件

调用时序约束：已通过 OH_AI_ModelCreate 创建模型对象
调用时序约束：已通过 OH_AI_ContextCreate 创建上下文对象
模型路径指向有效的模型文件

入参

名称	参数类型	详细说明	约束取值范围
model	OH_AI_ModelHandle	模型对象句柄	非 NULL，通过 OH_AI_ModelCreate 创建的有效句柄
model_path	const char*	定义模型文件路径	非 NULL，指向有效模型文件路径字符串
model_context	const OH_AI_ContextHandle	定义用于在执行期间存储选项的上下文句柄	非 NULL，通过 OH_AI_ContextCreate 创建的有效句柄

返回值

返回值	文字含义	触发场景
OH_AI_STATUS_SUCCESS(0)	构建成功	模型文件合法，构建完成
OH_AI_STATUS_FAILED(1)	构建失败	模型文件无效、路径不存在或构建过程异常

OH_AI_ModelBuild

OH_AI_Status OH_AI_ModelBuild(OH_AI_ModelHandle model, const void* model_data, size_t data_size, const OH_AI_ContextHandle model_context)

功能说明

从模型文件缓冲区加载并构建模型，使其可以在设备上运行
适用于模型数据已加载到内存的场景，无需通过文件路径访问

前置条件

调用时序约束：已通过 OH_AI_ModelCreate 创建模型对象

入参

名称	参数类型	详细说明	约束取值范围
model	OH_AI_ModelHandle	模型对象句柄	非 NULL，通过 OH_AI_ModelCreate 创建的有效句柄
model_data	const void*	定义从模型文件读取的缓冲区	非 NULL，指向有效模型数据缓冲区
data_size	size_t	定义模型文件缓冲区的字节数	大于 0
model_context	const OH_AI_ContextHandle	定义用于在执行期间存储选项的上下文句柄	非 NULL，通过 OH_AI_ContextCreate 创建的有效句柄

返回值

返回值	文字含义	触发场景
OH_AI_STATUS_SUCCESS(0)	构建成功	模型数据合法，构建完成
OH_AI_STATUS_FAILED(1)	构建失败	模型数据无效或构建过程异常

OH_AI_ModelBuildFromName

OH_AI_Status OH_AI_ModelBuildFromName(OH_AI_ModelHandle model, const char* model_name, const OH_AI_ContextHandle model_context)

功能说明

依据模型名称构建模型，使其可以在设备上运行
适用于系统预置模型或已注册模型，通过名称引用而非文件路径

前置条件

调用时序约束：已通过 OH_AI_ModelCreate 创建模型对象

入参

名称	参数类型	详细说明	约束取值范围
model	OH_AI_ModelHandle	模型对象句柄	非 NULL，通过 OH_AI_ModelCreate 创建的有效句柄
model_name	const char*	定义模型名称	非 NULL，指向有效模型名称字符串
model_context	const OH_AI_ContextHandle	定义用于在执行期间存储选项的上下文句柄	非 NULL，通过 OH_AI_ContextCreate 创建的有效句柄

返回值

返回值	文字含义	触发场景
OH_AI_STATUS_SUCCESS(0)	构建成功	模型名称合法，构建完成
OH_AI_STATUS_FAILED(1)	构建失败	模型名称无效或构建过程异常

OH_AI_ModelDestroy

void OH_AI_ModelDestroy(OH_AI_ModelHandle* model)

功能说明

销毁模型对象，释放模型占用的资源
传入模型对象句柄的指针，销毁后句柄被置空
不可对同一模型句柄重复销毁

入参

名称	参数类型	详细说明	约束取值范围
model	OH_AI_ModelHandle*	模型对象句柄指针	非 NULL，指向有效的模型对象句柄

OH_AI_ModelGetInputs

OH_AI_TensorHandleArray OH_AI_ModelGetInputs(const OH_AI_ModelHandle model)

功能说明

获取模型的所有输入张量句柄，返回包含所有输入张量句柄的数组
返回的张量句柄用于向模型传入推理输入数据

前置条件

调用时序约束：模型已构建完成，否则无法获取有效输入张量

入参

名称	参数类型	详细说明	约束取值范围
model	const OH_AI_ModelHandle	模型对象句柄	非 NULL，已构建完成的有效模型句柄

返回值

返回类型：OH_AI_TensorHandleArray，包含所有输入张量句柄的数组

OH_AI_ModelGetOutputs

OH_AI_TensorHandleArray OH_AI_ModelGetOutputs(const OH_AI_ModelHandle model)

功能说明

获取模型的所有输出张量句柄，返回包含所有输出张量句柄的数组
返回的张量句柄用于接收模型推理输出数据

前置条件

调用时序约束：模型已构建完成，否则无法获取有效输出张量

入参

名称	参数类型	详细说明	约束取值范围
model	const OH_AI_ModelHandle	模型对象句柄	非 NULL，已构建完成的有效模型句柄

返回值

返回类型：OH_AI_TensorHandleArray，包含所有输出张量句柄的数组

OH_AI_ModelPredict

OH_AI_Status OH_AI_ModelPredict(OH_AI_ModelHandle model, const OH_AI_TensorHandleArray inputs, OH_AI_TensorHandleArray* outputs)

功能说明

执行模型推理，将输入张量数据传入模型并获取推理结果
推理结果通过输出张量句柄数组返回

前置条件

调用时序约束：模型已构建完成，输入张量数据已提前填充

入参

名称	参数类型	详细说明	约束取值范围
model	OH_AI_ModelHandle	模型对象句柄	非 NULL，已构建完成的有效模型句柄
inputs	const OH_AI_TensorHandleArray	包含所有输入张量句柄的数组	handle_num 与模型输入数一致，handle_list 非 NULL

出参

名称	数据类型	输出说明
outputs	OH_AI_TensorHandleArray*	包含所有输出张量句柄的数组指针

返回值

返回值	文字含义	触发场景
OH_AI_STATUS_SUCCESS(0)	推理成功	输入数据合法，推理完成
OH_AI_STATUS_FAILED(1)	推理失败	输入数据无效或推理过程异常

OH_AI_TensorGetDataSize

size_t OH_AI_TensorGetDataSize(const OH_AI_TensorHandle tensor)

功能说明

获取张量的数据大小，返回张量中数据的字节总数
需传入有效的张量对象句柄
返回值可用于确定数据缓冲区大小

入参

名称	参数类型	详细说明	约束取值范围
tensor	const OH_AI_TensorHandle	张量对象句柄	非 NULL，有效的张量句柄

返回值

返回类型：size_t，张量的数据大小（字节数）

OH_AI_TensorGetShape

const int64_t* OH_AI_TensorGetShape(const OH_AI_TensorHandle tensor, size_t* shape_num)

功能说明

获取张量的形状，返回形状数组及维度数
需传入有效的张量对象句柄
返回的形状数组描述张量各维度大小

入参

名称	参数类型	详细说明	约束取值范围
tensor	const OH_AI_TensorHandle	张量对象的句柄	非 NULL，有效的张量句柄

出参

名称	数据类型	输出说明
shape_num	size_t*	输出张量形状的维度数

返回值

返回类型：const int64_t*，张量的形状数组指针

OH_AI_TensorGetElementNum

int64_t OH_AI_TensorGetElementNum(const OH_AI_TensorHandle tensor)

功能说明

获取张量中元素的个数，返回张量中包含的所有元素总数
需传入有效的张量对象句柄
返回值为各维度大小的乘积

入参

名称	参数类型	详细说明	约束取值范围
tensor	const OH_AI_TensorHandle	张量对象句柄	非 NULL，有效的张量句柄

返回值

返回类型：int64_t，张量中元素的个数

OH_AI_TensorGetDataType

OH_AI_DataType OH_AI_TensorGetDataType(const OH_AI_TensorHandle tensor)

功能说明

获取张量的数据类型，返回张量中元素的数据类型枚举值
需传入有效的张量对象句柄
数据类型可用于确定元素的字节大小和解析方式

入参

名称	参数类型	详细说明	约束取值范围
tensor	const OH_AI_TensorHandle	张量对象句柄	非 NULL，有效的张量句柄

返回值

返回类型：OH_AI_DataType，张量的数据类型

OH_AI_TensorGetMutableData

void* OH_AI_TensorGetMutableData(const OH_AI_TensorHandle tensor)

功能说明

获取张量的数据指针，如果内部数据为空，会分配内存
需传入有效的张量对象句柄
返回的指针可直接读写张量中的数据

入参

名称	参数类型	详细说明	约束取值范围
tensor	const OH_AI_TensorHandle	张量对象句柄	非 NULL，有效的张量句柄

返回值

返回类型：void*，张量的数据指针；若内部数据为空则分配内存后返回

OH_AI_GetErrorCode

int32_t OH_AI_GetErrorCode(void)

功能说明

获取详细错误码，返回最近一次AI接口调用的详细错误信息
在接口返回 OH_AI_STATUS_FAILED 后调用，获取具体错误原因
错误码为平台定义的整数值，不同错误对应不同取值

返回值

返回类型：int32_t，详细错误码

Enumerations

OH_AI_Status

typedef enum OH_AI_Status {
    OH_AI_STATUS_SUCCESS = 0,
    OH_AI_STATUS_FAILED = 1,
} OH_AI_Status;

枚举成员	取值	描述
OH_AI_STATUS_SUCCESS	0	执行成功
OH_AI_STATUS_FAILED	1	执行失败

OH_AI_DataType

typedef enum OH_AI_DataType {
    OH_AI_DATATYPE_UNKNOWN = 0,
    OH_AI_DATATYPE_OBJECTTYPE_STRING = 12,
    OH_AI_DATATYPE_OBJECTTYPE_LIST = 13,
    OH_AI_DATATYPE_OBJECTTYPE_TUPLE = 14,
    OH_AI_DATATYPE_OBJECTTYPE_TENSOR = 17,
    OH_AI_DATATYPE_NUMBERTYPE_BEGIN = 29,
    OH_AI_DATATYPE_NUMBERTYPE_BOOL = 30,
    OH_AI_DATATYPE_NUMBERTYPE_INT8 = 32,
    OH_AI_DATATYPE_NUMBERTYPE_INT16 = 33,
    OH_AI_DATATYPE_NUMBERTYPE_INT32 = 34,
    OH_AI_DATATYPE_NUMBERTYPE_INT64 = 35,
    OH_AI_DATATYPE_NUMBERTYPE_UINT8 = 37,
    OH_AI_DATATYPE_NUMBERTYPE_UINT16 = 38,
    OH_AI_DATATYPE_NUMBERTYPE_UINT32 = 39,
    OH_AI_DATATYPE_NUMBERTYPE_UINT64 = 40,
    OH_AI_DATATYPE_NUMBERTYPE_FLOAT16 = 42,
    OH_AI_DATATYPE_NUMBERTYPE_FLOAT32 = 43,
    OH_AI_DATATYPE_NUMBERTYPE_FLOAT64 = 44,
    OH_AI_DATATYPE_NUMBERTYPE_END = 46,
    OH_AI_DataTypeInvalid = INT32_MAX,
} OH_AI_DataType;

枚举成员	取值	描述
OH_AI_DATATYPE_UNKNOWN	0	未知数据类型
OH_AI_DATATYPE_OBJECTTYPE_STRING	12	字符串类型
OH_AI_DATATYPE_OBJECTTYPE_LIST	13	列表类型
OH_AI_DATATYPE_OBJECTTYPE_TUPLE	14	元组类型
OH_AI_DATATYPE_OBJECTTYPE_TENSOR	17	张量类型
OH_AI_DATATYPE_NUMBERTYPE_BEGIN	29	数值类型起始标记
OH_AI_DATATYPE_NUMBERTYPE_BOOL	30	布尔类型
OH_AI_DATATYPE_NUMBERTYPE_INT8	32	8位有符号整数
OH_AI_DATATYPE_NUMBERTYPE_INT16	33	16位有符号整数
OH_AI_DATATYPE_NUMBERTYPE_INT32	34	32位有符号整数
OH_AI_DATATYPE_NUMBERTYPE_INT64	35	64位有符号整数
OH_AI_DATATYPE_NUMBERTYPE_UINT8	37	8位无符号整数
OH_AI_DATATYPE_NUMBERTYPE_UINT16	38	16位无符号整数
OH_AI_DATATYPE_NUMBERTYPE_UINT32	39	32位无符号整数
OH_AI_DATATYPE_NUMBERTYPE_UINT64	40	64位无符号整数
OH_AI_DATATYPE_NUMBERTYPE_FLOAT16	42	16位浮点数
OH_AI_DATATYPE_NUMBERTYPE_FLOAT32	43	32位浮点数
OH_AI_DATATYPE_NUMBERTYPE_FLOAT64	44	64位浮点数
OH_AI_DATATYPE_NUMBERTYPE_END	46	数值类型结束标记
OH_AI_DataTypeInvalid	INT32_MAX	无效数据类型

Structures

OH_AI_TensorHandleArray

typedef struct OH_AI_TensorHandleArray {
    size_t handle_num;
    OH_AI_TensorHandle* handle_list;
} OH_AI_TensorHandleArray;

成员说明

成员名称	数据类型	描述
handle_num	size_t	张量句柄数量
handle_list	OH_AI_TensorHandle*	张量句柄列表指针

Type definitions

OH_AI_TensorHandle

typedef void* OH_AI_TensorHandle;

使用说明 张量对象句柄类型，用于 OH_AI_ModelGetInputs、OH_AI_ModelGetOutputs、OH_AI_TensorGetDataSize、OH_AI_TensorGetShape、OH_AI_TensorGetElementNum、OH_AI_TensorGetDataType、OH_AI_TensorGetMutableData 接口的入参或返回值

OH_AI_ContextHandle

typedef void* OH_AI_ContextHandle;

使用说明 上下文对象句柄类型，用于 OH_AI_ContextDestroy、OH_AI_ModelBuildFromFile、OH_AI_ModelBuild、OH_AI_ModelBuildFromName 接口的入参

OH_AI_ModelHandle

typedef void* OH_AI_ModelHandle;

使用说明 模型对象句柄类型，用于 OH_AI_ModelBuildFromFile、OH_AI_ModelBuild、OH_AI_ModelBuildFromName、OH_AI_ModelDestroy、OH_AI_ModelGetInputs、OH_AI_ModelGetOutputs、OH_AI_ModelPredict 接口的入参

Macros

OH_AI_API

#ifndef OH_AI_API
#ifdef _WIN32
#define OH_AI_API __declspec(dllexport)
#else
#define OH_AI_API __attribute__((visibility("default")))
#endif
#endif