Freigeben über

Schnellstart: Azure KI Content Understanding-REST-APIs

  • Artikel

  • Beginnen Sie mit der Verwendung der neuesten Vorschauversion der Azure KI Content Understanding-REST-API (2024-12-01-preview).

  • Azure KI Content Understanding ist ein neuer Azure KI-Dienst, der auf generativer KI basiert und Dateien jeder Modalität (Dokumente, Bilder, Videos und Audio) analysiert und eine strukturierte Ausgabe in Formaten mit benutzerdefinierten Feldern extrahiert.

  • Integrieren Sie den Content Understanding-Dienst einfach in Ihre Workflows und Anwendungen, indem Sie die REST-APIs aufrufen.

  • In diesem Schnellstart werden Sie durch die Verwendung der Content Understanding-REST-API für das Erstellen eines benutzerdefinierten Analysetools und das Extrahieren von Inhalten und Feldern aus Ihrer Eingabe geführt.

Voraussetzungen

Für den Einstieg benötigen Sie ein aktives Azure-Abonnement. Falls Sie über kein Azure-Konto verfügen, können Sie ein kostenloses Abonnement erstellen.

  • Wenn Sie Ihr Azure-Abonnement haben, erstellen Sie im Azure-Portal eine Azure KI Services-Ressource. Diese Ressource für mehrere Dienste ermöglicht den Zugriff auf verschiedene Azure KI Services mit einem einzigen Satz von Anmeldeinformationen.

    • Diese Ressource wird im Portal unter „Azure KI Services“ → „Azure KI Services“ aufgeführt.

      Wichtig

      Azure stellt mehrere Ressourcentypen namens Azure KI Services bereit. Wählen Sie unbedingt die unter „Azure KI Services“ → „Azure KI Services“ aufgeführte Ressource wie in der folgenden Abbildung gezeigt aus. Weitere Informationen finden Sie unter Erstellen einer Azure KI Services-Ressource.

      Screenshot der Seite der Ressource für mehrere Dienste im Azure-Portal

  • In diesem Schnellstart verwenden Sie das Befehlszeilentool cURL. Wenn es nicht installiert ist, können Sie eine Version für Ihre Entwicklungsumgebung herunterladen:

Erstellen eines benutzerdefinierten Analysetools

Zum Erstellen eines benutzerdefinierten Analysetools müssen Sie ein Feldschema definieren, das die strukturierten Daten beschreibt, die Sie extrahieren möchten. Im folgenden Beispiel wird ein Schema zum Extrahieren grundlegender Informationen aus einem Rechnungsdokument definiert.

Erstellen Sie zunächst eine JSON-Datei mit dem Namen request_body.json und dem folgenden Inhalt:

{
  "description": "Sample invoice analyzer",
  "scenario": "document",
  "config": {
    "returnDetails": true
  },
  "fieldSchema": {
    "fields": {
      "VendorName": {
        "type": "string",
        "method": "extract",
        "description": "Vendor issuing the invoice"
      },
      "Items": {
        "type": "array",
        "method": "extract",
        "items": {
          "type": "object",
          "properties": {
            "Description": {
              "type": "string",
              "method": "extract",
              "description": "Description of the item"
            },
            "Amount": {
              "type": "number",
              "method": "extract",
              "description": "Amount of the item"
            }
          }
        }
      }
    }
  }
}

Nehmen Sie vor dem Ausführen der folgenden cURL-Befehle die folgenden Änderungen an der HTTP-Anforderung vor:

  1. Ersetzen Sie {endpoint} und {key} durch die Werte für Endpunkt und Schlüssel aus Ihrer Azure KI Services-Instanz im Azure-Portal.
  2. Ersetzen Sie {analyzerId} durch den Namen des neuen Analysetools, z. B. myInvoice.

PUT-Anforderung

curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d @request_body.json

PUT-Antwort

Die Antwort 201 (Created) enthält einen Operation-Location-Header mit einer URL, über die Sie den Status dieses asynchronen Erstellungsvorgangs nachverfolgen können.

201 Created
Operation-Location: {endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2024-12-01-preview

Wenn Sie nach dem Abschluss HTTP GET mit der URL ausführen, wird "status": "succeeded" zurückgegeben.

curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Analysieren einer Datei

Sie können Dateien mithilfe des erstellten benutzerdefinierten Analysetools analysieren, um die im Schema definierten Felder zu extrahieren.

Nehmen Sie vor dem Ausführen des cURL-Befehls die folgenden Änderungen an der HTTP-Anforderung vor:

  1. Ersetzen Sie {endpoint} und {key} durch die Werte für Endpunkt und Schlüssel aus Ihrer Azure KI Services-Instanz im Azure-Portal.
  2. Ersetzen Sie {analyzerId} durch den Namen des zuvor erstellten benutzerdefinierten Analysetools.
  3. Ersetzen Sie {fileUrl} durch eine öffentlich zugängliche URL der zu analysierenden Datei, z. B. einen Pfad zu einer Azure Storage Blob-Instanz mit einer SAS (Shared Access Signature) oder zur Beispiel-URL https://github.com/Azure-Samples/cognitive-services-REST-api-samples/raw/master/curl/form-recognizer/rest-api/invoice.pdf.

POST-Anforderung

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{analyzerId}:analyze?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"{fileUrl}\"}"

POST-Antwort

Die Antwort 202 (Accepted) enthält einen Operation-Location-Header mit einer URL, über die Sie den Status dieses asynchronen Analysevorgangs nachverfolgen können.

202 Accepted
Operation-Location: {endpoint}/contentunderstanding/analyzers/{analyzerId}/results/{resultId}?api-version=2024-12-01-preview

Abrufen des Analyseergebnisses

Verwenden Sie die resultId aus dem zurückgegebenen Operation-Location-Header der vorherigen POST-Antwort, und rufen Sie das Ergebnis der Analyse ab.

  1. Ersetzen Sie {endpoint} und {key} durch die Werte für Endpunkt und Schlüssel aus Ihrer Azure KI Services-Instanz im Azure-Portal.
  2. Ersetzen Sie {analyzerId} durch den Namen des zuvor erstellten benutzerdefinierten Analysetools.
  3. Ersetzen Sie {resultId} durch die von der POST-Anforderung zurückgegebenen resultId.

GET-Anforderung

curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{analyzerId}/results/{resultId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}"

GET-Antwort

Die JSON-Antwort 200 (OK) enthält ein Feld status, das den Status des Vorgangs angibt. Wenn der Vorgang nicht abgeschlossen ist, lautet der Wert von status entweder running oder notStarted. In solchen Fällen sollten Sie die API erneut aufrufen – entweder manuell oder über ein Skript. Warten Sie zwischen den Aufrufen mindestens eine Sekunde.

Beispiel für eine Antwort

{
  "id": "bcf8c7c7-03ab-4204-b22c-2b34203ef5db",
  "status": "Succeeded",
  "result": {
    "analyzerId": "sample_invoice_analyzer",
    "apiVersion": "2024-12-01-preview",
    "createdAt": "2024-11-13T07:15:46Z",
    "warnings": [],
    "contents": [
      {
        "markdown": "CONTOSO LTD.\n\n\n# INVOICE\n\nContoso Headquarters...",
        "fields": {
          "VendorName": {
            "type": "string",
            "valueString": "CONTOSO LTD.",
            "spans": [ { "offset": 0, "length": 12 } ],
            "confidence": 0.941,
            "source": "D(1,0.5729,0.6582,2.3353,0.6582,2.3353,0.8957,0.5729,0.8957)"
          },
          "Items": {
            "type": "array",
            "valueArray": [
              {
                "type": "object",
                "valueObject": {
                  "Description": {
                    "type": "string",
                    "valueString": "Consulting Services",
                    "spans": [ { "offset": 909, "length": 19 } ],
                    "confidence": 0.971,
                    "source": "D(1,2.3264,5.673,3.6413,5.673,3.6413,5.8402,2.3264,5.8402)"
                  },
                  "Amount": {
                    "type": "number",
                    "valueNumber": 60,
                    "spans": [ { "offset": 995, "length": 6 } ],
                    "confidence": 0.989,
                    "source": "D(1,7.4507,5.6684,7.9245,5.6684,7.9245,5.8323,7.4507,5.8323)"
                  }
                }
              }, ...
            ]
          }
        },
        "kind": "document",
        "startPageNumber": 1,
        "endPageNumber": 1,
        "unit": "inch",
        "pages": [
          {
            "pageNumber": 1,
            "angle": -0.0039,
            "width": 8.5,
            "height": 11,
            "spans": [ { "offset": 0, "length": 1650 } ],
            "words": [
              {
                "content": "CONTOSO",
                "span": { "offset": 0, "length": 7 },
                "confidence": 0.997,
                "source": "D(1,0.5739,0.6582,1.7446,0.6595,1.7434,0.8952,0.5729,0.8915)"
              }, ...
            ],
            "lines": [
              {
                "content": "CONTOSO LTD.",
                "source": "D(1,0.5734,0.6563,2.335,0.6601,2.3345,0.8933,0.5729,0.8895)",
                "span": { "offset": 0, "length": 12 }
              }, ...
            ]
          }
        ],
        "paragraphs": [
          {
            "content": "CONTOSO LTD.",
            "source": "D(1,0.5734,0.6563,2.335,0.6601,2.3345,0.8933,0.5729,0.8895)",
            "span": { "offset": 0, "length": 12 }
          }, ...
        ],
        "sections": [
          {
            "span": { "offset": 0, "length": 1649 },
            "elements": [ "/sections/1", "/sections/2" ]
          },
          {
            "span": { "offset": 0, "length": 12 },
            "elements": [ "/paragraphs/0" ]
          }, ...
        ],
        "tables": [
          {
            "rowCount": 2,
            "columnCount": 6,
            "cells": [
              {
                "kind": "columnHeader",
                "rowIndex": 0,
                "columnIndex": 0,
                "rowSpan": 1,
                "columnSpan": 1,
                "content": "SALESPERSON",
                "source": "D(1,0.5389,4.5514,1.7505,4.5514,1.7505,4.8364,0.5389,4.8364)",
                "span": { "offset": 512, "length": 11 },
                "elements": [ "/paragraphs/19" ]
              }, ...
            ],
            "source": "D(1,0.4885,4.5543,8.0163,4.5539,8.015,5.1207,0.4879,5.1209)",
            "span": { "offset": 495, "length": 228 }
          }, ...
        ]
      }
    ]
  }
}

Nächste Schritte

  • In diesem Schnellstart haben Sie erfahren, wie Sie die REST-API aufrufen, um ein benutzerdefiniertes Analysetool zu erstellen. Für ein besseres Benutzererlebnis können Sie das Azure KI Foundry-Portal ausprobieren.