Criar um analisador de Compreensão de Conteúdo

Concluído

Tip

Consulte a guia Texto e imagens para obter mais detalhes!

Na maioria dos cenários, deve considerar criar e testar analisadores usando a interface visual do Content Understanding Studio. No entanto, em alguns casos pode querer criar um analisador submetendo uma definição JSON do esquema dos 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 forma mais simples, um esquema é um conjunto de campos, que podem ser especificados em um documento JSON, como mostrado neste exemplo de uma definição de 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 é baseado 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 espera-se que sejam 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 utiliza para o processamento.

Observação

Este exemplo é deliberadamente simples, com o mínimo de informações necessárias para criar um analisador funcional. Na realidade, o esquema provavelmente incluiria mais campos de diferentes tipos, e a definição do analisador incluiria mais definições de configuração. O JSON pode até incluir um documento de exemplo. Consulte a documentação da API Azure Content Understanding para mais detalhes.

Usar o SDK Python para criar um analisador

Com a definição do analisador definida, pode usar o SDK Python para criar o analisador. A ContentUnderstandingClient classe fornece um begin_create_analyzer método que trata da criação assíncrona por si.

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

Em alternativa, pode usar diretamente a API REST. Os dados JSON são enviados como uma PUT solicitação ao ponto de extremidade com a chave API no cabeçalho da solicitação para dar início à operação de criação do analizador.

A resposta da PUT solicitação 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 GET solicitação.

O seguinte código Python envia um pedido para criar um analisador baseado no conteúdo de um ficheiro chamado card.json (que se assume 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!")