Migração do Document Intelligence v3.1

  • Artigo

Este conteúdo se aplica a:checkmarkv4.0 (versão prévia)checkmarkv3.1 (GA)checkmarkv3.0 (GA)checkmarkv2.1 (GA)

Importante

A API REST v3.1 do Document Intelligence apresenta alterações interruptivas na solicitação da API REST e analisa a resposta JSON.

Migrando da versão prévia da API v3.1

As APIs de versão prévia são preteridas periodicamente. Se você estiver usando uma API de versão prévia, atualize seu aplicativo para a versão da API de disponibilidade geral. Para migrar da versão da API 2023-02-28-preview para a versão da API (GA) 2023-07-31 usando o SDK, atualize para a versão atual do SDK específico do idioma.

A API (GA) 2023-07-31 tem algumas atualizações e alterações em relação à API de versão prévia:

  • Os recursos habilitados por padrão são limitados aos essenciais para o modelo específico com o benefício de latência e tamanho de resposta reduzidos. Os recursos adicionados podem ser habilitados por meio de valores de enumeração no parâmetro features.
  • Alguns recursos de layout de leitura predefinida e keyValuePairs, além do prebuilt-{document,invoice}, não tem mais suporte.
  • Desabilitando códigos de barras por padrão para leitura predefinida e layout predefinido, idiomas para leitura predefinida e keyValuePairs para fatura predefinida.
  • A extração de anotações foi removida.
  • Os campos de consulta e nomes comuns de pares chave-valor foram removidos.
  • Há suporte para arquivos Office/HTML no modelo de leitura predefinida, extraindo palavras e parágrafos sem caixas delimitadoras. Não há mais suporte para imagens incorporadas. Se recursos complementares forem solicitados para arquivos do Office/HTML, uma matriz vazia será retornada sem erros.

Recursos de análise

ID do modelo Extração de Texto Parágrafos Funções de Parágrafo Marcas de Seleção Tabelas Pares Chave-Valor Idiomas Códigos de barras Análise de Documentos Fórmulas* StyleFont* Alta Resolução do OCR*
prebuilt-read ✓ ✓ O O O O O
prebuilt-layout ✓ ✓ ✓ ✓ ✓ 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
prebuilt-receipt ✓ 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
prebuilt-contract ✓ ✓ ✓ ✓ O O ✓ O O O
{ customModelName } ✓ ✓ ✓ ✓ ✓ O O ✓ O O O

✓ - O habilitado - Fórmulas Opcionais/StyleFont/Alta Resolução do OCR* - Os recursos Premium incorrem em custos adicionais

Migrando da v3.0

Comparado com a v3.0, o Document Intelligence v3.1 apresenta vários novos recursos e funcionalidades:

  • Extração de código de barras.
  • Recursos de complemento, incluindo alta resolução, fórmula e extração de propriedades de fonte.
  • Modelo de classificação personalizada para divisão e classificação de documentos.
  • Expansão do idioma e suporte a novos campos no modelo de Fatura e Recibo.
  • Suporte a novo tipo de documento no modelo de documento de ID.
  • Novo modelo de Cartão de plano de saúde predefinido.
  • Há suporte para arquivos Office/HTML no modelo de leitura predefinida, extraindo palavras e parágrafos sem caixas delimitadoras. Não há mais suporte para imagens incorporadas. Se recursos complementares forem solicitados para arquivos do Office/HTML, uma matriz vazia será retornada sem erros.
  • Validade do modelo para modelos personalizados de extração e classificação - Nossos novos modelos personalizados se baseiam em um grande modelo básico que atualizamos periodicamente para melhorar a qualidade. Uma data de validade é introduzida em todos os modelos personalizados para permitir a desativação dos modelos básicos correspondentes. Depois que um modelo personalizado expira, você precisa treinar novamente o modelo usando a versão mais recente da API (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": { ... }
}
  • Cota de criação de modelo neural personalizado - O número de modelos neurais que cada assinatura pode criar por região a cada mês é limitado. Expandimos o JSON do resultado para incluir a cota e as informações usadas para ajudar você a entender o uso atual como parte das informações do recurso retornadas por GET /info.
{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}
  • Um parâmetro de consulta features opcional para analisar as operações pode, opcionalmente, habilitar recursos específicos. Alguns recursos premium podem incorrer em cobrança adicional. Veja Analisar lista de recursos para obter detalhes.
  • Estenda os objetos de campo de moeda extraídos para gerar um campo de código de moeda normalizado quando possível. Atualmente, os campos atuais podem retornar valor (por exemplo, 123,45) e currencySymbol (por exemplo, $). Esse recurso mapeia o símbolo de moeda para um código ISO 4217 canônico (ex. USD). Opcionalmente, o modelo pode utilizar o conteúdo global do documento para eliminar a ambiguidade ou inferir o código da moeda.
{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

Além da melhoria da qualidade do modelo, é altamente recomendável atualizar seu aplicativo para usar a v3.1 para se beneficiar desses novos recursos.

Migrando da v2.1 ou v2.0

O Document Intelligence v3.1 é a versão mais recente de GA com os recursos mais avançados, a maioria dos idiomas e cobertura de tipos de documento e qualidade de modelo aprimorada. Veja a visão geral do modelo para obter os recursos e funcionalidades disponíveis na v3.1.

A partir da versão v3.0, a API REST do Document Intelligence foi reprojetada para melhor usabilidade. Nesta seção, saiba as diferenças entre Document Intelligence v2.0, v2.1 e v3.1 e como migrar para a versão mais recente da API.

Cuidado

  • A versão 2023-07-31 da API REST inclui uma alteração significativa no JSON de resposta de análise da API REST.
  • A propriedade boundingBox é renomeada para polygon em cada instância.

Alterações nos pontos de extremidade da API REST

A API REST v3.1 combina as operações de análise de layout, modelos predefinidos e modelos personalizados em um único par de operações, atribuindo o documentModels e modelId à análise de layout (layout predefinido) e modelos predefinido.

Solicitação POST

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

Solicitação GET

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

Operação de análise

  • O conteúdo de solicitação e o padrão de chamada permanecem inalterados.
  • A operação de análise especifica o documento de entrada e as configurações específicas de conteúdo, retornando a URL de resultado de análise por meio do cabeçalho Operation-Location na resposta.
  • Sonde esta URL de resultado de análise por meio de uma solicitação GET para verificar o status da operação de análise (o intervalo mínimo recomendado entre solicitações é de 1 segundo).
  • Após o êxito, o status é definido como bem-sucedido e analyzeResult é retornado no corpo da resposta. Se forem encontrados erros, o status será definido como failed, e um erro será retornado.
Modelar v2.0 v2.1 v3.1
Prefixo da URL de solicitação https://{your-form-recognizer-endpoint}/formrecognizer/v2.0 https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
Documentação geral N/D N/D /documentModels/prebuilt-document:analyze
Layout /layout/analyze /layout/analyze /documentModels/prebuilt-layout:analyze
Personalizado /custom/models/{modelId}/analyze /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Fatura N/D /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Receipt /prebuilt/receipt/analyze /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Documento de identificação N/D /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Cartão de visita N/D /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 N/D N/D /documentModels/prebuilt-tax.us.w2:analyze
cartão do seguro de saúde N/D N/D /documentModels/prebuilt-healthInsuranceCard.us:analyze
Contrato N/D N/D /documentModels/prebuilt-contract:analyze

Analisar o corpo da solicitação

O conteúdo a ser analisado é fornecido por meio do corpo da solicitação. A URL ou os dados codificados em base64 podem ser usados para construir a solicitação.

Para especificar uma URL da Web publicamente acessível, defina o  Content-Type comoapplication/json e envie o corpo do JSON a seguir:

{
  "urlSource": "{urlPath}"
}

A codificação Base 64 também tem suporte no Document Intelligence v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Parâmetros com suporte de forma adicional

Parâmetros que continuam com suporte:

  • pages: analise apenas um subconjunto específico de páginas no documento. Lista de números de página indexados do número 1 a ser analisado. Ex.: "1-3,5,7-9"
  • locale: dica de localidade para reconhecimento de texto e análise de documentos. O valor pode conter apenas o código de idioma (por exemplo, en, fr) ou a marca de idioma do BCP 47 (por exemplo "en-US").

Parâmetros que não têm mais suporte:

  • includeTextDetails

O novo formato de resposta é mais compacto e a saída completa sempre é retornada.

Alterações para analisar o resultado

A resposta de análise é refatorada para os seguintes resultados de nível superior a fim de dar suporte a elementos de várias páginas.

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

Observação

As alterações de resposta do analyzeResult incluem várias alterações, como mover para cima de uma propriedade de páginas para uma propriedade de alavanca 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
}, ...
}
}, ...
]
}

Modelo de compilação ou treinamento

O objeto de modelo tem duas atualizações na nova API

  • modelId agora é uma propriedade que pode ser definida em um modelo para um nome legível humano.
  • modelName foi renomeado para description
  • buildMode é uma nova propriedade com valores template para modelos de formulário personalizados ou neural para modelos neurais personalizados.

A operação build é invocada para treinar um modelo. O conteúdo de solicitação e o padrão de chamada permanecem inalterados. A operação de compilação especifica o modelo e o conjunto de resultados de treinamento, retorna o resultado por meio do cabeçalho Operation-Location na resposta. Sonde esta URL operação de modelo por meio de uma solicitação GET para verificar o status da operação de compilação (o intervalo mínimo recomendado entre solicitações é de 1 segundo). Ao contrário da v2.1, essa URL não é o local do recurso do modelo. Em vez disso, a URL do modelo pode ser construída a partir do modelId fornecido, também recuperada da propriedade resourceLocation na resposta. Após o êxito, o status é definido como succeeded e o resultado contém as informações do modelo personalizado. Se forem encontrados erros, o status será definido como failed e o erro será retornado.

O código a seguir é uma solicitação de compilação de exemplo usando um token SAS. Observe a barra à direita ao definir o prefixo ou o caminho da pasta.

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/}"
  }
}

Alterações no modelo de composição

A composição de modelo agora está limitada a um único nível de aninhamento. Os modelos compostos agora são consistentes com modelos personalizados com a adição de propriedades modelId e description.

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

Alterações no modelo de cópia

O padrão de chamada para o modelo de cópia permanece inalterado:

  • Autorize a operação de cópia com a chamada de recurso de destino authorizeCopy. Agora uma solicitação POST.
  • Enviar a autorização para o recurso de origem para copiar a chamada de modelo copyTo
  • Sondar a operação retornada para validar que a operação foi concluída com êxito

As únicas alterações na função de modelo de cópia são:

  • A ação HTTP na authorizeCopy agora é uma solicitação POST.
  • A carga de autorização contém todas as informações necessárias para enviar a solicitação de cópia.

Autorize a cópia

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

Use o corpo da resposta da ação autorizar para construir a solicitação para a cópia.

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

Alterações em modelos de lista

Os modelos de lista são estendidos para agora retornar modelos predefinidos e personalizados. Todos os nomes de modelo predefinidos começam com prebuilt-. Somente os modelos com um status de êxito são retornados. Para listar modelos que falharam ou estão em andamento, consulte Operações de lista.

Solicitação de modelos de lista de exemplo

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

Alterar para obter o modelo

Como obter modelo agora inclui modelos pré-construídos, a operação get retorna um dicionário docTypes. Cada descrição de tipo de documento inclui nome, descrição opcional, esquema de campo e confiança de campo opcional. O esquema de campo descreve a lista de campos potencialmente retornados com o tipo de documento.

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

Nova operação obter informações

A operação info no serviço retorna a contagem de modelos personalizados e o limite de modelo personalizado.

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

Resposta de exemplo

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

Próximas etapas