Partilhar via

Guia de início rápido: Noções básicas sobre APIs REST de conteúdo do Azure AI

  • Artigo

  • Comece a usar a versão de visualização mais recente da API REST de Compreensão de Conteúdo do Azure AI (2024-12-01-preview).

  • O Entendimento de Conteúdo do Azure AI é um novo Serviço de IA do Azure baseado em IA generativa que analisa arquivos de qualquer modalidade (documentos, imagens, vídeos e áudio) e extrai saída estruturada em formatos de campo definidos pelo usuário.

  • Integre o serviço de Compreensão de Conteúdo em seus fluxos de trabalho e aplicativos facilmente chamando nossas APIs REST.

  • Este guia de início rápido orienta você pelo uso da API REST de Compreensão de Conteúdo para criar um analisador personalizado e extrair conteúdo e campos de sua entrada.

Pré-requisitos

Para começar, você precisa de uma assinatura ativa do Azure. Se não tiver uma conta do Azure, pode criar uma subscrição gratuita.

  • Depois de ter sua assinatura do Azure, crie um recurso dos Serviços de IA do Azure no portal do Azure. Este recurso multisserviço permite o acesso a vários serviços de IA do Azure com um único conjunto de credenciais.

    • Este recurso está listado em Serviços de IA do Azure → Serviços de IA do Azure no portal.

      Importante

      O Azure fornece mais de um tipo de recurso chamado Serviços de IA do Azure. Certifique-se de selecionar o listado em Serviços de IA do Azure → Serviços de IA do Azure, conforme descrito na imagem a seguir. Para obter mais informações, consulte Criar um recurso dos Serviços de IA do Azure.

      Captura de ecrã da página de recursos multisserviço no portal do Azure.

  • Neste início rápido, usamos a ferramenta de linha de comando cURL. Se ele não estiver instalado, você pode baixar uma versão para seu ambiente de desenvolvimento:

Criar um analisador personalizado

Para criar um analisador personalizado, você precisa definir um esquema de campo que descreva os dados estruturados que você deseja extrair. No exemplo a seguir, definimos um esquema para extrair informações básicas de um documento de fatura.

Primeiro, crie um arquivo JSON nomeado request_body.json com o seguinte conteúdo:

{
  "description": "Sample invoice analyzer",
  "scenario": "document",
  "config": {
    "returnDetails": true
  },
  "fieldSchema": {
    "fields": {
      "VendorName": {
        "type": "string",
        "method": "extract",
        "description": "Vendor issuing the invoice"
      },
      "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"
            }
          }
        }
      }
    }
  }
}

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

  1. Substitua {endpoint} e {key} pelos valores de ponto de extremidade e chave da sua instância dos Serviços de IA do Azure do portal do Azure.
  2. Substitua {analyzerId} pelo nome do novo analisador e crie, como myInvoice.

Pedido PUT

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

Resposta PUT

A resposta 201 (Created) inclui um Operation-Location cabeçalho contendo uma URL que você pode usar para controlar o status dessa operação de criação assíncrona.

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

Após a conclusão, a execução de um HTTP GET na URL retorna "status": "succeeded".

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

Analisar um ficheiro

Você pode analisar arquivos usando o analisador personalizado criado para 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 sua instância dos Serviços de IA do Azure do portal do Azure.
  2. Substitua {analyzerId} pelo nome do analisador personalizado criado anteriormente.
  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/cognitive-services-REST-api-samples/raw/master/curl/form-recognizer/rest-api/invoice.pdfde exemplo.

Pedido POST

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{analyzerId}:analyze?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"{fileUrl}\"}"

Resposta POST

A resposta 202 (Accepted) inclui um Operation-Location cabeçalho contendo uma URL que você pode usar para controlar o status dessa operação de análise assíncrona.

202 Accepted
Operation-Location: {endpoint}/contentunderstanding/analyzers/{analyzerId}/results/{resultId}?api-version=2024-12-01-preview

Obter resultado da análise

Use o resultId Operation-Location cabeçalho do cabeçalho retornado pela resposta anterior POST e recupere o resultado da análise.

  1. Substitua {endpoint} e {key} pelos valores de ponto de extremidade e chave da sua instância dos Serviços de IA do Azure do portal do Azure.
  2. Substitua {analyzerId} pelo nome do analisador personalizado criado anteriormente.
  3. Substitua {resultId} resultId pelo retornado da POST solicitação.

Pedido GET

curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{analyzerId}/results/{resultId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}"

OBTER resposta

A resposta JSON 200 (OK) inclui um status campo que indica o status da operação. Se a operação não estiver concluída, o valor de status é running ou notStarted. Nesses casos, você deve chamar a API novamente, manualmente ou por meio de um script. Aguarde um intervalo de um segundo ou mais entre as chamadas.

Resposta da amostra

{
  "id": "bcf8c7c7-03ab-4204-b22c-2b34203ef5db",
  "status": "Succeeded",
  "result": {
    "analyzerId": "sample_invoice_analyzer",
    "apiVersion": "2024-12-01-preview",
    "createdAt": "2024-11-13T07:15:46Z",
    "warnings": [],
    "contents": [
      {
        "markdown": "CONTOSO LTD.\n\n\n# INVOICE\n\nContoso Headquarters...",
        "fields": {
          "VendorName": {
            "type": "string",
            "valueString": "CONTOSO LTD.",
            "spans": [ { "offset": 0, "length": 12 } ],
            "confidence": 0.941,
            "source": "D(1,0.5729,0.6582,2.3353,0.6582,2.3353,0.8957,0.5729,0.8957)"
          },
          "Items": {
            "type": "array",
            "valueArray": [
              {
                "type": "object",
                "valueObject": {
                  "Description": {
                    "type": "string",
                    "valueString": "Consulting Services",
                    "spans": [ { "offset": 909, "length": 19 } ],
                    "confidence": 0.971,
                    "source": "D(1,2.3264,5.673,3.6413,5.673,3.6413,5.8402,2.3264,5.8402)"
                  },
                  "Amount": {
                    "type": "number",
                    "valueNumber": 60,
                    "spans": [ { "offset": 995, "length": 6 } ],
                    "confidence": 0.989,
                    "source": "D(1,7.4507,5.6684,7.9245,5.6684,7.9245,5.8323,7.4507,5.8323)"
                  }
                }
              }, ...
            ]
          }
        },
        "kind": "document",
        "startPageNumber": 1,
        "endPageNumber": 1,
        "unit": "inch",
        "pages": [
          {
            "pageNumber": 1,
            "angle": -0.0039,
            "width": 8.5,
            "height": 11,
            "spans": [ { "offset": 0, "length": 1650 } ],
            "words": [
              {
                "content": "CONTOSO",
                "span": { "offset": 0, "length": 7 },
                "confidence": 0.997,
                "source": "D(1,0.5739,0.6582,1.7446,0.6595,1.7434,0.8952,0.5729,0.8915)"
              }, ...
            ],
            "lines": [
              {
                "content": "CONTOSO LTD.",
                "source": "D(1,0.5734,0.6563,2.335,0.6601,2.3345,0.8933,0.5729,0.8895)",
                "span": { "offset": 0, "length": 12 }
              }, ...
            ]
          }
        ],
        "paragraphs": [
          {
            "content": "CONTOSO LTD.",
            "source": "D(1,0.5734,0.6563,2.335,0.6601,2.3345,0.8933,0.5729,0.8895)",
            "span": { "offset": 0, "length": 12 }
          }, ...
        ],
        "sections": [
          {
            "span": { "offset": 0, "length": 1649 },
            "elements": [ "/sections/1", "/sections/2" ]
          },
          {
            "span": { "offset": 0, "length": 12 },
            "elements": [ "/paragraphs/0" ]
          }, ...
        ],
        "tables": [
          {
            "rowCount": 2,
            "columnCount": 6,
            "cells": [
              {
                "kind": "columnHeader",
                "rowIndex": 0,
                "columnIndex": 0,
                "rowSpan": 1,
                "columnSpan": 1,
                "content": "SALESPERSON",
                "source": "D(1,0.5389,4.5514,1.7505,4.5514,1.7505,4.8364,0.5389,4.8364)",
                "span": { "offset": 512, "length": 11 },
                "elements": [ "/paragraphs/19" ]
              }, ...
            ],
            "source": "D(1,0.4885,4.5543,8.0163,4.5539,8.015,5.1207,0.4879,5.1209)",
            "span": { "offset": 495, "length": 228 }
          }, ...
        ]
      }
    ]
  }
}

Próximos passos

  • Neste guia de início rápido, você aprendeu como chamar a API REST para criar um analisador personalizado. Para uma experiência do usuário, experimente o portal do Azure AI Foundry.