# 人脸验证与检索 Android SDK 文档

# 1、简介

人脸识别（Face Recognition），是一项提取人脸特征信息进行智能分析的生物识别技术，识别率高达99.4%，比肉眼更准确。 MSC SDK 中人脸识别（IdentityVerifier）功能，主要分为下面几种类型：

（1）人脸验证（Face Verification）——1:1 相似度对比通过提取两张人脸的特征，进行相似度对比，最终返回相应的置信度得分，系统根据特征匹配程度决定“拒绝”或者“接受”。用于判断两个输入人脸是否属于同一人。

（2）人脸检索（Face Detection）——1:N相似度对比在大规模人脸数据库中快速找出与待检索人脸相似度最高的一个或多个人脸。

人脸识别详细的接口介绍及说明请参考： MSC Android API 文档 (opens new window)，在集成过程中如有疑问，可登录讯飞开放平台论坛 (opens new window)，查找答案或与其他开发者交流。

# 2. 参数相关说明

在人脸识别过程的主要参数有：

人脸识别会话类型（MFV_SST）：会话类型，包括注册（enroll），验证（verify），删除（delete）
用户ID（AUTH_ID）：标识每个使用人脸功能的终端用户的唯一ID
业务场景（MFV_SCENES）：业务类型，人脸业务为ifr

其中人脸检测和聚焦是对任意人脸图片检测，与用户是否已注册无关，故不需要设置用户 ID。识别结果通过 RequestListener 回调返回，其中包含了是否成功等信息，详细的 JSON 格式请参照人脸识别结果。

名称	说明
enroll/注册	上传包含一张人脸的图片到云端，引擎对其进行特征抽取，生成一个与之对应的模型，返回模型id(fid)。
verify/验证	注册成功后，上传包含一张人脸的图片到云端，引擎将其与所注册的人脸模型进行比对，验证是否为同一个人，返回验证结果。
delete/删除	删除注册的人脸模型
auth_id/用户id	由应用传入，用于标识用户身份，长度为6-18个字符（由英文字母、数字、下划线组成，不能以数字开头），注：注册和验证都必须指定auth_id.

项目	要求
色彩、格式	彩色，PNG、JPG、BMP格式的图片。
人脸大小、角度	大小应超过100*100像素，可以容忍一定程度的侧脸，为保证识别准确率，最好使用正脸图片。
光照	均匀光照，可容忍部分阴影。
遮挡物	脸部尽量无遮挡，眼镜等物品会一定程度上影响准确率。

# 3、SDK集成指南

# 1、导入SDK

将在官网下载的Android SDK 压缩包中libs目录下所有子文件拷贝至Android工程的libs目录下。如下图所示：

注：

arm版本已经逐步淘汰了，arm架构的推荐使用armeabi-v7a。
如果您需要将应用push到设备使用，请将设备cpu对应指令集的libmsc.so push到/system/lib中。

# 2、添加用户权限

在工程 AndroidManifest.xml 文件中添加如下权限

<!--连接网络权限，用于执行云端语音能力 -->
<uses-permission android:name="android.permission.INTERNET"/>
<!--获取手机录音机使用权限，听写、识别、语义理解需要用到此权限 -->
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<!--读取网络信息状态 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<!--获取当前wifi状态 -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<!--允许程序改变网络连接状态 -->
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"/>
<!--读取手机信息权限 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<!--读取联系人权限，上传联系人需要用到此权限 -->
<uses-permission android:name="android.permission.READ_CONTACTS"/>
<!--外存储写权限，构建语法需要用到此权限 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<!--外存储读权限，构建语法需要用到此权限 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<!--配置权限，用来记录应用配置信息 -->
<uses-permission android:name="android.permission.WRITE_SETTINGS"/>
<!--手机定位信息，用来为语义等功能提供定位，提供更精准的服务-->
<!--定位信息是敏感信息，可通过Setting.setLocationEnable(false)关闭定位请求 -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<!--如需使用人脸识别，还要添加：摄相头权限，拍照需要用到 -->
<uses-permission android:name="android.permission.CAMERA" />

注意：如需在打包或者生成APK的时候进行混淆，请在proguard.cfg中添加如下代码：

-keep class com.iflytek.**{*;}
-keepattributes Signature

# 3、接入

为保证用户个人隐私，防止APP不当收集用户信息，我们强烈建议您遵守以下流程接入本SDK保证合规，防止因调用时机不当引发的后果，例如但不限于：APP被应用市场下架等。（1）您需要确保贵APP有《隐私政策》，并且在用户首次启动App时就弹出《隐私政策》争得用户同意。（2）您务必在App的《第三方共享清单及SDK目录》中告知用户MSC SDK收集的个人信息类型以及MSC SDK隐私政策。（3）个人信息收集说明：MSC SDK需要收集唯一设备识别码（android ID）以提供能力授权服务。（4）隐私政策 (opens new window)请点击查看。（5）您务必严格遵守如下调用步骤，确保用户同意《隐私政策》之后，且在用户主动使用本SDK提供的各项功能时再进行相关函数调用。

确保App启动后，在用户阅读并同意《隐私政策》并取得用户授权之后，在用户使用SDK功能时，方可调函数SpeechUtility.createUtility(SpeechApp.this,xxxx)以使用MSC SDK。反之，如果用户不同意《隐私政策》授权，则不允许调用SpeechUtility.createUtility(SpeechApp.this,xxxx)初函数。
参考示例：SDK demo源码中获取到《隐私政策》的用户授权，后续的SDK demo函数SpeechUtility.createUtility(SpeechApp.this, xxxx)建议在用户使用SDK功能时进行使用。

接入即创建语音配置对象，只有接入后才可以使用MSC的各项服务。接入代码如下：

// 将“12345678”替换成您申请的APPID，申请地址：http://www.xfyun.cn
// 请勿在“=”与appid之间添加任何空字符或者转义符
SpeechUtility.createUtility(context, SpeechConstant.APPID +"=12345678");

# 4.人脸注册

根据mEnrollListener的onResult回调方法中得到注册结果

// 设置会话场景
mIdVerifier.setParameter(SpeechConstant.MFV_SCENES, "ifr");
// 设置会话类型
mIdVerifier.setParameter(SpeechConstant.MFV_SST, "enroll");
// 设置用户id
mIdVerifier.setParameter(SpeechConstant.AUTH_ID, authid);
// 注册监听器（IdentityListener）mEnrollListener，开始会话。
// 并通过mEnrollListener中onResult回调中获得json格式结果
mIdVerifier.startWorking(mEnrollListener);
// 子业务执行参数，若无可以传空字符传
StringBuffer params = new StringBuffer();
// 写入数据，mImageData为图片的二进制数据
mIdVerifier.writeData("ifr", params.toString(), mImageData, 0, mImageData.length);
// 停止写入
mIdVerifier.stopWrite("ifr");

# 5.人脸验证

通过mVerifyListener中onResult回调中获得json格式结果

// 设置会话场景
mIdVerifier.setParameter(SpeechConstant.MFV_SCENES, "ifr");
// 设置会话类型
mIdVerifier.setParameter(SpeechConstant.MFV_SST, "verify");
// 设置验证模式，单一验证模式：sin
mIdVerifier.setParameter(SpeechConstant.MFV_VCM, "sin");
// 用户id
mIdVerifier.setParameter(SpeechConstant.AUTH_ID, authid);
// 注册监听器（IdentityListener）mVerifyListener，开始会话。
mIdVerifier.startWorking(mVerifyListener);
// 子业务执行参数，若无可以传空字符传
StringBuffer params = new StringBuffer();
// 写入数据，mImageData为图片的二进制数据
mIdVerifier.writeData("ifr", params.toString(), mImageData, 0, mImageData.length);
// 停止写入
mIdVerifier.stopWrite("ifr");

# 6.模型操作（删除）

人脸注册成功后，在语音云端上会生成一个对应的模型来存储人脸信息，人脸模型的操作即对模型进行删除，暂时尚未支持查询"query"操作

// 设置会话场景
mIdVerifier.setParameter(SpeechConstant.MFV_SCENES, "ifr");
// 用户id
mIdVerifier.setParameter(SpeechConstant.AUTH_ID, authid);
// 设置模型参数，若无可以传空字符传
StringBuffer params = new StringBuffer();
// 执行模型操作，cmd取值"delete" 删除
mIdVerifier.execute("ifr", cmd, params.toString(), mModelListener);

# 7.1:N检索

鉴别与验证的过程相似，不过鉴别需要设置组 ID，以指定要鉴别的组。其参数设置如下：

// 设置业务场景
mIdVerifier.setParameter( SpeechConstant.MFV_SCENES, "ifr" ); 
// 设置业务类型：鉴别（identify）
mIdVerifier.setParameter( SpeechConstant.MFV_SST, "identify" );
// 设置监听器，开始会话
mIdVerifier.startWorking( listener );
// 指定组id，最相似结果数
String params = "group_id="+groudID
while( !isDataFinished ){
	  // 写入数据
   	 mIdVerifier.writeData( scence, params, data, offset, length );
	}
	mIdVerifier.stopWrite( scence );
}

# 8.人脸识别结果

JSON字段	类型	说明
sst	String	业务类型，取值为“enroll”或“verify”
ret	int	返回值，0为成功，-1为失败
ssub	String	业务类型为ifr
face_score	double	人脸验证的得分（验证时返回）
sid	String	本次交互会话的id
model_id/fid	String	注册或验证是返回的模型id
user	String	返回匹配用户id（1:N验证时返回）
decision	String	描述信息，accepted：验证成功，rejected：验证失败

注册结果示例：

{
    "ret":0,
    "suc":1,
    "rgn":1,
    "sst":"enroll",
    "ssub":"ifr",
    "fid":"2e7d53cb78deadc67518dd53ac2e2a3a"
}

验证结果示例：

{
    "ret":0,
    "face_score":99.999,
    "voice_score":0,
    "ssub":"ifr",
    "decision":"accepted",
    "fusion_score":99.999,
    "sst":"verify"
}

1:N结果示例：

{
  "ret": 0,
  "group_id": "11749608747",
  "group_name": "nameone",
  "ifv_result": {
    "need_update": 0,
    "candidates": [
      {
        "model_id": "3f6686eabe7f2a617059896ca666650e",
        "decision": "accepted",
        "score": 99.999809,
        "user": "1"
      },
      {
        "model_id": "d144c89191857e0066d8a1a96befe04d",
        "decision": "rejected",
        "score": 11.833752,
        "user": "2"
      },
      {
        "model_id": "731f6e197820b90b4ee44f40e989f409",
        "decision": "rejected",
        "score": 4.859908,
        "user": "easy"
      }
    ]
  },
  "sst": "identify",
  "ssub": "ifr",
  "topc": 3
}

# 4、视频教程

起源发展 (opens new window)

概念解析 (opens new window)

技术原理 (opens new window)

典型应用 (opens new window)

SDK集成指南iOS (opens new window)

# 5、常见问题

# 人脸验证与检索的主要功能是什么？

答：将人脸特征信息进行比对，判断是否属于同一个人。

# 人脸验证与检索的识别率是多少？

答：目前识别率高达99.4%，比肉眼更准确。

# 人脸验证与检索支持活体检测吗？

答：人脸验证与检索是支持静态照片，不支持活体检测功能。

# 人脸验证与检索最大支持创建多少个组，每个组最多支持多少人？

答：未付费最多可以创建10组，每组最多100人，商务合作：100组，每组10000人，超过组上限会报10144错误。

在这篇文章中：