运行Azure Face快速入门代码触发InvalidRequest API报错

问题复现 #

• 运行环境：Python 3.9，使用Azure学生免费权益账号创建Face服务，已正确配置Key与Endpoint参数，直接运行官方快速入门示例代码，保留示例默认图片链接
• 报错触发位置：执行创建PersonGroup代码行时抛出异常
• 完整报错信息：

Person group: 61ec255a-06db-45dd-ac7e-90c9dfac98b0
Traceback (most recent call last):
  File "f:\College\SEM 6\IOT\azure code\file.py", line 43, in <module>
    face_client.person_group.create(person_group_id=PERSON_GROUP_ID, name=PERSON_GROUP_ID, recognition_model='recognition_04')
  File "C:\Users\hp\AppData\Local\Programs\Python\Python39\lib\site-packages\azure\cognitiveservices\vision\face\operations\_person_group_operations.py", line 121, in create
    raise models.APIErrorException(self._deserialize, response)
azure.cognitiveservices.vision.face.models._models_py3.APIErrorException: (InvalidRequest) Invalid request has been sent.

核心触发原因 #

90%以上该场景报错由以下原因导致：

• 最常见原因：免费层与识别模型不兼容。Azure学生权益默认可创建的F0免费定价层Face资源，不支持示例代码里指定的recognition_04识别模型，仅支持recognition_01、recognition_02两个旧版识别模型，传入不支持的模型参数会直接触发无效请求错误。
• 次要原因：未开通人脸识别受限功能权限。2020年起Azure对所有人脸识别相关功能增加了准入审核，新创建的Face资源（尤其是S0标准层）未提交审核通过前，无法调用PersonGroup创建、人脸特征入库、人脸比对类接口，会直接返回请求无效。
• 低概率原因：PersonGroup ID冲突或格式不合法。如果之前运行代码已经创建过同ID的PersonGroup未清理，或者ID包含不支持的特殊字符、长度超限，也可能触发该报错（该场景通常会返回明确的资源已存在/参数格式错误提示，概率较低）。

可直接落地的解决方案 #

1. 第一步先修改识别模型参数（优先操作，90%场景改完即可解决）
   把创建PersonGroup的代码行中recognition_model参数从recognition_04改为recognition_01，修改后代码如下：

   face_client.person_group.create(person_group_id=PERSON_GROUP_ID, name=PERSON_GROUP_ID, recognition_model='recognition_01')
   

   注意：如果后续代码里包含人脸检测、添加人脸到PersonGroup的逻辑，所有涉及recognition_model、detection_model的参数要保持版本匹配，不要混用不同版本的识别模型，否则后续训练、识别步骤会报错。
2. 检查资源权限与定价层
   进入Azure门户找到已创建的Face资源：
   • 如果使用F0免费层，只能使用旧版识别模型，无法调用recognition_03、recognition_04相关接口，不需要提交功能审核即可使用基础的人脸检测、旧版模型识别功能。
   • 如果需要使用新版识别模型，需要将资源升级到S0标准层，按门户提示提交人脸识别功能使用申请，审核通过后才能正常调用相关接口。
3. 清理残留资源验证ID合法性
   建议将PERSON_GROUP_ID替换为长度不超过64位、由小写字母、数字、短横线组成的字符串，执行创建前先清理可能存在的同ID残留资源：

   # 清理同ID旧资源，资源不存在时抛出的异常可直接忽略
   try:
       face_client.person_group.delete(person_group_id=PERSON_GROUP_ID)
   except Exception:
       pass
   # 重新执行创建操作
   face_client.person_group.create(person_group_id=PERSON_GROUP_ID, name=PERSON_GROUP_ID, recognition_model='recognition_01')
   

内容的提问来源于stack exchange，提问作者Shreya Bhadwal