Compartir a través de

Análisis por lotes de Document Intelligence (versión preliminar)

  • Artículo

Importante

  • Las versiones preliminares públicas de Documento de inteligencia proporcionan acceso anticipado a las características que están en desarrollo activo. Antes de la disponibilidad general (GA), las características, los enfoques y los procesos podrían cambiar en función de los comentarios de los usuarios.
  • La versión preliminar pública de las bibliotecas cliente de Documento de inteligencia tiene como valor predeterminado la versión de la API de REST 2024-07-31-preview.
  • La versión preliminar pública 2024-07-31-preview solo está disponible en las siguientes regiones de Azure. Tenga en cuenta que el modelo generativo personalizado (extracción de campos del documento) en AI Studio solo está disponible en la región Centro-norte de EE. UU.:
    • Este de EE. UU.
    • Oeste de EE. UU. 2
    • Oeste de Europa
    • Centro-Norte de EE. UU

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 facturas, una serie de documentos de préstamo o un grupo de documentos de formación de modelos personalizados.

  • 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.

Los modelos siguientes admiten el análisis por lotes:

  • Lectura. Extraiga líneas de texto, palabras, idiomas detectados y estilo manuscrito de formularios y documentos.

  • Diseño. Extraiga texto, tablas, marcas de selección e información de estructura de formularios y documentos.

  • Plantilla personalizada. Entrene modelos para extraer pares clave/valor, marcas de selección, tablas, campos de firma y regiones de formularios estructurados.

  • Neuronal personalizada. Entrene modelos para extraer campos de datos especificados de documentos estructurados, semiestructurados y no estructurados.

  • Modelo generativo personalizado. Entrene modelos para extraer datos especificados de objetos complejos, como tablas anidadas, campos abstractos o generativos y formatos realmente no estructurados.

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.

  • El azureBlobFileListSource parámetro se puede usar para dividir las solicitudes más grandes en las más pequeñas.

  • 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 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.

    • Si usa el mismo contenedor, establezca 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.

Permitir solo una azureBlobSource o azureBlobFileListSource.

POST /documentModels/{modelId}:analyzeBatch

[
  {
    "azureBlobSource": {
      "containerUrl": "{your-source-container-SAS-URL}",
      "prefix": "trainingDocs/"
    },
    "azureBlobFileListSource": {
      "containerUrl": "{your-source-container-SAS-URL}",
      "fileList": "myFileList.jsonl"
    },
    "resultContainerUrl": "{your-result-container-SAS-URL}",
    "resultPrefix": "trainingDocsResult/",
    "overwriteExisting": false
  }
]

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.