Partilhar via

Migração do Document Intelligence v3.1

  • Artigo

Este conteúdo aplica-se a: marca de verificação v4.0 (pré-visualização) marca de verificação v3.1 (GA)marca de verificação v3.0 (GA) marca de verificação v2.1 (GA)

Importante

Document Intelligence REST API v3.1 introduz alterações significativas na solicitação da API REST e analisa o JSON de resposta.

Migrando da versão da API de visualização v3.1

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

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

  • 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. Recursos adicionados podem ser ativados através de valores enum no features parâmetro.
  • Alguns recursos de layout de leitura pré-construída e keyValuePairs além de prebuilt-{document,invoice} não são mais suportados.
  • Desativando códigos de barras por padrão para leitura pré-construída e layout pré-construído, idiomas para leitura pré-construída e keyValuePairs para fatura pré-construída.
  • A extração de anotações é removida.
  • Os campos de consulta e os nomes comuns dos pares chave-valor são removidos.
  • Os arquivos Office/HTML são suportados no modelo de leitura pré-incorporada, extraindo palavras e parágrafos sem caixas delimitadoras. As imagens incorporadas não são mais suportadas. Se recursos de complemento forem solicitados para arquivos Office/HTML, uma matriz vazia será retornada sem erros.

Recursos de análise

Model ID 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 Documental Fórmulas* StyleFont* OCR de alta resolução*
leitura pré-embutida ✓ ✓ O O O O O
layout pré-construído ✓ ✓ ✓ ✓ ✓ O O O O O
documento pré-construído ✓ ✓ ✓ ✓ ✓ ✓ O O O O O
cartão de visita pré-construído ✓ ✓
prebuilt-idDocument ✓ O O ✓ O O O
fatura pré-embutida ✓ ✓ ✓ O O O ✓ O O O
recibo pré-embutido ✓ O O ✓ O O O
prebuilt-healthInsuranceCard.us ✓ O O ✓ O O O
pré-construído-tax.us.w2 ✓ ✓ O O ✓ O O O
pré-construído-tax.us.1098 ✓ ✓ O O ✓ O O O
pré-construído-tax.us.1098E ✓ ✓ O O ✓ O O O
pré-construído-tax.us.1098T ✓ ✓ O O ✓ O O O
contrato pré-construído ✓ ✓ ✓ ✓ O O ✓ O O O
{ customModelName } ✓ ✓ ✓ ✓ ✓ O O ✓ O O O

✓ - Ativado O - Fórmulas opcionais / StyleFont / OCR de alta resolução* - Recursos premium incorrem em custos adicionais

Migrando da v3.0

Em comparação com a v3.0, o Document Intelligence v3.1 introduz vários novos recursos e capacidades:

  • Extração de código de barras .
  • Recursos complementares , incluindo extração de alta resolução, fórmula e propriedades de fonte.
  • Modelo de classificação personalizado para divisão e classificação de documentos.
  • Expansão linguística e suporte a novos campos no modelo de Fatura e Recibo .
  • Suporte a novo tipo de documento no modelo de documento ID.
  • Novo modelo de cartão de seguro de saúde pré-construído.
  • Os arquivos Office/HTML são suportados no modelo de leitura pré-incorporada, extraindo palavras e parágrafos sem caixas delimitadoras. As imagens incorporadas não são mais suportadas. Se recursos de complemento forem solicitados para arquivos Office/HTML, uma matriz vazia será retornada sem erros.
  • Expiração de modelos para extração personalizada e modelos de classificação - Nossos novos modelos personalizados se baseiam em um modelo de base grande que atualizamos periodicamente para melhorar a qualidade. Uma data de expiração é introduzida em todos os modelos personalizados para permitir a desativação dos modelos básicos correspondentes. Quando um modelo personalizado expirar, você precisará 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 construçã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 de resultado para incluir a cota e as informações usadas para ajudá-lo a entender o uso atual como parte das informações de recursos retornadas por GET /info.
{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}
  • Um parâmetro de consulta opcional features para operações Analyze pode, opcionalmente, habilitar recursos específicos. Algumas funcionalidades premium podem incorrer em faturação adicional. Consulte Analisar lista de recursos para obter detalhes.
  • Estenda os objetos de campo de moeda extraídos para produzir um campo de código de moeda normalizado quando possível. Atualmente, os campos atuais podem retornar amount (ex. 123.45) e currencySymbol (ex. $). Este recurso mapeia o símbolo da moeda para um código canônico ISO 4217 (ex. USD). O modelo pode, opcionalmente, utilizar o conteúdo global do documento para desambiguar 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 do GA com os recursos mais ricos, a maioria dos idiomas e tipos de documentos e a melhor qualidade do modelo. Consulte a visão geral do modelo para obter os recursos e capacidades disponíveis na v3.1.

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

Atenção

  • 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 boundingBox propriedade é 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 para análise de layout, modelos pré-construídos e modelos personalizados em um único par de operações, atribuindo documentModels e modelId à análise de layout e modelos pré-construídos.

Pedido POST

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

Pedido GET

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

Analise a operação

  • A carga útil da solicitação e o padrão de chamada permanecem inalterados.
  • A operação Analyze especifica o documento de entrada e as configurações específicas do conteúdo, ela retorna a URL do resultado da análise por meio do cabeçalho Operation-Location na resposta.
  • Sonde este 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 as 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.
Modelo v2.0 v2,1 v3,1
Prefixo de URL de solicitação https://{seu-formulário-recognizer-endpoint}/formrecognizer/v2.0 https://{seu-formulário-recognizer-endpoint}/formrecognizer/v2.1 https://{seu-formulário-recognizer-endpoint}/formrecognizer
Documento geral N/A N/A /documentModels/prebuilt-document:analyze
Esquema /layout/analisar /layout/analisar /documentModels/prebuilt-layout:analyze
Personalizadas /custom/models/{modelId}/analyze /custom/{modelId}/analisar /documentModels/{modelId}:analyze
Fatura N/A /pré-construído/fatura/analisar /documentModels/prebuilt-invoice:analyze
Receção /pré-construído/recibo/analisar /pré-construído/recibo/analisar /documentModels/prebuilt-receipt:analyze
Documento de identificação N/A /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Cartão de visita N/A /prebuilt/businessCard/analisar /documentModels/prebuilt-businessCard:analyze
W-2 N/A N/A /documentModels/prebuilt-tax.us.w2:analyze
Cartão de seguro de doença N/A N/A /documentModels/prebuilt-healthInsuranceCard.us:analyze
Contrato N/A N/A /documentModels/prebuilt-contract:analyze

Analise o corpo da solicitação

O conteúdo a ser analisado é fornecido através do corpo solicitante. A URL ou os dados codificados em base64 podem ser usados pelo usuário para construir a solicitação.

Para especificar uma URL da Web acessível publicamente, defina Content-Type como application/json e envie o seguinte corpo JSON:

{
  "urlSource": "{urlPath}"
}

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

{
  "base64Source": "{base64EncodedContent}"
}

Além disso, os parâmetros suportados

Parâmetros que continuam a ser suportados:

  • pages : Analise apenas um subconjunto específico de páginas no documento. Lista de números de página indexados a partir do número 1 a analisar. 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 (ex. , fr) ou a marca de idioma BCP 47 (ex. en"en-US").

Parâmetros não suportados mais:

  • 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 para oferecer suporte a elementos de várias páginas.

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

Nota

As alterações de resposta analyzeResult incluem uma série de alterações, como subir de uma propriedade de pages para uma propriedade de alavanca superior dentro 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
}, ...
}
}, ...
]
}

Construir ou treinar modelo

O objeto de modelo tem três atualizações na nova API

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

A build operação é invocada para treinar um modelo. A carga útil da solicitação e o padrão de chamada permanecem inalterados. A operação de compilação especifica o modelo e o conjunto de dados de treinamento, retorna o resultado por meio do cabeçalho Operation-Location na resposta. Sonde a URL da operação deste modelo, por meio de uma solicitação GET para verificar o status da operação de compilação (o intervalo mínimo recomendado entre as solicitações é de 1 segundo). Ao contrário da v2.1, este URL não é a localização do recurso do modelo. Em vez disso, a URL do modelo pode ser construída a partir de um determinado modelId, também recuperado 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 do 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 modelId e description propriedades.

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 authorizeCopydo recurso de destino . Agora um pedido POST.
  • Enviar a autorização para o recurso de origem para copiar a chamada de modelo copyTo
  • Sondar a operação retornada para validar a operação concluída com êxito

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

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

Autorizar a cópia

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

Use o corpo de resposta da ação authorize 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 aos modelos de lista

Os modelos de lista são estendidos para agora retornar modelos pré-construídos e personalizados. Todos os nomes de modelos pré-construídos começam com prebuilt-. Apenas os modelos com status de bem-sucedido são retornados. Para listar modelos que falharam ou estão em andamento, consulte Listar operações.

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 o modelo get agora inclui modelos pré-construídos, a operação get retorna um docTypes dicionário. 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 get info

A info operação 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 amostra

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

Próximos passos