Créez un analyseur de compréhension de contenu

Effectué

Tip

Pour plus d’informations, consultez l’onglet Texte et images !

Dans la plupart des scénarios, vous devez envisager de créer et de tester des analyseurs à l’aide de l’interface visuelle dans Content Understanding Studio. Toutefois, dans certains cas, vous pouvez créer un analyseur en envoyant une définition JSON du schéma pour vos champs de contenu souhaités à l’API.

Définition d’un schéma pour un analyseur

Les analyseurs sont basés sur des schémas qui définissent les champs que vous souhaitez extraire ou générer à partir d’un fichier de contenu. Au plus simple, un schéma est un ensemble de champs, qui peuvent être spécifiés dans un document JSON, comme illustré dans cet exemple de définition d’analyseur :

{
    "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"
    }
}

Cet exemple de schéma d’analyseur personnalisé est basé sur l’analyseur de documents prédéfini et décrit deux champs que vous prévoyez de trouver sur une carte de visite : ContactName et EmailAddress. Les deux champs sont définis comme des types de données de chaîne et sont censés être extraits d’un document (en d’autres termes, les valeurs de chaîne sont censées exister dans le document afin qu’elles puissent être « lues » ; plutôt que d’être des champs qui peuvent être générés en inférence des informations sur le document). L’objet models spécifie les modèles générateurs que l’analyseur utilise pour le traitement.

Remarque

Cet exemple est délibérément simple, avec les informations minimales nécessaires pour créer un analyseur de travail. En réalité, le schéma inclurait probablement davantage de champs de différents types, et la définition de l’analyseur inclurait plus de paramètres de configuration. Le json peut même inclure un exemple de document. Pour plus d’informations, consultez la documentation de l’API Azure Content Understanding .

Utilisation du Kit de développement logiciel (SDK) Python pour créer un analyseur

Avec votre définition d’analyseur en place, vous pouvez utiliser le Kit de développement logiciel (SDK) Python pour créer l’analyseur. La ContentUnderstandingClient classe fournit une begin_create_analyzer méthode qui gère le processus de création asynchrone pour vous.

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}")

Utilisation de l’API REST pour créer un analyseur

Vous pouvez également utiliser directement l’API REST. Les données JSON sont envoyées en tant que PUT demande au point de terminaison avec la clé API dans l’en-tête de requête pour démarrer l’opération de création de l’analyseur.

La réponse de la PUT requête inclut un Operation-Location dans l’en-tête, qui fournit une URL de rappel que vous pouvez utiliser pour vérifier l’état de la requête en envoyant une GET requête.

Le code Python suivant envoie une demande pour créer un analyseur en fonction du contenu d’un fichier nommé card.json (qui est supposé contenir la définition JSON décrite précédemment) :

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!")