microsoft/azure-ai-document-intelligence-dotnet

Azure.AI.DocumentIntelligence (.NET)

Extraia texto, tabelas e dados estruturados de documentos usando modelos predefinidos e personalizados.

Instalação

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

Versão Atual: v1.0.0 (GA)

Variáveis de Ambiente

DOCUMENT_INTELLIGENCE_ENDPOINT=https://<resource-name>.cognitiveservices.azure.com/  # Obrigatório: endpoint do Document Intelligence
DOCUMENT_INTELLIGENCE_API_KEY=<your-api-key>  # Obrigatório apenas para autenticação AzureKeyCredential
BLOB_CONTAINER_SAS_URL=https://<storage>.blob.core.windows.net/<container>?<sas-token>  # Opcional: URL SAS do contêiner de blob para dados de treinamento
AZURE_TOKEN_CREDENTIALS=prod  # Obrigatório apenas se DefaultAzureCredential for usado em produção

Autenticação

Credencial de Token do Microsoft Entra

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

string endpoint = Environment.GetEnvironmentVariable("DOCUMENT_INTELLIGENCE_ENDPOINT");
// Desenvolvimento local: DefaultAzureCredential. Produção: defina AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<credential_específico>
var credential = new DefaultAzureCredential(
    DefaultAzureCredential.DefaultEnvironmentVariableName
);
// Ou use uma credencial específica diretamente em produção:
// Consulte 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);

Nota: O Entra ID requer um subdomínio personalizado (ex.: https://<resource-name>.cognitiveservices.azure.com/), não um endpoint regional.

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

Tipos de Cliente

Cliente	Finalidade
DocumentIntelligenceClient	Analisar documentos, classificar documentos
DocumentIntelligenceAdministrationClient	Construir/gerenciar modelos e classificadores personalizados

Modelos Predefinidos

ID do Modelo	Descrição
prebuilt-read	Extrair texto, idiomas, manuscrito
prebuilt-layout	Extrair texto, tabelas, marcas de seleção, estrutura
prebuilt-invoice	Extrair campos de fatura (fornecedor, itens, totais)
prebuilt-receipt	Extrair campos de recibo (comerciante, itens, total)
prebuilt-idDocument	Extrair campos de documento de identificação (nome, data de nascimento, endereço)
prebuilt-businessCard	Extrair campos de cartão de visita
prebuilt-tax.us.w2	Extrair campos do formulário fiscal W-2
prebuilt-healthInsuranceCard.us	Extrair campos de cartão de seguro saúde

Fluxos de Trabalho Principais

1. Analisar Fatura

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($"Nome do Fornecedor: '{vendorName}', confiança: {vendorNameField.Confidence}");
    }

    if (document.Fields.TryGetValue("InvoiceTotal", out DocumentField invoiceTotalField)
        && invoiceTotalField.FieldType == DocumentFieldType.Currency)
    {
        CurrencyValue invoiceTotal = invoiceTotalField.ValueCurrency;
        Console.WriteLine($"Total da Fatura: '{invoiceTotal.CurrencySymbol}{invoiceTotal.Amount}'");
    }
    
    // Extrair itens de linha
    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. Extrair Layout (Texto, Tabelas, Estrutura)

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

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

AnalyzeResult result = operation.Value;

// Extrair texto por página
foreach (DocumentPage page in result.Pages)
{
    Console.WriteLine($"Página {page.PageNumber}: {page.Lines.Count} linhas, {page.Words.Count} palavras");
    
    foreach (DocumentLine line in page.Lines)
    {
        Console.WriteLine($"  Linha: '{line.Content}'");
    }
}

// Extrair tabelas
foreach (DocumentTable table in result.Tables)
{
    Console.WriteLine($"Tabela: {table.RowCount} linhas x {table.ColumnCount} colunas");
    foreach (DocumentTableCell cell in table.Cells)
    {
        Console.WriteLine($"  Célula ({cell.RowIndex}, {cell.ColumnIndex}): {cell.Content}");
    }
}

3. Analisar Recibo

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($"Comerciante: {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($"Data: {dateField.ValueDate}");
}

4. Construir Modelo Personalizado

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

string modelId = "meu-modelo-personalizado";
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 do Modelo: {model.ModelId}");
Console.WriteLine($"Criado em: {model.CreatedOn}");

foreach (var docType in model.DocumentTypes)
{
    Console.WriteLine($"Tipo de documento: {docType.Key}");
    foreach (var field in docType.Value.FieldSchema)
    {
        Console.WriteLine($"  Campo: {field.Key}, Confiança: {docType.Value.FieldConfidence[field.Key]}");
    }
}

5. Construir Classificador de Documentos

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

var sourceA = new BlobContentSource(blobContainerUri) { Prefix = "TipoA/treino" };
var sourceB = new BlobContentSource(blobContainerUri) { Prefix = "TipoB/treino" };

var docTypes = new Dictionary<string, ClassifierDocumentTypeDetails>()
{
    { "TipoA", new ClassifierDocumentTypeDetails(sourceA) },
    { "TipoB", 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 do Classificador: {classifier.ClassifierId}");

6. Classificar Documento

string classifierId = "meu-classificador";
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($"Tipo de documento: {document.DocumentType}, confiança: {document.Confidence}");
}

7. Gerenciar Modelos

// Obter detalhes do recurso
DocumentIntelligenceResourceDetails resourceDetails = await adminClient.GetResourceDetailsAsync();
Console.WriteLine($"Modelos personalizados: {resourceDetails.CustomDocumentModels.Count}/{resourceDetails.CustomDocumentModels.Limit}");

// Obter modelo específico
DocumentModelDetails model = await adminClient.GetModelAsync("meu-id-modelo");
Console.WriteLine($"Modelo: {model.ModelId}, Criado em: {model.CreatedOn}");

// Listar modelos
await foreach (DocumentModelDetails modelItem in adminClient.GetModelsAsync())
{
    Console.WriteLine($"Modelo: {modelItem.ModelId}");
}

// Excluir modelo
await adminClient.DeleteModelAsync("meu-id-modelo");

Referência de Tipos Principais

Tipo	Descrição
DocumentIntelligenceClient	Cliente principal para análise
DocumentIntelligenceAdministrationClient	Gerenciamento de modelos
AnalyzeResult	Resultado da análise de documento
AnalyzedDocument	Documento único dentro do resultado
DocumentField	Campo extraído com valor e confiança
DocumentFieldType	String, Date, Number, Currency, etc.
DocumentPage	Informações da página (linhas, palavras, marcas de seleção)
DocumentTable	Tabela extraída com células
DocumentModelDetails	Metadados do modelo personalizado
BlobContentSource	Fonte de dados de treinamento

Modos de Construção

Modo	Caso de Uso
DocumentBuildMode.Template	Documentos com layout fixo (formulários)
DocumentBuildMode.Neural	Documentos com layout variável

Melhores Práticas

1. Use DefaultAzureCredential para produção
2. Reutilize instâncias do cliente — os clientes são thread-safe
3. Lide com operações de longa duração — Use WaitUntil.Completed para simplicidade
4. Verifique a confiança dos campos — Sempre verifique a propriedade Confidence
5. Use o modelo apropriado — Predefinido para documentos comuns, personalizado para especializados
6. Use subdomínio personalizado — Obrigatório para autenticação com Entra ID

Tratamento de Erros

using Azure;

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

SDKs Relacionados

SDK	Finalidade	Instalação
Azure.AI.DocumentIntelligence	Análise de documentos (este SDK)	dotnet add package Azure.AI.DocumentIntelligence
Azure.AI.FormRecognizer	SDK legado (obsoleto)	Use DocumentIntelligence no lugar

Links de Referência

Recurso	URL
Pacote NuGet	https://www.nuget.org/packages/Azure.AI.DocumentIntelligence
Referência de API	https://learn.microsoft.com/dotnet/api/azure.ai.documentintelligence
Exemplos no 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/
Modelos Predefinidos	https://aka.ms/azsdk/formrecognizer/models