Freigeben über

Erstellen eines benutzerdefinierten Analyzers mithilfe von REST-APIs

Inhaltsverständnisanalyseer definieren, wie Erkenntnisse aus Ihren Inhalten verarbeitet und extrahiert werden. Sie stellen eine einheitliche Verarbeitungs- und Ausgabestruktur für alle Inhalte sicher, sodass Sie zuverlässige und vorhersagbare Ergebnisse erzielen. Bei gängigen Anwendungsfällen können Sie die vorgefertigten Analysatoren verwenden. In diesem Handbuch wird gezeigt, wie Sie diese Analyzer an Ihre Anforderungen anpassen können.

In dieser Anleitung verwenden Sie das Befehlszeilentool cURL. Wenn sie nicht installiert ist, können Sie die entsprechende Version für Ihre Entwicklerumgebung herunterladen .

Voraussetzungen

Stellen Sie zu Beginn sicher, dass Sie über die folgenden Ressourcen und Berechtigungen verfügen:

  • Ein Azure-Abonnement. Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen.
  • Nachdem Sie Ihr Azure-Abonnement erhalten haben, erstellen Sie eine Microsoft Foundry-Ressource im Azure-Portal. Achten Sie darauf, sie in einer unterstützten Region zu erstellen.
    • Das Portal listet diese Ressource unter Foundry>Foundry.
  • Richten Sie Standardmodellbereitstellungen für Ihre Ressource für Inhaltsverständnis ein. Durch das Festlegen von Standardeinstellungen erstellen Sie eine Verbindung zu den Microsoft Foundry-Modellen, die Sie für Inhaltsverständnisanfragen verwenden. Wählen Sie eine der folgenden Methoden:

    1. Wechseln Sie zur Seite "Inhaltsverständniseinstellungen".

    2. Wählen Sie oben links die Schaltfläche "+Ressource hinzufügen " aus.

    3. Wählen Sie die Foundry-Ressource aus, die Sie verwenden möchten, und wählen Sie "Nächstes Speichern">aus.

      Stellen Sie sicher, dass das Kontrollkästchen "Automatische Bereitstellung für erforderliche Modelle aktivieren" aktiviert ist, wenn keine Standardeinstellungen verfügbar sind . Diese Auswahl stellt sicher, dass Ihre Ressource vollständig mit den erforderlichen GPT-4.1, GPT-4.1-miniund text-embedding-3-large Modellen eingerichtet ist. Für unterschiedliche vorkonfigurierte Analysegeräte sind unterschiedliche Modelle erforderlich.

    Indem Sie diese Schritte ausführen, richten Sie eine Verbindung zwischen Inhaltsverständnis- und Foundry-Modellen in Ihrer Foundry-Ressource ein.

Definieren eines Analyseschemas

Zum Erstellen eines benutzerdefinierten Analyzers definieren Sie ein Feldschema, das die strukturierten Daten beschreibt, die Sie extrahieren möchten. Im folgenden Beispiel erstellen Sie einen Analysator basierend auf der vorgefertigten Dokumentenanalyse für die Verarbeitung eines Belegs.

Erstellen Sie eine JSON-Datei mit dem folgenden Inhalt receipt.json.

{
  "description": "Sample receipt analyzer",
  "baseAnalyzerId": "prebuilt-document",
  "models": {
      "completion": "gpt-4.1",
      "embedding": "text-embedding-ada-002"

    },
  "config": {
    "returnDetails": true,
    "enableFormula": false,
    "disableContentFiltering": false,
    "estimateFieldSourceAndConfidence": true,
    "tableFormat": "html"
  },
 "fieldSchema": {
    "fields": {
      "VendorName": {
        "type": "string",
        "method": "extract",
        "description": "Vendor issuing the receipt"
      },
      "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"
            }
          }
        }
      }
    }
  }
}

Wenn Sie über verschiedene Arten von Dokumenten verfügen, die Sie verarbeiten müssen, aber Sie nur die Quittungen kategorisieren und analysieren möchten, erstellen Sie einen Analyzer, der das Dokument zuerst kategorisiert. Leiten Sie sie dann mit dem folgenden Schema an den zuvor erstellten Analyzer weiter.

Erstellen Sie eine JSON-Datei mit dem folgenden Inhalt categorize.json.

{
  "baseAnalyzerId": "prebuilt-document",
  // Use the base analyzer to invoke the document specific capabilities.

  //Specify the model the analyzer should use. This is one of the supported completion models and one of the supported embeddings model. The specific deployment used during analyze is set on the resource or provided in the analyze request.
  "models": {
      "completion": "gpt-4.1",
      "embedding": "text-embedding-ada-002"

    },
  "config": {
    // Enable splitting of the input into segments. Set this property to false if you only expect a single document within the input file. When specified and enableSegment=false, the whole content will be classified into one of the categories.
    "enableSegment": false,

    "contentCategories": {
      // Category name.
      "receipt": {
        // Description to help with classification and splitting.
        "description": "Any images or documents of receipts",

        // Define the analyzer that any content classified as a receipt should be routed to
        "analyzerId": "receipt"
      },

      "invoice": {
        "description": "Any images or documents of invoice",
        "analyzerId": "prebuilt-invoice"
      },
      "policeReport": {
        "description": "A police or law enforcement report detailing the events that lead to the loss."
        // Don't perform analysis for this category.
      }

    },

    // Omit original content object and only return content objects from additional analysis.
    "omitContent": true
  }

  //You can use fieldSchema here to define fields that are needed from the entire input content.

}

Erstellen Sie einen Analyzer

PUT-Anforderung

Erstellen Sie zuerst einen Beleganalysator, und erstellen Sie dann das Kategorisierungswerkzeug.

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

PUT-Antwort

Die 201 Created Antwort enthält einen Operation-Location Header mit einer URL, mit der Sie den Status dieses asynchronen Analyseerstellungsvorgangs nachverfolgen können.

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

Nach Abschluss des Vorgangs gibt ein HTTP-GET auf die URL des Vorgangsorts "status": "succeeded" zurück.

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

Analysieren einer Datei

Übermitteln der Datei

Sie können nun die von Ihnen erstellte benutzerdefinierte Analyse verwenden, um Dateien zu verarbeiten und die felder zu extrahieren, die Sie im Schema definiert haben.

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 Endpunkt- und Schlüsselwerte aus Ihrer Foundry-Instanz im Azure-Portal.
  2. Ersetzen Sie {analyzerId} durch den Namen des benutzerdefinierten Analyzers, den Sie mit der categorize.json Datei erstellt haben.
  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/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png.

POST-Anforderung

In diesem Beispiel wird die benutzerdefinierte Analyse verwendet, die Sie mit der categorize.json Datei erstellt haben, um einen Beleg zu analysieren.

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{analyzerId}:analyze?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs":[
          {
            "url": "https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png"
          }          
        ]
      }'

POST-Antwort

Die 202 Accepted Antwort enthält das {resultId}, das Sie verwenden können, um den Status dieses asynchronen Vorgangs nachzuverfolgen.

{
  "id": {resultId},
  "status": "Running",
  "result": {
    "analyzerId": {analyzerId},
    "apiVersion": "2025-11-01",
    "createdAt": "YYYY-MM-DDTHH:MM:SSZ",
    "warnings": [],
    "contents": []
  }
}

Abrufen des Analyseergebnisses

Verwenden Sie die Operation-Location aus der POST Antwort, um das Ergebnis der Analyse zu erhalten.

GET-Anforderung

curl -i -X GET "{endpoint}/contentunderstanding/analyzerResults/{resultId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

GET-Antwort

Eine 200 OK Antwort enthält ein status Feld, das den Fortschritt des Vorgangs anzeigt.

  • Das status ist Succeeded, wenn der Vorgang erfolgreich abgeschlossen ist.
  • Wenn der Status running oder notStarted lautet, rufen Sie die API erneut manuell auf oder verwenden Sie ein Skript. Warten Sie mindestens eine Sekunde zwischen Anfragen.
Beispielantwort
{
  "id": {resultId},
  "status": "Succeeded",
  "result": {
    "analyzerId": {analyzerId},
    "apiVersion": "2025-11-01",
    "createdAt": "YYYY-MM-DDTHH:MM:SSZ",
    "warnings": [],
    "contents": [
      {
        "path": "input1/segment1",
        "category": "receipt",
        "markdown": "Contoso\n\n123 Main Street\nRedmond, WA 98052\n\n987-654-3210\n\n6/10/2019 13:59\nSales Associate: Paul\n\n\n<table>\n<tr>\n<td>2 Surface Pro 6</td>\n<td>$1,998.00</td>\n</tr>\n<tr>\n<td>3 Surface Pen</td>\n<td>$299.97</td>\n</tr>\n</table> ...",
        "fields": {
          "VendorName": {
            "type": "string",
            "valueString": "Contoso",
            "spans": [{"offset": 0,"length": 7}],
            "confidence": 0.996,
            "source": "D(1,774.0000,72.0000,974.0000,70.0000,974.0000,111.0000,774.0000,113.0000)"
          },
          "Items": {
            "type": "array",
            "valueArray": [
              {
                "type": "object",
                "valueObject": {
                  "Description": {
                    "type": "string",
                    "valueString": "2 Surface Pro 6",
                    "spans": [ { "offset": 115, "length": 15}],
                    "confidence": 0.423,
                    "source": "D(1,704.0000,482.0000,875.0000,482.0000,875.0000,508.0000,704.0000,508.0000)"
                  },
                  "Amount": {
                    "type": "number",
                    "valueNumber": 1998,
                    "spans": [{ "offset": 140,"length": 9}
                    ],
                    "confidence": 0.957,
                    "source": "D(1,952.0000,482.0000,1048.0000,482.0000,1048.0000,508.0000,952.0000,509.0000)"
                  }
                }
              }, ...
            ]
          }
        },
        "kind": "document",
        "startPageNumber": 1,
        "endPageNumber": 1,
        "unit": "pixel",
        "pages": [
          {
            "pageNumber": 1,
            "angle": -0.0944,
            "width": 1743,
            "height": 878
          }
        ],
        "analyzerId": "{analyzerId}",
        "mimeType": "image/png"
      }
    ]
  },
  "usage": {
    "documentPages": 1,
    "tokens": {
      "contextualization": 1000
    }
  }
}

Verwandte Inhalte

  • Last updated on