Azure Form Recognizer QA到PROD复制模型后GetCustomModels返回空问题

问题复现背景 #

• 开发环境累计构建完成1000余个通过输出测试的自定义模型
• 迁移路径：通过Form Recognizer客户端SDK调用StartModelCopyTo方法，将模型从QA环境复制到PROD生产环境
• 迁移流程控制逻辑：轮询单个模型复制任务状态，当接口返回PercentageCompleted为100%时，立即启动下一个模型的复制流程
• 当前迁移进度：1000余个模型全部完成到生产环境的复制操作

异常表现 #

生产环境调用GetCustomModels方法拉取全量自定义模型列表时返回结果为空，但传入具体modelId调用单模型详情查询接口时，可正常返回对应模型的完整配置与元数据信息。
该问题目前已被业务团队判定为阻塞性问题，项目暂未完成签字验收，除此之外Form Recognizer服务使用过程中还存在其他待排查异常。

同类问题说明 #

该问题属于批量迁移场景下的常见问题，已有大量开发者反馈过相同表现，核心诱因和对应修复方案如下：

• 存储层索引同步延迟
  现有迁移逻辑在单模型复制完成后立刻启动下一个任务，1000+模型连续高并发写入时，Form Recognizer服务端用于支撑全量列表查询的二级索引不会实时和主存储同步。单模型查询直接走主存储读取所以返回正常，全量列表查询走未同步完成的索引就会返回空结果。
  处理方式：
  1. 批量迁移全部结束后预留2-24小时的索引同步窗口，等待服务端后台任务完成索引构建后再调用列表接口，绝大多数场景下等待后列表可自动恢复正常
  2. 如果业务侧需要立刻上线使用，可以在迁移过程中自行记录所有迁移成功的modelId并落库存储，业务查询模型列表时优先读取本地存储的modelId清单，再按需调用单模型查询接口补全详情，绕开列表接口的同步延迟问题
• 分页逻辑缺失
  GetCustomModels接口默认单页返回模型数量上限为100个，若调用时未传入分页参数、也未实现全分页迭代逻辑，当账号下模型总数超过100个时，很容易出现返回结果不全甚至为空的问题——批量迁移刚结束时服务端分页计数缓存未刷新，该问题触发概率会显著升高。
  处理方式：
  检查SDK调用代码，确保开启了全量分页迭代，不要只读取第一页返回结果。以C# SDK为例，正确的全量拉取代码如下：

  List<CustomFormModelInfo> allModels = new List<CustomFormModelInfo>();
  await foreach (CustomFormModelInfo modelInfo in client.GetCustomModelsAsync())
  {
      allModels.Add(modelInfo);
  }
  

• 调用权限不匹配
  若生产环境调用GetCustomModels使用的密钥是迁移过程中生成的单模型粒度临时授权密钥，或者对应的自定义角色缺少全模型列表读取权限（Microsoft.CognitiveServices/accounts/FormRecognizer/models/read），也会出现列表查询为空，但持有具体modelId时因拥有单模型读权限可正常查询的情况。
  处理方式：
  到云服务控制台核对当前调用凭证的权限配置，使用资源级别的全权限密钥调用列表接口，不要使用单模型临时授权凭证做全量查询。

内容的提问来源于stack exchange，提问作者Mahendra Raja