azure-ai-document-intelligence-dotnet

Azure.AI.DocumentIntelligence (.NET)

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

安装

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

当前版本：v1.0.0 (GA)

环境变量

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（推荐）

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 密钥

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	提取医疗保险卡字段

核心工作流

在分析或训练之前，请确认资源所在区域／租户，并确认允许将文档内容发送到 Azure。身份证件、发票和医疗文档可能包含高度敏感的信息：请使用获批的样本数据，不要记录提取出的个人字段或 SAS URL，并将短期存储访问权限限制在所需的容器范围内。固定 SDK／API 版本，并在相应的官方示例中核实支持的模型／字段类型和重载；代码片段并非可编译的应用程序。置信度分数不代表准确性已得到验证：在据此做出决策前，请根据源页面和业务规则核对字段。训练／分析可能会产生费用；删除操作只能针对明确获准的模型。

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

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;

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

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

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

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($"Classifier 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 type: {document.DocumentType}, confidence: {document.Confidence}");
}

7. 管理模型

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

关键类型参考

类型	说明
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($"Error: {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

适用场景

当需要执行概览中描述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审核的替代品。
• 如果缺少所需输入、权限、安全边界或成功标准，请停止并请求澄清。