Migración de Document Intelligence v4.0

Guías de migración del SDK

Para obtener instrucciones sobre cómo actualizar el código de la aplicación para usar los SDK v4.0, consulte las guías de migración del SDK específicas del lenguaje en nuestros repositorios de GitHub. Estas guías proporcionan instrucciones para actualizar el código para llamar a los nuevos métodos de API y controlar los formatos de respuesta actualizados introducidos en v4.0:

• SDK de .NET/C#

• SDK de Java

• SDK de Python

• SDK de JavaScript/TypeScript*

Migración de v3.1 a v4.0

Las API en versión preliminar se vuelven obsoletas 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. Para migrar desde una versión preliminar de la API a la 2024-11-30 (GA) versión de API mediante el SDK, actualice a la versión actual del SDK específico del lenguaje. Las versiones anteriores de la API v3.x se retirarán según las programaciones publicadas; v3.0 se retira el 30 de marzo de 2029.

Características de análisis

✓ - 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 alta resolución, la fórmula y la extracción de propiedades de fuente.
• Modelo de clasificación personalizado para la división y clasificación de documentos.
• Soporte para la ampliación de idiomas y los nuevos campos en el modelo Invoice y Receipt.
• Nuevo tipo de documento compatible con el modelo de Documento de id.
• Nuevo modelo de tarjeta de seguro de salud precompilado.
• Los archivos Office/HTML se admiten en el modelo de lectura preconstruido, extrayendo palabras y párrafos sin cajas delimitadoras. 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 del modelo 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 limitada. Expandimos el JSON de resultado 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 parámetro de consulta opcional features para analizar operaciones puede habilitar opcionalmente características específicas. Algunas características premium pueden incurrir en facturación agregada. Consulte Analyze feature list (Analizar 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 utilizar opcionalmente el contenido global del documento para desambiguar 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 usar v3.1 para beneficiarse de estas nuevas funcionalidades.

Migración desde v2.1 o v2.0

Document Intelligence v4.0 es la última versión de disponibilidad general, con la gama de funcionalidades más completa, la mayor cobertura de idiomas y tipos de documento, y una mejor calidad de los modelos. Consulte información general sobre el modelo para conocer las características y funcionalidades disponibles en v4.0.

A partir de la versión 3.0, la API REST de Document Intelligence se ha rediseñado para mejorar la facilidad de uso. En esta sección, aprenderá 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.

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

La API REST v3.1 combina las operaciones de análisis para el análisis de diseño, los modelos predefinidos y los modelos personalizados en un único par de operaciones al asignar documentModels y modelId al análisis de diseño y a los modelos predefinidos.

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

Análisis de la operación

• La carga de solicitud y el patrón de llamada permanecen sin cambios.
• La Analyze operación especifica las configuraciones específicas del documento de entrada y el contenido, devuelve la dirección URL del resultado analizada a través del encabezado Operation-Location en la respuesta.
• Sondee la Analyze Result dirección URL a través de una solicitud GET para comprobar el estado de la Analyze operación (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 detectan errores, el estado se establece en failed y se devuelve un error.

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 pueden ser utilizados para construir la solicitud.

Para especificar una dirección URL web accesible públicamente, 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 además

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 indexados desde el número 1 para analizar. Por ejemplo, "1-3,5,7-9"
• locale : sugerencia de localización 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 BCP 47 etiqueta de idioma (por ejemplo, "en-US").

Los parámetros ya no se admiten:

• includeTextDetails

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

Cambios para analizar el resultado

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

{
// 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 ahora es una propiedad que se puede establecer en un modelo para un nombre legible por humanos.
• modelName se cambia el nombre a description
• buildMode es una nueva propiedad con valores de template para modelos de formulario personalizados o neural para modelos neuronales personalizados.

La build operación se invoca para entrenar un modelo. La carga de 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, devuelve el resultado a través del encabezado Operation-Location en la respuesta. Sondee esta dirección URL de la operación del 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 v2.1, esta dirección URL no es la ubicación del recurso 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. Al tener éxito, el estado se establece en succeeded y el resultado contiene la información del modelo personalizado. Si se detectan errores, el estado se establece en failedy 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 el modelo de composición

La composición de modelos ahora está limitada a un único nivel de anidamiento. Los modelos compuestos ahora son coherentes con los modelos personalizados con 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:

• Autorice la operación de copia llamando al recurso de destino authorizeCopy. Ahora una solicitud POST.
• Enviar la autorización al recurso de origen y copiar la invocación del modelo copyTo
• Consulte la operación devuelta para verificar que se ha completado correctamente.

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

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

Autorización de 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

Ahora, los modelos de lista se extienden para incluir modelos predefinidos y personalizados. Todos los nombres de modelo creados previamente comienzan por prebuilt-. Solo se devuelven los modelos con el estado correcto. Para enumerar los modelos con errores o que están en curso, consulte Operaciones de lista.

Solicitud de modelos de lista de ejemplo

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

Cambio en la operación de obtención de modelos

Como Get Model ahora incluye modelos precompilados, la Get operación devuelve un docTypes diccionario. Cada descripción del tipo de documento incluye nombre, descripción opcional, esquema de campo y confianza de campo opcional. El esquema de campo describe la lista de campos que se pueden devolver 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 del servicio devuelve el número de modelos personalizados y el límite de modelos personalizados.

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

Respuesta de ejemplo

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

Pasos siguientes

• Revisión de la nueva API REST
• ¿Qué es La inteligencia de documentos?
• Inicio rápido de Document Intelligence 0