Azure AI 文档智能 .NET SDK

azure-ai-document-intelligence-dotnet

分类数据

作者Agentic Awesome Skills 社区

许可MIT

评分4.90/5

使用15.5K

Azure.AI.DocumentIntelligence (.NET)

使用预置模型和自定义模型从文档中提取文本、表格和结构化数据。

安装

bash

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

当前版本: v1.0.0 (GA)

环境变量

bash

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>

身份验证

Microsoft Entra ID (推荐)

csharp

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);

> 注意: Entra ID 需要使用自定义子域名（例如 https://<resource-name>.cognitiveservices.azure.com/），而非区域端点。

API 密钥

csharp

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));

客户端类型

| 客户端 | 用途 |
|--------|---------|
| DocumentIntelligenceClient | 分析文档、对文档进行分类 |
| DocumentIntelligenceAdministrationClient | 构建/管理自定义模型和分类器 |

预置模型

| 模型 ID | 描述 |
|----------|-------------|
| prebuilt-read | 提取文本、语言、手写内容 |
| prebuilt-layout | 提取文本、表格、选择标记、结构 |
| prebuilt-invoice | 提取发票字段（供应商、项目、总额） |
| prebuilt-receipt | 提取收据字段（商家、项目、总额） |
| prebuilt-idDocument | 提取身份证件字段（姓名、出生日期、地址） |
| prebuilt-businessCard | 提取名片字段 |
| prebuilt-tax.us.w2 | 提取美国 W-2 税单字段 |
| prebuilt-healthInsuranceCard.us | 提取美国医疗保险卡字段 |

核心工作流

1. 分析发票

csharp

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}'");
    }
    
    // 提取行项目

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}");
}
}
}

code

### 2. 提取布局（文本、表格、结构）

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

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

AnalyzeResult result = operation.Value;

// 按页提取文本
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}'");
}
}

// 提取表格
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}");
}
}

code

### 3. 分析收据

csharp
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}");
}

code

### 4. 构建自定义模型

csharp
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]}");
}
}

code

### 5. 构建文档分类器

csharp
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 ClassifierDocumentTypeDetail
s(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}");

code

### 6. 对文档进行分类

csharp
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}");
}

code

### 7. 管理模型

csharp
// 获取资源详情
DocumentIntelligenceResourceDetails resourceDetails = await adminClient.GetResourceDetailsAsync();
Console.WriteLine($"Custom models: {resourceDetails.CustomDocumentModels.Count}/{resourceDetails.CustomDocumentModels.Limit}");

// 获取特定模型
DocumentModelDetails model = await adminClient.GetModelAsync("my-model-id");
Console.WriteLine($"Model: {model.ModelId}, Created: {model.CreatedOn}");

// 列出模型
await foreach (DocumentModelDetails modelItem in adminClient.GetModelsAsync())
{
Console.WriteLine($"Model: {modelItem.ModelId}");
}

// 删除模型
await adminClient.DeleteModelAsync("my-model-id");

code

## 关键类型参考
| 类型 | 描述 |
|------|-------------|
| DocumentIntelligenceClient | 用于分析的主客户端 |
| DocumentIntelligenceAdministrationClient | 用于模型管理 |
| AnalyzeResult | 文档分析结果 |
| AnalyzedDocument | 结果中的单个文档 |
| DocumentField | 包含值和置信度的提取字段 |
| DocumentFieldType | 字符串、日期、数字、货币等 |
| DocumentPage | 页面信息（行、词、选择标记） |
| DocumentTable | 包含单元格的提取表格 |
| DocumentModelDetails | 自定义模型元数据 |
| BlobContentSource | 训练数据源 |
构建模式
| 模式 | 使用场景 |
|------|----------|
| DocumentBuildMode.Template | 固定布局文档（表单） |
| DocumentBuildMode.Neural | 可变布局文档 |
最佳实践
1. 生产环境使用 DefaultAzureCredential
2. 复用客户端实例 —— 客户端是线程安全的
3. 处理长时间运行的操作 —— 为简化操作请使用 WaitUntil.Completed
4. 检查字段置信度 —— 始终验证 Confidence 属性
5. 选择合适的模型 —— 常见文档使用预置模型，专业文档使用自定义模型
6. 使用自定义子域名 —— Entra ID 身份验证必需
错误处理

csharp using Azure;

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


相关 SDK

| SDK | 用途 | 安装 | |-----|---------|---------| |Azure.AI.DocumentIntelligence | 文档分析（本 SDK） | dotnet add package Azure.AI.DocumentIntelligence| |Azure.AI.FormRecognizer` | 旧版 SDK（已弃用） | 请改用 DocumentIntelligence |

参考链接

| 资源 | URL |
|----------|-----|
| NuGet Pa | |
| NuGet 包 | https://www.nuget.org/packages/Azure.AI.DocumentIntelligence |
| API 参考 | https://learn.microsoft.com/dotnet/api/azure.ai.documentintelligence |
| GitHub 示例 | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/documentintelligence/Azure.AI.DocumentIntelligence/samples |
| Document Intelligence Studio | https://documentintelligence.ai.azure.com/ |
| 预置模型 | https://aka.ms/azsdk/formrecognizer/models |

使用场景

本技能适用于执行概述中描述的工作流或操作。

局限性

仅在任务明确符合上述范围时使用此技能。

不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。

如果缺少必要的输入、权限、安全边界或成功标准，请停止操作并请求澄清。

Azure AI 文档智能 .NET SDK

Azure.AI.DocumentIntelligence (.NET)

安装

环境变量

身份验证

Microsoft Entra ID (推荐)

API 密钥

客户端类型

预置模型

核心工作流

1. 分析发票

构建模式

最佳实践

`错误处理`

相关 SDK

参考链接

使用场景

局限性

扫码进交流群