Condividi tramite


Guida introduttiva: Informazioni sui contenuti di Azure per intelligenza artificiale sulle API REST

  • Iniziare a usare la versione di anteprima più recente dell'API REST Analisi del contenuto di Azure per intelligenza artificiale (2024-12-01-preview).

  • Azure AI Content Understanding è un nuovo servizio di intelligenza artificiale basato sull'intelligenza artificiale di Azure che analizza i file di qualsiasi modalità (documenti, immagini, video e audio) ed estrae l'output strutturato in formati di campo definiti dall'utente.

  • Integrare facilmente il servizio Content Understanding nei flussi di lavoro e nelle applicazioni chiamando le API REST.

  • Questa guida introduttiva illustra l'uso dell'API REST Content Understanding per creare un analizzatore personalizzato ed estrarre contenuto e campi dall'input.

Prerequisiti

Per iniziare, è necessaria una sottoscrizione di Azure attiva. Se non si ha un account Azure, è possibile creare una sottoscrizione gratuita.

  • Dopo aver creato la sottoscrizione di Azure, creare una risorsa di Servizi di intelligenza artificiale di Azure nella portale di Azure. Questa risorsa multiservizio consente l'accesso a più servizi di intelligenza artificiale di Azure con un singolo set di credenziali.

    • Questa risorsa è elencata in Servizi di intelligenza artificiale di Azure → i servizi di intelligenza artificiale di Azure nel portale.

      Importante

      Azure offre più tipi di risorsa denominati servizi di intelligenza artificiale di Azure. Assicurarsi di selezionare quello elencato in Servizi di intelligenza artificiale di Azure → i servizi di intelligenza artificiale di Azure, come illustrato nell'immagine seguente. Per altre informazioni, vedere Creare una risorsa di Servizi di intelligenza artificiale di Azure.

      Screenshot della pagina delle risorse multiservizio nella portale di Azure.

  • In questa guida introduttiva si usa lo strumento da riga di comando cURL. Se non è installato, è possibile scaricare una versione per l'ambiente di sviluppo:

Creare un analizzatore personalizzato

Per creare un analizzatore personalizzato, è necessario definire uno schema di campo che descrive i dati strutturati da estrarre. Nell'esempio seguente viene definito uno schema per estrarre informazioni di base da un documento di fattura.

Creare prima di tutto un file JSON denominato request_body.json con il contenuto seguente:

{
  "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"
            }
          }
        }
      }
    }
  }
}

Prima di eseguire i comandi seguenti, apportare le modifiche seguenti cURL alla richiesta HTTP:

  1. Sostituire {endpoint} e {key} con i valori dell'endpoint e della chiave dell portale di Azure'istanza di Servizi di intelligenza artificiale di Azure.
  2. Sostituire {analyzerId} con il nome del nuovo analizzatore e creare, ad esempio myInvoice.

Richiesta 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

Risposta PUT

La risposta 201 (Created) include un'intestazione Operation-Location contenente un URL che è possibile usare per tenere traccia dello stato di questa operazione di creazione asincrona.

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

Al termine, l'esecuzione di un'operazione HTTP GET nell'URL restituisce "status": "succeeded".

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

Analizzare un file

È possibile analizzare i file usando l'analizzatore personalizzato creato per estrarre i campi definiti nello schema.

Prima di eseguire il comando cURL, apportare le modifiche seguenti alla richiesta HTTP:

  1. Sostituire {endpoint} e {key} con i valori dell'endpoint e della chiave dell portale di Azure'istanza di Servizi di intelligenza artificiale di Azure.
  2. Sostituire {analyzerId} con il nome dell'analizzatore personalizzato creato in precedenza.
  3. Sostituire {fileUrl} con un URL accessibile pubblicamente del file da analizzare, ad esempio un percorso di un BLOB Archiviazione di Azure con una firma di accesso condiviso (SAS) o l'URL https://github.com/Azure-Samples/cognitive-services-REST-api-samples/raw/master/curl/form-recognizer/rest-api/invoice.pdfdi esempio .

Richiesta POST

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

Risposta POSTH

La risposta 202 (Accepted) include un'intestazione Operation-Location contenente un URL che è possibile usare per tenere traccia dello stato di questa operazione di analisi asincrona.

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

Ottenere il risultato dell'analisi

Usare l'oggetto resultId dall'intestazione Operation-Location restituita dalla risposta precedente POST e recuperare il risultato dell'analisi.

  1. Sostituire {endpoint} e {key} con i valori dell'endpoint e della chiave dell portale di Azure'istanza di Servizi di intelligenza artificiale di Azure.
  2. Sostituire {analyzerId} con il nome dell'analizzatore personalizzato creato in precedenza.
  3. Sostituire {resultId} con l'oggetto resultId restituito dalla POST richiesta.

Richiesta GET

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

Risposta Get

La risposta JSON 200 (OK) include un status campo che indica lo stato dell'operazione. Se l'operazione non è completa, il valore di status è running o notStarted. In questi casi, è necessario chiamare di nuovo l'API, manualmente o tramite uno script. Attendere un intervallo di un secondo o più tra le chiamate.

Risposta di esempio

{
  "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 }
          }, ...
        ]
      }
    ]
  }
}

Passaggi successivi

  • In questa guida introduttiva si è appreso come chiamare l'API REST per creare un analizzatore personalizzato. Per un'esperienza utente, provare Azure AI Foundry.