Compartilhar via

Criar um analisador personalizado usando APIs REST

Os analisadores de Compreensão de Conteúdo definem como processar e extrair insights do seu conteúdo. Eles garantem o processamento uniforme e a estrutura de saída em todo o conteúdo para fornecer resultados confiáveis e previsíveis. Oferecemos analisadores predefinidos para casos de uso comuns. Este guia mostra como esses analisadores podem ser personalizados para atender melhor às suas necessidades.

Neste guia, usamos a ferramenta de linha de comando cURL. Se ele não estiver instalado, você poderá baixar a versão apropriada para seu ambiente de desenvolvedor.

Pré-requisitos

Antes de começar, confirme se você tem os seguintes recursos e permissões:

  • Uma assinatura do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita.
  • Depois de ter sua assinatura do Azure, crie um Recurso da Fábrica da Microsoft no portal do Azure. Certifique-se de criá-lo em uma região com suporte.
    • Esse recurso está listado em Fábrica>Fábrica no portal.
  • Configure implantações de modelo padrão para o recurso de Compreensão de Conteúdo. Definir padrões cria uma conexão com os modelos de Foundry que você usa para solicitações de Compreensão de Conteúdo. Use um dos seguintes métodos:
    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 clique em Avançar e, em seguida, Salvar
      • Certifique-se de deixar a opção "Habilitar implantação automática para modelos obrigatórios se não houver padrões disponíveis." marcada. Isso garante que seu recurso esteja totalmente configurado com os modelos GPT-4.1, GPT-4.1-mini e text-embedding-3-large obrigatórios. 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.

Definir um esquema do analisador

Para criar um analisador personalizado, defina um esquema de campo que descreva os dados estruturados que você deseja extrair. No exemplo a seguir, criamos um analisador com base no analisador de documentos predefinido para processar um recibo.

Crie um arquivo JSON nomeado receipt.json com o seguinte conteúdo:

{
  "description": "Sample receipt analyzer",
  "baseAnalyzerId": "prebuilt-document",
  "models": {
      "completion": "gpt-4.1",
      "embedding": "text-embedding-ada-002"

    },
  "config": {
    "returnDetails": true,
    "enableFormula": false,
    "disableContentFiltering": false,
    "estimateFieldSourceAndConfidence": true,
    "tableFormat": "html"
  },
 "fieldSchema": {
    "fields": {
      "VendorName": {
        "type": "string",
        "method": "extract",
        "description": "Vendor issuing the receipt"
      },
      "Items": {
        "type": "array",
        "method": "extract",
        "items": {
          "type": "object",
          "properties": {
            "Description": {
              "type": "string",
              "method": "extract",
              "description": "Description of the item"
            },
            "Amount": {
              "type": "number",
              "method": "extract",
              "description": "Amount of the item"
            }
          }
        }
      }
    }
  }
}

Se você tiver vários tipos de documentos que precisa processar, mas quiser categorizar e analisar somente os recibos, poderá criar um analisador que categorize o documento primeiro. Em seguida, encaminhe-o para o analisador que você criou acima com o esquema a seguir.

Crie um arquivo JSON nomeado categorize.json com o seguinte conteúdo:

{
  "baseAnalyzerId": "prebuilt-document",
  // Use the base analyzer to invoke the document specific capabilities.

  //Specify the model the analyzer should use. This is one of the supported completion models and one of the supported embeddings model. The specific deployment used during analyze is set on the resource or provided in the analyze request.
  "models": {
      "completion": "gpt-4.1",
      "embedding": "text-embedding-ada-002"

    },
  "config": {
    // Enable splitting of the input into segments. Set this property to false if you only expect a single document within the input file. When specified and enableSegment=false, the whole content will be classified into one of the categories.
    "enableSegment": false,

    "contentCategories": {
      // Category name.
      "receipt": {
        // Description to help with classification and splitting.
        "description": "Any images or documents of receipts",

        // Define the analyzer that any content classified as a receipt should be routed to
        "analyzerId": "receipt"
      },

      "invoice": {
        "description": "Any images or documents of invoice",
        "analyzerId": "prebuilt-invoice"
      },
      "policeReport": {
        "description": "A police or law enforcement report detailing the events that lead to the loss."
        // Don't perform analysis for this category.
      }

    },

    // Omit original content object and only return content objects from additional analysis.
    "omitContent": true
  }

  //You can use fieldSchema here to define fields that are needed from the entire input content.

}

Criar um analisador

Solicitação PUT

Crie um analisador de recibos primeiro e, em seguida, crie o analisador de categorização.

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

Reposta PUT

A resposta 201 Created inclui um Operation-Location cabeçalho que contém uma URL que você pode usar para acompanhar o status dessa operação de criação de analisador assíncrono.

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

Quando a operação for concluída, executar um HTTP GET na URL do local da operação retornará "status": "succeeded".

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

Analisar um arquivo

Enviar o arquivo

Agora você pode usar o analisador personalizado criado para processar arquivos e extrair os campos definidos no esquema.

Antes de executar o comando cURL, faça as seguintes alterações na solicitação HTTP:

  1. Substitua {endpoint} e {key} pelos valores de ponto de extremidade e chave da instância do Foundry no portal do Azure.
  2. Substitua {analyzerId} pelo nome do analisador personalizado que você criou com o categorize.json arquivo.
  3. Substitua {fileUrl} por uma URL publicamente acessível do arquivo a ser analisado, como um caminho para um Azure Storage Blob com uma assinatura de acesso compartilhado (SAS) ou a URL de exemplo https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png.

Solicitação POST

Este exemplo usa o analisador personalizado criado com o categorize.json arquivo para analisar um recibo.

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{analyzerId}: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/receipt.png"
          }          
        ]
      }'

Resposta POST

A 202 Accepted resposta inclui o {resultId} que você pode usar para acompanhar o status dessa operação assíncrona.

{
  "id": {resultId},
  "status": "Running",
  "result": {
    "analyzerId": {analyzerId},
    "apiVersion": "2025-11-01",
    "createdAt": "YYYY-MM-DDTHH:MM:SSZ",
    "warnings": [],
    "contents": []
  }
}

Obter o resultado da análise

Use Operation-Location da resposta POST e recupere o resultado da análise.

Solicitação GET

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

Resposta GET

Uma 200 OK resposta inclui um status campo que mostra o progresso da operação.

  • status será Succeeded se a operação for concluída com sucesso.
  • Se for running ou notStarted, chame a API novamente manualmente ou com um script: aguarde pelo menos um segundo entre as solicitações.
Resposta de exemplo
{
  "id": {resultId},
  "status": "Succeeded",
  "result": {
    "analyzerId": {analyzerId},
    "apiVersion": "2025-11-01",
    "createdAt": "YYYY-MM-DDTHH:MM:SSZ",
    "warnings": [],
    "contents": [
      {
        "path": "input1/segment1",
        "category": "receipt",
        "markdown": "Contoso\n\n123 Main Street\nRedmond, WA 98052\n\n987-654-3210\n\n6/10/2019 13:59\nSales Associate: Paul\n\n\n<table>\n<tr>\n<td>2 Surface Pro 6</td>\n<td>$1,998.00</td>\n</tr>\n<tr>\n<td>3 Surface Pen</td>\n<td>$299.97</td>\n</tr>\n</table> ...",
        "fields": {
          "VendorName": {
            "type": "string",
            "valueString": "Contoso",
            "spans": [{"offset": 0,"length": 7}],
            "confidence": 0.996,
            "source": "D(1,774.0000,72.0000,974.0000,70.0000,974.0000,111.0000,774.0000,113.0000)"
          },
          "Items": {
            "type": "array",
            "valueArray": [
              {
                "type": "object",
                "valueObject": {
                  "Description": {
                    "type": "string",
                    "valueString": "2 Surface Pro 6",
                    "spans": [ { "offset": 115, "length": 15}],
                    "confidence": 0.423,
                    "source": "D(1,704.0000,482.0000,875.0000,482.0000,875.0000,508.0000,704.0000,508.0000)"
                  },
                  "Amount": {
                    "type": "number",
                    "valueNumber": 1998,
                    "spans": [{ "offset": 140,"length": 9}
                    ],
                    "confidence": 0.957,
                    "source": "D(1,952.0000,482.0000,1048.0000,482.0000,1048.0000,508.0000,952.0000,509.0000)"
                  }
                }
              }, ...
            ]
          }
        },
        "kind": "document",
        "startPageNumber": 1,
        "endPageNumber": 1,
        "unit": "pixel",
        "pages": [
          {
            "pageNumber": 1,
            "angle": -0.0944,
            "width": 1743,
            "height": 878
          }
        ],
        "analyzerId": "{analyzerId}",
        "mimeType": "image/png"
      }
    ]
  },
  "usage": {
    "documentPages": 1,
    "tokens": {
      "contextualization": 1000
    }
  }
}

Conteúdo relacionado

  • Last updated on