microsoft/azure-ai-document-intelligence-dotnet

Azure.AI.DocumentIntelligence (.NET)

Extrahieren Sie Text, Tabellen und strukturierte Daten aus Dokumenten mit vorgefertigten und benutzerdefinierten Modellen.

Installation

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

Aktuelle Version: v1.0.0 (GA)

Umgebungsvariablen

DOCUMENT_INTELLIGENCE_ENDPOINT=https://<Ressourcenname>.cognitiveservices.azure.com/  # Erforderlich: Document Intelligence-Endpunkt
DOCUMENT_INTELLIGENCE_API_KEY=<Ihr-API-Schlüssel>  # Nur bei AzureKeyCredential-Authentifizierung erforderlich
BLOB_CONTAINER_SAS_URL=https://<Speicher>.blob.core.windows.net/<Container>?<SAS-Token>  # Optional: Blob-Container-SAS-URL für Trainingsdaten
AZURE_TOKEN_CREDENTIALS=prod  # Nur erforderlich, wenn DefaultAzureCredential in der Produktion verwendet wird

Authentifizierung

Microsoft Entra-Token-Anmeldeinformation

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

string endpoint = Environment.GetEnvironmentVariable("DOCUMENT_INTELLIGENCE_ENDPOINT");
// Lokale Entwicklung: DefaultAzureCredential. Produktion: Setzen Sie AZURE_TOKEN_CREDENTIALS=prod oder AZURE_TOKEN_CREDENTIALS=<spezifische_Anmeldeinformation>
var credential = new DefaultAzureCredential(
    DefaultAzureCredential.DefaultEnvironmentVariableName
);
// Oder verwenden Sie direkt eine bestimmte Anmeldeinformation in der Produktion:
// Siehe 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);

Hinweis: Entra ID erfordert eine benutzerdefinierte Subdomain (z. B. https://<Ressourcenname>.cognitiveservices.azure.com/), keinen regionalen Endpunkt.

API-Schlüssel

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

Client-Typen

Client	Zweck
DocumentIntelligenceClient	Analysieren von Dokumenten, Klassifizieren von Dokumenten
DocumentIntelligenceAdministrationClient	Erstellen/Verwalten von benutzerdefinierten Modellen und Klassifikatoren

Vorgefertigte Modelle

Modell-ID	Beschreibung
prebuilt-read	Text, Sprachen, Handschrift extrahieren
prebuilt-layout	Text, Tabellen, Auswahlmarkierungen, Struktur extrahieren
prebuilt-invoice	Rechnungsfelder extrahieren (Lieferant, Artikel, Summen)
prebuilt-receipt	Belegfelder extrahieren (Händler, Artikel, Gesamtsumme)
prebuilt-idDocument	Ausweisdokumentfelder extrahieren (Name, Geburtsdatum, Adresse)
prebuilt-businessCard	Visitenkartenfelder extrahieren
prebuilt-tax.us.w2	W-2-Steuerformularfelder extrahieren
prebuilt-healthInsuranceCard.us	Krankenversicherungskartenfelder extrahieren

Kern-Workflows

1. Rechnung analysieren

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($"Lieferantenname: '{vendorName}', Konfidenz: {vendorNameField.Confidence}");
    }

    if (document.Fields.TryGetValue("InvoiceTotal", out DocumentField invoiceTotalField)
        && invoiceTotalField.FieldType == DocumentFieldType.Currency)
    {
        CurrencyValue invoiceTotal = invoiceTotalField.ValueCurrency;
        Console.WriteLine($"Rechnungssumme: '{invoiceTotal.CurrencySymbol}{invoiceTotal.Amount}'");
    }
    
    // Positionen extrahieren
    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($"  Artikel: {descField.ValueString}");
        }
    }
}

2. Layout extrahieren (Text, Tabellen, Struktur)

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

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

AnalyzeResult result = operation.Value;

// Text nach Seite extrahieren
foreach (DocumentPage page in result.Pages)
{
    Console.WriteLine($"Seite {page.PageNumber}: {page.Lines.Count} Zeilen, {page.Words.Count} Wörter");
    
    foreach (DocumentLine line in page.Lines)
    {
        Console.WriteLine($"  Zeile: '{line.Content}'");
    }
}

// Tabellen extrahieren
foreach (DocumentTable table in result.Tables)
{
    Console.WriteLine($"Tabelle: {table.RowCount} Zeilen x {table.ColumnCount} Spalten");
    foreach (DocumentTableCell cell in table.Cells)
    {
        Console.WriteLine($"  Zelle ({cell.RowIndex}, {cell.ColumnIndex}): {cell.Content}");
    }
}

3. Beleg analysieren

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($"Händler: {merchantField.ValueString}");
        
    if (document.Fields.TryGetValue("Total", out DocumentField totalField))
        Console.WriteLine($"Gesamtsumme: {totalField.ValueCurrency.Amount}");
        
    if (document.Fields.TryGetValue("TransactionDate", out DocumentField dateField))
        Console.WriteLine($"Datum: {dateField.ValueDate}");
}

4. Benutzerdefiniertes Modell erstellen

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($"Modell-ID: {model.ModelId}");
Console.WriteLine($"Erstellt: {model.CreatedOn}");

foreach (var docType in model.DocumentTypes)
{
    Console.WriteLine($"Dokumenttyp: {docType.Key}");
    foreach (var field in docType.Value.FieldSchema)
    {
        Console.WriteLine($"  Feld: {field.Key}, Konfidenz: {docType.Value.FieldConfidence[field.Key]}");
    }
}

5. Dokumentklassifikator erstellen

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($"Klassifikator-ID: {classifier.ClassifierId}");

6. Dokument klassifizieren

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

7. Modelle verwalten

// Ressourcendetails abrufen
DocumentIntelligenceResourceDetails resourceDetails = await adminClient.GetResourceDetailsAsync();
Console.WriteLine($"Benutzerdefinierte Modelle: {resourceDetails.CustomDocumentModels.Count}/{resourceDetails.CustomDocumentModels.Limit}");

// Bestimmtes Modell abrufen
DocumentModelDetails model = await adminClient.GetModelAsync("my-model-id");
Console.WriteLine($"Modell: {model.ModelId}, Erstellt: {model.CreatedOn}");

// Modelle auflisten
await foreach (DocumentModelDetails modelItem in adminClient.GetModelsAsync())
{
    Console.WriteLine($"Modell: {modelItem.ModelId}");
}

// Modell löschen
await adminClient.DeleteModelAsync("my-model-id");

Referenz zu Schlüsseltypen

Typ	Beschreibung
DocumentIntelligenceClient	Hauptclient für Analysen
DocumentIntelligenceAdministrationClient	Modellverwaltung
AnalyzeResult	Ergebnis der Dokumentenanalyse
AnalyzedDocument	Einzelnes Dokument innerhalb des Ergebnisses
DocumentField	Extrahiertes Feld mit Wert und Konfidenz
DocumentFieldType	String, Datum, Zahl, Währung usw.
DocumentPage	Seiteninfo (Zeilen, Wörter, Auswahlmarkierungen)
DocumentTable	Extrahierten Tabelle mit Zellen
DocumentModelDetails	Metadaten des benutzerdefinierten Modells
BlobContentSource	Datenquelle für Training

Erstellungsmodi

Modus	Anwendungsfall
DocumentBuildMode.Template	Dokumente mit festem Layout (Formulare)
DocumentBuildMode.Neural	Dokumente mit variablem Layout

Bewährte Methoden

1. Verwenden Sie DefaultAzureCredential für die Produktion
2. Wiederverwenden von Client-Instanzen – Clients sind threadsicher
3. Behandlung von lang andauernden Vorgängen – Verwenden Sie WaitUntil.Completed für Einfachheit
4. Überprüfen der Feldkonfidenz – Überprüfen Sie immer die Confidence-Eigenschaft
5. Verwenden des geeigneten Modells – Vorgefertigt für häufige Dokumente, benutzerdefiniert für spezialisierte
6. Verwenden Sie eine benutzerdefinierte Subdomain – Erforderlich für Entra-ID-Authentifizierung

Fehlerbehandlung

using Azure;

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

Verwandte SDKs

SDK	Zweck	Installation
Azure.AI.DocumentIntelligence	Dokumentenanalyse (dieses SDK)	dotnet add package Azure.AI.DocumentIntelligence
Azure.AI.FormRecognizer	Legacy-SDK (veraltet)	Verwenden Sie stattdessen DocumentIntelligence

Referenzlinks

Ressource	URL
NuGet-Paket	https://www.nuget.org/packages/Azure.AI.DocumentIntelligence
API-Referenz	https://learn.microsoft.com/dotnet/api/azure.ai.documentintelligence
GitHub-Beispiele	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/documentintelligence/Azure.AI.DocumentIntelligence/samples
Document Intelligence Studio	https://documentintelligence.ai.azure.com/
Vorgefertigte Modelle	https://aka.ms/azsdk/formrecognizer/models