Classificar e rotear seus dados usando o Content Understanding

O Content Understanding permite criar fluxos de trabalho de classificação personalizados que categorizam seu conteúdo e o roteiam para o analisador correto. Com o roteamento, você pode enviar vários fluxos de dados pelo mesmo pipeline e garantir que seus dados sejam processados pelo melhor analisador para seu tipo.

Este guia orienta você por duas etapas:

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

Pré-requisitos

Para começar, verifique se você tem os seguintes recursos e permissões:

Uma assinatura Azure. Se você não tiver uma assinatura Azure, criar uma conta gratuita.
Um recurso Microsoft Foundry no portal Azure, criado em uma região suportada.
- Esse recurso está listado no portal em Foundry>Foundry.
Configure implantações de modelo padrão para o recurso de Compreensão de Conteúdo. Ao definir padrões, você cria uma conexão com os modelos de Microsoft Foundry usados para solicitações de Compreensão de Conteúdo. Escolha um dos seguintes métodos:
- Portal
- REST API
1. Vá para a página de configurações de Compreensão de Conteúdo.
2. Selecione o botão + Adicionar recurso no canto superior esquerdo.
3. Selecione o recurso Foundry que você deseja usar e selecione Avançar>Salvar.
  
  Verifique se a caixa de seleção Habilitar implantação automática para modelos obrigatórios se nenhum padrão estiver disponível está marcada. Essa seleção garante que seu recurso esteja totalmente configurado com os modelos necessários GPT-4.1, GPT-4.1-mini e text-embedding-3-large. Diferentes analisadores predefinidos exigem modelos diferentes.
Seguindo estas etapas, você configura uma conexão entre os modelos de Compreensão de Conteúdo e Foundry no recurso Foundry.
1. No recurso Foundry, crie implantações dos modelos GPT-4.1, GPT-4.1-mini e text-embedding-3-large do Foundry. Para obter detalhes sobre como implantar esses modelos, consulte Criar implantações de modelo no portal Microsoft Foundry. Diferentes analisadores predefinidos exigem modelos diferentes, portanto, você precisa implantar os três.
2. Defina implantações de modelo padrão no nível do recurso. Antes de executar o seguinte cURL comando, faça as seguintes alterações na solicitação HTTP:
  1. Substitua {endpoint} e {key} pelos valores correspondentes da instância do Foundry no portal do Azure.
  2. Substitua {myGPT41Deployment}, {myGPT41MiniDeployment} e {myEmbeddingDeployment} com os nomes reais de implantação de modelo 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 ambiente de desenvolvimento (para a aba API REST).

Etapa 1: Criar um classificador básico

Um classificador básico categoriza documentos em categorias de conteúdo personalizadas. Você define as categorias com nomes e descrições e o serviço usa essas definições para classificar seus arquivos de entrada. O enableSegment parâmetro controla se o classificador divide arquivos de vários documentos em segmentos ou trata todo o arquivo como um único documento.

Content Understanding Studio
REST API

Acesse o portal do Content Understanding Studio e entre com suas credenciais. Se você estiver familiarizado com a experiência clássica do Azure Document Intelligence no Foundry Tools Studio, o Content Understanding estenderá o mesmo conteúdo e extração de campo 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 acessar recursos multimodal.

Criar um projeto de classificador

Comece com um novo projeto: selecione Criar projeto na home page.
Selecione o tipo de projeto: selecione a opção para Classify and route with custom categories.
Carregue seus dados: carregue um pedaço de dados de exemplo para começar a classificar.
Criar regras de roteamento: na guia Regras de roteamento , selecione Add category. Dê à categoria um nome e uma descrição. Para um classificador básico, você pode ignorar a atribuição de um analisador específico a cada categoria.
Teste seu fluxo de trabalho de classificação: quando suas regras de roteamento personalizadas estiverem prontas para teste, selecione Executar análise para ver a saída das regras em seus dados.
Crie o analisador de classificação: quando estiver satisfeito com a saída, selecione o botão Criar analisador na parte superior da página. Dê um nome ao analisador e selecione Salvar.

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

Definir 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 seus arquivos de entrada.

Crie um arquivo JSON nomeado 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 principais nesta definição são:

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

Criar o classificador

Use uma solicitação PUT para criar o analisador de 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 você pode usar para acompanhar o status 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 for concluída, um HTTP GET na URL do local da operação retornará "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

Envie um documento para classificação usando o :analyze endpoint. Substitua {classifierId} pelo nome do classificador que você criou.

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 essa URL para recuperar os resultados da análise.

Obter resultados de classificação

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

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

Referência: Resultados do Analisador – Obter

Limpar

Exclua o classificador quando terminar.

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

Etapa 2: Classificar e rotear com analisadores personalizados

Para ir além da classificação básica, você pode rotear cada categoria para um analisador específico para extração de campo. Essa abordagem combina a classificação com a extração de dados em um único pipeline: o classificador identifica o tipo de documento e o encaminha para o analisador correto, que extrai campos personalizados para essa categoria.

Content Understanding Studio
REST API

Para rotear seus dados com êxito, crie analisadores personalizados para cada categoria. Para obter mais informações sobre como criar analisadores personalizados, consulte Criar e melhorar seu analisador personalizado no Content Understanding Studio.

Crie analisadores personalizados primeiro: crie analisadores personalizados para cada tipo de documento que você deseja rotear. Por exemplo, crie um analisador personalizado para aplicativos de empréstimo com um esquema de extração de campo específico para esse tipo de documento.
Criar ou atualizar regras de roteamento: na guia Regras de roteamento , selecione Add category. Dê à categoria um nome e uma descrição e selecione um analisador para corresponder a essa rota. A ferramenta permite que você visualize o esquema de cada analisador para assegurar que você selecione o correto.
Teste seu fluxo de trabalho de classificação: selecione Executar análise para ver a saída das regras em seus dados. Você pode carregar dados de exemplo adicionais para teste para ver como ele é executado com várias regras diferentes.
Crie o analisador de classificação: quando estiver satisfeito com a saída, selecione o botão Criar analisador na parte superior da página. Dê um nome ao analisador e selecione Salvar.
Use seu analisador de classificação: agora você tem um ponto de extremidade de analisador que pode usar em seu próprio aplicativo por meio 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 solicitação de empréstimo com extração de campos.

Crie um arquivo JSON nomeado 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 solicitação PUT :

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 URL Operation-Location no cabeçalho da resposta até que o status seja "succeeded".

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

Definir o classificador aprimorado com roteamento

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

Crie um arquivo JSON nomeado enhanced-classifier.json com o conteúdo a seguir. Substitua {loanAnalyzerId} pela ID do analisador usada 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 Loan application na categoria. Isso instrui o serviço a encaminhar documentos classificados como solicitações de empréstimo por meio do analisador personalizado para extração de campos. As categorias sem um analyzerId são classificadas, mas não roteadas para um analisador específico.

Criar o classificador aprimorado

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 URL Operation-Location no cabeçalho da resposta até que o status seja "succeeded".

Analisar um documento com o classificador aprimorado

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"
          }
        ]
      }'

Obter resultados de classificação aprimorados

Use a Operation-Location URL do cabeçalho de resposta para recuperar 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 ao lado de campos extraídos. Os documentos roteados para o analisador de empréstimo personalizado incluem valores de campo extraídos, como ApplicantName, LoanAmountRequested, e LoanPurpose no objeto fields para esse segmento.

Referência: Resultados do Analisador – Obter

Limpar

Exclua os analisadores quando terminar.

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 notebook Python completo de ponta a ponta, consulte o exemplo classifier no GitHub.

Próximas etapas

Saiba mais sobre as melhores práticas para o Azure Content Understanding nas ferramentas Foundry.
Siga o tutorial para criar um analisador personalizado usando APIs REST.
Explore conceitos de classificadores para cenários avançados.

Comentários

Esta página foi útil?

Last updated on 2026-05-04