AAS 技能实战:使用 Azure.AI.DocumentIntelligence (.NET) 从文档中提取文本、表格与结构化数据
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 类临时错误实施带退避的重试策略。
最佳实践
技能文档给出六条生产级最佳实践,结合前文可形成完整的落地清单:
- 生产环境使用
DefaultAzureCredential:避免硬编码密钥,本地与云端零切换。 - 复用客户端实例:客户端是线程安全的,应在依赖注入容器中注册为单例,避免每次请求新建连接。
- 正确处理长耗时操作:简单场景用
WaitUntil.Completed;需要异步化或进度反馈时,用WaitUntil.Started获取Operation句柄后自行轮询UpdateStatusAsync。 - 始终检查字段置信度:
DocumentField.Confidence与分类结果的document.Confidence都应设阈值过滤低置信度结果。 - 选择合适的模型:常见单据用预置模型(零训练成本),专用单据用自定义模型,先用分类器路由再精析。
- 使用自定义子域:这是 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、字段结构保持延续,可对照上文工作流逐一替换客户端与调用)。
使用边界
该技能仅应在任务目标与上述范围匹配时启用:即"从文档中提取文本/表格/结构化字段、训练自定义模型或构建分类器"这类明确需求。其输出不能替代针对具体环境的验证、测试与专家评审;当输入文档类型、权限边界、成功标准等关键前提缺失时,应停下向用户澄清后再执行。
延伸阅读
- 技能原文:plugins/agentic-awesome-skills-claude/skills/azure-ai-document-intelligence-dotnet/SKILL.md(根目录副本 skills/azure-ai-document-intelligence-dotnet/SKILL.md)
- 同服务 TypeScript 版本技能:plugins/agentic-awesome-skills-claude/skills/azure-ai-document-intelligence-ts/SKILL.md
- 技能目录登记信息:data/catalog.json、data/skills_index.json、data/aliases.json