microsoft/azure-ai-document-intelligence-dotnet

Azure.AI.DocumentIntelligence (.NET)

Extrae texto, tablas y datos estructurados de documentos usando modelos predefinidos y personalizados.

Instalación

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

Versión actual: v1.0.0 (GA)

Variables de entorno

DOCUMENT_INTELLIGENCE_ENDPOINT=https://<nombre-recurso>.cognitiveservices.azure.com/  # Obligatorio: punto de conexión de Document Intelligence
DOCUMENT_INTELLIGENCE_API_KEY=<tu-clave-api>  # Solo necesario para autenticación AzureKeyCredential
BLOB_CONTAINER_SAS_URL=https://<storage>.blob.core.windows.net/<contenedor>?<token-sas>  # Opcional: URL SAS del contenedor de blobs para datos de entrenamiento
AZURE_TOKEN_CREDENTIALS=prod  # Obligatorio solo si se usa DefaultAzureCredential en producción

Autenticación

Credencial de token de Microsoft Entra

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

string endpoint = Environment.GetEnvironmentVariable("DOCUMENT_INTELLIGENCE_ENDPOINT");
// Desarrollo local: DefaultAzureCredential. Producción: establecer AZURE_TOKEN_CREDENTIALS=prod o AZURE_TOKEN_CREDENTIALS=<credencial_específica>
var credential = new DefaultAzureCredential(
    DefaultAzureCredential.DefaultEnvironmentVariableName
);
// O usar una credencial específica directamente en producción:
// 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: Entra ID requiere un subdominio personalizado (por ejemplo, https://<nombre-recurso>.cognitiveservices.azure.com/), no un punto de conexión regional.

Clave 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	Propósito
DocumentIntelligenceClient	Analizar documentos, clasificar documentos
DocumentIntelligenceAdministrationClient	Construir/gestionar modelos y clasificadores personalizados

Modelos predefinidos

ID del modelo	Descripción
prebuilt-read	Extraer texto, idiomas, escritura a mano
prebuilt-layout	Extraer texto, tablas, marcas de selección, estructura
prebuilt-invoice	Extraer campos de factura (proveedor, artículos, totales)
prebuilt-receipt	Extraer campos de recibo (comercio, artículos, total)
prebuilt-idDocument	Extraer campos de documento de identidad (nombre, fecha de nacimiento, dirección)
prebuilt-businessCard	Extraer campos de tarjeta de presentación
prebuilt-tax.us.w2	Extraer campos del formulario de impuestos W-2
prebuilt-healthInsuranceCard.us	Extraer campos de tarjeta de seguro médico

Flujos de trabajo principales

1. Analizar factura

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($"Nombre del proveedor: '{vendorName}', confianza: {vendorNameField.Confidence}");
    }

    if (document.Fields.TryGetValue("InvoiceTotal", out DocumentField invoiceTotalField)
        && invoiceTotalField.FieldType == DocumentFieldType.Currency)
    {
        CurrencyValue invoiceTotal = invoiceTotalField.ValueCurrency;
        Console.WriteLine($"Total de la factura: '{invoiceTotal.CurrencySymbol}{invoiceTotal.Amount}'");
    }
    
    // Extraer líneas de artículos
    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($"  Artículo: {descField.ValueString}");
        }
    }
}

2. Extraer diseño (texto, tablas, estructura)

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

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

AnalyzeResult result = operation.Value;

// Extraer texto por página
foreach (DocumentPage page in result.Pages)
{
    Console.WriteLine($"Página {page.PageNumber}: {page.Lines.Count} líneas, {page.Words.Count} palabras");
    
    foreach (DocumentLine line in page.Lines)
    {
        Console.WriteLine($"  Línea: '{line.Content}'");
    }
}

// Extraer tablas
foreach (DocumentTable table in result.Tables)
{
    Console.WriteLine($"Tabla: {table.RowCount} filas x {table.ColumnCount} columnas");
    foreach (DocumentTableCell cell in table.Cells)
    {
        Console.WriteLine($"  Celda ({cell.RowIndex}, {cell.ColumnIndex}): {cell.Content}");
    }
}

3. Analizar 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($"Comercio: {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($"Fecha: {dateField.ValueDate}");
}

4. Construir modelo personalizado

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 del modelo: {model.ModelId}");
Console.WriteLine($"Creado: {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}, Confianza: {docType.Value.FieldConfidence[field.Key]}");
    }
}

5. Construir clasificador de documentos

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 del clasificador: {classifier.ClassifierId}");

6. Clasificar documento

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($"Tipo de documento: {document.DocumentType}, confianza: {document.Confidence}");
}

7. Gestionar modelos

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

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

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

// Eliminar modelo
await adminClient.DeleteModelAsync("my-model-id");

Referencia de tipos clave

Tipo	Descripción
DocumentIntelligenceClient	Cliente principal para análisis
DocumentIntelligenceAdministrationClient	Gestión de modelos
AnalyzeResult	Resultado del análisis de documentos
AnalyzedDocument	Documento individual dentro del resultado
DocumentField	Campo extraído con valor y confianza
DocumentFieldType	Cadena, Fecha, Número, Moneda, etc.
DocumentPage	Información de página (líneas, palabras, marcas de selección)
DocumentTable	Tabla extraída con celdas
DocumentModelDetails	Metadatos del modelo personalizado
BlobContentSource	Fuente de datos de entrenamiento

Modos de construcción

Modo	Caso de uso
DocumentBuildMode.Template	Documentos con diseño fijo (formularios)
DocumentBuildMode.Neural	Documentos con diseño variable

Prácticas recomendadas

1. Usa DefaultAzureCredential para producción
2. Reutiliza instancias de cliente — los clientes son seguros para subprocesos
3. Maneja operaciones de larga duración — Usa WaitUntil.Completed para simplicidad
4. Verifica la confianza del campo — Siempre comprueba la propiedad Confidence
5. Usa el modelo adecuado — Predefinido para documentos comunes, personalizado para especializados
6. Usa un subdominio personalizado — Obligatorio para autenticación con Entra ID

Manejo de errores

using Azure;

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

SDKs relacionados

SDK	Propósito	Instalación
Azure.AI.DocumentIntelligence	Análisis de documentos (este SDK)	dotnet add package Azure.AI.DocumentIntelligence
Azure.AI.FormRecognizer	SDK heredado (obsoleto)	Usa DocumentIntelligence en su lugar

Enlaces de referencia

Recurso	URL
Paquete NuGet	https://www.nuget.org/packages/Azure.AI.DocumentIntelligence
Referencia de API	https://learn.microsoft.com/dotnet/api/azure.ai.documentintelligence
Ejemplos en 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