人脸识别已经不再是大厂专属的技术，普通业务系统接入人脸识别的门槛越来越低。百度 AI 开放平台提供了成熟的人脸识别能力，包括人脸检测、人脸对比、人脸搜索、活体检测等，每天有一定的免费调用量，非常适合中小型项目快速落地。本文将以 Spring Boot 为基础框架，完整演示如何封装百度 AI 的人脸识别接口，实现人脸注册和人脸比对两个最常用的功能。
一、准备工作：创建应用并获取密钥
接入百度 AI 的第一步是拥有一个百度智能云账号。登录百度智能云控制台后，在产品服务中找到「人脸识别」模块，进入后点击「创建应用」。创建应用时需要填写应用名称和描述，接口选择默认勾选的人脸识别即可。
应用创建成功后，会得到三个关键参数：AppID、API Key 和 Secret Key。这三个参数是调用接口的身份凭证，其中 API Key 和 Secret Key 用于获取 Access Token，务必妥善保管，不要硬编码提交到公开仓库中，建议放在配置文件或环境变量里。
百度的所有 AI 接口调用前都需要先获取 Access Token，该 Token 有效期一般为 30 天，可以缓存起来重复使用，避免每次请求都重新获取，否则容易触发频率限制。获取 Token 的接口是一个标准的 HTTP GET 请求，带上 grant_type、client_id 和 client_secret 参数即可。
二、项目搭建与依赖引入
创建一个普通的 Spring Boot 项目，推荐使用 2.7.x 或 3.x 版本。如果追求简洁，可以直接引入百度官方的 Java SDK，它封装了 HTTP 请求、参数签名、错误码解析等细节，用起来省心不少。除了 SDK，还需要 lombok 简化实体类编写，用 hutool 处理图片的 Base64 转换。
<dependencies>
<!-- 百度 AI Java SDK -->
<dependency>
<groupId>com.baidu.aip</groupId>
<artifactId>java-sdk</artifactId>
<version>4.16.18</version>
</dependency>
<!-- hutool 工具包 -->
<dependency>
<groupId>cn.hutool</groupId>
<artifactId>hutool-all</artifactId>
<version>5.8.25</version>
</dependency>
<!-- lombok -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
</dependencies>接着在 application.yml 中配置百度相关的参数，将密钥与代码解耦：
baidu:
ai:
app-id: 你的AppID
api-key: 你的APIKey
secret-key: 你的SecretKey
face-group: user_group这里的 face-group 是人脸库的分组名称。百度的人脸搜索是按照用户组来管理的，同一个组下可以注册多个用户，每个用户可以挂多张人脸照片，比对时会在指定组内进行检索。
三、封装人脸识别核心服务
先写一个配置类，把 SDK 的客户端 AipFace 交给 Spring 容器管理。AipFace 是线程安全的，全局一个实例即可，它的构造函数接收 AppID、API Key 和 Secret Key 三个参数：
@Configuration
public class BaiduAiConfig {
@Value("${baidu.ai.app-id}")
private String appId;
@Value("${baidu.ai.api-key}")
private String apiKey;
@Value("${baidu.ai.secret-key}")
private String secretKey;
@Bean
public AipFace aipFace() {
AipFace client = new AipFace(appId, apiKey, secretKey);
// 可选：设置超时时间
client.setConnectionTimeoutInMillis(5000);
client.setSocketTimeoutInMillis(30000);
return client;
}
}然后编写核心服务类。人脸注册时，百度支持三种图片格式：本地文件路径、URL 地址和 Base64 字符串。实际项目中前端通常把拍照结果转成 Base64 上传，所以以 Base64 为主。注意传给 SDK 的 Base64 字符串不要带 data:image/jpeg;base64, 这样的前缀，需要先截掉，否则接口会报图片格式错误。
@Service
@RequiredArgsConstructor
public class FaceService {
private final AipFace aipFace;
@Value("${baidu.ai.face-group}")
private String faceGroup;
/**
* 人脸注册：把用户照片存入人脸库
*/
public JSONObject faceRegister(String userId, String base64Img) {
// 去掉 Base64 前缀
String img = base64Img.contains(",")
? base64Img.substring(base64Img.indexOf(",") + 1)
: base64Img;
HashMap<String, String> options = new HashMap<>();
options.put("user_info", "用户人脸信息");
options.put("quality_control", "NORMAL"); // 图片质量控制
options.put("liveness_control", "LOW"); // 活体检测等级
// 图片类型为 Base64
return aipFace.addUser(img, "BASE64", faceGroup, userId, options);
}
/**
* 人脸比对：在人脸库中搜索匹配的用户
*/
public JSONObject faceSearch(String base64Img) {
String img = base64Img.contains(",")
? base64Img.substring(base64Img.indexOf(",") + 1)
: base64Img;
HashMap<String, String> options = new HashMap<>();
options.put("quality_control", "NORMAL");
options.put("liveness_control", "LOW");
options.put("max_user_num", "1"); // 只返回相似度最高的一个用户
return aipFace.search(img, "BASE64", faceGroup, options);
}
}上面的代码中，quality_control 控制上传图片的质量要求，值越严格对照片清晰度要求越高；liveness_control 控制活体检测等级，如果是安全性要求高的场景比如支付，建议设置为 HIGH。返回的 JSONObject 中包含 error_code 字段，为 0 表示调用成功，非 0 时可以根据官方错误码文档定位问题。
四、Controller 层与调用流程
服务层封装好后，对外暴露两个接口即可。前端注册人脸时上传 Base64 图片和用户 ID，登录时只上传 Base64 图片，由后端去人脸库中检索。写一个简单的 Controller 示例：
@RestController
@RequestMapping("/face")
@RequiredArgsConstructor
public class FaceController {
private final FaceService faceService;
/**
* 人脸注册接口
*/
@PostMapping("/register")
public String register(@RequestParam String userId,
@RequestParam String image) {
JSONObject result = faceService.faceRegister(userId, image);
if (result.getInt("error_code") == 0) {
return "注册成功";
}
return "注册失败：" + result.getString("error_msg");
}
/**
* 人脸搜索比对接口
*/
@PostMapping("/search")
public String search(@RequestParam String image) {
JSONObject result = faceService.faceSearch(image);
if (result.getInt("error_code") == 0) {
JSONObject user = result.getJSONObject("result")
.getJSONArray("user_list")
.getJSONObject(0);
double score = user.getDouble("score");
if (score > 80) {
return "识别通过，用户ID：" + user.getString("user_id")
+ "，相似度：" + score;
}
return "相似度不足，识别失败";
}
return "识别失败：" + result.getString("error_msg");
}
}关于相似度阈值，score 是 0 到 100 的浮点数，一般业务场景设置 80 作为及格线比较合适，对安全性要求高可以提到 90 以上。低于 80 的匹配结果建议直接判定为陌生人，不要返回任何用户信息，防止误识别带来安全问题。
五、常见问题与注意事项
第一个高频问题是错误码 18，代表 QPS 超限。免费额度下人脸识别接口的并发有限，如果系统调用量大，需要在获取 Token 后做缓存，并且对接口调用做限流处理，比如用 Guava 的 RateLimiter 控制每秒请求数。
第二个问题是错误码 222202，表示图片中没有人脸。这种情况多半是前端传的照片质量差、人脸太小或者角度过大导致的。可以在前端调用摄像头时引导用户正对镜头，同时开启 SDK 的图片质量控制，把模糊、遮挡的照片在注册阶段就拦截下来。
第三个需要注意的点是人脸数据的合规性。人脸信息属于敏感个人信息，按照相关法规要求，采集前必须获得用户明确授权，并做好告知义务。注册到百度人脸库的数据要可控可删，用户注销账号时应调用 faceService 中的 deleteUser 方法同步删除云端人脸数据，避免法律风险。
最后，Base64 传输会让请求体变得很大，一张几 MB 的照片编码后体积膨胀约三分之一，容易超出网关或 Tomcat 的默认请求限制。可以在配置文件中调整 spring.servlet.multipart.max-file-size 和 server.tomcat.max-http-form-post-size，或者让前端先压缩图片再上传，减轻服务端压力。
整体来看，借助百度 AI 开放平台的 SDK，Spring Boot 整合人脸识别的核心工作量其实不大，重点在于细节处理：Token 缓存、Base64 前缀、阈值设定和数据合规。把这些环节处理好，一套稳定可用的人脸识别服务就能快速上线了。
Spring Boot人脸识别百度AI开放平台修改时间：2026-09-10 19:00:43