Schnellstart: Analysieren eines Dokuments mit der Content Understanding-CLI

In dieser Schnellstartanleitung verwenden Sie die CLI (azd ai cu) für Azure Content Understanding in Foundry Tools, um Dokumenttext und Layout zu extrahieren. Sie analysieren eine Beispielrechnung mit prebuilt-layout und speichern das Ergebnis als Markdown oder JSON.

Important

Die CLI befindet sich in der Vorschau. Vorschauen werden ohne Vereinbarung auf Serviceebene bereitgestellt und werden für Produktionsworkloads nicht empfohlen. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbedingungen für Microsoft Azure-Vorschauversionen.

Die CLI verwendet standardmäßig die 2025-11-01 GA-Dienst-API. Der Vorschauversionsstatus ist von der Dienst-API-Version getrennt.

Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen.

Voraussetzungen

Die Befehle in dieser Schnellstartanleitung funktionieren in Bash und PowerShell. Sie benötigen keine Python, ein Sprach-SDK oder ein initialisiertes azd Projekt. Der prebuilt-layout Analyzer erfordert keine Sprach- oder Einbettungsmodellbereitstellungen.

Inhaltsverständniserweiterung installieren

Vergewissern Sie sich, dass azd Version 1.37.0 oder höher ist, installieren Sie dann die Content Understanding-Erweiterung, und überprüfen Sie ihre Version:

azd version
azd ext install azure.ai.content-understanding
azd ai cu version

Referenz:azd-Version, Erweiterungsbefehle.

Der letzte Befehl zeigt die Erweiterungs-ID und die installierte Version an, ähnlich wie in diesem Beispiel. Ihre Version kann unterschiedlich sein:

azure.ai.content-understanding 0.1.0-preview

Stellen Sie eine Verbindung mit Ihrer Ressource her

Kopieren Sie Ihren Ressourcenendpunkt aus dem Azure-Portal. Verwenden Sie den Ressourcenendpunkt, z. B. https://<resource-name>.services.ai.azure.com/, nicht eine Foundry-Projekt-URL.

Wenn Sie bereits über einen gespeicherten Endpunkt verfügen, notieren Sie sich den Wert mit azd ai cu config get CU_ENDPOINT, bevor Sie ihn ersetzen.

Melden Sie sich an, speichern Sie den Endpunkt als CLI-Benutzerstandard, und überprüfen Sie Ihre Verbindung. Ersetzen Sie <your-resource-endpoint> durch Ihren Endpunkt:

azd auth login
azd ai cu config set CU_ENDPOINT "<your-resource-endpoint>"
azd ai cu doctor

Referenz:Eine Verbindung mit Microsoft Foundry herstellen und die Einrichtung überprüfen.

Der gespeicherte Endpunkt ist in zukünftigen Sitzungen ohne azd init verfügbar. Shellvariablen und anwendbare azd Umgebungseinstellungen haben Vorrang vor diesem gespeicherten Standardwert. Der doctor Bericht zeigt die effektiven Einstellungen und deren Quellen an.

Beheben Sie alle Authentifizierungs- oder Ressourcenzugriffsfehler, bevor Sie fortfahren. Eine Warnung über fehlende generative Modellstandardwerte hindert Sie nicht daran, prebuilt-layout zu verwenden.

Die CLI verwendet Microsoft Entra ID Authentifizierung über azd. Die API-Schlüsselauthentifizierung wird nicht unterstützt.

Herunterladen eines Beispiels

Laden Sie in einem schreibbaren Verzeichnis die Beispielrechnung mit dem Befehl für Ihre Shell herunter. Führen Sie die verbleibenden Befehle aus diesem Verzeichnis aus.

$sampleRoot = "https://raw.githubusercontent.com/Azure-Samples"
$samplePath = "azure-ai-content-understanding-assets/main/document/invoice.pdf"
Invoke-WebRequest -Uri "$sampleRoot/$samplePath" -OutFile invoice.pdf

Sie können die Beispielrechnung auch in Ihrem Browser herunterladen. Speichern Sie sie als invoice.pdf in Ihrem Arbeitsverzeichnis.

Analysieren eines Dokuments

Wenn Sie keinen Standardanalysator konfigurieren, verwendet die CLI prebuilt-layout, um Dokumenttext und Layout zu extrahieren. Dieser Befehl lädt das Beispiel in Ihre konfigurierte Azure Ressource hoch und kann Gebühren verursachen:

azd ai cu analyze invoice.pdf

Der Befehl zeigt YAML-Frontmatter gefolgt von extrahiertem Dokument-Markdown an. Ein verkürztes Ergebnis sieht wie folgt aus:

---
mimeType: application/pdf
pages: 1
---
<!-- InputPageNumber: 1 -->

CONTOSO LTD.


# INVOICE

Das Terminal zeigt die Markdown-Quelle an. Tabellen können als HTML angezeigt werden; Verwenden Sie eine Markdown-Vorschau, um gespeicherte Inhalte anzuzeigen.

Verwenden Sie --analyzer <analyzer-id> (oder -a) zum Überschreiben des Standardwerts für einen Befehl. Um den gespeicherten Standardwert zu ändern, führen Sie den Befehl aus azd ai cu config set CU_DEFAULT_ANALYZER "<analyzer-id>".

Ergebnis speichern

Wählen Sie Markdown zum Lesen oder JSON für die vollständige Dienstantwort aus. Jeder Befehl führt eine neue Analyse aus, die Gebühren verursachen kann. Keiner der beiden Befehle exportiert das vorherige Ergebnis.

Markdown

Führen Sie Folgendes aus, um YAML-Front-Matter und Dokumentmarkdown zu speichern:

azd ai cu analyze invoice.pdf --analyzer prebuilt-layout --output-file out.md

JSON

Verwenden Sie --output json (oder -o json) für die vollständige Dienstantwort:

azd ai cu analyze invoice.pdf -a prebuilt-layout -o json --output-file out.json

Bei beiden Formaten meldet das Terminal die Eingabe, den Status und den Ausgabepfad. Öffnen Sie out.md oder out.json, um den gespeicherten Inhalt zu prüfen.

In der JSON-Antwort befindet sich das Dokument Markdown unter result.contents[0].markdown. Die Antwort enthält auch Layoutdetails und kann Dienstwarnungen und Nutzung enthalten. Die Dateinamenerweiterung allein wählt nicht das Ausgabeformat aus.

Troubleshooting

Thema Resolution
azd ai cu ist nicht verfügbar Überprüfen Sie, ob es sich bei azd um Version 1.37.0 oder höher handelt und ob azure.ai.content-understanding installiert ist.
Authentifizierungs- oder Ressourcenzugriffsfehler Führen Sie azd auth login aus, und vergewissern Sie sich, dass die angemeldete Identität über Content Understanding-Datenebenenzugriff für die Ressource verfügt.
doctor meldet fehlende Standardeinstellungen für das generative Modell Weiter mit prebuilt-layout. Bevor Sie Analysetools verwenden, die generative Modelle erfordern, befolgen Sie die Einrichtungsanleitung für CLI-Modelle.
The CU endpoint must be a resource URL, not an operation URL Verwenden Sie den Ressourcenendpunkt, wie https://<resource-name>.services.ai.azure.com/, und nicht eine Foundry-Projekt- oder API-Vorgangs-URL.
Ein Befehl verwendet eine andere Ressource als erwartet. Überprüfen Sie den effektiven Endpunkt und seine Quelle im doctor Bericht. Eine Shellvariable CU_ENDPOINT oder eine entsprechende Umgebungsvariable azd kann den gespeicherten Benutzerstandard außer Kraft setzen.
An input path does not exist or could not be resolved Nehmen Sie die Ausführung in dem Verzeichnis vor, das invoice.pdf enthält, oder übergeben Sie den korrekt zitierten Pfad zur heruntergeladenen Datei.
A result file already exists Verwenden Sie einen neuen Ausgabedateinamen. Fügen Sie --on-existing skip hinzu, um das vorherige Ergebnis beizubehalten, ohne es erneut zu analysieren. Verwenden Sie --on-existing reanalyze nur, um eine andere Anforderung zu senden und dieses Ergebnis zu ersetzen.

Bereinigen von Ressourcen

Diese Schnellstartanleitung verwendet eine vorhandene Ressource und erstellt keine Azure Ressourcen. Wenn Sie einen vorhandenen Benutzerstandard ersetzt haben, stellen Sie den vorherigen Wert wieder her azd ai cu config set CU_ENDPOINT "<previous-resource-endpoint>" , anstatt ihn zu entfernen.

Wenn Sie den Endpunkt nur für diese Schnellstartanleitung gespeichert haben, entfernen Sie ihn optional:

azd ai cu config unset CU_ENDPOINT

Referenz:CLI-Konfiguration.

Mit diesem Befehl wird nur die Benutzervorgabe entfernt. Shellvariablen oder -einstellungen in azd-Projektumgebungen werden nicht gelöscht.

Löschen Sie die lokalen Beispiel- und Ergebnisdateien, wenn Sie sie nicht mehr benötigen.

Verwandte Inhalte

  • Zuletzt aktualisiert um