Análisis por lotes de Documentos de inteligencia

Artículo
12/15/2024

La API de análisis por lotes permite procesar de forma masiva varios documentos mediante una solicitud asincrónica. En lugar de tener que presentar los documentos individualmente y realizar un seguimiento de varios id. de solicitud, puede analizar simultáneamente una colección de documentos como facturas, una serie de documentos de préstamo o un grupo de documentos personalizados. La API por lotes permite leer los documentos del almacenamiento de Azure Blob Storage y escribir los resultados en el almacenamiento Blob Storage.

Para usar el análisis por lotes, necesita una cuenta de Azure Blob Storage con contenedores específicos para los documentos de origen y las salidas procesadas.
Tras la finalización, el resultado de la operación por lotes enumera todos los documentos individuales procesados con su estado, como succeeded, skipped, o failed.
La versión preliminar de Batch API está disponible a través de los precios de pago por uso.

Guía de análisis por lotes

El máximo número de documentos procesados por solicitud de análisis por lotes (incluidos los documentos omitidos) es de 10 000.
Los resultados de la operación se conservan durante 24 horas después de la finalización. Los documentos y los resultados están en la cuenta de almacenamiento proporcionada, pero el estado de la operación ya no está disponible 24 horas después de la finalización.

¿Ya está listo para comenzar?

Requisitos previos

Necesita una suscripción de Azure activa. Si no tiene una suscripción de Azure, puede crear una gratis.
Una vez que tenga la suscripción de Azure A instancia de Documento de instancia en Azure Portal. Puede usar el plan de tarifa gratuito (F0) para probar el servicio.
Después de implementar el recurso, seleccione el botón Ir al recurso para obtener la clave y el punto de conexión.
- Necesita la clave y el punto de conexión del recurso para conectar la aplicación al servicio de Documento de inteligencia. En una sección posterior de este mismo inicio rápido, va a pegar la clave y el punto de conexión en el código. Puede encontrar estos valores en la página Claves y punto de conexión de Azure Portal.
Una cuenta de Azure Blob Storage. Va a crear contenedores en la cuenta de Azure Blob Storage para los archivos de origen y de resultados:
- Contenedor de origen. Este contenedor es donde carga los archivos para su análisis (obligatorio).
- Contenedor de resultados. Este contenedor es donde se almacenan los archivos procesados (opcional).

Puede designar el mismo contenedor de Azure Blob Storage para los documentos de origen y los procesados. Sin embargo, para minimizar las posibles posibilidades de sobrescribir datos accidentalmente, se recomienda elegir contenedores independientes.

Autorización de contenedor de almacenamiento

Puede elegir una de las siguientes opciones para autorizar el acceso al recurso Document.

✔️ Identidad administrada. La identidad administrada de Azure es una entidad de servicio que crea una identidad de Microsoft Entra y permisos específicos para los recursos administrados de Azure. Las identidades administradas le permiten ejecutar su aplicación Documento de inteligencia sin tener que incrustar credenciales en su código. Las identidades administradas son una manera más segura de conceder acceso a los datos de almacenamiento y reemplazar el requisito de incluir tokens de firma de acceso compartido (SAS) con las direcciones URL de origen y resultado.

Para más información, consulte Identidades administradas para el Documento de inteligencia.

Recorte de pantalla del flujo de identidad administrada (control de acceso basado en rol).

Importante

Al usar identidades administradas, no incluya una dirección URL de token de SAS con las solicitudes HTTP, ya que si lo hace, se producirá un error en las solicitudes. El uso de identidades administradas reemplaza el requisito de incluir tokens de firma de acceso compartido (SAS).

Una firma de acceso compartido (SAS). Una firma de acceso compartido es una URL que concede acceso restringido durante un periodo de tiempo determinado a su servicio del Documento de inteligencia. Para utilizar este método, es necesario crear tokens de Firma de acceso compartido (SAS) para los contenedores de origen y resultado. Los contenedores de origen y de resultados deben incluir un token de Firma de acceso compartido (SAS), anexado como una cadena de consulta. El token se puede asignar al contenedor o a blobs específicos.

Captura de pantalla del URI de almacenamiento con el token de SAS anexado.

El contenedor de origen o el blob deben designar el acceso de lectura, escritura, listay eliminación.
El contenedor de resultados o el blob deben designar el acceso de escritura, listay eliminación.

Para más información, consulte Creación de tokens de SAS.

Llamada a la API de análisis por lotes

Especifique la URL del contenedor Azure Blob Storage para su conjunto de documentos de origen dentro de los objetos azureBlobSource o azureBlobFileListSource.

Especifique los archivos de entrada

La API de lotes admite dos opciones para especificar los archivos que se van a procesar. Si necesita que se procesen todos los archivos de un contenedor o carpeta, y el número de archivos es inferior al límite de 10 000 para una única solicitud por lotes, utilice el contenedor azureBlobSource.

Si tiene archivos específicos en el contenedor o carpeta a procesar o el número de archivos a procesar supera el límite máximo para un único lote, utilice azureBlobFileListSource. Divida el conjunto de datos en varios lotes y agregue un archivo con la lista de archivos que deben procesarse en formato JSONL en la carpeta raíz del contenedor. Un ejemplo del formato de la lista de archivos.

{"file": "Adatum Corporation.pdf"}
{"file": "Best For You Organics Company.pdf"}

Especifique la ubicación de los resultados

Especifique la dirección URL del contenedor de Azure Blob Storage para los resultados del análisis por lotes mediante resultContainerUrl. Para evitar sobrescrituras accidentales, se recomienda utilizar distintos contenedores para los documentos originales y los procesados.

Establezca la propiedad booleana overwriteExisting en Falso si no desea que se sobrescriba ningún resultado existente con los mismos nombres de archivo. Este ajuste no afecta a la facturación y solo impide que los resultados se sobrescriban después de procesar el archivo de entrada.

Agrupe el resultPrefix con el espacio de nombres de los resultados de esta ejecución de la API por lotes.

Si va a utilizar el mismo contenedor para la entrada y la salida, agrupe resultContainerUrl y resultPrefix para que coincida con la entrada azureBlobSource.
Al usar el mismo contenedor, puede incluir el overwriteExisting campo para decidir si se sobrescribirán los archivos con los archivos de resultados del análisis.

Compilación y ejecución de la solicitud POST

Antes de realizar la solicitud POST, sustituya {your-source-container-SAS-URL} y {your-result-container-SAS-URL} por los valores de sus instancias de contenedor de almacenamiento Azure Blob.

El siguiente ejemplo muestra cómo agregar la propiedad azureBlobSource a la solicitud:

Permitir solo una azureBlobSource o azureBlobFileListSource.

POST /documentModels/{modelId}:analyzeBatch

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "trainingDocs/"
  },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "layoutresult/",
  "overwriteExisting": true
}

El siguiente ejemplo muestra cómo agregar la propiedad azureBlobFileListSource a la solicitud:

POST /documentModels/{modelId}:analyzeBatch

{
   "azureBlobFileListSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
      "fileList": "myFileList.jsonl"
    },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "customresult/",
  "overwriteExisting": true
}

Respuesta correcta

202 Accepted
Operation-Location: /documentModels/{modelId}/analyzeBatchResults/{resultId}

Recuperación de los resultados de la API de análisis por lotes

Una vez ejecutada la operación de Batch API, puede recuperar los resultados del análisis por lotes mediante laGET operación. Esta operación obtiene información sobre el estado de la operación, el porcentaje de finalización de la operación y la fecha/hora de creación y actualización de la operación.

GET /documentModels/{modelId}/analyzeBatchResults/{resultId}
200 OK

{
  "status": "running",      // notStarted, running, completed, failed
  "percentCompleted": 67,   // Estimated based on the number of processed documents
  "createdDateTime": "2021-09-24T13:00:46Z",
  "lastUpdatedDateTime": "2021-09-24T13:00:49Z"
...
}

Interpretación de mensajes de estado

Para cada documento, se asigna un estado, ya sea succeeded, failed, o skipped. Para cada documento, hay dos direcciones URL proporcionadas para validar los resultados: sourceUrl, que es el contenedor de almacenamiento de blobs de origen para el documento de entrada correcto y resultUrl, que se construye combinando resultContainerUrl yresultPrefix para crear la ruta de acceso relativa para el archivo de origen y .ocr.json.

Estado notStarted o running. La operación de análisis por lotes no se inicia o no se completa. Espere hasta que se complete la operación para todos los documentos.
Estado completed. Finaliza la operación de análisis por lotes.
Estado failed. Error en la operación por lotes. Esta respuesta suele producirse si hay problemas generales con la solicitud. Los errores en archivos individuales se devuelven en la respuesta del informe por lotes, incluso si se produjo un error en todos los archivos. Por ejemplo, los errores de almacenamiento no detienen la operación por lotes en su conjunto, por lo que puede acceder a resultados parciales a través de la respuesta del informe por lotes.

Solo los archivos que tienen un succeeded estado tienen la propiedad resultUrl generada en la respuesta. Esto permite que el entrenamiento del modelo detecte los nombres de archivo que terminan con .ocr.json y los identifique como los únicos archivos que pueden utilizarse para el entrenamiento.

Ejemplo de una succeeded respuesta de estado:

[
  "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
      {
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
          "code": "InvalidArgument",
          "message": "Invalid argument.",
          "innererror": {
            "code": "InvalidSasToken",
            "message": "The shared access signature (SAS) is invalid: {details}"
                   }
               }
          }
      ]
   }
]
...

Ejemplo de una failed respuesta de estado:

Este error solo se devuelve si hay errores en la solicitud por lotes general.
Una vez iniciada la operación de análisis por lotes, el estado de las operaciones de documentos individuales no afecta al estado del trabajo por lotes global, aunque todos los archivos tengan el estadofailed.

[
    "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
            "code": "InvalidArgument",
            "message": "Invalid argument.",
            "innererror": {
              "code": "InvalidSasToken",
              "message": "The shared access signature (SAS) is invalid: {details}"
                }
            }
        ]
    }
]
...

Ejemplo de skipped respuesta de estado:

[
    "result": {
    "succeededCount": 3,
    "failedCount": 0,
    "skippedCount": 2,
    "details": [
        ...
        "sourceUrl": "https://myStorageAccount.blob.core.windows.net/myContainer/trainingDocs/file4.jpg",
        "status": "skipped",
        "error": {
            "code": "OutputExists",
            "message": "Analysis skipped because result file {path} already exists."
             }
        ]
    }
]
...

Los resultados del análisis por lotes le ayudan a identificar qué archivos se analizan correctamente y validan los resultados del análisis comparando el archivo en con resultUrl el archivo de salida en resultContainerUrl.

Nota:

Los resultados del análisis no se devuelven para archivos individuales hasta que se haya completado el análisis por lotes de todo el conjunto de documentos. Para realizar un seguimiento detallado del progreso más allá de percentCompleted, puede supervisar*.ocr.json los archivos a medida que se escriben en elresultContainerUrl.

Pasos siguientes

Puede ver ejemplos de código en GitHub.

Compartir vía