microsoft/azure-ai-document-intelligence-dotnet

Azure.AI.DocumentIntelligence (.NET)

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

安装

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

当前版本：v1.0.0（正式发布版）

环境变量

DOCUMENT_INTELLIGENCE_ENDPOINT=https://<资源名称>.cognitiveservices.azure.com/  # 必填：Document Intelligence 终结点
DOCUMENT_INTELLIGENCE_API_KEY=<你的 API 密钥>  # 仅在使用 AzureKeyCredential 身份验证时需要
BLOB_CONTAINER_SAS_URL=https://<存储>.blob.core.windows.net/<容器>?<SAS 令牌>  # 可选：用于训练数据的 Blob 容器 SAS URL
AZURE_TOKEN_CREDENTIALS=prod  # 仅在生产环境中使用 DefaultAzureCredential 时需要

身份验证

Microsoft Entra 令牌凭据

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

string endpoint = Environment.GetEnvironmentVariable("DOCUMENT_INTELLIGENCE_ENDPOINT");
// 本地开发：DefaultAzureCredential。生产环境：设置 AZURE_TOKEN_CREDENTIALS=prod 或 AZURE_TOKEN_CREDENTIALS=<具体凭据>
var credential = new DefaultAzureCredential(
    DefaultAzureCredential.DefaultEnvironmentVariableName
);
// 或者在生产环境中直接使用特定的凭据：
// 参见 https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes
// var credential = new ManagedIdentityCredential();
var client = new DocumentIntelligenceClient(new Uri(endpoint), credential);

注意：Entra ID 需要一个 自定义子域（例如 https://<资源名称>.cognitiveservices.azure.com/），而不是区域终结点。

API 密钥

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. 分析发票

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($"供应商名称：'{vendorName}'，置信度：{vendorNameField.Confidence}");
    }

    if (document.Fields.TryGetValue("InvoiceTotal", out DocumentField invoiceTotalField)
        && invoiceTotalField.FieldType == DocumentFieldType.Currency)
    {
        CurrencyValue invoiceTotal = invoiceTotalField.ValueCurrency;
        Console.WriteLine($"发票总金额：'{invoiceTotal.CurrencySymbol}{invoiceTotal.Amount}'");
    }
    
    // 提取行项目
    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($"  项目：{descField.ValueString}");
        }
    }
}

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

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.PageNumber} 页：{page.Lines.Count} 行，{page.Words.Count} 个单词");
    
    foreach (DocumentLine line in page.Lines)
    {
        Console.WriteLine($"  行：'{line.Content}'");
    }
}

// 提取表格
foreach (DocumentTable table in result.Tables)
{
    Console.WriteLine($"表格：{table.RowCount} 行 x {table.ColumnCount} 列");
    foreach (DocumentTableCell cell in table.Cells)
    {
        Console.WriteLine($"  单元格（{cell.RowIndex}，{cell.ColumnIndex}）：{cell.Content}");
    }
}

3. 分析收据

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($"商家：{merchantField.ValueString}");
        
    if (document.Fields.TryGetValue("Total", out DocumentField totalField))
        Console.WriteLine($"总金额：{totalField.ValueCurrency.Amount}");
        
    if (document.Fields.TryGetValue("TransactionDate", out DocumentField dateField))
        Console.WriteLine($"日期：{dateField.ValueDate}");
}

4. 构建自定义模型

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($"模型 ID：{model.ModelId}");
Console.WriteLine($"创建时间：{model.CreatedOn}");

foreach (var docType in model.DocumentTypes)
{
    Console.WriteLine($"文档类型：{docType.Key}");
    foreach (var field in docType.Value.FieldSchema)
    {
        Console.WriteLine($"  字段：{field.Key}，置信度：{docType.Value.FieldConfidence[field.Key]}");
    }
}

5. 构建文档分类器

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($"分类器 ID：{classifier.ClassifierId}");

6. 分类文档

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.DocumentType}，置信度：{document.Confidence}");
}

7. 管理模型

// 获取资源详细信息
DocumentIntelligenceResourceDetails resourceDetails = await adminClient.GetResourceDetailsAsync();
Console.WriteLine($"自定义模型：{resourceDetails.CustomDocumentModels.Count}/{resourceDetails.CustomDocumentModels.Limit}");

// 获取特定模型
DocumentModelDetails model = await adminClient.GetModelAsync("my-model-id");
Console.WriteLine($"模型：{model.ModelId}，创建时间：{model.CreatedOn}");

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

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

关键类型参考

类型	描述
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 身份验证所必需

错误处理

using Azure;

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

相关 SDK

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

参考链接

资源	URL
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