Migración de Document Intelligence v3.1

  • Artículo

Este contenido se aplica a:checkmarkv4.0 (versión preliminar)checkmarkv3.1 (GA)checkmarkv3.0 (GA)checkmarkv2.1 (GA)

Importante

La API de REST v3.1 de Document Intelligence presenta cambios importantes en la solicitud de API REST y analiza el código JSON de respuesta.

Migración desde la versión preliminar de la API v3.1

Las API en versión preliminar se van dejando en desuso periódicamente. Si usa una versión preliminar de la API, actualice la aplicación para que tenga como destino la versión de la API de disponibilidad general (GA). Para migrar de la versión 2023-02-28-versión preliminar de la API a la versión 2023-07-31(GA) de la API usando el SDK, actualice a la versión actual del SDK específico del idioma.

La API 2023-07-31 (GA) tiene algunas actualizaciones y cambios con respecto a la versión preliminar de la API:

  • Las características que están habilitadas de manera predeterminada se limitan a las esenciales para el modelo concreto con la ventaja de reducir la latencia y el tamaño de respuesta. Las características agregadas se pueden habilitar a través de valores numéricos en features parámetro.
  • Algunas características de diseño de lectura precompilada y keyValuePairs más allá de precompilada-{documento,factura} ya no son admitidas.
  • Deshabilitación de códigos de barras de forma predeterminada para la lectura y el diseño precompilados, idiomas para la lectura precompilada y pares de valores clave para la factura precompilada.
  • Se quita la extracción de anotaciones.
  • Se quitan los campos de consulta y los nombres comunes de los pares clave-valor.
  • Los archivos Office/HTML son admitidos en el modelo de lectura precompilado, extrayendo palabras y párrafos sin recuadros delimitadores. Las imágenes incrustadas ya no se admiten. Si se solicitan características de complemento para archivos Office/HTML, se devuelve una matriz vacía sin errores.

Características de análisis

Identificador del modelo Extracción de texto Párrafos Roles de párrafo Marcas de selección Tablas Pares clave de valor Idiomas Códigos de barras Análisis de documentos Fórmulas* StyleFont* Alta resolución de OCR*
prebuilt-read ✓ ✓ O O O O O
diseño preelaborado ✓ ✓ ✓ ✓ ✓ O O O O O
prebuilt-document ✓ ✓ ✓ ✓ ✓ ✓ O O O O O
prebuilt-businessCard ✓ ✓
prebuilt-idDocument ✓ O O ✓ O O O
prebuilt-invoice ✓ ✓ ✓ O O O ✓ O O O
Recibo precompilado ✓ O O ✓ O O O
prebuilt-healthInsuranceCard.us ✓ O O ✓ O O O
prebuilt-tax.us.w2 ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098 ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098E ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098T ✓ ✓ O O ✓ O O O
contrato precompilado ✓ ✓ ✓ ✓ O O ✓ O O O
{ customModelName } ✓ ✓ ✓ ✓ ✓ O O ✓ O O O

✓ - O habilitado - Fórmulas opcionales/ StyleFont/OCR Alta Resolución* - Las características Premium incurren en costos adicionales

Migración desde la versión 3.0

En comparación con la versión 3.0, Document Intelligence v3.1 presenta varias características y funcionalidades nuevas:

  • Extracción de códigos de barras.
  • Funcionalidades de complementos, incluida la extracción de propiedades de alta resolución, fórmula y fuente.
  • Modelo de clasificación personalizado para la división y clasificación de documentos.
  • Ampliación de idiomas y soporte de nuevos campos en el modelo de Factura y Recibo.
  • Nuevo tipo de documento compatible con el modelo de Documento de id.
  • Nuevo modelo de tarjeta sanitaria precompilada.
  • Los archivos Office/HTML son admitidos en el modelo de lectura precompilado, extrayendo palabras y párrafos sin recuadros delimitadores. Las imágenes incrustadas ya no se admiten. Si se solicitan características de complemento para archivos Office/HTML, se devuelve una matriz vacía sin errores.
  • Expiración de modelos para modelos de extracción y clasificación personalizados: nuestros nuevos modelos personalizados se basan en un modelo base grande que actualizamos periódicamente para mejorar la calidad. Se introduce una fecha de expiración en todos los modelos personalizados para habilitar la retirada de los modelos base correspondientes. Una vez que expire un modelo personalizado, debe volver a entrenar el modelo mediante la versión de API más reciente (modelo base).
GET /documentModels/{customModelId}?api-version={apiVersion}
{
  "modelId": "{customModelId}",
  "description": "{customModelDescription}",
  "createdDateTime": "2023-09-24T12:54:35Z",
  "expirationDateTime": "2025-01-01T00:00:00Z",
  "apiVersion": "2023-07-31",
  "docTypes": { ... }
}
  • Cuota de compilación del modelo neuronal personalizado: el número de modelos neuronales que cada suscripción puede compilar por región cada mes es limitado. Expandimos el resultado JSON para incluir la cuota y la información usada para ayudarle a comprender el uso actual como parte de la información de recursos devuelta por GET /info.
{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}
  • Un featuresparámetro de consulta opcional de las operaciones de análisis puede habilitar funciones específicas. Algunas características prémium pueden incurrir en facturación adicional. Consulte Análisis de la lista de características para obtener más información.
  • Amplíe los objetos de campo de moneda extraídos para generar un campo de código de moneda normalizado siempre que sea posible. Actualmente, los campos actuales pueden devolver la cantidad (por ejemplo, 123.45) y currencySymbol (por ejemplo, $). Esta característica asigna el símbolo de moneda a un código ISO 4217 canónico (por ejemplo, USD). El modelo puede usar opcionalmente el contenido del documento global para eliminar la ambigüedad o deducir el código de moneda.
{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

Además de la mejora de la calidad del modelo, se recomienda encarecidamente actualizar la aplicación para que use v3.1 para beneficiarse de estas nuevas funcionalidades.

Migración desde v2.1 o v2.0

Document Intelligence v3.1 es la versión de disponibilidad general más reciente con las características más ricas, la mayoría de los lenguajes y la cobertura de tipos de documentos y la calidad mejorada del modelo. Consulte introducción al modelo para conocer las características y funcionalidades disponibles en v3.1.

A partir de la versión 3.0, la API REST del Documento de inteligencia se ha rediseñado para mejorar su uso. En esta sección, aprenda las diferencias entre Document Intelligence v2.0, v2.1 y v3.1 y cómo pasar a la versión más reciente de la API.

Precaución

  • La versión de la API de REST 31-07-2023 incluye un cambio importante en el JSON de análisis de respuesta de la API de REST.
  • Se ha cambiado el nombre de la propiedad boundingBox a polygon en cada instancia.

Cambios en los puntos de conexión de la API REST

La API REST v3.1 combina las operaciones de análisis de los análisis de diseño, los modelos precompilados y los modelos personalizados en un único par de operaciones mediante la asignación de documentModels y modelId al análisis de diseño (diseño precompilado) y modelos precompilados.

Solicitud POST

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31

Solicitud GET

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2023-07-31

Operación de análisis

  • La carga de la solicitud y el patrón de llamada permanecen sin cambios.
  • La operación de análisis especifica el documento de entrada y las configuraciones específicas del contenido, y devuelve la dirección URL del resultado de análisis a través del encabezado Operation-Location en la respuesta.
  • Sondee esta dirección URL de resultado de análisis a través de una solicitud GET para comprobar el estado de la operación de análisis (el intervalo mínimo recomendado entre las solicitudes es de 1 segundo).
  • Si es correcto, el estado se establece como correcto y en el cuerpo de la respuesta se devuelve analyzeResult. Si se producen errores, el estado se establece en failed, y se devuelve un error.
Modelo v2.0 v2.1 v3.1
Prefijo de dirección URL de solicitud https://{your-form-recognizer-endpoint}/formrecognizer/v2.0 https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
Documento general N/D N/D /documentModels/prebuilt-document:analyze
Diseño /layout/analyze /layout/analyze /documentModels/prebuilt-layout:analyze
Personalizada /custom/models/{modelId}/analyze /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Factura N/D /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Recibo /prebuilt/receipt/analyze /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Documento de identificación N/D /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Tarjeta de presentación N/D /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 N/D N/D /documentModels/prebuilt-tax.us.w2:analyze
Tarjeta de seguro de salud N/D N/D /documentModels/prebuilt-healthInsuranceCard.us:analyze
Contrato N/D N/D /documentModels/prebuilt-contract:analyze

Análisis del cuerpo de la solicitud

El contenido que se va a analizar se proporciona a través del cuerpo de la solicitud. La dirección URL o los datos codificados en Base64 se pueden usar para construir la solicitud.

Para especificar una dirección URL web de acceso público, establezca Content-Type en application/json y envíe el siguiente cuerpo JSON:

{
  "urlSource": "{urlPath}"
}

La codificación base 64 también se admite en Document Intelligence v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Parámetros admitidos adicionales

Parámetros que siguen siendo compatibles:

  • pages: analice solo un subconjunto específico de páginas del documento. Lista de números de página indizados desde el número 1 que analizar. Por ejemplo, "1-3,5,7-9"
  • locale: sugerencia de configuración regional para el reconocimiento de texto y el análisis de documentos. El valor solo puede contener el código de idioma (por ejemplo, en, fr) o la etiqueta de idioma BCP 47 (por ejemplo, "en-US").

Parámetros que ya no se admiten:

  • includeTextDetails

El nuevo formato de respuesta es más compacto y siempre se devuelve la salida completa.

Cambios en el resultado de análisis

La respuesta de análisis se ha refactorizado a los siguientes resultados de nivel superior para admitir elementos de varias páginas.

  • pages
  • tables
  • keyValuePairs
  • entities
  • styles
  • documents

Nota:

Los cambios en la respuesta analyzeResult son varios, como pasar de una propiedad de páginas a una propiedad de nivel superior dentro de analyzeResult.


{
// Basic analyze result metadata
"apiVersion": "2022-08-31", // REST API version used
"modelId": "prebuilt-invoice", // ModelId used
"stringIndexType": "textElements", // Character unit used for string offsets and lengths:
// textElements, unicodeCodePoint, utf16CodeUnit // Concatenated content in global reading order across pages.
// Words are generally delimited by space, except CJK (Chinese, Japanese, Korean) characters.
// Lines and selection marks are generally delimited by newline character.
// Selection marks are represented in Markdown emoji syntax (:selected:, :unselected:).
"content": "CONTOSO LTD.\nINVOICE\nContoso Headquarters...", "pages": [ // List of pages analyzed
{
// Basic page metadata
"pageNumber": 1, // 1-indexed page number
"angle": 0, // Orientation of content in clockwise direction (degree)
"width": 0, // Page width
"height": 0, // Page height
"unit": "pixel", // Unit for width, height, and polygon coordinates
"spans": [ // Parts of top-level content covered by page
{
"offset": 0, // Offset in content
"length": 7 // Length in content
}
], // List of words in page
"words": [
{
"text": "CONTOSO", // Equivalent to $.content.Substring(span.offset, span.length)
"boundingBox": [ ... ], // Position in page
"confidence": 0.99, // Extraction confidence
"span": { ... } // Part of top-level content covered by word
}, ...
], // List of selectionMarks in page
"selectionMarks": [
{
"state": "selected", // Selection state: selected, unselected
"boundingBox": [ ... ], // Position in page
"confidence": 0.95, // Extraction confidence
"span": { ... } // Part of top-level content covered by selection mark
}, ...
], // List of lines in page
"lines": [
{
"content": "CONTOSO LTD.", // Concatenated content of line (may contain both words and selectionMarks)
"boundingBox": [ ... ], // Position in page
"spans": [ ... ], // Parts of top-level content covered by line
}, ...
]
}, ...
], // List of extracted tables
"tables": [
{
"rowCount": 1, // Number of rows in table
"columnCount": 1, // Number of columns in table
"boundingRegions": [ // Polygons or Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"polygon": [ ... ], // Previously Bounding box, renamed to polygon in the 2022-08-31 API
}
],
"spans": [ ... ], // Parts of top-level content covered by table // List of cells in table
"cells": [
{
"kind": "stub", // Cell kind: content (default), rowHeader, columnHeader, stub, description
"rowIndex": 0, // 0-indexed row position of cell
"columnIndex": 0, // 0-indexed column position of cell
"rowSpan": 1, // Number of rows spanned by cell (default=1)
"columnSpan": 1, // Number of columns spanned by cell (default=1)
"content": "SALESPERSON", // Concatenated content of cell
"boundingRegions": [ ... ], // Bounding regions covered by cell
"spans": [ ... ] // Parts of top-level content covered by cell
}, ...
]
}, ...
], // List of extracted key-value pairs
"keyValuePairs": [
{
"key": { // Extracted key
"content": "INVOICE:", // Key content
"boundingRegions": [ ... ], // Key bounding regions
"spans": [ ... ] // Key spans
},
"value": { // Extracted value corresponding to key, if any
"content": "INV-100", // Value content
"boundingRegions": [ ... ], // Value bounding regions
"spans": [ ... ] // Value spans
},
"confidence": 0.95 // Extraction confidence
}, ...
],
"styles": [
{
"isHandwritten": true, // Is content in this style handwritten?
"spans": [ ... ], // Spans covered by this style
"confidence": 0.95 // Detection confidence
}, ...
], // List of extracted documents
"documents": [
{
"docType": "prebuilt-invoice", // Classified document type (model dependent)
"boundingRegions": [ ... ], // Document bounding regions
"spans": [ ... ], // Document spans
"confidence": 0.99, // Document splitting/classification confidence // List of extracted fields
"fields": {
"VendorName": { // Field name (docType dependent)
"type": "string", // Field value type: string, number, array, object, ...
"valueString": "CONTOSO LTD.",// Normalized field value
"content": "CONTOSO LTD.", // Raw extracted field content
"boundingRegions": [ ... ], // Field bounding regions
"spans": [ ... ], // Field spans
"confidence": 0.99 // Extraction confidence
}, ...
}
}, ...
]
}

Compilación o entrenamiento del modelo

El objeto de modelo tiene tres actualizaciones en la nueva API

  • modelId es ahora una propiedad que se puede establecer en un nombre legible para el usuario en un modelo.
  • modelName ahora se llama description
  • buildMode es una nueva propiedad con los valores de template para los modelos de formularios personalizados o de neural para los modelos neuronales personalizados.

La operación build se invoca para entrenar un modelo. La carga de la solicitud y el patrón de llamada permanecen sin cambios. La operación de compilación especifica el modelo y el conjunto de datos de entrenamiento, y devuelve el resultado a través del encabezado Operation-Location de la respuesta. Sondee esta dirección URL de la operación de modelo a través de una solicitud GET para comprobar el estado de la operación de compilación (el intervalo mínimo recomendado entre las solicitudes es de 1 segundo). A diferencia de la versión 2.1, esta dirección URL no es la ubicación de recursos del modelo. En su lugar, la dirección URL del modelo se puede construir a partir del valor de modelId especificado, que también se recupera de la propiedad resourceLocation en la respuesta. Si la operación es correcta, el estado se establece en succeeded y el resultado contiene la información del modelo personalizado. Si se producen errores, el estado se establece en failed y se devuelve el error.

El código siguiente es una solicitud de compilación de ejemplo mediante un token de SAS. Tenga en cuenta la barra diagonal final al establecer la ruta de acceso del prefijo o de la carpeta.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:build?api-version=2022-08-31

{
  "modelId": {modelId},
  "description": "Sample model",
  "buildMode": "template",
  "azureBlobSource": {
    "containerUrl": "https://{storageAccount}.blob.core.windows.net/{containerName}?{sasToken}",
    "prefix": "{folderName/}"
  }
}

Cambios en la composición de modelos

La composición de modelos ahora está limitada a un único nivel de anidamiento. Los modelos compuestos ahora son coherentes con los modelos personalizados gracias a la adición de las propiedades modelId y description.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:compose?api-version=2022-08-31
{
  "modelId": "{composedModelId}",
  "description": "{composedModelDescription}",
  "componentModels": [
    { "modelId": "{modelId1}" },
    { "modelId": "{modelId2}" },
  ]
}

Cambios en el modelo de copia

El patrón de llamada para el modelo de copia permanece sin cambios:

  • Autorización de la operación de copia con el recurso de destino llamando a authorizeCopy. Ahora, una solicitud POST.
  • Envío de la autorización al recurso de origen para copiar el modelo llamando a copyTo.
  • Sondeo de la operación devuelta para validar que la operación se completó correctamente.

Los únicos cambios en la función del modelo de copia son:

  • La acción HTTP en authorizeCopy ahora es una solicitud POST.
  • La carga de autorización contiene toda la información necesaria para enviar la solicitud de copia.

Autorizar la copia

POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2022-08-31
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

Use el cuerpo de respuesta de la acción de autorización para construir la solicitud de la copia.

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copyTo?api-version=2022-08-31
{
  "targetResourceId": "{targetResourceId}",
  "targetResourceRegion": "{targetResourceRegion}",
  "targetModelId": "{targetModelId}",
  "targetModelLocation": "https://{targetHost}/formrecognizer/documentModels/{targetModelId}",
  "accessToken": "{accessToken}",
  "expirationDateTime": "2021-08-02T03:56:11Z"
}

Cambios en los modelos de lista

Los modelos de lista se amplían para devolver ahora modelos pregenerados y personalizados. Todos los nombres de modelos precompilados comienzan por prebuilt-. Solo se devuelven los modelos con el estado correcto. Para enumerar los modelos con errores o en curso, consulte Operaciones de enumeración.

Solicitud de enumeración de modelos de ejemplo

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2022-08-31

Cambio en el modelo de obtención

Como el modelo de obtención incluye ahora modelos precompilados, la operación de obtención devuelve un diccionario docTypes. La descripción de cada tipo de documento incluye el nombre, la descripción opcional, el esquema del campo y la confianza del campo opcional. El esquema de campo describe la lista de campos posiblemente devueltos con el tipo de documento.

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31

Nueva operación de obtención de información

La operación info en el servicio devuelve el recuento y el límite de modelos personalizados.

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-08-31

Respuesta de muestra

{
  "customDocumentModels": {
    "count": 5,
    "limit": 100
  }
}

Pasos siguientes