Unterstützung nativer Dokumente für Azure KI Language (Vorschau)

  • Artikel

Wichtig

  • Die Unterstützung nativer Dokumente ist eine beschränkte Vorschauversion. Um den Zugriff auf das Feature zur Unterstützung nativer Dokumente anzufordern, füllen Sie das Formular zum Beantragen des Zugriffs auf Sprachdienstvorschauen aus, und übermitteln Sie es.

  • Öffentliche Vorschaureleases von Azure KI Language bieten frühzeitigen Zugriff auf Features, die sich in der aktiven Entwicklung befinden.

  • Features, Ansätze und Prozesse können sich aufgrund von Benutzerfeedback vor der allgemeinen Verfügbarkeit (General Availability, GA) ändern.

Azure KI Language ist ein cloudbasierter Dienst, der Features zur linguistischen Datenverarbeitung (Natural Language Processing, NLP) auf textbasierte Daten anwendet. Mit der Funktion zur Unterstützung nativer Dokumente können Sie API-Anforderungen asynchron senden, indem Sie einen HTTP POST-Anforderungstext verwenden, um Ihre Daten und die HTTP GET-Anforderungsabfragezeichenfolge zum Abrufen der Statusergebnisse zu senden. Ihre verarbeiteten Dokumente befinden sich in Ihrem Azure Blob Storage-Zielcontainer.

Ein natives Dokument bezieht sich auf das Dateiformat, das zur Erstellung des Originaldokuments verwendet wurde, z. B. Microsoft Word (docx) oder eine portierbare Dokumentdatei (pdf). Durch die Unterstützung nativer Dokumente ist vor der Verwendung von Azure KI Language-Ressourcen keine Textvorverarbeitung mehr erforderlich. Derzeit steht die Unterstützung nativer Dokumente für die folgenden Funktionen zur Verfügung:

  • Personenbezogene Informationen (Personally Identifiable Information, PII). Die PII-Erkennungsfunktion kann vertrauliche Informationen in unstrukturiertem Text identifizieren, kategorisieren und unkenntlich machen. Die PiiEntityRecognition-API unterstützt die Verarbeitung nativer Dokumente.

  • Dokumentzusammenfassung. Die Dokumentzusammenfassung verwendet linguistische Datenverarbeitung, um extraktive (Extraktion wichtiger Sätze) oder abstrahierende (kontextbezogene Wortextraktion) Zusammenfassungen für Dokumente zu generieren. Sowohl AbstractiveSummarization- als auch ExtractiveSummarization-APIs unterstützen die Verarbeitung nativer Dokumente.

Unterstützte Dokumentformate

Anwendungen verwenden native Dateiformate, um native Dokumente zu erstellen, zu speichern oder zu öffnen. Derzeit unterstützen Funktionen für personenbezogene Informationen und Dokumentzusammenfassung die folgenden nativen Dokumentformate:

Dateityp Dateierweiterung Beschreibung
Text .txt Ein unformatiertes Textdokument.
Adobe PDF .pdf Ein als portierbare Dokumentdatei formatiertes Dokument
Microsoft Word .docx Eine Microsoft Word-Dokumentdatei

Eingaberichtlinien

Unterstützte Dateiformate

Typ Unterstützung und Einschränkungen
PDFs Vollständig gescannte PDF-Dateien werden nicht unterstützt.
Text in Bildern Digitale Bilder mit eingebetteten Text werden nicht unterstützt.
Digitale Tabellen Tabellen in gescannten Dokumenten werden nicht unterstützt.

Dokumentgröße

attribute Eingabebegrenzung
Gesamtanzahl von Dokumenten pro Anforderung ≤ 20
Gesamtgröße des Inhalts pro Anforderung ≤ 1 MB

Einschließen nativer Dokumente in eine HTTP-Anforderung

Fangen wir an:

  • Für dieses Projekt verwenden wir das Befehlszeilentool cURL, um REST-API-Aufrufe auszuführen.

    Hinweis

    Das cURL-Paket ist in den meisten Windows 10- und Windows 11-Versionen sowie den meisten macOS- und Linux-Distributionen vorinstalliert. Sie können die Paketversion mithilfe der folgenden Befehle überprüfen: Windows: curl.exe -V, macOS: curl -V, Linux: curl --version

  • Wenn cURL nicht installiert ist, finden Sie hier Installationslinks für Ihre Plattform:

  • Ein aktives Azure-Konto. Falls Sie noch kein Konto haben, können Sie ein kostenloses Konto erstellen.

  • Ein Azure Blob Storage-Konto. Für Ihre Quell- und Zieldateien müssen Sie in Ihrem Azure Blob Storage-Konto auch Container erstellen:

    • Quellcontainer: In diesen Container laden Sie Ihre nativen Dateien für die Analyse hoch (erforderlich).
    • Zielcontainer: In diesem Container werden Ihre analysierten Dateien gespeichert (erforderlich).

  • Eine Sprachressource in Form eines einzelnen Diensts (keine Azure KI Services-Ressource mit mehreren Diensten)

    Füllen Sie die Felder für das Sprachressourcenprojekt für Instanzdetails wie folgt aus:

    1. Abonnement. Wählen Sie eines Ihrer verfügbaren Azure-Abonnements aus.

    2. Ressourcengruppe: Sie können eine neue Ressourcengruppe erstellen oder Ihre Ressource zu einer bereits vorhandenen Ressourcengruppe hinzufügen, die denselben Lebenszyklus, dieselben Berechtigungen und dieselben Richtlinien aufweist.

    3. Ressourcenregion: Wählen Sie die Option Global aus, es sei denn, Ihr Unternehmen oder Ihre Anwendung erfordert eine spezifische Region. Wenn Sie planen, eine systemseitig zugewiesene verwaltete Identität (RBAC) für die Authentifizierung zu verwenden, wählen Sie eine geografische Region aus, z. B. USA, Westen.

    4. Name: Geben Sie den Namen ein, den Sie für Ihre Ressource ausgewählt haben. Der ausgewählte Name muss innerhalb von Azure eindeutig sein.

    5. Tarif: Sie können den kostenlosen Tarif (Free F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

    6. Klicken Sie auf Überprüfen + erstellen.

    7. Lesen Sie die Nutzungsbedingungen, und klicken Sie auf Erstellen, um Ihre Ressource bereitzustellen.

    8. Nachdem die Ressource erfolgreich bereitgestellt wurde, wählen Sie Zu Ressource wechseln aus.

Abrufen des Schlüssels und des Sprachdienstendpunkts

Für Anforderungen an den Sprachdienst benötigen Sie einen schreibgeschützten Schlüssel und einen benutzerdefinierten Endpunkt zur Authentifizierung des Zugriffs.

  1. Wählen Sie Zu Ressource wechseln aus, nachdem eine von Ihnen erstellte neue Ressource bereitgestellt wurde. Navigieren Sie direkt zu Ihrer Ressourcenseite, falls Sie über eine vorhandene Sprachdienstressource für die Formularerkennung verfügen.

  2. Klicken Sie in der linken Schiene unter Ressourcenverwaltung auf Schlüssel und Endpunkt.

  3. Sie können key und language service instance endpoint kopieren und in die Codebeispiele einfügen, um Ihre Anforderung an den Sprachdienst zu authentifizieren. Für einen API-Aufruf ist nur ein Schlüssel erforderlich.

Erstellen von Azure Blob Storage-Containern

Erstellen Sie Container in Ihrem Azure Blob Storage-Konto für Quell- und Zieldateien.

  • Quellcontainer: In diesen Container laden Sie Ihre nativen Dateien für die Analyse hoch (erforderlich).
  • Zielcontainer: In diesem Container werden Ihre analysierten Dateien gespeichert (erforderlich).

Authentifizierung

Ihrer Sprachressource muss Zugriff auf Ihr Speicherkonto gewährt werden, damit Blobs erstellt, gelesen oder gelöscht werden können. Es gibt zwei primäre Methoden, mit denen Sie Zugriff auf Ihre Speicherdaten gewähren können:

Für dieses Projekt authentifizieren wir den Zugriff auf die source location- und target location-URLs mit SAS-Token (Shared Access Signature), die als Abfragezeichenfolgen angefügt werden. Jedem Token wird ein bestimmtes Blob (Datei) zugewiesen.

Screenshot: Speicher-URL mit angehängtem SAS-Token

  • Ihr Quellcontainer oder Blob muss über Zugriff vom Typ Lesen und Auflisten verfügen.
  • Ihr Zielcontainer oder Blob muss über Zugriff vom Typ Schreiben und Auflisten verfügen.

Tipp

Da wir eine einzelne Datei (Blob) verarbeiten, wird empfohlen wir, den SAS-Zugriff auf Blobebene zu delegieren.

Anforderungsheader und -parameter

parameter Beschreibung
-X POST <endpoint> Gibt Ihren Sprachressourcenendpunkt für den Zugriff auf die API an.
--header Content-Type: application/json Der Inhaltstyp zum Senden von JSON-Daten
--header "Ocp-Apim-Subscription-Key:<key> Gibt den Sprachressourcenschlüssel für den Zugriff auf die API an
-data Die JSON-Datei mit den Daten, die Sie mit Ihrer Anforderung übergeben möchten.

Die folgenden cURL-Befehle werden über eine Bash-Shell ausgeführt. Fügen Sie in diese Befehle Ihren Ressourcennamen und Ressourcenschlüssel sowie Ihre JSON-Werte ein. Versuchen Sie, native Dokumente zu analysieren, indem Sie das Codebeispielprojekt Personally Identifiable Information (PII) oder Document Summarization auswählen:

Beispieldokument für personenbezogene Informationen

Für diesen Schnellstart benötigen Sie ein Quelldokument, das in Ihren Quellcontainer hochgeladen wurde. Sie können unser Microsoft Word-Beispieldokument oder Adobe PDF für dieses Projekt herunterladen. Die Quellsprache ist Englisch.

Erstellen der POST-Anforderung

  1. Erstellen Sie mit Ihrem bevorzugten Editor oder Ihrer bevorzugten IDE ein neues Verzeichnis namens native-document für Ihre App.

  2. Erstellen Sie in Ihrem Verzeichnis namens native-document eine neue JSON-Datei namens pii-detection.json.

  3. Kopieren Sie das folgende Anforderungsbeispiel für personenbezogenen Informationen, und fügen Sie es in Ihre pii-detection.json-Datei ein. Ersetzen Sie {your-source-container-SAS-URL} und {your-target-container-SAS-URL} durch die Werte Ihrer Speicherkontocontainer-Instanz aus dem Azure-Portal:

Anforderungsbeispiel

{
    "displayName": "Extracting Location & US Region",
    "analysisInput": {
        "documents": [
            {
                "language": "en-US",
                "id": "Output-excel-file",
                "source": {
                    "location": "{your-source-blob-with-SAS-URL}"
                },
                "target": {
                    "location": "{your-target-container-with-SAS-URL}"
                }
            } 
        ]
    },
    "tasks": [
        {
            "kind": "PiiEntityRecognition",
            "parameters":{
                "excludePiiCategories" : ["PersonType", "Category2", "Category3"],
                "redactionPolicy": "UseRedactionCharacterWithRefId" 
            }
        }
    ]
}

  • Der Quellwert location ist die SAS-URL für das Quelldokument (Blob)und nicht die SAS-URL des Quellcontainers.

  • Die für redactionPolicy möglichen Wert sind UseRedactionCharacterWithRefId (Standard) oder UseEntityTypeName. Weitere Informationen finden Sie unter PiiTask-Parameter.

Ausführen der POST-Anforderung

  1. Dies ist die vorläufige Struktur der POST-Anforderung:

       POST {your-language-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview

  2. Ersetzen Sie vor dem Ausführen der POST-Anforderung {your-language-resource-endpoint} und {your-key} durch die Werte Ihrer Sprachdienstinstanz aus dem Azure-Portal.

    Wichtig

    Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. Verwenden Sie für die Produktion eine sichere Art der Speicherung und des Zugriffs auf Ihre Anmeldeinformationen wie Azure Key Vault. Weitere Informationen finden Sie unter Azure KI Services-Sicherheit.

    PowerShell

       cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

    Eingabeaufforderung/Terminal

       curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

  3. Hier sehen Sie eine Beispielantwort:

    HTTP/1.1 202 Accepted
Content-Length: 0
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2023-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: West US 2
Date: Thu, 25 Jan 2024 15:12:32 GMT

POST-Antwort (jobId)

Sie erhalten eine Antwort vom Typ 202 (Erfolg), die einen schreibgeschützten Operation-Location-Header enthält. Der Wert dieses Headers enthält eine jobId, die abgefragt werden kann, um den Status des asynchronen Vorgangs und die Ergebnisse mithilfe einer GET-Anforderung abzurufen:

Screenshot mit dem Wert von „operation-location“ in der POST-Antwort

Abrufen von Analyseergebnissen (GET-Anforderung)

  1. Nach der erfolgreichen POST-Anforderung können Sie den in der POST-Anforderung zurückgegebenen Operation-Location-Header abfragen, um die verarbeiteten Daten anzuzeigen.

  2. Dies ist die vorläufige Struktur der GET-Anforderung:

      GET {your-language-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview

  3. Nehmen Sie die folgenden Änderungen vor, bevor Sie den Befehl ausführen:

    • Ersetzen Sie {jobId} durch den Operation-Location-Header aus der POST-Antwort.

    • Ersetzen Sie {your-language-resource-endpoint} und {your-key} durch die Werte aus Ihrer Sprachdienstinstanz im Azure-Portal.

Get-Anforderung

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

    curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

Untersuchen der Antwort

Sie erhalten die Antwort vom Typ 200 (Erfolg) mit einer JSON-Ausgabe. Das erste Feld Status gibt das Ergebnis des Vorgangs an. Wenn der Vorgang nicht abgeschlossen ist, ist der Wert von Status entweder „running“ oder „notStarted“, und Sie müssen die API entweder manuell oder über ein Skript erneut aufrufen. Ein Intervall von mindestens einer Sekunde zwischen den Aufrufen wird empfohlen.

Beispiel für eine Antwort

{
  "jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
  "lastUpdatedDateTime": "2024-01-24T13:17:58Z",
  "createdDateTime": "2024-01-24T13:17:47Z",
  "expirationDateTime": "2024-01-25T13:17:47Z",
  "status": "succeeded",
  "errors": [],
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "PiiEntityRecognitionLROResults",
        "lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "doc_0",
              "source": {
                "kind": "AzureBlob",
                "location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.result.json"
                },
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.docx"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-09-01"
        }
      }
    ]
  }
}

Nach erfolgreichem Abschluss:

  • Die analysierten Dokumente befinden sich in Ihrem Zielcontainer.
  • Bei erfolgreicher Ausführung gibt die POST-Methode den Antwortcode 202 Accepted zurück, der anzeigt, dass die Batch-Anforderung vom Dienst erstellt wurde.
  • Die POST-Anfrage hat auch Antwortheader zurückgegeben, unter anderem Operation-Location. Dieser Header stellt einen Wert bereit, der in nachfolgenden GET-Anforderungen verwendet wird.

Bereinigen von Ressourcen

Wenn Sie ein Azure KI Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind.

Nächste Schritte

Übersicht über Erkennung personenbezogener Informationen Übersicht über die Dokumentzusammenfassung