Partilhar via

Crie 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 processamento uniforme e estrutura de saída em todo o seu conteúdo para fornecer resultados confiáveis e previsíveis. Oferecemos analisadores pré-construídos para casos de uso comuns. Este guia mostra como esses analisadores podem ser personalizados para melhor atender às suas necessidades.

Neste guia, usamos a ferramenta de linha de comando cURL. Se não estiver instalado, pode descarregar a versão apropriada para o seu ambiente de programador.

Pré-requisitos

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

  • Uma assinatura do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita.
  • Depois de ter a sua subscrição Azure, crie um recurso Microsoft Foundry no portal Azure. Certifique-se de criá-lo em uma 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. Definir os padrões cria uma ligação aos modelos Foundry que usa para pedidos de Compreensão de Conteúdo. Escolha um dos métodos seguintes:
    1. Vá à página de definições de Compreensão de Conteúdo
    2. Selecione o botão "+ Adicionar recurso" no canto superior esquerdo
    3. Selecione o recurso Foundry que pretende usar e clique em Seguinte, depois Guardar
      • Certifique-se de deixar "Ativar a implantação automática para modelos obrigatórios caso não existam predefinições disponíveis." assinalado. Isto assegura que o seu recurso está configurado integralmente com os modelos requisitados 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.

Definir um esquema de 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 baseado no analisador de documentos pré-construído 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 tiver vários tipos de documentos que precisa de processar, mas quiser categorizar e analisar apenas os recibos, pode criar um analisador que categorize primeiro o documento. Depois, encaminha-o para o analisador que criaste acima com o esquema seguinte.

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.

}

Crie um analisador

Pedido PUT

Crie primeiro um analisador de recibos e depois 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

Resposta PUT

A resposta 201 Created inclui um cabeçalho Operation-Location contendo uma URL que pode usar para monitorizar o estado desta operação assíncrona de criação do analisador.

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

Após a conclusão, a execução de um HTTP GET no URL do local da operação retorna "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 ficheiro

Submeter o ficheiro

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} com o endpoint e os valores-chave da sua instância Azure Portal Foundry.
  2. Substitui {analyzerId} pelo nome do analisador personalizado que criaste com o categorize.json ficheiro.
  3. Substitua {fileUrl} por uma URL acessível publicamente do arquivo a ser analisado, como um caminho para um Blob de Armazenamento do Azure com uma assinatura de acesso compartilhado (SAS) ou a URL https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.pngde exemplo.

Solicitação POST

Este exemplo utiliza o analisador personalizado que criou com o categorize.json ficheiro 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 resposta 202 Accepted inclui o {resultId}, que pode ser usado para controlar o estado desta operação assíncrona.

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

Obter resultado de análise

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

Pedido 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 é Succeeded se a operação for concluída com êxito.
  • Se for running ou notStarted, chame a API novamente manualmente ou com um script: aguarde pelo menos um segundo entre as solicitações.
Resposta da amostra
{
  "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