Yii框架不提供人脸识别能力，需集成百度AI等外部API；应封装FaceAuthService类调用detect/match/verifyLiveness，用缓存管理access_token，通过自定义验证器串联登录流程，并在配置中统一管理相似度阈值等策略。
Yii 框架本身**不提供人脸识别能力**，它没有内置人脸检测、特征提取或活体判断模块。想在 Yii 项目里做“刷脸登录”或“实名核验”，你得靠外部服务或 SDK，Yii 只负责调度、鉴权、会话管理和前后端胶水逻辑。 下面直接说清楚怎么做、为什么这么选、以及最容易翻车的几个点。
Yii 中调用百度 AI 人脸识别 API 的实际写法
这是目前最稳、文档最全、免费额度够用的方案（日调用 500 次），适合中低并发业务场景。
- 不要在
User::validatePassword()里塞图像处理逻辑——它本该只比密码哈希，加 CV 会拖慢登录主链路，且违反单一职责 - 单独建一个
FaceAuthService类，封装detect、match、verifyLiveness三个核心方法，每个方法对应百度 Face API 的一个 endpoint - 调用前必须先获取
access_token，但别每次请求都去拿——用 Yii 的yii\caching\Cache缓存它（过期时间设为 25 分钟，留 5 分钟缓冲） - 上传图片时，前端必须传 base64 或二进制流；后端用
yii\web\UploadedFile::getInstanceByName()接收后，转成file_get_contents()或fopen(..., 'rb')再 POST 给百度
如何把识别结果和 Yii 用户登录流程串起来
典型流程是：用户拍照 → 后端调百度 API 做活体+人脸比对 → 比对成功后才执行 Yii::$app->user->login($user)。
- 不能跳过
IdentityInterface的约束：即使你用的是身份证照片比对，最终仍要返回一个有效的User实例（比如根据身份证号查出已有账号，或自动注册新账号） -
LoginForm模型里要新增字段face_image_base64和id_card_number，并在rules()中加自定义验证器，例如['face_image_base64', 'validateFaceMatch'] - 验证器内部调
FaceAuthService::match($base64, $idCardNumber)，失败就$this->addError('face_image_base64', '人脸不匹配或非活体') - 注意：比对失败时，
login()不能被执行；但 session、cookie、CSRF token 等仍需保持一致，否则前端刷新会丢状态
为什么不用 OpenCV 或 face_recognition 库直连 Yii
技术上可行，但生产环境基本不可取。
- PHP 的
exec('python -m face_recognition...')调用方式极不稳定：超时难控、内存泄漏常见、GPU 加速几乎无效 - 模型加载耗时长（ResNet-50 特征提取约 800ms/帧），Yii 的同步阻塞模型会让整个 Web 进程卡住，QPS 直接归零
- 安全审计通不过：临时写入图像文件到
runtime/，再被 Python 读取，路径穿越和权限问题频发 - 部署成本飙升：你需要在每台 PHP-FPM 机器上装 Python、CUDA、dlib、torch —— 这和用 Yii 的初衷（快速交付、轻量运维）背道而驰
真正关键的不是“怎么调 API”，而是**识别失败时的降级路径设计**。比如活体检测不通过，是否允许切回短信验证码？比对置信度 0.78 是否算通过？这些阈值和策略必须写死在配置里（如 params['face']['min_similarity'] = 0.82），而不是散落在 service 方法的 if 判断中。否则上线后调一次参数就得改三处代码。
