Pular para o conteúdo principal

Desafio 47: Azure Content Understanding — Análise Multimodal

Tempo Estimado

45-60 min | Custo: ~$1,50 (transações AI Services) | Domínio: Mineração e Extração de Conhecimento (15-20%)

Status do Serviço

Azure Content Understanding é uma capacidade mais recente do Azure AI. Consulte a documentação para as versões de API mais recentes e disponibilidade. Este desafio utiliza padrões de API REST alinhados com a interface documentada.

Habilidades do exame cobertas​

HabilidadePeso
Criar um analisador Azure Content UnderstandingAlto
Resumir e classificar documentosAlto
Extrair entidades de documentosMédio
Extrair tabelas e pares chave-valorMédio
Processar imagens e extrair dados estruturadosMédio

Visão geral​

Azure Content Understanding oferece capacidades de análise multimodal que vão além do OCR tradicional e do Document Intelligence:

CapacidadeDescrição
Resumo de documentosGerar resumos concisos de documentos longos
Classificação de documentosClassificar documentos em categorias personalizadas
Extração de entidadesExtrair entidades personalizadas com compreensão LLM
Extração de tabelasExtrair tabelas estruturadas de documentos
Análise de imagensCompreender e descrever conteúdo de imagens
Suporte multi-formatoPDF, imagens, documentos Office, áudio, vídeo

Conceitos-chave​

  • Analisador (Analyzer): Um pipeline configurado que define o que extrair do conteúdo
  • Campo (Field): Uma informação específica a ser extraída (com tipo e descrição)
  • Esquema (Schema): A estrutura de saída esperada para o analisador

Pré-requisitos​

  • Assinatura Azure com função de Contribuidor
  • Recurso Azure AI Services (conta multi-serviço) em uma região suportada
  • Python 3.9+ com biblioteca requests (baseado em REST)
  • .NET 8 com HttpClient
  • Documentos de amostra (PDF, imagens)

Implementação​

Tarefa 1: Criar um recurso Azure AI Services​

RG="rg-ai102-content"
LOCATION="eastus"
AI_SERVICE="ai-content-$(openssl rand -hex 4)"

az group create --name $RG --location $LOCATION

# Create Azure AI Services (multi-service) resource
az cognitiveservices account create \
  --name $AI_SERVICE \
  --resource-group $RG \
  --location $LOCATION \
  --kind AIServices \
  --sku S0 \
  --yes

AI_ENDPOINT=$(az cognitiveservices account show \
  --name $AI_SERVICE --resource-group $RG \
  --query "properties.endpoint" -o tsv)

AI_KEY=$(az cognitiveservices account keys list \
  --name $AI_SERVICE --resource-group $RG \
  --query "key1" -o tsv)

Tarefa 2: Criar um analisador de documentos com campos personalizados​

import requests
import json
import time

endpoint = AI_ENDPOINT.rstrip("/")
api_key = AI_KEY
api_version = "2024-12-01-preview"

# Create an analyzer for extracting invoice data
analyzer_definition = {
    "description": "Invoice analyzer with summarization and entity extraction",
    "scenario": "document",
    "fieldSchema": {
        "fields": {
            "Summary": {
                "type": "string",
                "description": "A brief summary of the document content"
            },
            "DocumentType": {
                "type": "string",
                "description": "The type of document (invoice, receipt, contract, etc.)"
            },
            "VendorName": {
                "type": "string",
                "description": "The name of the vendor or sender"
            },
            "TotalAmount": {
                "type": "number",
                "description": "The total monetary amount"
            },
            "Currency": {
                "type": "string",
                "description": "The currency code (USD, EUR, etc.)"
            },
            "KeyEntities": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "category": {"type": "string"}
                    }
                },
                "description": "Key entities mentioned in the document"
            }
        }
    }
}

# Create the analyzer
analyzer_id = "invoice-analyzer"
url = f"{endpoint}/contentunderstanding/analyzers/{analyzer_id}?api-version={api_version}"

response = requests.put(
    url,
    headers={
        "Ocp-Apim-Subscription-Key": api_key,
        "Content-Type": "application/json"
    },
    json=analyzer_definition
)

if response.status_code in [200, 201]:
    print(f"Analyzer '{analyzer_id}' created successfully")
    print(json.dumps(response.json(), indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")

Tarefa 3: Analisar um documento​

# Submit document for analysis
analyze_url = f"{endpoint}/contentunderstanding/analyzers/{analyzer_id}:analyze?api-version={api_version}"

# Analyze from URL
analyze_request = {
    "url": "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_forms/forms/Invoice_1.pdf"
}

response = requests.post(
    analyze_url,
    headers={
        "Ocp-Apim-Subscription-Key": api_key,
        "Content-Type": "application/json"
    },
    json=analyze_request
)

if response.status_code == 202:
    operation_url = response.headers["Operation-Location"]
    print(f"Analysis started. Polling: {operation_url}")

    # Poll for results
    while True:
        time.sleep(5)
        poll_response = requests.get(
            operation_url,
            headers={"Ocp-Apim-Subscription-Key": api_key}
        )
        status_data = poll_response.json()
        status = status_data.get("status", "unknown")
        print(f"  Status: {status}")

        if status == "succeeded":
            result = status_data.get("result", {})
            print("\n=== Analysis Results ===")
            contents = result.get("contents", [])
            for content in contents:
                fields = content.get("fields", {})
                for field_name, field_data in fields.items():
                    value = field_data.get("value", "N/A")
                    confidence = field_data.get("confidence", 0)
                    print(f"  {field_name}: {value} (confidence: {confidence:.2%})")
            break
        elif status == "failed":
            print(f"Analysis failed: {status_data}")
            break
else:
    print(f"Error: {response.status_code} - {response.text}")

Tarefa 4: Criar um analisador de imagens​

# Create analyzer for image content
image_analyzer = {
    "description": "Image content analyzer for product photos",
    "scenario": "image",
    "fieldSchema": {
        "fields": {
            "Description": {
                "type": "string",
                "description": "Detailed description of the image content"
            },
            "ObjectsDetected": {
                "type": "array",
                "items": {"type": "string"},
                "description": "List of objects visible in the image"
            },
            "DominantColors": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Dominant colors in the image"
            },
            "TextContent": {
                "type": "string",
                "description": "Any text visible in the image"
            }
        }
    }
}

img_analyzer_id = "image-analyzer"
url = f"{endpoint}/contentunderstanding/analyzers/{img_analyzer_id}?api-version={api_version}"

response = requests.put(
    url,
    headers={
        "Ocp-Apim-Subscription-Key": api_key,
        "Content-Type": "application/json"
    },
    json=image_analyzer
)
print(f"Image analyzer created: {response.status_code}")

Tarefa 5: Gerenciar analisadores (listar, obter, excluir)​

# List all analyzers
list_url = f"{endpoint}/contentunderstanding/analyzers?api-version={api_version}"
response = requests.get(list_url, headers={"Ocp-Apim-Subscription-Key": api_key})
analyzers = response.json().get("value", [])
print("Analyzers:")
for a in analyzers:
    print(f"  - {a['analyzerId']}: {a.get('description', 'N/A')}")

# Get analyzer details
get_url = f"{endpoint}/contentunderstanding/analyzers/{analyzer_id}?api-version={api_version}"
response = requests.get(get_url, headers={"Ocp-Apim-Subscription-Key": api_key})
print(f"\nAnalyzer details: {json.dumps(response.json(), indent=2)}")

# Delete an analyzer
delete_url = f"{endpoint}/contentunderstanding/analyzers/{analyzer_id}?api-version={api_version}"
response = requests.delete(delete_url, headers={"Ocp-Apim-Subscription-Key": api_key})
print(f"Delete status: {response.status_code}")

Saída Esperada​

{
  "status": "succeeded",
  "result": {
    "contents": [
      {
        "fields": {
          "Summary": {
            "value": "Invoice #INV-001 from Contoso Ltd for consulting services totaling $3,800.00 USD, due February 15, 2024.",
            "confidence": 0.92
          },
          "DocumentType": {
            "value": "invoice",
            "confidence": 0.98
          },
          "VendorName": {
            "value": "Contoso Ltd",
            "confidence": 0.95
          },
          "TotalAmount": {
            "value": 3800.00,
            "confidence": 0.93
          },
          "Currency": {
            "value": "USD",
            "confidence": 0.97
          }
        }
      }
    ]
  }
}

Quebra & conserta​

#CenárioSintomaCausa RaizCorreção
1Criação do analisador falhaHTTP 400 com erro de validação de esquemaTipo de campo inválido (ex: usando "int" em vez de "number")Use tipos suportados: string, number, boolean, array, object
2Análise retorna baixa confiançaCampos extraídos com < 50% de confiançaDescrição do campo é muito vaga para o modelo de IAEscreva descrições de campo mais específicas que orientem a extração
3"Resource not found" na análiseHTTP 404ID do analisador digitado incorretamente ou região não suporta Content UnderstandingVerifique o ID do analisador e confira a disponibilidade regional
4Timeout em documentos grandesOperação nunca completaDocumento excede os limites de tamanhoVerifique os limites de tamanho de arquivo; divida documentos grandes
5Resultados vazios para imagemTodos os campos retornam nullUsando cenário "document" para conteúdo de imagemUse o cenário "image" para arquivos de imagem

Verificação de Conhecimento​

1. Você precisa extrair campos personalizados de documentos onde o esquema muda por cliente. Qual serviço do Azure permite definir campos de extração com descrições em linguagem natural?

2. Qual é a principal diferença entre o Azure Content Understanding e o Azure Document Intelligence para processamento de documentos?

3. Você cria um analisador Content Understanding com cenário 'document'. Um usuário envia um arquivo de imagem. O que acontece?

4. Como o Content Understanding determina quais dados extrair de um documento?

5. Qual código de status HTTP indica que a operação de análise foi aceita e está processando de forma assíncrona?

Limpeza​

az group delete --name rg-ai102-content --yes --no-wait

Saiba Mais​