Condividi tramite

Creare un analizzatore personalizzato tramite LE API REST

Gli analizzatori di Analisi del contenuto definiscono come elaborare ed estrarre informazioni dettagliate dai contenuti. Garantiscono un'elaborazione uniforme e una struttura di output in tutto il contenuto per ottenere risultati affidabili e prevedibili. Sono disponibili analizzatori predefiniti per i casi d'uso comuni. Questa guida illustra come personalizzare questi analizzatori in base alle proprie esigenze.

In questa guida viene usato lo strumento da riga di comando cURL. Se non è installato, è possibile scaricare la versione appropriata per l'ambiente di sviluppo.

Definire uno schema dell'analizzatore

Per creare un analizzatore personalizzato, definire uno schema di campo che descrive i dati strutturati da estrarre. Nell'esempio seguente viene creato un analizzatore basato sull'analizzatore di documenti predefinito per l'elaborazione di una ricevuta.

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

{
  "description": "Sample receipt analyzer",
  "baseAnalyzerId": "prebuilt-documentAnalyzer",
  "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"
            }
          }
        }
      }
    }
  }
}

Analizzatore di build

Richiesta HTTP di tipo PUT

curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2025-05-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 dell'analizzatore asincrono.

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

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

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

Analizzare il file

Invia file

È ora possibile usare l'analizzatore personalizzato creato per elaborare i file ed 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'istanza di Azure AI Foundry del portale 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/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.pngdi esempio .

Richiesta POST

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

Risposta POST

La 202 Accepted risposta include l'oggetto {resultId} che è possibile usare per tenere traccia dello stato di questa operazione asincrona.

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

Ottenere il risultato dell'analisi

  1. Sostituire {endpoint} e {key} con i valori dell'endpoint e della chiave dell'istanza di Azure AI Foundry del portale di Azure.
  2. Sostituisci {resultId} con resultId nella risposta POST.

Richiesta GET

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

Risposta GET

Una 200 OK risposta include un status campo che mostra lo stato dell'operazione.

  • status è Succeeded se l'operazione viene completata correttamente.
  • Se è running o notStarted, chiamare di nuovo l'API manualmente o con uno script: attendere almeno un secondo tra le richieste.
Risposta di esempio
{
  "id": {resultId},
  "status": "Succeeded",
  "result": {
    "analyzerId": {analyzerId},
    "apiVersion": "2025-05-01-preview",
    "createdAt": "YYYY-MM-DDTHH:MM:SSZ",
    "warnings": [],
    "contents": [
      {
        "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.0848,
            "width": 1743,
            "height": 878,
            "spans": [
              {
                "offset": 0,
                "length": 375
              }
            ],
            "words": [
              {
                "content": "Contoso",
                "span": {"offset": 0,"length": 7 },
                "confidence": 0.995,
                "source": "D(1,774,72,974,70,974,111,774,113)"
              }, ...

            ],
            "lines": [
              {
                "content": "Contoso",
                "source": "D(1,774,71,973,70,974,111,774,113)",
                "span": {"offset": 0,"length": 7}
              }, ...
            ]
          }
        ],
        "paragraphs": [
          {
            "content": "Contoso",
            "source": "D(1,774,71,973,70,974,111,774,113)",
            "span": {"offset": 0,"length": 7}
          }, ...
        ],
        "sectios": [
          {
            "span": {"offset": 0,"length": 374 },
            "elements": ["/paragraphs/0","/paragraphs/1", ...]
          }
        ],
        "tables": [
          {
            "rowCount": 2,
            "columnCount": 2,
            "cells": [
              {
                "kind": "content",
                "rowIndex": 0,
                "columnIndex": 0,
                "rowSpan": 1,
                "columnSpan": 1,
                "content": "2 Surface Pro 6",
                "source": "D(1,691,471,911,470,911,514,691,515)",
                "span": {"offset": 115,"length": 15},
                "elements": ["/paragraphs/4"]
              }, ...
            ],
            "source": "D(1,759,593,1056,592,1057,741,760,742)",
            "span": {"offset": 223,"length": 151}
          }
        ]
      }
    ]
  }
}