Compartir a través de

Inicio rápido: API de REST de Comprensión del contenido de Azure AI

  • Artículo

  • Iniciar a usar la versión preliminar más reciente de la API de REST de Comprensión del contenido de Azure AI (2024-12-01-versión preliminar).

  • La comprensión de contenidos de Azure AI es un nuevo Servicio de Azure AIasado en IA generativa que analiza archivos de cualquier modalidad (documentos, imágenes, vídeos y audio) y extrae resultados estructurados en formatos de campo definidos por el usuario.

  • Integre el servicio de comprensión de contenidos en sus flujos de trabajo y aplicaciones fácilmente mediante una llamada a nuestras API de REST.

  • Este inicio rápido le guía a través del uso de la API de REST de Comprensión de Contenidos para crear un analizador personalizado y extraer contenido y campos de la entrada.

Requisitos previos

Para empezar, necesita Una suscripción de Azure activa. Si no tiene una cuenta de Azure, puede crear una suscripción gratuita.

  • Una vez que tenga la suscripción de Azure, cree un Recurso de Servicios de Azure AI en Azure Portal. Este recurso de varios servicios permite el acceso a varios servicios de Azure AI con un único conjunto de credenciales.

    • Este recurso aparece en Servicios de Azure AI → Servicios de Azure AI en el portal.

      Importante

      Azure proporciona más de un tipo de recurso denominado servicios de Azure AI. Asegúrese de seleccionar la que aparece en Servicios de Azure AI → Servicios de Azure AI, tal como se muestra en la imagen siguiente. Para más información, vea Creación de un recurso de Servicios de Azure AI.

      Captura de pantalla de la página de recursos de varios servicios en Azure Portal.

  • En este inicio rápido, usamos la herramienta de línea de comandos cURL. Si no está instalado, puede descargar una versión para el entorno de desarrollo:

Creación de un analizador personalizado

Para crear un analizador personalizado, debe definir un esquema de campo que describa los datos estructurados que desea extraer. En el ejemplo siguiente, definimos un esquema para extraer información básica de un documento de factura.

En primer lugar, cree un archivo JSON denominado request_body.json con el siguiente contenido:

{
  "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 ejecutar los siguientes comandos de cURL, realice los siguientes cambios en la solicitud HTTP:

  1. Reemplace {endpoint} y {key} por los valores de punto de conexión y clave de la instancia de Servicios de Azure AI de Azure Portal.
  2. Reemplace {analyzerId} por el nombre del nuevo analizador y cree, como myInvoice.

Solicitud 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

Respuesta PUT

La respuesta 201 (Created) incluye un encabezado Operation-Location que contiene una dirección URL que puede usar para realizar un seguimiento del estado de esta operación de creación asincrónica.

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

Tras finalizar, la realización de un HTTP GET en la dirección URL devuelve "status": "succeeded".

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

Análisis de un archivo

Puede analizar archivos mediante el analizador personalizado que creó para extraer los campos definidos en el esquema.

Antes de ejecutar el comando cURL, realice los cambios siguientes en la solicitud HTTP:

  1. Reemplace {endpoint} y {key} por los valores de punto de conexión y clave de la instancia de Servicios de Azure AI de Azure Portal.
  2. Reemplace {analyzerId} por el nombre del analizador personalizado creado anteriormente.
  3. Reemplace {fileUrl} por una dirección URL de acceso público del archivo que se va a analizar, como una ruta de acceso a un Azure Storage Blob con una firma de acceso compartido (SAS) o la dirección URL de ejemplo https://github.com/Azure-Samples/cognitive-services-REST-api-samples/raw/master/curl/form-recognizer/rest-api/invoice.pdf.

Solicitud 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}\"}"

Respuesta de POST

La respuesta 202 (Accepted) incluye un encabezado Operation-Location que contiene una dirección URL que puede usar para realizar un seguimiento del estado de esta operación de análisis asincrónica.

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

Obtención del resultado de análisis

Use el resultId del encabezado Operation-Location devuelto por la respuesta POST anterior y recupere el resultado del análisis.

  1. Reemplace {endpoint} y {key} por los valores de punto de conexión y clave de la instancia de Servicios de Azure AI de Azure Portal.
  2. Reemplace {analyzerId} por el nombre del analizador personalizado creado anteriormente.
  3. Reemplace {resultId} por el resultId devuelto de la solicitud de POST.

Solicitud GET

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

Respuesta GET

La respuesta JSON 200 (OK) incluye un campo status que indica el estado de la operación. Si la operación no se completa, el valor de status es running o notStarted. En tales casos, debe llamar a la API de nuevo, ya sea manualmente o a través de un script. Espere un intervalo de un segundo o más entre llamadas.

Respuesta de muestra

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

Pasos siguientes