Classifique e encaminhe os seus dados usando o Content Understanding

O Content Understanding permite-lhe criar fluxos de trabalho personalizados de classificação que categorizam o seu conteúdo e o encaminham para o analisador certo. Com o roteamento, pode enviar múltiplos fluxos de dados pelo mesmo pipeline e garantir que os seus dados sejam processados pelo melhor analisador para o seu tipo de dados.

Este guia guia-o por dois passos:

Crie um classificador básico que categorize os documentos em categorias personalizadas.
Classificar e encaminhar com analisadores personalizados que combinam classificação com extração em campo para cada categoria.

Pré-requisitos

Para começar, certifique-se de que possui os seguintes recursos e permissões:

Uma subscrição do Azure. Se não tiver uma subscrição Azure, crie uma conta gratuita.
Um recurso Microsoft Foundry no portal Azure, criado numa região suportada.
- Este recurso está listado em Foundry>Foundry no portal.
Configure implementações de modelos padrão para o seu recurso de Compreensão de Conteúdo. Ao definir os valores predefinidos, cria uma conexão com os modelos do Microsoft Foundry que utiliza para pedidos de Compreensão de Conteúdo. Escolha um dos seguintes métodos:
- Portal
- API REST
1. Vai à página de Definições de Compreensão de Conteúdo.
2. Selecione o botão + Adicionar recurso no canto superior esquerdo.
3. Seleciona o recurso Foundry que quer usar e depois seleciona Seguinte>Guardar.
  
  Certifique-se de que a opção Ativar autodeployment para modelos necessários caso não existam predefinidos esteja selecionada. Esta seleção garante que o seu recurso está totalmente configurado com os modelos necessários GPT-4.1, GPT-4.1-mini, e text-embedding-3-large . Diferentes analisadores pré-montados requerem modelos diferentes.
Ao seguir estes passos, estabelece uma ligação entre Compreensão de Conteúdo e modelos Foundry no seu recurso Foundry.
1. No seu recurso Foundry, crie desdobramentos dos modelos Foundry GPT-4.1, GPT-4.1-mini e text-embedding-3-large. Para detalhes sobre como implementar estes modelos, veja Criar implementações de modelos no portal Microsoft Foundry. Diferentes analisadores pré-montados requerem modelos diferentes, por isso tens de implementar os três.
2. Defina as implementações padrão do modelo ao nível dos recursos. Antes de executar o comando seguinte cURL , faça as seguintes alterações ao pedido HTTP:
  1. Substitua {endpoint} e {key} pelos valores correspondentes da sua instância Foundry no portal Azure.
  2. Substitua {myGPT41Deployment}, {myGPT41MiniDeployment}, e {myEmbeddingDeployment} pelos nomes reais de implementação dos seus modelos a partir do seu recurso Foundry.
```
curl -i -X PATCH "{endpoint}/contentunderstanding/defaults?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d '{
        "modelDeployments": {
          "gpt-4.1": "{myGPT41Deployment}",
          "gpt-4.1-mini": "{myGPT41MiniDeployment}",
          "text-embedding-3-large": "{myEmbeddingDeployment}"
        }
      }'
```
cURL instalado para o teu ambiente de desenvolvimento (para o separador REST API).

Passo 1: Criar um classificador básico

Um classificador básico categoriza os documentos em categorias de conteúdo personalizadas. Defines as categorias com nomes e descrições, e o serviço usa essas definições para classificar os teus ficheiros de entrada. O enableSegment parâmetro controla se o classificador divide ficheiros multi-documento em segmentos ou trata o ficheiro inteiro como um único documento.

Estúdio de Compreensão de Conteúdos
API REST

Vai ao portal Content Understanding Studio e inicia sessão com as tuas credenciais. Se está familiarizado com a clássica experiência do Azure Document Intelligence no Foundry Tools Studio, o Content Understanding estende o mesmo conteúdo e extração de campos em todas as modalidades — documento, imagem, vídeo e áudio. Selecione a opção para experimentar a nova experiência de Compreensão de Conteúdo para aceder a capacidades multimodais.

Criar um projeto de classificador

Comece com um novo projeto: Selecione Criar projeto na página inicial.
Selecione o seu tipo de projeto: Selecione a opção para Classify and route with custom categories.
Carregue os seus dados: Carregue um dado de exemplo para começar a classificar.
Criar regras de encaminhamento: No separador Regras de Roteamento , selecione Add category. Dê um nome e uma descrição à categoria. Para um classificador básico, podes saltar a atribuição de um analisador específico a cada categoria.
Teste o seu fluxo de trabalho de classificação: Quando as suas regras de encaminhamento personalizadas estiverem prontas para teste, selecione Executar análise para ver a saída das regras nos seus dados.
Construa o seu analisador de classificação: Quando estiver satisfeito com o resultado, selecione o botão Construir analisador no topo da página. Dá um nome ao analisador e seleciona Guardar.

Antes de executar qualquer um dos seguintes comandos cURL, substitua {endpoint} e {key} pelos valores correspondentes da sua instância Foundry no portal Azure.

Defina o classificador

Defina contentCategories dentro da configuração do analisador. Cada categoria tem um nome e uma descrição que o serviço usa para classificar os seus ficheiros de entrada.

Crie um ficheiro JSON chamado classifier.json com o seguinte conteúdo:

{
  "baseAnalyzerId": "prebuilt-document",
  "description": "Custom classifier for document categorization",
  "config": {
    "returnDetails": true,
    "enableSegment": true,
    "contentCategories": {
      "Loan application": {
        "description": "Documents submitted by individuals or businesses to request funding, typically including personal or business details, financial history, loan amount, purpose, and supporting documentation."
      },
      "Invoice": {
        "description": "Billing documents issued by sellers or service providers to request payment for goods or services, detailing items, prices, taxes, totals, and payment terms."
      },
      "Bank_Statement": {
        "description": "Official statements issued by banks that summarize account activity over a period, including deposits, withdrawals, fees, and balances."
      }
    }
  },
  "models": {"completion": "gpt-4.1"}
}

Os campos-chave nesta definição são:

Campo	Descrição
`baseAnalyzerId`	O analisador pré-construído para estender. Uso `prebuilt-document` para classificação de documentos.
`contentCategories`	Um dicionário com até 200 nomes de categorias e descrições.
`enableSegment`	Quando `true`, divide e classifica automaticamente diferentes tipos de documentos dentro de um único ficheiro. Quando `false`, trata todo o ficheiro como um único documento.

Criar o classificador

Utilize uma PUT requisição para criar o analisador classificador.

curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{classifierId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d @classifier.json

A 201 Created resposta inclui um Operation-Location cabeçalho com uma URL que pode usar para acompanhar o estado da operação de criação assíncrona.

201 Created
Operation-Location: {endpoint}/contentunderstanding/analyzers/{classifierId}/operations/{operationId}?api-version=2025-11-01

Quando a operação termina, um HTTP GET na URL de localização da operação devolve "status": "succeeded".

curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{classifierId}/operations/{operationId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Referência: Analisadores de Conteúdo - Criar ou Substituir

Classificar um documento

Submeta um documento para classificação usando o :analyze endpoint. Substitui {classifierId} pelo nome do classificador que criaste.

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{classifierId}:analyze?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs": [
          {
            "url": "https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/mixed_financial_docs.pdf"
          }
        ]
      }'

A resposta inclui um Operation-Location cabeçalho. Use esse URL para obter os resultados da análise.

Obtenha resultados de classificação

curl -i -X GET "{Operation-Location}" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Uma resposta bem-sucedida retorna "status": "Succeeded" com os resultados de classificação no objeto result. Cada segmento inclui um category, startPageNumber, e endPageNumber.

Referência: Resultados do Analisador - Obtenha

Limpar

Apaga o classificador quando terminares.

curl -i -X DELETE "{endpoint}/contentunderstanding/analyzers/{classifierId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Passo 2: Classificar e encaminhar com analisadores personalizados

Para além da classificação básica, podes encaminhar cada categoria para um analisador específico para extração em campo. Esta abordagem combina classificação com extração de dados num único pipeline: o classificador identifica o tipo de documento e depois encaminha-o para o analisador correto, que extrai campos adaptados a essa categoria.

Estúdio de Compreensão de Conteúdos
API REST

Para encaminhar com sucesso os seus dados, crie analisadores personalizados para cada categoria. Para mais informações sobre como construir analisadores personalizados, consulte Criar e melhorar o seu analisador personalizado no Content Understanding Studio.

Crie analisadores personalizados primeiro: Crie analisadores personalizados para cada tipo de documento que pretende encaminhar. Por exemplo, crie um analisador personalizado para pedidos de empréstimo com um esquema de extração de campo específico para esse tipo de documento.
Criar ou atualizar regras de encaminhamento: No separador Regras de Roteamento , selecione Add category. Dê à categoria um nome e uma descrição, e selecione um analisador que corresponda a essa rota. A ferramenta permite-lhe pré-visualizar o esquema de cada analisador para garantir que tem o modelo correto.
Teste o seu fluxo de trabalho de classificação: Selecione Executar análise para ver a saída das regras nos seus dados. Podes carregar dados de amostra adicionais para testar e ver como se comporta com várias regras diferentes.
Construa o seu analisador de classificação: Quando estiver satisfeito com o resultado, selecione o botão Construir analisador no topo da página. Dá um nome ao analisador e seleciona Guardar.
Utilize o seu classificador: Agora tem um endpoint de análise que pode usar na sua própria aplicação através da API REST.

Criar um analisador personalizado para uma categoria

Primeiro, crie um analisador personalizado que extraia campos específicos para uma categoria de documento. Este exemplo define um analisador de candidaturas de empréstimo com extração em campo.

Crie um ficheiro JSON chamado loan-analyzer.json com o seguinte conteúdo:

{
  "baseAnalyzerId": "prebuilt-document",
  "description": "Loan application analyzer - extracts key information from loan applications",
  "config": {
    "returnDetails": true,
    "enableLayout": true,
    "enableFormula": false,
    "estimateFieldSourceAndConfidence": true
  },
  "fieldSchema": {
    "fields": {
      "ApplicationDate": {
        "type": "date",
        "method": "generate",
        "description": "The date when the loan application was submitted."
      },
      "ApplicantName": {
        "type": "string",
        "method": "generate",
        "description": "Full name of the loan applicant or company."
      },
      "LoanAmountRequested": {
        "type": "number",
        "method": "generate",
        "description": "The total loan amount requested by the applicant."
      },
      "LoanPurpose": {
        "type": "string",
        "method": "generate",
        "description": "The stated purpose or reason for the loan."
      },
      "Summary": {
        "type": "string",
        "method": "generate",
        "description": "A brief summary overview of the loan application details."
      }
    }
  },
  "models": {"completion": "gpt-4.1"}
}

Crie o analisador personalizado com uma PUT requisição.

curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{loanAnalyzerId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d @loan-analyzer.json

Consulte a Operation-Location URL a partir do cabeçalho de resposta até que o estado seja "succeeded".

Referência: Analisadores de Conteúdo - Criar ou Substituir

Defina o classificador aprimorado com roteamento

Crie um classificador que encaminhe cada categoria para um analisador específico. Use o analyzerId campo em cada categoria para apontar para o analisador que gere essa categoria.

Crie um ficheiro JSON com o seguinte enhanced-classifier.json conteúdo. Substitui {loanAnalyzerId} pelo ID do analisador que usaste na etapa anterior.

{
  "baseAnalyzerId": "prebuilt-document",
  "description": "Enhanced classifier with custom loan analyzer",
  "config": {
    "returnDetails": true,
    "enableSegment": true,
    "contentCategories": {
      "Loan application": {
        "description": "Documents submitted by individuals or businesses to request funding, typically including personal or business details, financial history, loan amount, purpose, and supporting documentation.",
        "analyzerId": "{loanAnalyzerId}"
      },
      "Invoice": {
        "description": "Billing documents issued by sellers or service providers to request payment for goods or services, detailing items, prices, taxes, totals, and payment terms."
      },
      "Bank_Statement": {
        "description": "Official statements issued by banks that summarize account activity over a period, including deposits, withdrawals, fees, and balances."
      }
    }
  },
  "models": {"completion": "gpt-4.1"}
}

A principal diferença em relação a um classificador básico é a analyzerId propriedade na Loan application categoria. Isto indica ao serviço para encaminhar documentos classificados como pedidos de empréstimo através do analisador personalizado para extração em campo. Categorias sem um analyzerId são classificadas mas não encaminhadas para um analisador específico.

Crie o classificador melhorado

curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{enhancedClassifierId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d @enhanced-classifier.json

Consulte a Operation-Location URL a partir do cabeçalho de resposta até que o estado seja "succeeded".

Analise um documento com o classificador melhorado

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{enhancedClassifierId}:analyze?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs": [
          {
            "url": "https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/mixed_financial_docs.pdf"
          }
        ]
      }'

Obtenha resultados de classificação melhorados

Use a Operation-Location URL do cabeçalho de resposta para obter os resultados.

curl -i -X GET "{Operation-Location}" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Uma resposta bem-sucedida retorna "status": "Succeeded" com resultados de classificação juntamente com os campos extraídos. Os documentos encaminhados para o analisador de empréstimos personalizado incluem valores extraídos de campos como ApplicantName, LoanAmountRequested, e LoanPurpose no objeto fields para esse segmento.

Referência: Resultados do Analisador - Obtenha

Limpar

Apaga os analisadores quando terminares.

curl -i -X DELETE "{endpoint}/contentunderstanding/analyzers/{enhancedClassifierId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

curl -i -X DELETE "{endpoint}/contentunderstanding/analyzers/{loanAnalyzerId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Dica

Para um caderno completo de Python de ponta a ponta, veja a amostra do classificador em GitHub.

Próximos passos

Saiba mais sobre as melhores práticas para compreensão de conteúdos Azure na Foundry Tools.
Siga o tutorial para criar um analisador personalizado usando APIs REST.
Investigue conceitos de classificadores para cenários avançados.

Comentários

Esta página foi útil?

Last updated on 2026-04-21