Een Content Understanding Analyzer maken

Voltooid

Tip

Zie het tabblad Tekst en afbeeldingen voor meer informatie.

In de meeste scenario's moet u overwegen om analyses te maken en te testen met behulp van de visuele interface in Content Understanding Studio. In sommige gevallen wilt u echter een analyse maken door een JSON-definitie van het schema in te dienen voor de gewenste inhoudsvelden naar de API.

Een schema voor een analyse definiëren

Analyzers zijn gebaseerd op schema's waarmee de velden worden gedefinieerd die u wilt extraheren of genereren uit een inhoudsbestand. Op de eenvoudigste wijze is een schema een set velden, die kunnen worden opgegeven in een JSON-document, zoals wordt weergegeven in dit voorbeeld van een analysedefinitie:

{
    "description": "Simple business card",
    "baseAnalyzerId": "prebuilt-document",
    "config": {
        "returnDetails": true
    },
    "fieldSchema": {
        "fields": {
            "ContactName": {
                "type": "string",
                "method": "extract",
                "description": "Name on business card"
            },
            "EmailAddress": {
                "type": "string",
                "method": "extract",
                "description": "Email address on business card"
            }
        }
    },
    "models": {
        "completion": "gpt-4.1",
        "embedding": "text-embedding-3-large"
    }
}

Dit voorbeeld van een aangepast analyseschema is gebaseerd op de vooraf gemaakte documentanalyse en beschrijft twee velden die u zou verwachten op een visitekaartje: ContactName en EmailAddress. Beide velden worden gedefinieerd als gegevenstypen voor tekenreeksen en worden naar verwachting geëxtraheerd uit een document (met andere woorden, de tekenreekswaarden worden verwacht in het document te bestaan, zodat ze kunnen worden 'gelezen'; in plaats van velden te zijn die kunnen worden gegenereerd door informatie over het document op te geven). Het models object specificeert de generatieve modellen die de analyse gebruikt voor verwerking.

Opmerking

Dit voorbeeld is opzettelijk eenvoudig, met de minimale informatie die nodig is om een werkende analyse te maken. In werkelijkheid zou het schema waarschijnlijk meer velden van verschillende typen bevatten en bevat de definitie van de analyse meer configuratie-instellingen. De JSON kan zelfs een voorbeelddocument bevatten. Zie de documentatie van de Azure Content Understanding-API voor meer informatie.

De Python SDK gebruiken om een analyse te maken

Nu uw analysedefinitie is ingesteld, kunt u de Python SDK gebruiken om de analyse te maken. De ContentUnderstandingClient klasse biedt een begin_create_analyzer methode die het proces van asynchrone aanmaak voor u beheert.

from azure.ai.contentunderstanding import ContentUnderstandingClient
from azure.core.credentials import AzureKeyCredential

# Authenticate the client
endpoint = "<YOUR_ENDPOINT>"
credential = AzureKeyCredential("<YOUR_API_KEY>")
client = ContentUnderstandingClient(endpoint=endpoint, credential=credential)

# Define the analyzer
analyzer_name = "business_card_analyser"
analyzer_definition = {
    "description": "Simple business card",
    "baseAnalyzerId": "prebuilt-document",
    "config": {"returnDetails": True},
    "fieldSchema": {
        "fields": {
            "ContactName": {
                "type": "string",
                "method": "extract",
                "description": "Name on business card"
            },
            "EmailAddress": {
                "type": "string",
                "method": "extract",
                "description": "Email address on business card"
            }
        }
    },
    "models": {
        "completion": "gpt-4.1",
        "embedding": "text-embedding-3-large"
    }
}

# Create the analyzer and wait for completion
poller = client.begin_create_analyzer(analyzer_name, body=analyzer_definition)
result = poller.result()
print(f"Analyzer created: {result.analyzer_id}")

De REST API gebruiken om een analyse te maken

U kunt de REST API ook rechtstreeks gebruiken. De JSON-gegevens worden verzonden als een PUT aanvraag naar het eindpunt met de API-sleutel in de aanvraagheader om de bewerking voor het maken van de analyse te starten.

Het antwoord van de PUT aanvraag bevat een Operation-Location in de header, die een callback-URL biedt die u kunt gebruiken om de status van de aanvraag te controleren door een GET aanvraag in te dienen.

Met de volgende Python-code wordt een aanvraag verzonden om een analyse te maken op basis van de inhoud van een bestand met de naam card.json (dat wordt verondersteld de eerder beschreven JSON-definitie te bevatten):

import json
import requests

# Get the business card schema
with open("card.json", "r") as file:
    schema_json = json.load(file)

# Use a PUT request to submit the schema for a new analyzer
analyzer_name = "business_card_analyser"

headers = {
    "Ocp-Apim-Subscription-Key": "<YOUR_API_KEY>",
    "Content-Type": "application/json"}

url = f"{<YOUR_ENDPOINT>}/contentunderstanding/analyzers/{analyzer_name}?api-version=2025-11-01"

response = requests.put(url, headers=headers, data=json.dumps(schema_json))

# Get the response and extract the ID assigned to the operation
callback_url = response.headers["Operation-Location"]

# Use a GET request to check the status of the operation
result_response = requests.get(callback_url, headers=headers)

# Keep polling until the operation is complete
status = result_response.json().get("status")
while status == "Running":
    result_response = requests.get(callback_url, headers=headers)
    status = result_response.json().get("status")

print("Done!")