Crear un analizador de comprensión de contenidos

En la mayoría de los escenarios, debe considerar la posibilidad de crear y probar analizadores mediante la interfaz visual de Content Understanding Studio. Sin embargo, en algunos casos es posible que desee crear un analizador mediante el envío de una definición JSON del esquema para los campos de contenido deseados a la API.

Definición de un esquema para un analizador

Los analizadores se basan en esquemas que definen los campos que desea extraer o generar a partir de un archivo de contenido. En su forma más sencilla, un esquema es un conjunto de campos, que se pueden especificar en un documento JSON, como se muestra en este ejemplo de una definición de analizador:

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

Este ejemplo de un esquema de analizador personalizado se basa en el analizador de documentos pregenerado y describe dos campos que espera encontrar en una tarjeta de presentación: ContactName y EmailAddress. Ambos campos se definen como tipos de datos de cadena y se espera que se extraigan de un documento (es decir, se espera que los valores de cadena existan en el documento para que se puedan "leer"; en lugar de ser campos que se pueden generar inferiendo información sobre el documento). El models objeto especifica los modelos generativos que usa el analizador para su procesamiento.

Uso del SDK de Python para crear un analizador

Con la definición del analizador en su lugar, puede usar el SDK de Python para crear el analizador. La ContentUnderstandingClient clase proporciona un método begin_create_analyzer que se encarga por ti del proceso de creación asincrónica.

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

Uso de la API REST para crear un analizador

Como alternativa, puede usar la API REST directamente. Los datos JSON se envían como una PUT solicitud al punto de conexión con la clave de API en el encabezado de solicitud para iniciar la operación de creación del analizador.

La respuesta de la solicitud PUT incluye una ubicación-operación en el encabezado, que proporciona una dirección URL de devolución de llamada que puede usar para comprobar el estado de la solicitud mediante el envío de una solicitud GET.

El código de Python siguiente envía una solicitud para crear un analizador basado en el contenido de un archivo denominado card.json (que se supone que contiene la definición JSON descrita anteriormente):

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