人脸识别接口说明文档

文档版本	V1.0
修订日期	2026-08-18
对应头文件	`components/media/framework/api/include/api_fr.h`
类型定义	`components/media/framework/api/include/api_fr.h`
适用模块	人脸识别组件（FR / Face Recognition）

1 概述

本模块对外提供 hi_fw_fr_* 系列接口，封装了人脸检测 + 人脸特征提取 + 底库比对的完整能力。组件在内部串行调度 AIDETECT 检测模型与 AIVSR 特征模型，自动从 VPSS 通道取帧、推理并回调结果；同时提供人脸底库的加载/卸载与实时人脸录入（现场采集特征入库）能力。任务以独立工作线程运行，调用方通过结果回调获取每帧的人脸框、类别、置信度与底库匹配分数。

支持两种运行模式：直调（Direct）——与应用同进程，通过 light_msg 进程内同步消息分发；IPC（Client）——跨进程调用（需配套 server 进程）。

模型层次：

hi_fw_fr（任务句柄）
  └─ 推理工作线程（按 interval_ms 周期取帧）
        ├─ 人脸检测（AIDETECT，model_path）
        ├─ 人脸特征提取 / 比对（AIVSR，fr_model_path + database_dir）
        └─ 结果回调 on_result（每帧）

2 接口总览

编号	接口	模块	功能概述
1	`hi_fw_fr_direct_init`	初始化	直调（同进程）模式全局初始化
2	`hi_fw_fr_direct_deinit`	初始化	直调模式去初始化
3	`hi_fw_fr_client_init`	初始化	IPC 客户端模式初始化
4	`hi_fw_fr_client_deinit`	初始化	IPC 客户端去初始化
5	`hi_fw_fr_create_task`	任务生命周期	创建人脸识别任务（加载模型、绑定 VPSS 源与回调）
6	`hi_fw_fr_destroy_task`	任务生命周期	销毁任务并释放 NPU/模型资源
7	`hi_fw_fr_start_task`	任务生命周期	启动任务（开始周期推理）
8	`hi_fw_fr_stop_task`	任务生命周期	停止任务（暂停推理）
9	`hi_fw_fr_set_interval`	任务生命周期	动态设置推理周期
10	`hi_fw_fr_get_interval`	任务生命周期	查询当前推理周期
11	`hi_fw_fr_load_face_db`	人脸底库	加载人脸特征底库（directory 下 `*.txt` 特征文件）
12	`hi_fw_fr_unload_face_db`	人脸底库	卸载人脸特征底库
13	`hi_fw_fr_register_face`	实时录入	现场采集人脸特征并录入底库（阻塞至成功/超时）
14	`hi_fw_fr_cancel_register`	实时录入	取消进行中的录入流程

3 API 参考

各接口错误返回值统一约定：返回 TD_SUCCESS（0）成功；返回 TD_FAILURE（-1）失败（具体失败原因经日志输出）。模式差异：直调模式直接在调用进程内执行；IPC 模式经网络/套接字转发，调用语义一致。

3.1 hi_fw_fr_direct_init

【描述】

初始化 fr 组件的直调（同进程）运行模式，创建进程内 light_msg 消息通道。须在创建任何任务之前调用一次。重复调用返回成功（幂等）。

【语法】

td_s32 hi_fw_fr_direct_init(td_void);

【参数】

无。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	初始化成功。
`TD_FAILURE (-1)`	初始化失败（消息通道创建失败等）。

【注意】

直调模式与 IPC 模式互斥选择，二者只需初始化其一。
与 hi_fw_fr_direct_deinit 成对调用；未初始化时调用 hi_fw_fr_create_task 会失败。

【举例】

if (hi_fw_fr_direct_init() != TD_SUCCESS) {
    printf("fr direct init failed\n");
    return -1;
}

【相关主题】

hi_fw_fr_direct_deinit、hi_fw_fr_client_init、hi_fw_fr_create_task

3.2 hi_fw_fr_direct_deinit

【描述】

去初始化 fr 直调模式，释放全局资源。须在所有任务销毁后调用。

【语法】

td_void hi_fw_fr_direct_deinit(td_void);

【参数】

无。

【返回值】

无。

【注意】

调用前必须销毁所有 fr 任务（hi_fw_fr_destroy_task），否则存在悬空引用风险。
应用退出清理路径中与 hi_fw_fr_direct_init 逆序成对调用。

【举例】

hi_fw_fr_direct_deinit();

【相关主题】

hi_fw_fr_direct_init、hi_fw_fr_destroy_task

3.3 hi_fw_fr_client_init

【描述】

以 IPC 客户端模式初始化 fr 组件，连接到指定端点的 fr server。直调与 IPC 二选一。

【语法】

td_s32 hi_fw_fr_client_init(const td_char *endpoint);

【参数】

参数名称	输入/输出	类型	描述
`endpoint`	输入	`const td_char *`	server 端点标识（如 UDS 路径）；不可为 NULL。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	初始化成功。
`TD_FAILURE (-1)`	初始化失败（端点无效、连接失败等）。

【注意】

当前 home_robot 应用采用直调模式，本接口用于 IPC 部署场景。
与 hi_fw_fr_client_deinit 成对调用。

【举例】

if (hi_fw_fr_client_init("/tmp/fr_server.sock") != TD_SUCCESS) {
    /* fallback to direct mode */
}

【相关主题】

hi_fw_fr_client_deinit、hi_fw_fr_direct_init

3.4 hi_fw_fr_client_deinit

【描述】

去初始化 fr IPC 客户端模式，断开与 server 的连接并释放客户端资源。

【语法】

td_s32 hi_fw_fr_client_deinit(td_void);

【参数】

无。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	成功。
`TD_FAILURE (-1)`	失败。

【注意】

须在任务销毁后调用；与 hi_fw_fr_client_init 成对。

【举例】

hi_fw_fr_client_deinit();

【相关主题】

hi_fw_fr_client_init

3.5 hi_fw_fr_create_task

【描述】

创建人脸识别任务：加载检测/特征模型、绑定 VPSS 取帧源与结果回调，创建内部工作线程（创建后处于待启动状态）。任务创建即持有 NPU 模型资源，同一时刻仅支持一套 fr 任务（CV610 NPU 约束）。

【语法】

td_s32 hi_fw_fr_create_task(const hi_fw_fr_task_attr *attr,
                            hi_fw_fr_handle *handle);

【参数】

参数名称	输入/输出	类型	描述
`attr`	输入	`const hi_fw_fr_task_attr *`	任务属性（模型路径、输入源、回调、周期）；不可为 NULL。
`handle`	输出	`hi_fw_fr_handle *`	成功时返回任务句柄；不可为 NULL。

hi_fw_fr_task_attr 成员：

成员名称	描述
`model_path`	AIDETECT 检测模型路径（如 `det_hvf_hor.bin`）；必填。
`fr_model_path`	AIVSR 特征模型路径（如 `vsr_fr.bin`）；为 NULL 时仅做检测不比对。
`database_dir`	人脸特征底库目录；可选，NULL 表示不加载底库。
`src`	输入源配置（当前支持 VPSS 源：`vpss_grp` / `vpss_chn`）。
`on_result`	每帧结果回调；不可为 NULL。
`interval_ms`	推理周期（毫秒），如 33ms ≈ 30fps。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	任务创建成功，`handle` 有效。
`TD_FAILURE (-1)`	创建失败（模型缺失、NPU 资源占用、参数非法等）。

【注意】

创建前必须先调用 hi_fw_fr_direct_init（直调模式）或 hi_fw_fr_client_init（IPC 模式），否则返回失败。
模型文件缺失时创建失败并输出日志，应用需自行重试或告警。
创建后需调用 hi_fw_fr_start_task 才开始推理。

【举例】

hi_fw_fr_task_attr attr;
memset_s(&attr, sizeof(attr), 0, sizeof(attr));
attr.model_path    = "/usr/lib/model/det_hvf_hor.bin";
attr.fr_model_path = "/usr/lib/model/vsr_fr.bin";
attr.database_dir  = "/usr/lib/model";
attr.src.type      = HI_FW_FR_SOURCE_VPSS;
attr.src.vpss.vpss_grp = 0;
attr.src.vpss.vpss_chn = 2;
attr.on_result     = my_fr_cb;
attr.interval_ms   = 33;
if (hi_fw_fr_create_task(&attr, &fr_handle) != TD_SUCCESS) {
    printf("fr create task failed\n");
}

【相关主题】

hi_fw_fr_task_attr、hi_fw_fr_destroy_task、hi_fw_fr_start_task、hi_fw_fr_load_face_db

3.6 hi_fw_fr_destroy_task

【描述】

销毁 fr 任务：停止工作线程、卸载模型并释放 NPU 资源。销毁后句柄不可再使用。

【语法】

td_s32 hi_fw_fr_destroy_task(hi_fw_fr_handle handle);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_fr_handle`	待销毁的任务句柄；NULL 时返回失败。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	销毁成功。
`TD_FAILURE (-1)`	句柄无效或销毁失败。

【注意】

销毁前建议先 hi_fw_fr_stop_task 停止推理，或直接销毁（内部会停止工作线程）。
销毁后回调不会再触发；调用方不得再使用该句柄。
与 hi_fw_fr_create_task 成对调用。

【举例】

hi_fw_fr_destroy_task(fr_handle);
fr_handle = NULL;

【相关主题】

hi_fw_fr_create_task、hi_fw_fr_stop_task

3.7 hi_fw_fr_start_task

【描述】

启动 fr 任务，工作线程开始按 interval_ms 周期从绑定 VPSS 通道取帧并推理，每帧回调 on_result。

【语法】

td_s32 hi_fw_fr_start_task(hi_fw_fr_handle handle, td_s32 count);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_fr_handle`	任务句柄；不可为 NULL。
`count`	输入	`td_s32`	固定推理帧数：`-1` 表示持续运行直到 `stop/destroy`；`>=0` 表示处理 `count` 帧后自动暂停。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	启动成功。
`TD_FAILURE (-1)`	启动失败（句柄无效、任务状态异常等）。

【注意】

对已运行的任务重复调用返回成功（幂等）。
count >= 0 场景（如快照 N 帧）处理完自动回到暂停态，无需显式 stop。

【举例】

hi_fw_fr_start_task(fr_handle, -1);   /* 持续运行 */

【相关主题】

hi_fw_fr_stop_task、hi_fw_fr_create_task

3.8 hi_fw_fr_stop_task

【描述】

暂停 fr 任务推理（不销毁任务与模型）。停止后回调不再触发，可通过 start_task 恢复。

【语法】

td_s32 hi_fw_fr_stop_task(hi_fw_fr_handle handle);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_fr_handle`	任务句柄；不可为 NULL。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	停止成功。
`TD_FAILURE (-1)`	句柄无效或停止失败。

【注意】

停止不释放 NPU/模型资源，如需释放请用 hi_fw_fr_destroy_task。

【举例】

hi_fw_fr_stop_task(fr_handle);

【相关主题】

hi_fw_fr_start_task、hi_fw_fr_destroy_task

3.9 hi_fw_fr_set_interval

【描述】

动态调整任务推理周期（毫秒）。修改在下一推理周期生效。

【语法】

td_s32 hi_fw_fr_set_interval(hi_fw_fr_handle handle, td_u32 interval_ms);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_fr_handle`	任务句柄；不可为 NULL。
`interval_ms`	输入	`td_u32`	推理周期（毫秒）；`0` 视为非法，按创建时的默认值处理或返回失败。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	设置成功。
`TD_FAILURE (-1)`	句柄无效或参数非法。

【注意】

用于运行中动态调速（如低功耗场景拉长周期）。
与 hi_fw_fr_get_interval 成对使用。

【举例】

hi_fw_fr_set_interval(fr_handle, 100);   /* 降频到 10fps */

【相关主题】

hi_fw_fr_get_interval、hi_fw_fr_task_attr.interval_ms

3.10 hi_fw_fr_get_interval

【描述】

查询任务当前推理周期（毫秒）。

【语法】

td_s32 hi_fw_fr_get_interval(hi_fw_fr_handle handle, td_u32 *interval_ms);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_fr_handle`	任务句柄；不可为 NULL。
`interval_ms`	输出	`td_u32 *`	返回当前推理周期；不可为 NULL。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	查询成功。
`TD_FAILURE (-1)`	句柄无效或输出指针为 NULL。

【举例】

td_u32 interval = 0;
hi_fw_fr_get_interval(fr_handle, &interval);

【相关主题】

hi_fw_fr_set_interval

3.11 hi_fw_fr_load_face_db

【描述】

加载人脸特征底库：扫描 database_dir 目录下所有 *.txt 特征文件（首行为姓名，后续行为 128 维特征值），加载后检测到的人脸会与底库比对并输出 match_score 与匹配姓名。

【语法】

td_s32 hi_fw_fr_load_face_db(hi_fw_fr_handle handle);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_fr_handle`	任务句柄；不可为 NULL。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	底库加载完成（含 0 人）。
`TD_FAILURE (-1)`	加载失败（目录无效等）。

【注意】

底库目录在 hi_fw_fr_create_task 的 attr.database_dir 指定；加载后可用 hi_fw_fr_register_face 增量写入。
未匹配到底库的人脸，回调结果中 name 为 "unknown"、match_score 为 0。
与 hi_fw_fr_unload_face_db 成对。

【举例】

hi_fw_fr_load_face_db(fr_handle);

【相关主题】

hi_fw_fr_unload_face_db、hi_fw_fr_register_face、hi_fw_fr_task_attr.database_dir

3.12 hi_fw_fr_unload_face_db

【描述】

卸载已加载的人脸特征底库。卸载后比对功能停用，检测到的人脸均视为 unknown。

【语法】

td_s32 hi_fw_fr_unload_face_db(hi_fw_fr_handle handle);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_fr_handle`	任务句柄；不可为 NULL。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	卸载成功。
`TD_FAILURE (-1)`	句柄无效。

【注意】

卸载不删除磁盘上的特征文件，仅释放内存中的比对库。

【举例】

hi_fw_fr_unload_face_db(fr_handle);

【相关主题】

hi_fw_fr_load_face_db

3.13 hi_fw_fr_register_face

【描述】

实时录入人脸：阻塞等待摄像头前出现清晰人脸，提取特征并写入底库（同步落盘为 *.txt 特征文件）。录入期间任务自动切换到"录入"模式采集，完成后恢复检测。录入姓名由 name 指定。

【语法】

td_s32 hi_fw_fr_register_face(hi_fw_fr_handle handle, const td_char *name, td_s32 timeout_ms);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_fr_handle`	任务句柄；不可为 NULL。
`name`	输入	`const td_char *`	录入人姓名（写入底库，后续比对返回该姓名）；不可为 NULL。
`timeout_ms`	输入	`td_s32`	采集超时（毫秒），超时未采到清晰人脸则失败返回；`-1` 表示无限等待。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	录入成功，特征已入库并落盘。
`TD_FAILURE (-1)`	录入失败（超时、未检测到人脸、写库失败等）。

【注意】

该接口阻塞调用（最长 timeout_ms），建议在独立线程或状态机中调用，避免阻塞主流程（home_robot 在 AI 主线程的 FACE_ENROLL 态调用）。
录入期间推理结果回调仍会触发，调用方需自行过滤录入态结果。
录入成功后后续帧比对即可命中该 name。

【举例】

if (hi_fw_fr_register_face(fr_handle, "alice", 10000) == TD_SUCCESS) {
    printf("enroll ok\n");
}

【相关主题】

hi_fw_fr_cancel_register、hi_fw_fr_load_face_db、hi_fw_fr_object.name

3.14 hi_fw_fr_cancel_register

【描述】

取消进行中的人脸录入流程（由其他线程调用以中断阻塞中的 hi_fw_fr_register_face）。

【语法】

td_s32 hi_fw_fr_cancel_register(hi_fw_fr_handle handle);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_fr_handle`	任务句柄；不可为 NULL。

【返回值】

返回值	描述
`TD_SUCCESS (0)`	取消请求已发出。
`TD_FAILURE (-1)`	句柄无效。

【注意】

无进行中录入时调用返回成功（幂等）。

【举例】

hi_fw_fr_cancel_register(fr_handle);

【相关主题】

hi_fw_fr_register_face

4 数据类型

4.1 hi_fw_fr_handle

【说明】

fr 任务的不透明句柄，由 hi_fw_fr_create_task 创建，贯穿任务生命周期。

【定义】

typedef struct hi_fw_fr_task_opaque *hi_fw_fr_handle;

【成员】

无（不透明指针，内部实现隐藏）。

【注意事项】

句柄仅在其所属任务存活期间有效；hi_fw_fr_destroy_task 后不得再使用。
多线程共享同一句柄时需自行同步（内部工作线程与调用线程并发）。

【相关数据类型及接口】

hi_fw_fr_create_task、hi_fw_fr_destroy_task

4.2 hi_fw_fr_class

【说明】

识别/检测目标类别枚举（与 AIDETECT 类别对齐）。

【定义】

typedef enum {
    HI_FW_FR_CLASS_FACE          = 0,
    HI_FW_FR_CLASS_HUMAN         = 1,
    HI_FW_FR_CLASS_VEHICLE       = 2,
    HI_FW_FR_CLASS_PET           = 3,
    HI_FW_FR_CLASS_GARBAGE       = 4,
    HI_FW_FR_CLASS_BAG           = 5,
    HI_FW_FR_CLASS_WALLET        = 6,
    HI_FW_FR_CLASS_PHONE         = 7,
    HI_FW_FR_CLASS_HEAD_SHOULDER = 8,
    HI_FW_FR_CLASS_BICYCLE       = 9,
    HI_FW_FR_CLASS_MOTORCYCLE    = 10,
    HI_FW_FR_CLASS_PACKAGE       = 11,
    HI_FW_FR_CLASS_BUTT          = 12,
} hi_fw_fr_class;

【成员】

成员名称	描述
`HI_FW_FR_CLASS_FACE`	人脸。
`HI_FW_FR_CLASS_HUMAN`	人体。
`HI_FW_FR_CLASS_VEHICLE` / `PET` / `GARBAGE` / `BAG` / `WALLET` / `PHONE` / `BICYCLE` / `MOTORCYCLE` / `PACKAGE`	其他检测类别。
`HI_FW_FR_CLASS_HEAD_SHOULDER`	头肩。
`HI_FW_FR_CLASS_BUTT`	枚举结束哨兵。

【注意事项】

人脸比对仅针对 HI_FW_FR_CLASS_FACE 对象执行；其他类别直接透传检测框（match_score 为 0）。

【相关数据类型及接口】

hi_fw_fr_object

4.3 hi_fw_fr_rect

【说明】

图像坐标系中的矩形区域（人脸/目标框）。

【定义】

typedef struct {
    td_s32  x;
    td_s32  y;
    td_u32  width;
    td_u32  height;
} hi_fw_fr_rect;

【成员】

成员名称	描述
`x`	左上角 x 坐标（像素）。
`y`	左上角 y 坐标（像素）。
`width`	框宽（像素）。
`height`	框高（像素）。

【注意事项】

坐标为输入源图像分辨率坐标系（如 VPSS 通道分辨率 1920x1080）。

【相关数据类型及接口】

hi_fw_fr_object

4.4 hi_fw_fr_object

【说明】

单个识别对象：目标框 + 类别 + 置信度 + 底库匹配结果。

【定义】

typedef struct {
    hi_fw_fr_rect  rect;
    td_float               confidence;
    hi_fw_fr_class type;
    td_char                name[64];       /* matched person name, "unknown" if not matched */
    td_float               match_score;    /* face match similarity */
} hi_fw_fr_object;

【成员】

成员名称	描述
`rect`	目标框（见 `hi_fw_fr_rect`）。
`confidence`	检测置信度（0.0 ~ 1.0）。
`type`	目标类别（见 `hi_fw_fr_class`）。
`name`	底库匹配姓名；未命中时为 `"unknown"`。
`match_score`	人脸特征匹配分数（相似度）；未比对或未命中为 0。

【注意事项】

name 为 "unknown" 时不应视为底库命中，判断命中应以 match_score 是否达阈值（如 0.3）为准。
objs 由组件内部管理，仅在本次回调内有效。

【相关数据类型及接口】

hi_fw_fr_result、hi_fw_fr_rect

4.5 hi_fw_fr_result

【说明】

单帧识别结果：目标数量 + 对象数组指针。

【定义】

typedef struct {
    td_u32                          count;
    const hi_fw_fr_object  *objs;
} hi_fw_fr_result;

【成员】

成员名称	描述
`count`	本帧识别对象数量；0 表示无人脸/无目标。
`objs`	对象数组（`count` 个元素）。

【注意事项】

objs 内存由组件管理，仅在 on_result 回调函数体内有效，调用方如需保存需自行拷贝。

【相关数据类型及接口】

hi_fw_fr_object、hi_fw_fr_result_cb

4.6 hi_fw_fr_result_cb

【说明】

每帧识别结果回调函数类型。

【定义】

typedef td_void (*hi_fw_fr_result_cb)(hi_fw_fr_handle handle,
                                      const hi_fw_fr_result *result);

【成员】

参数名称	描述
`handle`	触发回调的任务句柄。
`result`	本帧识别结果（可能 count=0，表示无目标）。

【注意事项】

回调在组件工作线程中执行，回调内禁止长时间阻塞、禁止调用销毁类接口（会造成死锁/悬空）。
每帧都会触发（含无人脸帧，count=0），调用方可借此清理旧叠加。

【相关数据类型及接口】

hi_fw_fr_result、hi_fw_fr_task_attr.on_result

4.7 hi_fw_fr_source_type / hi_fw_fr_source / hi_fw_fr_source_vpss

【说明】

任务输入源配置：当前支持 VPSS 通道取帧。

【定义】

typedef enum {
    HI_FW_FR_SOURCE_VPSS = 0,
    HI_FW_FR_SOURCE_BUTT
} hi_fw_fr_source_type;

typedef struct {
    td_u32 vpss_grp;
    td_u32 vpss_chn;
} hi_fw_fr_source_vpss;

typedef struct {
    hi_fw_fr_source_type type;
    union {
        hi_fw_fr_source_vpss vpss;
    };
} hi_fw_fr_source;

【成员】

成员名称	描述
`type`	源类型（当前仅 `HI_FW_FR_SOURCE_VPSS`）。
`vpss_grp`	VPSS 组号（如 0）。
`vpss_chn`	VPSS 通道号（如 2）。

【注意事项】

该 VPSS 通道的输出像素格式需与组件期望一致（YVU420 SP）。
同一 VPSS 通道不建议被多个任务/模块同时取帧。

【相关数据类型及接口】

hi_fw_fr_task_attr

4.8 hi_fw_fr_task_attr

【说明】

hi_fw_fr_create_task 的任务属性配置。

【定义】

typedef struct {
    const td_char               *model_path;       /* AIDETECT detection model */
    const td_char               *fr_model_path;     /* AIVSR FR model (optional, NULL = detection only) */
    const td_char               *database_dir;      /* face feature database dir (optional) */
    hi_fw_fr_source      src;
    hi_fw_fr_result_cb   on_result;
    td_u32                       interval_ms;
} hi_fw_fr_task_attr;

【成员】

成员名称	描述
`model_path`	检测模型路径（必填）。
`fr_model_path`	特征模型路径（可选，NULL = 仅检测）。
`database_dir`	底库目录（可选）。
`src`	输入源（见 `hi_fw_fr_source`）。
`on_result`	结果回调（必填）。
`interval_ms`	推理周期（毫秒）。

【注意事项】

模型路径缺失会直接导致 create_task 失败，建议调用前 stat 校验。
interval_ms 为 0 时使用组件默认周期。

【相关数据类型及接口】

hi_fw_fr_create_task

4.9 关键常量

常量	取值	说明
`HI_FW_FR_CLASS_BUTT`	12	类别枚举结束哨兵。
`HI_FW_FR_SOURCE_BUTT`	1	输入源枚举结束哨兵。
`name` 未命中值	`"unknown"`	底库未命中时回调对象姓名。
`match_score` 推荐阈值	0.3	判定底库命中的相似度阈值（home_robot 使用）。

5 错误码

fr 组件未定义模块专属错误码宏，所有接口统一返回 TD_SUCCESS / TD_FAILURE，具体失败原因（如底层 MPP/AIComponent 错误码）通过日志打印。

错误代码	宏定义	描述
`0`	`TD_SUCCESS`	操作成功。
`-1`	`TD_FAILURE`	操作失败（详见日志：模型缺失 / NPU 资源不足 / 参数非法 / 超时等）。

底层透传错误码示例（经日志输出）：

错误代码（日志）	来源	描述
`0xa0038007`	MPP RGN	参数非法（如 RGN handle 跨区、属性不完整）。
`0xa003800c`	MPP RGN	操作/类型不支持（如 COVER 绑到不支持的模块）。
`0xa0058012`	MPP VENC	通道未启动（取流时编码未开始）。
`0xa0108007`	MPP VPSS	参数非法（通道未使能 / 绑定冲突）。

6 使用注意事项

句柄范围：hi_fw_fr_handle 由 hi_fw_fr_create_task 创建，hi_fw_fr_destroy_task 销毁后失效；回调内不得销毁任务。

时序依赖：遵循以下启停顺序（停止为逆序）：

启动：

hi_fw_fr_direct_init()                    // 直调模式全局初始化（或 client_init）
  → hi_fw_fr_create_task(attr, &handle)   // 创建任务（加载模型）
  → hi_fw_fr_load_face_db(handle)         // 加载底库（可选）
  → hi_fw_fr_start_task(handle, -1)       // 启动推理
  → [循环] on_result(每帧回调) → ...

停止（逆序）：

hi_fw_fr_stop_task(handle)                // 停止推理（可选）
  → hi_fw_fr_destroy_task(handle)         // 销毁任务、释放模型
  → hi_fw_fr_direct_deinit()              // 直调模式去初始化

资源配对：
- hi_fw_fr_direct_init / hi_fw_fr_direct_deinit（或 client 对）成对调用。
- hi_fw_fr_create_task / hi_fw_fr_destroy_task 成对调用。
- hi_fw_fr_load_face_db / hi_fw_fr_unload_face_db 成对调用（可选）。
- hi_fw_fr_set_interval / hi_fw_fr_get_interval 配合使用。
属性语义：model_path / fr_model_path / src / on_result 为静态属性，仅创建时生效；interval_ms 为动态属性，可在运行中通过 set_interval 调整。
模式差异：直调模式与 IPC 客户端模式二选一初始化；IPC 模式下创建/销毁/查询经网络往返，实时性低于直调（home_robot 使用直调模式）。
NPU 独占：CV610 NPU 同一时刻仅支持一套推理模型。fr 任务运行时不得与其他 AI 组件（如 human_track）并行加载模型；home_robot 通过三模式状态机串行复用。
回调线程安全：on_result 在组件工作线程执行，回调内更新共享状态需加锁，或仅置标志位由外部线程消费。

7 附注 / 关联文档

组件实现：components/media/framework/component_adapter/fr/src/fw_fr.c
直调实现：components/media/framework/api/direct/fr/fr_impl.c / api_fr.c
底层依赖：AIDETECT 接口（ss_mpi_aidetect_*）、AIVSR 接口（ss_mpi_aivsr_*）
参考应用：apps/cv610_ev_board/references/home_robot（FACE_SEARCH / FACE_ENROLL 状态机调用示例）
相关接口文档：人形跟踪组件（api_human_track.h）