Migração do Document Intelligence v4.0

Guias de migração SDk

Para orientações sobre como atualizar o código da sua aplicação para usar os SDKs v4.0, consulte os guias de migração de SDKs específicos por linguagem nos nossos repositórios do GitHub. Estes guias fornecem instruções para atualizar o seu código para chamar os novos métodos da API e lidar com os formatos de resposta atualizados introduzidos na v4.0:

• .NET/C# SDK

• Java SDK

• Python SDK

• JavaScript/TypeScript SDK*

Migração da v3.1 para a v4.0

As APIs de Pré-visualização são periodicamente descontinuadas. Se estiver a usar uma versão da API de pré-visualização, atualize a sua aplicação para direcionar a versão da API GA. Para migrar de uma versão de pré-visualização da API para a 2024-11-30 (GA) versão da API usando o SDK, atualize para a versão atual do SDK específico da linguagem.

Funcionalidades de análise

✓ - Ativado O - Fórmulas Opcionais/StyleFont/OCR Alta Resolução* - As funcionalidades premium acarretam custos adicionais

Migração da v3.0

Comparado com a v3.0, o Document Intelligence v3.1 introduz várias novas funcionalidades e capacidades:

• Extração de código de barras .
• Capacidades adicionais incluindo alta resolução, extração de fórmulas e propriedades de fontes.
• Modelo personalizado de classificação para divisão e classificação de documentos.
• Expansão linguística e suporte de novos campos no modelo de Fatura e Recibo .
• Suporte para novos tipos de documentos no modelo de documentos de identificação.
• Novo modelo pré-construído de cartão de seguro de saúde .
• Os ficheiros Office/HTML são suportados em modelos pré-construídos de leitura, extraindo palavras e parágrafos sem caixas delimitadoras. Imagens embutidas já não são suportadas. Se forem solicitadas funcionalidades adicionais para ficheiros Office/HTML, um array vazio é devolvido sem erros.
• Expiração do modelo para modelos personalizados de extração e classificação - Os nossos novos modelos personalizados baseiam-se num grande modelo base que atualizamos periodicamente para melhoria de qualidade. É introduzida uma data de validade para todos os modelos personalizados para permitir a aposentação dos modelos base correspondentes. Quando um modelo personalizado expira, é necessário re-treinar 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": { ... }
}

• Quota de construção de modelos neurais personalizados - O número de modelos neurais que cada subscrição pode construir por região todos os meses é limitado. Expandimos o resultado em JSON para incluir a quota e a informação usada para o ajudar a compreender o uso atual como parte da informação de recurso devolvida pelo GET /info.

{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}

• Um parâmetro opcional features de consulta para Analisar operações pode ativar funcionalidades específicas. Algumas funcionalidades premium podem acarretar faturação adicional. Consulte a lista de funcionalidades de Análise para mais detalhes.
• Estender os objetos do campo de moeda extraída para gerar um campo de código de moeda normalizado sempre que possível. Atualmente, os campos podem devolver montante (ex. 123,45) e símbolo da moeda (ex. $). Esta funcionalidade 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 de moeda.

{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

Além da melhoria da qualidade do modelo, é altamente recomendado que atualize a sua aplicação para usar a versão 3.1 e beneficiar destas novas capacidades.

Migração da v2.1 ou v2.0

O Document Intelligence v3.1 é a versão mais recente de GA com as funcionalidades mais avançadas, cobertura de quase todas as linguagens e tipos de documentos, e melhoria da qualidade dos modelos. Consulte a visão geral do modelo para as funcionalidades e capacidades disponíveis na v3.1.

A partir da versão 3.0, a API REST de Document Intelligence é redesenhada para melhor usabilidade. Nesta secção, aprenda as diferenças entre o Document Intelligence v2.0, v2.1 e v3.1 e como migrar para a versão mais recente da API.

Alterações aos endpoints 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 num único par de operações, atribuindo documentModels e modelId à análise de layout e aos 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

Analisar a operação

• A carga útil da solicitação e o padrão de chamada permanecem inalterados.
• A Analyze operação especifica o documento de entrada e as configurações específicas do conteúdo, devolvendo o URL do resultado analisado através do cabeçalho Operation-Location na resposta.
• Consulta a Analyze Result URL, através de um pedido GET, para verificar o estado da Analyze operação (o intervalo mínimo recomendado entre pedidos é de 1 segundo).
• Após o sucesso, o estado é definido como bem-sucedido e analyzeResult é devolvido no corpo da resposta. Se forem encontrados erros, o estado é definido para failed, e um erro é retornado.

Analisar o corpo do pedido

O conteúdo a analisar é fornecido através do corpo do pedido. Tanto a URL como os dados codificados em base64 podem ser usados pelo utilizador para efetuar o pedido.

Para especificar uma URL da Web publicamente acessível, defina o Tipo de Conteúdo para 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}"
}

Parâmetros adicionalmente suportados

Parâmetros que continuam a ser suportados:

• pages : Analisar 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 localização para reconhecimento de texto e análise de documentos. O valor pode conter apenas o código da língua (ex. en, fr) ou BCP a etiqueta de 47 línguas (ex. "en-US").

Parâmetros já não suportados:

• incluiTextoDetalhes

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

Alterações na análise dos resultados

A resposta de análise é refatorada para os seguintes resultados de alto nível e suporta elementos de várias 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
}, ...
}
}, ...
]
}

Construir ou treinar modelo

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

• modelId é agora uma propriedade que pode ser definida num modelo para um nome legível por humanos.
• modelName é renomeado para description
• buildMode é uma nova propriedade com valores de template para modelos de forma 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 build especifica o modelo e o conjunto de dados de treino, devolvendo o resultado através do cabeçalho Operation-Location na resposta. Consulte esta URL da operação modelo, através de um pedido GET, para verificar o estado da operação de compilação (o intervalo mínimo recomendado entre pedidos é 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 do modelId dado, também recuperada da propriedade resourceLocation na resposta. Em caso de sucesso, o estado é definido como succeeded e o resultado contém a informação personalizada do modelo. Se forem encontrados erros, o estado é definido para failed, e o erro é devolvido.

O código seguinte é um exemplo de pedido de compilação usando um token SAS. Note a barra final 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 ao modelo de composição

A composição do modelo está agora limitada a um único nível de aninhamento. Os modelos compostos são agora consistentes com modelos personalizados com a adição das 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 ao modelo de cópia

O padrão de chamada para o modelo de cópia mantém-se inalterado:

• Autorize a operação de cópia com o recurso alvo chamando authorizeCopy. Agora é feita uma requisição POST.
• Submeta a autorização ao recurso de origem e copie a chamada do modelo copyTo
• Verifique a operação retornada para validar que a operação foi concluída com sucesso.

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

• A ação HTTP no authorizeCopy é agora um pedido POST.
• A carga útil de autorização contém toda a informação necessária para submeter o pedido de cópia.

Autorize a cópia

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

Utilize o corpo de resposta da ação de autorização para construir o pedido de 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 tipo lista são agora ampliados para devolver modelos pré-configurados e personalizados. Todos os nomes de modelos pré-construídos começam por prebuilt-. Apenas modelos com o estado de concluído com sucesso são devolvidos. Para listar modelos que falharam ou estão em progresso, consulte Operações de Lista.

Pedido de uma lista de modelos de exemplo

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

Alteração para obter modelo da operação

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

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

Nova operação de obter informações

A operação info no serviço devolve tanto a contagem como o limite de modelos personalizados.

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

Resposta de exemplo

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

Próximos passos

• Revise a nova API REST
• O que é Inteligência Documental?
• Início rápido de Inteligência de Documentos 0