AAS 技能实战:使用 Azure.AI.DocumentIntelligence (.NET) 从文档中提取文本、表格与结构化数据

原创2026-09-21 19:14:441,874 阅读
文章标签:人工智能AI 技能AI 插件MCP 服务开发工具AI 应用

AAS 技能实战:使用 Azure.AI.DocumentIntelligence (.NET) 从文档中提取文本、表格与结构化数据

本篇技术指南以 AAS(Agentic Awesome Skills)仓库中的 azure-ai-document-intelligence-dotnet 技能为核心,系统讲解 Azure AI Document Intelligence 官方 .NET SDK(Azure.AI.DocumentIntelligence v1.0.0 GA)的安装、认证、预置模型选择、七大核心工作流(发票分析、版面提取、自定义模型构建、文档分类等)及生产级最佳实践。读完本文,你将能够在 .NET 应用中直接落地一套完整的文档智能提取与分类管线,并理解其底层长耗时操作(LRO)与字段置信度机制。

技能定位:AAS 仓库中的 Document Intelligence 技能

在 agentic-awesome-skills 仓库中,该技能被组织为社区来源(source: community)、风险等级 critical 的技能条目,登记于 数据目录、技能索引 与 别名索引 中。除了 .NET 版本外,仓库还提供 TypeScript 版本技能 azure-ai-document-intelligence-ts/SKILL.md,二者覆盖同一服务(DOCUMENT_INTELLIGENCE_ENDPOINT、DOCUMENT_INTELLIGENCE_API_KEY 环境变量约定一致),可供多语言团队对照使用。该技能面向的场景是:让 Agent 或 .NET 服务从 PDF、图片等文档中自动提取文本、表格、选择标记以及键值对形式的结构化字段,既能调用 Azure 托管的预置模型,也能基于自有样本构建自定义模型与文档分类器。

技能原文位于 plugins/agentic-awesome-skills-claude/skills/azure-ai-document-intelligence-dotnet/SKILL.md(根目录 skills/azure-ai-document-intelligence-dotnet/SKILL.md 与 plugins/agentic-awesome-skills/skills/azure-ai-document-intelligence-dotnet/SKILL.md 为同内容副本),下文所有代码均继承自该文档。

安装与版本

在 .NET 项目中通过 dotnet CLI 安装两个包:Azure.AI.DocumentIntelligence(文档智能主 SDK)与 Azure.Identity(提供 DefaultAzureCredential 等 Entra ID 认证组件):

dotnet add package Azure.AI.DocumentIntelligence
dotnet add package Azure.Identity

当前版本为 v1.0.0(GA)。从 SDK 命名可以看出,这是 Azure 官方在新一代 Document Intelligence 服务上推出的正式版 SDK,与之相对的 Azure.AI.FormRecognizer 为已弃用的旧版 SDK(详见下文"与旧版 SDK 的关系"一节)。

环境变量约定

技能约定以下三个环境变量作为运行时配置来源,与仓库中 TS 版本技能的环境变量命名保持一致:

DOCUMENT_INTELLIGENCE_ENDPOINT=https://<resource-name>.cognitiveservices.azure.com/
DOCUMENT_INTELLIGENCE_API_KEY=<your-api-key>
BLOB_CONTAINER_SAS_URL=https://<storage>.blob.core.windows.net/<container>?<sas-token>

其中:

  • DOCUMENT_INTELLIGENCE_ENDPOINT:Document Intelligence 资源的自定义子域端点。注意其主机名格式为 <resource-name>.cognitiveservices.azure.com,这是使用 Entra ID(微软 Entra ID,原 Azure AD)认证的硬性前提,区域级端点无法用于托管标识认证。
  • DOCUMENT_INTELLIGENCE_API_KEY:资源密钥(仅在使用 API Key 认证时需要)。
  • BLOB_CONTAINER_SAS_URL:用于自定义模型训练与分类器构建的训练数据源地址,通常指向存储账户中存放样本文档的容器,并携带 SAS 令牌。

认证方式

SDK 支持两种认证方式,技能明确推荐生产环境使用 Microsoft Entra ID。

Microsoft Entra ID(推荐)

using Azure.Identity;
using Azure.AI.DocumentIntelligence;

string endpoint = Environment.GetEnvironmentVariable("DOCUMENT_INTELLIGENCE_ENDPOINT");
var credential = new DefaultAzureCredential();
var client = new DocumentIntelligenceClient(new Uri(endpoint), credential);

DefaultAzureCredential 会依次尝试环境变量、托管标识、Azure CLI 登录等多种凭据源,在本地开发与云上部署之间无需修改代码即可无缝切换。关键约束已在代码注释中强调:Entra ID 认证要求使用自定义子域(例如 https://<resource-name>.cognitiveservices.azure.com/),而不是区域端点。

API Key

string endpoint = Environment.GetEnvironmentVariable("DOCUMENT_INTELLIGENCE_ENDPOINT");
string apiKey = Environment.GetEnvironmentVariable("DOCUMENT_INTELLIGENCE_API_KEY");
var client = new DocumentIntelligenceClient(new Uri(endpoint), new AzureKeyCredential(apiKey));

通过 AzureKeyCredential 将 API Key 传入客户端。这种方式实现简单,适合快速验证与受控环境;生产环境应优先采用 Entra ID。

客户端类型

SDK 提供两个核心客户端,职责划分清晰:

客户端 用途
DocumentIntelligenceClient 分析文档(调用预置或自定义模型)、分类文档
DocumentIntelligenceAdministrationClient 构建/管理自定义模型与分类器

两者的分工对应服务端的两类 API:分析类操作走 DocumentIntelligenceClient,而模型生命周期管理(构建、列举、删除、查询配额)走 DocumentIntelligenceAdministrationClient。

预置模型一览

预置模型(Prebuilt Models)是 Azure 托管的通用模型,开箱即用,无需训练数据:

模型 ID 说明
prebuilt-read 提取文本、语言、手写内容(OCR 能力)
prebuilt-layout 提取文本、表格、选择标记、版面结构
prebuilt-invoice 提取发票字段(供应商、明细项、合计金额)
prebuilt-receipt 提取收据字段(商户、明细项、总额)
prebuilt-idDocument 提取证件字段(姓名、出生日期、地址)
prebuilt-businessCard 提取名片字段
prebuilt-tax.us.w2 提取美国 W-2 税务表单字段
prebuilt-healthInsuranceCard.us 提取美国医疗保险卡字段

横向对比仓库中 TS 版本技能 的预置模型表,可以发现在 .NET 版文档之外服务还提供 prebuilt-contract(合同字段)与 prebuilt-bankStatement.us(银行对账单字段)等模型,可根据实际单据类型选择最贴近的预置模型,只有预置模型无法覆盖时再考虑自定义模型。

核心工作流

以下七个工作流构成该技能的实战主体,全部代码均可直接复制到 .NET 控制台或 ASP.NET Core 服务中使用。

1. 分析发票(Analyze Invoice)

调用 prebuilt-invoice 模型,从 URL 分析发票并提取供应商名称、合计金额与明细行项目:

using Azure.AI.DocumentIntelligence;

Uri invoiceUri = new Uri("https://example.com/invoice.pdf");

Operation<AnalyzeResult> operation = await client.AnalyzeDocumentAsync(
    WaitUntil.Completed,
    "prebuilt-invoice",
    invoiceUri);

AnalyzeResult result = operation.Value;

foreach (AnalyzedDocument document in result.Documents)
{
    if (document.Fields.TryGetValue("VendorName", out DocumentField vendorNameField)
        && vendorNameField.FieldType == DocumentFieldType.String)
    {
        string vendorName = vendorNameField.ValueString;
        Console.WriteLine($"Vendor Name: '{vendorName}', confidence: {vendorNameField.Confidence}");
    }

    if (document.Fields.TryGetValue("InvoiceTotal", out DocumentField invoiceTotalField)
        && invoiceTotalField.FieldType == DocumentFieldType.Currency)
    {
        CurrencyValue invoiceTotal = invoiceTotalField.ValueCurrency;
        Console.WriteLine($"Invoice Total: '{invoiceTotal.CurrencySymbol}{invoiceTotal.Amount}'");
    }

    // Extract line items
    if (document.Fields.TryGetValue("Items", out DocumentField itemsField)
        && itemsField.FieldType == DocumentFieldType.List)
    {
        foreach (DocumentField item in itemsField.ValueList)
        {
            var itemFields = item.ValueDictionary;
            if (itemFields.TryGetValue("Description", out DocumentField descField))
                Console.WriteLine($"  Item: {descField.ValueString}");
        }
    }
}

这段代码揭示了三个重要的 SDK 设计细节:

  • DocumentField 的强类型取值:同一个 DocumentField 通过 FieldType 区分类型,再通过对应的强类型属性取值——字符串取 ValueString,货币取 ValueCurrency(返回 CurrencyValue,含 CurrencySymbol 与 Amount),列表取 ValueList(元素为字典形式的 ValueDictionary)。
  • Confidence 字段:每个字段自带置信度,业务侧应结合置信度阈值决定是否采信,避免将低置信度字段直接入库。
  • WaitUntil.Completed:AnalyzeDocumentAsync 是异步长耗时操作(LRO),传入 WaitUntil.Completed 表示同步等待服务端完成并返回结果,调用简单直接;若传入 WaitUntil.Started 则可拿到 Operation 句柄后自行轮询或分离处理(见"最佳实践"第 3 条)。

2. 提取版面(文本、表格、结构)

使用 prebuilt-layout 模型,按页提取文本行,并按行列坐标提取表格单元:

Uri fileUri = new Uri("https://example.com/document.pdf");

Operation<AnalyzeResult> operation = await client.AnalyzeDocumentAsync(
    WaitUntil.Completed,
    "prebuilt-layout",
    fileUri);

AnalyzeResult result = operation.Value;

// Extract text by page
foreach (DocumentPage page in result.Pages)
{
    Console.WriteLine($"Page {page.PageNumber}: {page.Lines.Count} lines, {page.Words.Count} words");

    foreach (DocumentLine line in page.Lines)
    {
        Console.WriteLine($"  Line: '{line.Content}'");
    }
}

// Extract tables
foreach (DocumentTable table in result.Tables)
{
    Console.WriteLine($"Table: {table.RowCount} rows x {table.ColumnCount} columns");
    foreach (DocumentTableCell cell in table.Cells)
    {
        Console.WriteLine($"  Cell ({cell.RowIndex}, {cell.ColumnIndex}): {cell.Content}");
    }
}

AnalyzeResult 中 Pages 提供逐页的 DocumentPage(含 Lines、Words,以及技能文档中提到的 SelectionMarks 选择标记),Tables 提供 DocumentTable,其单元格 DocumentTableCell 携带 RowIndex/ColumnIndex 坐标与 Content 文本,可据此还原表格的二维结构。该工作流是通用文档解析(扫描件全文检索、版面归档)的基础。

3. 分析收据(Analyze Receipt)

使用 prebuilt-receipt 模型提取商户名、总额与交易日期:

Operation<AnalyzeResult> operation = await client.AnalyzeDocumentAsync(
    WaitUntil.Completed,
    "prebuilt-receipt",
    receiptUri);

AnalyzeResult result = operation.Value;

foreach (AnalyzedDocument document in result.Documents)
{
    if (document.Fields.TryGetValue("MerchantName", out DocumentField merchantField))
        Console.WriteLine($"Merchant: {merchantField.ValueString}");

    if (document.Fields.TryGetValue("Total", out DocumentField totalField))
        Console.WriteLine($"Total: {totalField.ValueCurrency.Amount}");

    if (document.Fields.TryGetValue("TransactionDate", out DocumentField dateField))
        Console.WriteLine($"Date: {dateField.ValueDate}");
}

该示例展示了 DocumentFieldType.Date 对应的取值属性 ValueDate。费用报销、对账核销类应用可在此基础上构建收据自动录入流程。

4. 构建自定义模型(Build Custom Model)

当预置模型无法覆盖业务单据(如专用采购单、内部表格)时,使用 DocumentIntelligenceAdministrationClient 基于带标注的训练样本构建自定义模型:

var adminClient = new DocumentIntelligenceAdministrationClient(
    new Uri(endpoint),
    new AzureKeyCredential(apiKey));

string modelId = "my-custom-model";
Uri blobContainerUri = new Uri("<blob-container-sas-url>");

var blobSource = new BlobContentSource(blobContainerUri);
var options = new BuildDocumentModelOptions(modelId, DocumentBuildMode.Template, blobSource);

Operation<DocumentModelDetails> operation = await adminClient.BuildDocumentModelAsync(
    WaitUntil.Completed,
    options);

DocumentModelDetails model = operation.Value;

Console.WriteLine($"Model ID: {model.ModelId}");
Console.WriteLine($"Created: {model.CreatedOn}");

foreach (var docType in model.DocumentTypes)
{
    Console.WriteLine($"Document type: {docType.Key}");
    foreach (var field in docType.Value.FieldSchema)
    {
        Console.WriteLine($"  Field: {field.Key}, Confidence: {docType.Value.FieldConfidence[field.Key]}");
    }
}

要点解读:

  • BlobContentSource 封装训练数据源,其 ContainerUri 来自 BLOB_CONTAINER_SAS_URL 环境变量;TS 版本技能中对应的 REST 请求体为 azureBlobSource: { containerUrl, prefix },可互相对照理解。
  • DocumentBuildMode 决定模型训练方式:Template 适合固定版面(表单),Neural 适合版面多变的文档(详见"构建模式"一节)。
  • 构建完成后,DocumentModelDetails.DocumentTypes 会给出每个文档类型的字段模式 FieldSchema 与字段置信度 FieldConfidence,可用于校验训练质量。

5. 构建文档分类器(Build Document Classifier)

分类器用于先判断文档属于哪一类型(如"发票"还是"收据"),再路由到对应模型精析。构建时通过 Prefix 指定每个类型的训练样本子目录:

string classifierId = "my-classifier";
Uri blobContainerUri = new Uri("<blob-container-sas-url>");

var sourceA = new BlobContentSource(blobContainerUri) { Prefix = "TypeA/train" };
var sourceB = new BlobContentSource(blobContainerUri) { Prefix = "TypeB/train" };

var docTypes = new Dictionary<string, ClassifierDocumentTypeDetails>()
{
    { "TypeA", new ClassifierDocumentTypeDetails(sourceA) },
    { "TypeB", new ClassifierDocumentTypeDetails(sourceB) }
};

var options = new BuildClassifierOptions(classifierId, docTypes);

Operation<DocumentClassifierDetails> operation = await adminClient.BuildClassifierAsync(
    WaitUntil.Completed,
    options);

DocumentClassifierDetails classifier = operation.Value;
Console.WriteLine($"Classifier ID: {classifier.ClassifierId}");

训练数据组织方式为:同一 Blob 容器下按类型分目录存放样本,Prefix 指向各类型目录(如 TypeA/train、TypeB/train),与 TS 版本技能中 docTypes: { invoices: { azureBlobSource: { prefix: "invoices/" } }, ... } 的结构一一对应。

6. 分类文档(Classify Document)

构建好的分类器通过 ClassifyDocumentAsync 对未知文档进行类型判定:

string classifierId = "my-classifier";
Uri documentUri = new Uri("https://example.com/document.pdf");

var options = new ClassifyDocumentOptions(classifierId, documentUri);

Operation<AnalyzeResult> operation = await client.ClassifyDocumentAsync(
    WaitUntil.Completed,
    options);

AnalyzeResult result = operation.Value;

foreach (AnalyzedDocument document in result.Documents)
{
    Console.WriteLine($"Document type: {document.DocumentType}, confidence: {document.Confidence}");
}

注意这里调用的是 DocumentIntelligenceClient(分类属于分析能力),分类结果通过 AnalyzedDocument.DocumentType 与 Confidence 暴露。在实际管线中,可将分类结果与"按类型选择模型精析"组合成路由:先分类,再据 DocumentType 选择 prebuilt-invoice 或 prebuilt-receipt 等模型继续提取。

7. 管理模型(Manage Models)

管理类操作全部经由 DocumentIntelligenceAdministrationClient,涵盖资源详情、单模型查询、模型列表与删除:

// Get resource details
DocumentIntelligenceResourceDetails resourceDetails = await adminClient.GetResourceDetailsAsync();
Console.WriteLine($"Custom models: {resourceDetails.CustomDocumentModels.Count}/{resourceDetails.CustomDocumentModels.Limit}");

// Get specific model
DocumentModelDetails model = await adminClient.GetModelAsync("my-model-id");
Console.WriteLine($"Model: {model.ModelId}, Created: {model.CreatedOn}");

// List models
await foreach (DocumentModelDetails modelItem in adminClient.GetModelsAsync())
{
    Console.WriteLine($"Model: {modelItem.ModelId}");
}

// Delete model
await adminClient.DeleteModelAsync("my-model-id");

GetResourceDetailsAsync 返回的 CustomDocumentModels.Count/Limit 可用于监控自定义模型配额使用情况(对应 TS 版本技能中的 GET /info 接口返回的 customDocumentModels.count/limit),GetModelsAsync 以异步流形式分页返回全部模型,适合在管理后台呈现。

关键类型速查

类型 说明
DocumentIntelligenceClient 主客户端,负责文档分析
DocumentIntelligenceAdministrationClient 模型管理(构建/列举/删除)
AnalyzeResult 文档分析结果
AnalyzedDocument 结果中的单个文档
DocumentField 提取出的字段(含值与置信度)
DocumentFieldType 字段类型:String、Date、Number、Currency 等
DocumentPage 页信息(行、词、选择标记)
DocumentTable 提取出的表格(含单元格)
DocumentModelDetails 自定义模型元数据
BlobContentSource 训练数据源

构建模式对比

模式 适用场景
DocumentBuildMode.Template 固定版面文档(表单类),如统一格式的申请表
DocumentBuildMode.Neural 版面可变的文档,如自由排版的对账单、合同

Template 模式训练快、对结构化表单精度高,但对版面变化敏感;Neural 模式泛化能力强,能处理同一语义字段在不同位置出现的文档,但需要更多训练样本。选型建议:业务单据版面统一优先 Template,来源繁杂、版面随供应商而变的文档优先 Neural(TS 版本技能的最佳实践同样推荐"对自定义模型优先使用 neural 模式以应对更多版面变化")。

错误处理

SDK 的错误统一通过 RequestFailedException 抛出,携带 HTTP 状态码与错误消息:

using Azure;

try
{
    var operation = await client.AnalyzeDocumentAsync(
        WaitUntil.Completed,
        "prebuilt-invoice",
        documentUri);
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Error: {ex.Status} - {ex.Message}");
}

ex.Status 为 HTTP 状态码(如 401 认证失败、403 权限不足、404 资源不存在、429 限流),ex.Message 为服务端错误详情。可在捕获后按状态码分级处理(重试、告警或降级),并对 429/5xx 类临时错误实施带退避的重试策略。

最佳实践

技能文档给出六条生产级最佳实践,结合前文可形成完整的落地清单:

  1. 生产环境使用 DefaultAzureCredential:避免硬编码密钥,本地与云端零切换。
  2. 复用客户端实例:客户端是线程安全的,应在依赖注入容器中注册为单例,避免每次请求新建连接。
  3. 正确处理长耗时操作:简单场景用 WaitUntil.Completed;需要异步化或进度反馈时,用 WaitUntil.Started 获取 Operation 句柄后自行轮询 UpdateStatusAsync。
  4. 始终检查字段置信度:DocumentField.Confidence 与分类结果的 document.Confidence 都应设阈值过滤低置信度结果。
  5. 选择合适的模型:常见单据用预置模型(零训练成本),专用单据用自定义模型,先用分类器路由再精析。
  6. 使用自定义子域:这是 Entra ID 认证的硬性前提(https://<resource-name>.cognitiveservices.azure.com/ 格式)。

与旧版 SDK 的关系

SDK 用途 安装
Azure.AI.DocumentIntelligence 文档分析(本 SDK,当前版本) dotnet add package Azure.AI.DocumentIntelligence
Azure.AI.FormRecognizer 旧版 SDK(已弃用) 应改用 DocumentIntelligence

Azure.AI.FormRecognizer 是早期服务(Form Recognizer)的对应 SDK,已进入弃用周期;新项目应一律使用 Azure.AI.DocumentIntelligence,历史项目建议规划迁移(API 上模型 ID、字段结构保持延续,可对照上文工作流逐一替换客户端与调用)。

使用边界

该技能仅应在任务目标与上述范围匹配时启用:即"从文档中提取文本/表格/结构化字段、训练自定义模型或构建分类器"这类明确需求。其输出不能替代针对具体环境的验证、测试与专家评审;当输入文档类型、权限边界、成功标准等关键前提缺失时,应停下向用户澄清后再执行。

延伸阅读

登录后查看全文
agentic-awesome-skills