SpringBoot 集成腾讯 AI 人脸识别

1、业务需求

接口文档门禁人脸识别：

POST /sys/inOut/add

入参：communityId 小区 id，extName 后缀，fileBase64 base64 人脸图片。

返回：status success（识别成功）/fail（人员不存在），data 返回人员名称。

前端摄像头拍照得到 base64 字符串传给后端，后端调用腾讯 AI 搜索人脸，如果匹配到居民，写入出入记录表。

//请求参数示例

{

"communityId": 2,

"extName": "png",

"fileBase64": "iVBORw0KGgoAAAANSUhEUgAAAoAAAAHgCAYAAAA10dzkAAAAAXNSR0IArs4c6QAAIABJREFUeF7sXe2OHblu3BljTX1lQUgyxEvv9HMQ5yIZq239/8B8gtdpbgl/6cAAAAASUVORK5CYII="

}

2、腾讯云准备

腾讯云控制台开通【人脸识别】IAI 服务；

获取 SecretId，SecretKey；

创建人员库 Group，按小区 id 分组，每个小区对应一个 GroupId。

3、pom.xml 依赖

复制代码

<!--腾讯云sdk 人脸识别IAI-->
<dependency>
    <groupId>com.tencentcloudapi</groupId>
    <artifactId>tencentcloud-sdk-java</artifactId>
    <version>3.1.842</version>
</dependency>
application.yml 配置
yaml
tencent:
  ai:
    secret-id: AKxxxx
    secret-key: xxxxx
    region: ap-beijing

4、腾讯 AI 工具类

复制代码

@Component
public class TencentAiFaceUtil {
    @Value("${tencent.ai.secret-id}")
    private String secretId;
    @Value("${tencent.ai.secret-key}")
    private String secretKey;
    @Value("${tencent.ai.region}")
    private String region;

    //获取client
    public IaiClient getIaiClient(){
        Credential cred = new Credential(secretId,secretKey);
        HttpProfile httpProfile = new HttpProfile();
        httpProfile.setEndpoint("iai.tencentcloudapi.com");
        ClientProfile clientProfile = new ClientProfile();
        clientProfile.setHttpProfile(httpProfile);
        return new IaiClient(cred,region,clientProfile);
    }

    /**
     * 人脸搜索：在指定分组搜索人脸
     * @param groupId 分组id(小区id)
     * @param imageBase64 base64图片
     * @return personId 居民id，匹配不到返回null
     */
    public String searchFace(String groupId,String imageBase64){
        IaiClient client = getIaiClient();
        SearchPersonsRequest req = new SearchPersonsRequest();
        req.setImage(imageBase64);
        req.setGroupIds(new String[]{groupId});
        try {
            SearchPersonsResponse resp = client.SearchPersons(req);
            //匹配相似度阈值，大于80判定同一个人
            if(resp.getResults().length>0 && resp.getResults()[0].getCandidates().length>0){
                Candidate candidate = resp.getResults()[0].getCandidates()[0];
                if(candidate.getScore()>80){
                    return candidate.getPersonId();
                }
            }
            return null;
        } catch (TencentCloudSDKException e) {
            log.error("腾讯人脸搜索接口异常",e);
            return null;
        }
    }
}

5、人脸识别业务接口

复制代码

@PostMapping("/inOut/add")
public Result faceCheck(@RequestBody InOutDTO dto){
    //groupId 使用小区id作为分组编号
    String groupId = String.valueOf(dto.getCommunityId());
    //调用腾讯AI搜索人脸
    String personId = tencentAiFaceUtil.searchFace(groupId, dto.getFileBase64());
    if(personId == null){
        //人员信息不存在
        return Result.fail("人员信息不存在","fail");
    }
    //根据personId查询居民信息
    Person person = personService.getById(personId);
    //新增出入记录
    InOutRecord record = new InOutRecord();
    record.setPersonId(person.getPersonId());
    record.setCommunityId(dto.getCommunityId());
    record.setInTime(new Date());
    record.setInPic(saveBase64Image(dto.getFileBase64(),dto.getExtName()));
    inOutService.save(record);
    return Result.success(person.getUserName()+"进入小区","success");
}

配套居民人脸采集接口 /sys/person/addPerson，传入 personId，base64，调用腾讯 API 创建 Person 加入对应小区 Group 人脸库。

6、踩坑总结

base64 不要带前缀data:image/png;base64,，腾讯 SDK 只接收纯 base64 字符串；前端要切割前缀；

图片大小限制，腾讯接口单张图片不能超过 2M；

设置合理相似度阈值，80 分，太低容易误识别；

增加超时处理，接口调用失败做降级，打印日志；

人脸库按小区 Group 分组，避免跨小区匹配到别的小区居民；

base64 图片后端解码保存到本地磁盘，出入记录存储图片访问 url。