能力定位：FReID 接收同一帧图像及人脸 106 点检测结果，输出 face_id 到稳定 track_id 的映射，用于人员离开画面后再次出现时维持身份标识。FReID 依赖人脸检测，不是独立的全身行人 ReID 接口。

公共说明

接入流程

初始化人脸检测；初始化配置必须包含所需模型、检测模式和人脸能力。Java 侧随后必须调用 FaceDetect.setFaceDetectConfig() 设置运行时检测配置，该配置应为初始化配置的子集。

创建 FReID 句柄并完成授权。

如需跨进程保留记忆，配置离线 TrackID 缓存文件，再加载 FReID 模型。

逐帧执行人脸检测，将同一帧图像及其人脸结果传入 FReID。

使用返回的 track_id 维护业务身份。

停止处理时按保存策略落盘并释放句柄。

输入与输出

项目	说明
前置算法	人脸 106 点检测；C 侧传入 bef_ai_face_106，Java 侧传入 detectFaceForFreid() 返回的 BefFreidFaceInfo
支持格式	RGBA8888、BGRA8888、BGR888、RGB888
图像方向	顺时针 0°、90°、180°、270°；对应枚举值 0/1/2/3，必须使用枚举常量，不要直接传角度数值
输出	最多 10 组 face_id → track_id 映射；仅使用 [0, count) 范围内的结果

同帧约束：人脸检测与 FReID 必须使用同一帧图像以及相同的宽、高、stride、像素格式和 orientation。Java 侧必须使用 detectFaceForFreid()，不能用普通 detectFace() 的结果代替。

运行参数

运行参数对 C 和 Java 含义一致。业务没有明确调优需求时使用默认值，不需要主动设置。

参数	值	类型	功能	默认值	是否需要设置
BEF_AI_FREID_THRESHOLD	0	float	设置人脸重识别匹配阈值；阈值越高，匹配越严格	由模型决定；初始化后可通过 getModelParam() 查询 model_thresh	非必需；仅在误匹配或漏匹配需要调优时设置
BEF_AI_FREID_FORCE_DETECT	1	int	控制是否启用强制检测：0 关闭，1 开启	0	非必需；普通接入保持默认值，仅在技术支持指导下设置。

C 使用 bef_effect_ai_freid_set_param_f() 或 bef_effect_ai_freid_set_param_i()；Java 使用 FreidDetect.setParam(...) 的 float 或 int 重载。内部 Demo 未主动设置运行参数，普通接入建议使用模型默认配置；USE_BUFFER、BUFFER_IMMEDIATE_MODE 和 MODEL_TYPE 等高级参数仅在技术支持指导下设置。

C 接入

接口说明

公开接口定义于 bef_effect_ai_freid.h，公共类型与错误码定义于 bef_effect_ai_public_define.h，人脸输入结构定义于 bef_effect_ai_face_detect.h。

1. 创建 FReID 句柄

代码块

参数说明

参数名	参数类型	参数说明
handle	bef_effect_handle_t *	输出参数，用于接收新创建的 FReID 句柄；使用结束后调用 bef_effect_ai_freid_release() 释放。

返回值

成功返回 BEF_RESULT_SUC，其他返回值参见 bef_effect_ai_public_define.h。

2. 校验离线授权

代码块

参数说明

参数名	参数类型	参数说明
handle	bef_effect_handle_t	由 bef_effect_ai_freid_create() 创建的 FReID 句柄。
licensePath	const char *	离线授权文件路径，不能为空字符串。

返回值

成功返回 BEF_RESULT_SUC；授权无效或授权文件未包含 FReID（人脸重识别）能力时返回对应错误码。

3. 校验在线授权

代码块

参数说明

参数名	参数类型	参数说明
handle	bef_effect_handle_t	由 bef_effect_ai_freid_create() 创建的 FReID 句柄。
licensePath	const char *	在线授权文件路径，不能为空字符串。

返回值

成功返回 BEF_RESULT_SUC；授权无效或授权文件未包含 FReID（人脸重识别）能力时返回对应错误码。

4. 加载 FReID 模型

代码块

参数说明

参数名	参数类型	参数说明
handle	bef_effect_handle_t	已完成授权校验的 FReID 句柄。
freidModelPath	const char *	FReID 模型文件路径，不能为空且文件必须可读。若已配置离线 TrackID，初始化时会尝试自动恢复。

返回值

成功返回 BEF_RESULT_SUC；空路径返回 BEF_RESULT_INVALID_PARAM_VALUE，模型不可读或无效时返回模型相关错误码。

5. 设置浮点型运行参数

代码块

参数说明

参数名	参数类型	参数说明
handle	bef_effect_handle_t	FReID 句柄。
type	bef_ai_freid_param_type	参数类型。当前实现接受 BEF_AI_FREID_THRESHOLD 和 BEF_AI_FREID_MODEL_TYPE。
value	float	参数值。普通接入仅在需要调优时设置匹配阈值。

返回值

成功返回 BEF_RESULT_SUC；不支持的参数类型返回 BEF_RESULT_INVALID_PARAM_VALUE。

6. 设置整型运行参数

代码块

参数说明

参数名	参数类型	参数说明
handle	bef_effect_handle_t	FReID 句柄。
type	bef_ai_freid_param_type	参数类型。当前实现接受 BEF_AI_FREID_FORCE_DETECT、BEF_AI_FREID_USE_BUFFER、BEF_AI_FREID_BUFFER_IMMEDIATE_MODE 和 BEF_AI_FREID_MODEL_TYPE。
value	int	参数值。普通接入仅在明确需要时设置 BEF_AI_FREID_FORCE_DETECT。

返回值

成功返回 BEF_RESULT_SUC；不支持的参数类型返回 BEF_RESULT_INVALID_PARAM_VALUE。

7. 配置离线 TrackID

代码块

参数说明

参数名	参数类型	参数说明
handle	bef_effect_handle_t	FReID 句柄。
enable_offline_track_id	int	是否启用离线 TrackID：0 表示关闭，非 0 表示开启。
offline_track_id_path	const char *	缓存文件路径；启用离线 TrackID 时不能为空。
save_mode	bef_ai_freid_offline_save_mode	BEF_AI_FREID_MANUAL_FLUSH_ONLY 表示仅手动保存；BEF_AI_FREID_AUTO_SAVE_ON_NEW_TRACK_ID 表示新增 TrackID 时自动保存。

返回值

成功返回 BEF_RESULT_SUC；路径或保存模式无效时返回 BEF_RESULT_INVALID_PARAM_VALUE。句柄已初始化时，配置成功后会立即尝试恢复已有缓存。

8. 恢复离线 TrackID

代码块

参数说明

参数名	参数类型	参数说明
handle	bef_effect_handle_t	已初始化并配置离线 TrackID 路径的 FReID 句柄。

返回值

成功返回 BEF_RESULT_SUC；缓存文件不存在时返回 BEF_RESULT_FILE_NOT_FIND，配置无效时返回 BEF_RESULT_INVALID_PARAM_VALUE。

9. 写入离线 TrackID

代码块

参数说明

参数名	参数类型	参数说明
handle	bef_effect_handle_t	已初始化并配置离线 TrackID 路径的 FReID 句柄。

返回值

成功返回 BEF_RESULT_SUC；配置无效、序列化失败或文件写入失败时返回对应错误码。

10. 查询模型参数

代码块

参数说明

参数名	参数类型	参数说明
handle	bef_effect_handle_t	已初始化的 FReID 句柄。
model_param	bef_ai_freid_model_param *	输出参数，返回 model_version、model_thresh 和 trackid_num。

返回值

成功返回 BEF_RESULT_SUC；model_param 为空时返回 BEF_RESULT_INVALID_PARAM_VALUE。

11. 释放 FReID 句柄

代码块

参数说明

参数名	参数类型	参数说明
handle	bef_effect_handle_t	待释放的 FReID 句柄。释放前会尝试写入已配置的离线 TrackID。

返回值

当前实现完成资源释放后返回 BEF_RESULT_SUC。

12. 执行 FReID 检测

代码块

参数说明

参数名	参数类型	参数说明
handle	bef_effect_handle_t	已初始化的 FReID 句柄。
image	const unsigned char *	当前帧图像数据。
pixel_format	bef_ai_pixel_format	像素格式，支持 RGBA8888、BGRA8888、BGR888 和 RGB888。
image_width	int	图像宽度，单位为像素。
image_height	int	图像高度，单位为像素。
image_stride	int	图像每行数据的字节跨度。
orientation	bef_ai_rotate_type	图像顺时针旋转方向，支持 0°、90°、180° 和 270°；bef_ai_rotate_type 枚举值为 0/1/2/3，必须使用枚举常量，不要直接传角度数值。
ptr_base_info	const bef_ai_face_106 *	同一帧的人脸 106 点结果数组，必须保留 ID、tracking_cnt 和 after_det。
face_count	int	输入人脸数量；内部最多处理结果结构可容纳的人脸数。
freid_result	bef_ai_freid_detect_result *	输出参数，由调用方分配；通过 count 和 freid_pairs 返回 face_id → track_id 映射。

返回值

成功返回 BEF_RESULT_SUC；空指针、方向无效或像素格式不支持时返回对应错误码。

ptr_base_info 必须来自同一帧人脸检测结果，并保留 ID、tracking_cnt、after_det。输出中的 face_id 是当前人脸跟踪 ID，track_id 是业务用于跨重新入镜关联身份的 FReID ID。

调用示例

Java 接入

接口说明

FReID 主类为 FreidDetect。FReID 所需的人脸输入由 FaceDetect.detectFaceForFreid() 生成；该方法属于 FaceDetect，调用前必须成功执行 FaceDetect.init() 和 FaceDetect.setFaceDetectConfig()。

1. 初始化 FReID

代码块

参数说明

参数名	参数类型	参数说明
freidModelPath	String	FReID 模型文件路径。
licensePath	String	授权文件路径。
onlineLicense	boolean	是否使用在线授权；两参数重载默认使用离线授权。

返回值

成功返回 BEF_RESULT_SUC。失败时返回 Java 包装层或 native 层错误码，统一按本文“错误处理”章节排查；不要仅根据 EffectsSDKResultCode 中同名常量推断所有 native 错误。重复初始化直接返回成功。

2. 设置运行参数

代码块

参数说明

参数名	参数类型	参数说明
paramType	FreidParamType	参数类型。float 重载用于浮点参数，int 重载用于整型参数。
value	float / int	参数值。业务没有明确调优需求时使用默认值。

返回值

成功返回 BEF_RESULT_SUC；未初始化时由 Java 包装层返回 -4，参数类型不受支持时 native 返回 BEF_RESULT_INVALID_PARAM_VALUE（-47）。错误码来源差异见本文“错误处理”。

3. 配置离线 TrackID

代码块

参数说明

参数名	参数类型	参数说明
enable	boolean	是否启用离线 TrackID。
datPath	String	缓存文件路径；enable 为 true 时不能为空。
saveMode	FreidOfflineTrackIdSaveMode	MANUAL_FLUSH_ONLY 表示仅手动保存；AUTO_SAVE_ON_NEW_TRACK_ID 表示新增 TrackID 时自动保存；saveMode 不能为 null（为 null 时返回 -47）。

返回值

成功返回 BEF_RESULT_SUC；参数无效时返回 BEF_RESULT_INVALID_PARAM_VALUE。该方法允许在 init() 前调用，配置会在初始化过程中应用。

4. 恢复离线 TrackID

代码块

参数说明

无。

返回值

成功返回 BEF_RESULT_SUC；未初始化时由 Java 包装层返回 -4，缓存不存在时 native 返回 BEF_RESULT_FILE_NOT_FIND（-2），配置无效时返回 BEF_RESULT_INVALID_PARAM_VALUE（-47）。

5. 写入离线 TrackID

代码块

参数说明

无。

返回值

成功返回 BEF_RESULT_SUC；未初始化时由 Java 包装层返回 -4，配置无效、序列化失败或文件写入失败时返回对应 native 错误码。

6. 查询模型参数

代码块

参数说明

无。

返回值

成功返回 BefFreidKeyParam，其中包含 model_version、model_thresh 和 trackid_num；未初始化或 native 调用失败时返回 null。

7. 释放 FReID

代码块

参数说明

无。

返回值

无。已初始化时释放 native 句柄；native 层释放前会尝试写入已配置的离线 TrackID。

8. 获取 FReID 人脸输入

代码块

参数说明

参数名	参数类型	参数说明
buffer	ByteBuffer	当前帧图像数据，必须为 DirectByteBuffer。
pixelFormat	PixlFormat	图像像素格式。
width	int	图像宽度，单位为像素。
height	int	图像高度，单位为像素。
stride	int	图像每行数据的字节跨度。
orientation	Rotation	图像顺时针旋转方向；使用 Rotation 枚举（CLOCKWISE_ROTATE_0/90/180/270，id 为 0/1/2/3），不要直接传角度数值。

返回值

成功返回 BefFreidFaceInfo，包含普通人脸检测结果及逐脸的 faceId、trackingCnt、afterDet；未初始化、未配置人脸检测参数或检测失败时返回 null。

9. 执行 FReID 检测

代码块

参数说明

参数名	参数类型	参数说明
imageBuffer	ByteBuffer	当前帧图像数据，必须为 DirectByteBuffer。
pixelFormat	PixlFormat	图像像素格式，需与生成 freidFaceInfo 时一致。
width	int	图像宽度，需与人脸检测输入一致。
height	int	图像高度，需与人脸检测输入一致。
stride	int	图像每行数据的字节跨度，需与人脸检测输入一致。
orientation	Rotation	图像顺时针旋转方向，需与人脸检测输入一致；使用 Rotation 枚举（CLOCKWISE_ROTATE_0/90/180/270，id 为 0/1/2/3），不要直接传角度数值。
freidFaceInfo	BefFreidFaceInfo	同一帧调用 detectFaceForFreid() 得到的人脸输入。

返回值

成功返回 BefFreidDetectResult；通过 count 和 freid_pairs 提供 face_id → track_id 映射。未初始化或 native 调用失败时返回 null。

imageBuffer 必须是 DirectByteBuffer。BefFreidFaceInfo 额外保存每张脸的 faceId、trackingCnt 和 afterDet；调用 detect() 时必须传入同一帧对应的对象。

调用示例

离线 TrackID 持久化

缓存文件作用：缓存文件保存 FReID 已建立的 TrackID 记忆状态。只要文件没有被删除、覆盖或更换路径，并在下次初始化时成功加载，FReID 就会延续此前记忆。freid_buffer.dat 只是 Demo 使用的文件名，客户可以自定义文件名、目录、保存时机、恢复时机和清理策略。

保存模式

模式	写入时机	用法与取舍
MANUAL_FLUSH_ONLY	仅在业务显式调用 C 的 bef_effect_ai_freid_flush_offline_track_id() 或 Java 的 flushOfflineTrackId() 时写入；release 当前也会尝试保存	在识别会话结束、停止 FReID、页面退出或应用进入后台前调用。可控制文件 I/O；上次成功保存后新增的记忆可能在异常退出时丢失
AUTO_SAVE_ON_NEW_TRACK_ID	每次检测成功后检查 TrackID 总数；总数变化且大于 0 时自动写入	无需逐帧调用 flush。记忆落盘更及时，异常退出丢失风险更低，但新增 TrackID 时会产生文件 I/O

使用规则

建议在 init 前配置缓存路径；初始化会自动尝试恢复，首次运行没有缓存文件不视为失败。

两种模式均可显式调用 flush；不要只依赖 release，因为异常退出时无法保证执行。

删除、清空或替换缓存文件会丢失既有记忆；更换路径会进入另一份独立记忆。

模型、算法版本或业务身份域变化时，建议使用新的缓存文件。

Android 建议使用 App 私有、稳定且可写的路径，例如 new File(context.getFilesDir(), "freid_buffer.dat")。内部 Demo 会在初始化和销毁时删除该文件以便重复演示，这不是 SDK 要求；正式业务需要跨启动保留身份时不要复制该删除逻辑，仅在用户主动重置身份库时清理文件。

错误处理

Java 错误码说明：FreidDetect 的部分初始化状态检查由 Java 包装层完成，其他错误由 JNI/native 返回。当前 EffectsSDKResultCode 中个别旧常量与 native 公共错误码同名但数值不同，因此请按实际返回的整数值和下表排查，不要只按 Java 常量名称推断 native 错误。

错误码	符号/来源	排查方向
0	BEF_RESULT_SUC	调用成功
-1	BEF_RESULT_FAIL	通用失败；离线 TrackID 序列化或文件读写失败时也会返回，检查缓存路径权限与存储空间
-2	BEF_RESULT_FILE_NOT_FIND	显式恢复时缓存文件不存在；首次运行可按无历史缓存处理
-4	Java 包装层 BEF_RESULT_INVALID_HANDLE	FreidDetect.setParam()、restoreOfflineTrackId() 或 flushOfflineTrackId() 在初始化前被调用
-5	native BEF_RESULT_INVALID_EFFECT_HANDLE	JNI/native 句柄为空或已失效，检查初始化和释放时序
-37	BEF_RESULT_INVALID_IMAGE_DATA	检查图像指针；Java 重点检查是否为 DirectByteBuffer
-38	native BEF_RESULT_INVALID_IMAGE_FORMAT	检查是否使用 RGBA8888、BGRA8888、BGR888 或 RGB888
-47	BEF_RESULT_INVALID_PARAM_VALUE	检查空路径、空对象、参数类型、方向、保存模式，以及 BefFreidFaceInfo 是否与当前帧匹配
-109	BEF_RESULT_SMASH_E_INVALID_MODEL	检查模型路径、文件完整性及 SDK/模型版本匹配
-114	BEF_RESULT_INVALID_LICENSE	检查授权文件、有效期、包名或应用标识
-129	BEF_RESULT_LICENSE_BAG_INVALID_SUB_FUNC	授权文件未包含 FReID（人脸重识别）能力，请联系技术支持确认授权范围

常见问题

为什么不能把普通人脸结果传给 FReID？

普通 Java 人脸结果不包含 FReID 所需的完整逐脸跟踪字段。请调用 detectFaceForFreid()，并将返回的 BefFreidFaceInfo 原样传入 FreidDetect.detect()。

为什么同一个人重新入镜后 face_id 会变化？

face_id 是人脸检测器的连续跟踪 ID，跟踪丢失后重新检测可能变化。业务身份关联应使用 FReID 输出的 track_id。

为什么重启后没有恢复历史记忆？

检查两次启动使用的缓存路径是否一致、应用是否具有读写权限，以及业务是否删除或覆盖了缓存文件。手动模式还必须在退出前成功调用 flush。

智能美化特效