// LATEST

一次人脸对比请求如何走完 FastAPI 与 InsightFace

把模型接成 HTTP 接口,最容易混在一起的是“请求合法”“模型成功运行”和“业务判断为同一人”。沿着 face_recognition_api 的调用链读一遍,才能看清这三件事分别在哪里发生。

从请求模型开始画边界

CompareFacesRequest 只有两个字符串字段:image1 和 image2。Pydantic 校验通过,只能说明 JSON 形状基本正确,不代表字符串是可解码图片,更不代表图片里有人脸。真正的 Base64 解码、长度与文件头检查在 validate_base64_image。

路由把两份字节交给 process_face_comparison_async,通过执行器进入同步的 face_service.compare_faces。核心服务依次执行图片解码、提取两张图的 embedding、余弦计算和阈值判断。六元组返回后,适配层补上耗时与小数精度,路由再装入 code/data/msg 信封。

JSON → 请求模型 → Base64/文件头检查
     → 线程池 → OpenCV 解码 → 人脸特征
     → 相似度/阈值 → 结果模型 → 响应信封

分层的价值在失败路径里

如果字符串格式正确但图片无法解码,核心服务会返回失败性质的业务元组,而不是 HTTP 异常。路由依然可能返回 HTTP 200、code=0、msg=人脸对比成功。接入方不能只看外层状态;至少还要检查两个人脸检测标志。

这并非要求所有“无人脸”都返回 500。设计可以把“请求执行成功但样本不可比”保留为业务结果,关键是状态名称明确,不能把基础设施失败也塞进同一结果。

如何验证自己的理解

建议用四组固定夹具覆盖边界:缺少字段、非法 Base64、可解码但无人脸的图片、两张合格人像。前两组检验协议层,第三组检验可比性,最后一组检验算法链。记录 HTTP 状态、外层 code、检测标志和消息,而不是只打印响应。

本文依据源码追踪调用链,未加载模型,也未测量准确率。最值得保留的架构笔记是:异步适配层负责调度,领域层负责判断,HTTP 层负责协议;三者的成功定义应该分别写清。


源码与阅读导航

本文属于「人脸识别服务源码笔记」第 01 篇。依据固定提交 b85ee88017bc 研读,后续版本可能不同。

全部专题与阅读顺序 · 下一篇:Base64 图片上传:10MB 限制为什么不等于 10MB 请求体

还没有评论

欢迎留下你的观点,保持交流的清晰和友好。

写下评论