Azure Document Intelligence v2.0 已退役：OCR API 迁移到 v4.0 要改哪些地方

Azure Document Intelligence v2.0 已退役：OCR API 迁移到 v4.0 要改哪些地方

Azure AI Document Intelligence v2.0 API 已在 8 月 31 日结束支持。Microsoft 说明退役按 API 版本判断，不限于预生产环境；商业 Azure 中仍调用 /formrecognizer/v2.0 的生产负载同样需要迁移。资源暂时返回结果，也不代表继续受支持。

当前 [Microsoft 迁移文档](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/versioning/v3-1-migration-guide?view=doc-intel-4.0.0)列出：v2.1 支持到 2027 年 9 月 15 日，v3.0 支持到 2029 年 3 月 30 日；最新 GA 是 2024-11-30 v4.0。排查要从真实请求、SDK 锁文件和网关日志确认版本，不能只看项目文档写着“Form Recognizer”。

v2.0 到 v4.0 是一次接口重构

v2.0 的请求路径把版本放在 /formrecognizer/v2.0 下，新版使用 documentModels/{modelId} 分析端点，并通过 api-version 指定版本。轮询仍依赖 Operation-Location，但路径、方法和结果结构都会影响现有封装。

响应 JSON 有破坏性变化。迁移文档举出的典型例子是 boundingBox 改为 polygon；表格、段落、选择标记、页面单位和置信度的层级也要按新版类型重新核对。旧代码若大量使用动态 JSON，接口可能返回 200，业务字段却悄悄变成空值，比直接报错更难发现。

自定义模型需要单独盘点。记录每个 modelId 的训练 API 版本、数据集、标签项目和调用方，确认新版是否可复制、升级或需要重训。不要在生产切换当天才发现训练素材只留在标注工具里。模型名称相同也不能证明输出坐标、字段名称和置信度分布完全一致。

用双写流量检查字段，而非只看成功率

迁移验证应从真实文档抽样，覆盖扫描件、手机照片、倾斜页面、中文小字、跨页表格、印章和低质量 PDF。同一份文件同时调用旧链路存档结果与 v4.0，比较字段级准确率、表格行列、polygon 坐标、页码、延迟和费用。旧版已退役时，可以用迁移前保存的回放集作为基线。

业务验收要高于 OCR 字符正确率。发票流程还要核对税额、币种、供应商和合计关系；合同要检查条款所在页与段落顺序；身份证件要处理遮挡和字段缺失。金额、身份和合规字段可交给确定性规则或另一视觉模型复核，模型间一致也不能替代原文证据。

上线采用小比例流量，保存原始响应和解析后的标准对象。若出现字段缺失、延迟激增或自定义模型不可用，应能按文档类型暂停，而不是把所有请求退回已退役端点。[PaddleOCR 文档识别实践](/articles/open-source-paddleocr-multilingual-document-ocr)可作为离线对照，但需要使用相同页面和字段口径。

模型网关隔离调用，解析代码仍要升级

统一 API 网关可以集中管理密钥、超时、配额和区域路由，却无法自动把旧版结果 JSON 翻译成新版业务对象。若网关同时承担字段转换，应给转换规则加版本号、契约测试和回放样本；否则一次端点升级会把风险隐藏在公共适配层。

Document Intelligence 适合结构化文档抽取，通用视觉大模型更适合解释复杂版面、图片内容或非固定字段。两者可以互补，不能未经评测互相替代。遇到长文档异步分析，还要保留任务 ID、轮询间隔和幂等处理，可参考 [可恢复异步 AI 任务设计](/articles/async-ai-tasks-that-survive-page-refresh)。

AnyAIS 可用于统一比较多模态模型对同一批文档的理解和复核能力，Azure OCR 仍由独立迁移链路负责。把结构化抽取、视觉复核和业务校验分层，API 退役时才不会牵动整套应用。