Criar um analisador de Compreensão de Conteúdo

Na maioria dos cenários, você deve considerar a criação e o teste de analisadores usando a interface visual no Content Understanding Studio. No entanto, em alguns casos, talvez você queira criar um analisador enviando uma definição JSON do esquema para os campos de conteúdo desejados para a API.

Definindo um esquema para um analisador

Os analisadores são baseados em esquemas que definem os campos que você deseja extrair ou gerar de um arquivo de conteúdo. Em sua mais simples, um esquema é um conjunto de campos, que pode ser especificado em um documento JSON, conforme mostrado neste exemplo de uma definição do analisador:

{
    "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 exemplo de um esquema de analisador personalizado baseia-se no analisador de documentos pré-criado e descreve dois campos que você esperaria encontrar em um cartão de visita: ContactName e EmailAddress. Ambos os campos são definidos como tipos de dados de cadeia de caracteres e devem ser extraídos de um documento (em outras palavras, espera-se que os valores de cadeia de caracteres existam no documento para que possam ser "lidos"; em vez de serem campos que podem ser gerados inferindo informações sobre o documento). O models objeto especifica os modelos generativos que o analisador usa para processamento.

Usando o SDK do Python para criar um analisador

Com a definição do analisador em vigor, você pode usar o SDK do Python para criar o analisador. A ContentUnderstandingClient classe fornece um begin_create_analyzer método que manipula o processo de criação assíncrona para você.

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

Usando a API REST para criar um analisador

Como alternativa, você pode usar a API REST diretamente. Os dados JSON são enviados como uma PUT solicitação para o endpoint com a API key no cabeçalho da solicitação para iniciar a operação de criação do analisador.

A resposta da solicitação PUT inclui um Operation-Location no cabeçalho, que fornece uma URL de retorno de chamada que você pode usar para verificar o status da solicitação enviando uma solicitação GET.

O código Python a seguir envia uma solicitação para criar um analisador com base no conteúdo de um arquivo chamado card.json (que se supõe conter a definição 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!")