C# Azure FormRecognizerClient无法读取跨页PDF表格及识别表头求助

跨页表格识别失败的根因与修复 #

• 核心限制匹配问题：使用v2.1版本SDK时，无论是自定义训练模型还是预建发票接口，都不支持自动拼接跨页拆分的逻辑表格，会将每个页面上的表格片段识别为完全独立的表格结构，跨页的行项会被判定为无效字段直接丢弃，这是跨页场景识别失败的根本原因。
• 版本升级要求：需将NuGet包Azure.AI.FormRecognizer升级至4.0.0及以上支持跨页表格能力的版本，初始化客户端时不要固定指定ServiceVersion.V2_1，使用对应高版本的服务配置。
• 接口调用配置修正：
  • 调用StartRecognizeInvoicesFromUriAsync时，传入配置了ReadingOrder = FormReadingOrder.Wireframe、IncludeFieldElements = true的RecognizeInvoicesOptions参数，关闭默认的流式阅读顺序判断，让SDK触发跨页表格的合并逻辑。
  • 自定义模型场景下，训练阶段需对跨页拆分的同一张表格使用关联标注，将两个页面的表格片段绑定为同一个逻辑表格结构，不要逐页单独标注独立表格；识别调用时同样传入对应支持跨页合并的自定义识别参数。

表格表头无法识别的修复方案 #

• 预建发票接口场景：v2.1及以上早期版本的预建模型默认仅识别固定位置的标准发票字段，不会自动捕获非预设位置的自定义表头。需在调用接口时通过QueryFields参数显式指定需要匹配的表头字段名，SDK会自动关联对应表头下的列数据。
• 自定义模型场景：训练标注阶段需将表头区域单独标记为键值对类型字段，不要将表头范围划入普通表格单元格的标注区域；选择分层表格结构的训练选项，不要使用扁平表格标注模式，否则SDK识别时会跳过表头匹配逻辑，直接逐行读取单元格值。

修正后的核心调用示例 #

// 初始化客户端（移除固定v2.1版本配置）
var credential = new AzureKeyCredential("your-key");
var endpoint = new Uri("your-form-recognizer-endpoint");
var client = new FormRecognizerClient(endpoint, credential);

// 配置带跨页处理能力的识别参数
var recognizeOptions = new RecognizeInvoicesOptions()
{
    IncludeFieldElements = true,
    ReadingOrder = FormReadingOrder.Wireframe,
    QueryFields = { "InvoiceId", "ItemDescription", "Quantity", "UnitPrice", "Amount", "TotalTax", "GrandTotal" }
};

// 执行识别调用
var recognizeTask = await client.StartRecognizeInvoicesFromUriAsync(new Uri("your-pdf-file-uri"), recognizeOptions);
var result = await recognizeTask.WaitForCompletionAsync();

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