Analisar a resposta da API do documento

Este conteúdo aplica-se a:v4.0 (preview)v3.1 (GA)v3.0 (GA)

Neste artigo, vamos examinar os diferentes objetos retornados como parte da resposta e como usar a resposta da API de análise de AnalyzeDocument documentos em seus aplicativos.

Analise a solicitação de documentos

As APIs de Document Intelligence analisam imagens, PDFs e outros arquivos de documentos para extrair e detetar vários elementos semânticos, de layout, de estilo e de conteúdo. A operação analyze é uma API assíncrona. O envio de um documento retorna um cabeçalho Operation-Location que contém a URL a ser pesquisada para conclusão. Quando uma solicitação de análise é concluída com êxito, a resposta contém os elementos descritos na extração de dados do modelo.

Elementos de resposta

• Os elementos de conteúdo são os elementos de texto básicos extraídos do documento.

• Os elementos de layout agrupam os elementos de conteúdo em unidades estruturais.

• Os elementos de estilo descrevem a fonte e o idioma dos elementos de conteúdo.

• Os elementos semânticos atribuem significado aos elementos de conteúdo especificados.

Todos os elementos de conteúdo são agrupados de acordo com as páginas, especificadas pelo número de página (1-indexed). Eles também são classificados por ordem de leitura que organiza elementos semanticamente contíguos juntos, mesmo que cruzem limites de linha ou coluna. Quando a ordem de leitura entre parágrafos e outros elementos de layout é ambígua, o serviço geralmente retorna o conteúdo em uma ordem da esquerda para a direita, de cima para baixo.

Nota

Atualmente, o Document Intelligence não suporta a ordem de leitura entre os limites da página. As marcas de seleção não são posicionadas dentro das palavras ao redor.

A propriedade de conteúdo de nível superior contém uma concatenação de todos os elementos de conteúdo em ordem de leitura. Todos os elementos especificam sua posição na ordem do leitor por meio de extensões dentro dessa cadeia de caracteres de conteúdo. O conteúdo de alguns elementos nem sempre é contíguo.

Analise a resposta

A resposta de análise para cada API retorna objetos diferentes. As respostas da API contêm elementos de modelos de componentes, quando aplicável.

Conteúdo da resposta	Description	API
páginas	Palavras, linhas e extensões reconhecidas a partir de cada página do documento de entrada.	Modelos de leitura, layout, documento geral, pré-construídos e personalizados
parágrafos	Conteúdo reconhecido como parágrafos.	Modelos de leitura, layout, documento geral, pré-construídos e personalizados
estilos	Propriedades do elemento de texto identificadas.	Modelos de leitura, layout, documento geral, pré-construídos e personalizados
Idiomas	Linguagem identificada associada a cada extensão do texto extraído	Lida
Tabelas	Conteúdo tabular identificado e extraído do documento. As tabelas referem-se a tabelas identificadas pelo modelo de layout pré-treinado. O conteúdo rotulado como tabelas é extraído como campos estruturados no objeto documents.	Layout, documento geral, fatura e modelos personalizados
Números	Figuras (gráficos, imagens) identificadas e extraídas do documento, fornecendo representações visuais que auxiliam na compreensão de informações complexas.	Modelo de layout
secções	Estrutura hierárquica do documento identificada e extraída do documento. Secção ou subsecção com os elementos correspondentes (parágrafo, quadro, figura) anexados.	Modelo de layout
keyValuePairs	Pares chave-valor reconhecidos por um modelo pré-treinado. A chave é uma extensão de texto do documento com o valor associado.	Documentos gerais e modelos de faturas
Documentação	Os campos reconhecidos são retornados no dicionário dentro da fields lista de documentos	Modelos pré-construídos, modelos personalizados.

Para obter mais informações sobre os objetos retornados por cada API, consulte extração de dados do modelo.

Propriedades do elemento

Espaças

Spans especificam a posição lógica de cada elemento na ordem geral de leitura, com cada span especificando um deslocamento de caractere e comprimento na propriedade de cadeia de caracteres de conteúdo de nível superior. Por padrão, deslocamentos e comprimentos de caracteres são retornados em unidades de caracteres percebidos pelo usuário (também conhecidos como grapheme clusters elementos de texto). Para acomodar diferentes ambientes de desenvolvimento que usam unidades de caracteres diferentes, o usuário também pode especificar o stringIndexIndex parâmetro query para retornar deslocamentos e comprimentos de span em pontos de código Unicode (Python 3) ou unidades de código UTF16 (Java, JavaScript, .NET). Para obter mais informações, consulteSuporte multilíngue/emoji.

Região delimitadora

As regiões delimitadoras descrevem a posição visual de cada elemento no arquivo. Quando os elementos não são visualmente contíguos ou páginas cruzadas (tabelas), as posições da maioria dos elementos são descritas através de uma matriz de regiões delimitadoras. Cada região especifica o número de página (1-indexado) e o polígono delimitador. O polígono delimitador é descrito como uma sequência de pontos, no sentido horário a partir da esquerda em relação à orientação natural do elemento. Para quadriláteros, os pontos do gráfico são cantos superior-esquerdo, superior-direito, inferior-direito e inferior-esquerdo. Cada ponto representa sua coordenada x, y na unidade de página especificada pela propriedade unit. Em geral, a unidade de medida para imagens é pixels, enquanto PDFs usam polegadas.

Nota

Atualmente, a Inteligência Documental retorna apenas quadriláteros de 4 vértices como polígonos delimitadores. Versões futuras podem retornar diferentes números de pontos para descrever formas mais complexas, como linhas curvas ou imagens não retangulares. Regiões delimitadoras aplicadas somente a arquivos renderizados, se o arquivo não for renderizado, as regiões delimitadoras não serão retornadas. Atualmente, os arquivos do formato docx/xlsx/pptx/html não são renderizados.

Elementos de conteúdo

Word

Uma palavra é um elemento de conteúdo composto por uma sequência de caracteres. Com o Document Intelligence, uma palavra é definida como uma sequência de caracteres adjacentes, com espaço em branco separando palavras umas das outras. Para idiomas que não usam separadores de espaço entre palavras, cada caractere é retornado como uma palavra separada, mesmo que não represente uma unidade semântica de palavras.

Marcas de seleção

Uma marca de seleção é um elemento de conteúdo que representa um glifo visual que indica o estado de uma seleção. A caixa de seleção é uma forma comum de marcas de seleção. No entanto, eles também são representados através de botões de opção ou uma célula encaixotada em uma forma visual. O estado de uma marca de seleção pode ser selecionado ou desmarcado, com representação visual diferente para indicar o estado.

Elementos de layout

Line

Uma linha é uma sequência ordenada de elementos de conteúdo consecutivos separados por um espaço visual, ou aqueles que são imediatamente adjacentes para idiomas sem delimitadores de espaço entre palavras. Os elementos de conteúdo no mesmo plano horizontal (linha), mas separados por mais de um único espaço visual, geralmente são divididos em várias linhas. Embora esse recurso às vezes divida o conteúdo semanticamente contíguo em linhas separadas, ele permite a representação do conteúdo textual dividido em várias colunas ou células. As linhas na escrita vertical são detetadas na direção vertical.

Parágrafo

Um parágrafo é uma sequência ordenada de linhas que formam uma unidade lógica. Normalmente, as linhas compartilham alinhamento e espaçamento comuns entre linhas. Os parágrafos geralmente são delimitados por meio de recuo, espaçamento adicionado ou marcadores/numeração. O conteúdo só pode ser atribuído a um único parágrafo. Os parágrafos selecionados também podem ser associados a uma função funcional no documento. Atualmente, as funções suportadas incluem cabeçalho de página, rodapé de página, número de página, título, título de seção e nota de rodapé.

Página

Uma página é um agrupamento de conteúdo que normalmente corresponde a um lado de uma folha de papel. Uma página renderizada é caracterizada através da largura e altura na unidade especificada. Em geral, as imagens usam pixel, enquanto os PDFs usam polegadas. A propriedade angle descreve o ângulo geral do texto em graus para páginas que podem ser giradas.

Nota

Para planilhas como o Excel, cada planilha é mapeada para uma página. Para apresentações, como o PowerPoint, cada slide é mapeado para uma página. Para formatos de arquivo sem um conceito nativo de páginas sem renderização, como documentos HTML ou Word, o conteúdo principal do arquivo é considerado uma única página.

Tabela

Uma tabela organiza o conteúdo em um grupo de células em um layout de grade. As linhas e colunas podem ser separadas visualmente por linhas de grade, faixas de cores ou maior espaçamento. A posição de uma célula da tabela é especificada através dos seus índices de linha e coluna. Uma célula pode abranger várias linhas e colunas.

Com base em sua posição e estilo, uma célula pode ser classificada como conteúdo geral, cabeçalho de linha, cabeçalho de coluna, cabeça de esboço ou descrição:

• Uma célula de cabeçalho de linha é normalmente a primeira célula de uma linha que descreve as outras células da linha.

• Uma célula de cabeçalho de coluna é normalmente a primeira célula de uma coluna que descreve as outras células de uma coluna.

• Uma linha ou coluna pode conter várias células de cabeçalho para descrever o conteúdo hierárquico.

• Uma célula de cabeça de esboço é normalmente a célula na primeira linha e na posição da primeira coluna. Pode estar vazio ou descrever os valores nas células de cabeçalho na mesma linha/coluna.

• Uma célula de descrição geralmente aparece na área superior ou inferior de uma tabela, descrevendo o conteúdo geral da tabela. No entanto, às vezes pode aparecer no meio de uma tabela para dividir a tabela em seções. Normalmente, as células de descrição se estendem por várias células em uma única linha.

• Uma legenda de tabela especifica o conteúdo que explica a tabela. Uma tabela pode ainda ter uma legenda associada e um conjunto de notas de rodapé. Ao contrário de uma célula de descrição, uma legenda normalmente fica fora do layout da grade. Uma nota de rodapé de tabela anota o conteúdo dentro da tabela, geralmente marcada com um símbolo de nota de rodapé frequentemente encontrado abaixo da grade da tabela.

As tabelas de layout diferem dos campos de documento extraídos de dados tabulares. As tabelas de layout são extraídas do conteúdo visual tabular no documento sem considerar a semântica do conteúdo. Na verdade, algumas tabelas de layout são projetadas puramente para layout visual e nem sempre contêm dados estruturados. O método para extrair dados estruturados de documentos com layout visual diverso, como detalhes detalhados de um recibo, geralmente requer um pós-processamento significativo. É essencial mapear os cabeçalhos de linha ou coluna para campos estruturados com nomes de campo normalizados. Dependendo do tipo de documento, use modelos pré-construídos ou treine um modelo personalizado para extrair esse conteúdo estruturado. As informações resultantes são expostas como campos de documento. Esses modelos treinados também podem lidar com dados tabulares sem cabeçalhos e dados estruturados em formulários não tabulares, por exemplo, a seção de experiência de trabalho de um currículo.

Números

As figuras (gráficos, imagens) em documentos desempenham um papel crucial na complementação e valorização do conteúdo textual, fornecendo representações visuais que auxiliam na compreensão de informações complexas. O objeto figures detetado pelo modelo Layout tem propriedades principais como boundingRegions (os locais espaciais da figura nas páginas do documento, incluindo o número da página e as coordenadas do polígono que delineiam o limite da figura), spans (detalha as extensões de texto relacionadas à figura, especificando seus deslocamentos e comprimentos dentro do texto do documento. Esta ligação ajuda a associar a figura ao seu contexto textual relevante), elements (os identificadores de elementos de texto ou parágrafos dentro do documento que estão relacionados ou descrevem a figura) e caption se existirem.

{
    "figures": [
      {
        "boundingRegions": [],
        "spans": [],
        "elements": [
          "/paragraphs/15",
          ...
        ],
        "caption": {
          "content": "Here is a figure with some text",
          "boundingRegions": [],
          "spans": [],
          "elements": [
            "/paragraphs/15"
          ]
        }
      }
    ]
}

Secções

A análise hierárquica da estrutura documental é fundamental na organização, compreensão e processamento de documentos extensos. Essa abordagem é vital para segmentar semanticamente documentos longos para aumentar a compreensão, facilitar a navegação e melhorar a recuperação de informações. O advento da Geração Aumentada de Recuperação (RAG) na IA geradora de documentos ressalta a importância da análise hierárquica da estrutura de documentos. O modelo Layout suporta seções e subseções na saída, que identifica a relação de seções e objeto dentro de cada seção. A estrutura hierárquica é mantida em elements cada secção.

{
    "sections": [
      {
        "spans": [],
        "elements": [
          "/paragraphs/0",
          "/sections/1",
          "/sections/2",
          "/sections/5"
        ]
      },
...
}

Campo de formulário (par de valores de chave)

Um campo de formulário consiste em um rótulo de campo (chave) e valor. O rótulo do campo é geralmente uma cadeia de texto descritiva que descreve o significado do campo. Muitas vezes aparece à esquerda do valor, embora também possa aparecer acima ou abaixo do valor. O valor do campo contém o valor de conteúdo de uma instância de campo específica. O valor pode consistir em palavras, marcas de seleção e outros elementos de conteúdo. Também pode estar vazio para campos de formulário não preenchidos. Um tipo especial de campo de formulário tem um valor de marca de seleção com o rótulo do campo à direita. Campo de documento é um conceito semelhante, mas distinto, dos campos de formulário gerais. O rótulo do campo (chave) em um campo de formulário geral deve aparecer no documento. Assim, geralmente não é possível capturar informações como o nome do comerciante em um recibo. Os campos do documento são rotulados e não extraem uma chave. Os campos de documento mapeiam apenas um valor extraído para uma chave rotulada. Para obter mais informações, consulteos campos do documento.

Elementos de estilo

Estilo

Um elemento style descreve o estilo de fonte a ser aplicado ao conteúdo do texto. O conteúdo é especificado por meio de extensões na propriedade de conteúdo global. Atualmente, o único estilo de fonte detetado é se o texto é manuscrito. À medida que outros estilos são adicionados, o texto pode ser descrito por meio de vários objetos de estilo não conflitantes. Para compacidade, todo o texto que compartilha o estilo de fonte específico (com a mesma confiança) é descrito por meio de um único objeto de estilo.

{
    "confidence": 1,
    "spans": [
        {
            "offset": 2402,
            "length": 7
        }
    ],
    "isHandwritten": true
}

Linguagem

Um elemento language descreve o idioma detetado para o conteúdo especificado por meio de extensões na propriedade global content. O idioma detetado é especificado por meio de uma marca de idioma BCP-47 para indicar o idioma principal e informações opcionais de script e região. Por exemplo, o inglês e o chinês tradicional são reconhecidos como "en" e zh-Hant, respectivamente. As diferenças ortográficas regionais para o inglês do Reino Unido podem levar a que o texto seja detetado como en-GB. Os elementos linguísticos não abrangem texto sem uma língua dominante (por exemplo, números).

Elementos semânticos

Nota

Os elementos semânticos discutidos aqui aplicam-se a modelos pré-construídos de Inteligência Documental. Seus modelos personalizados podem retornar representações de dados diferentes. Por exemplo, a data e a hora retornadas por um modelo personalizado podem ser representadas em um padrão diferente da formatação padrão ISO 8601.

Documento

Um documento é uma unidade semanticamente completa. Um arquivo pode conter vários documentos, como vários formulários fiscais em um arquivo PDF ou vários recibos em uma única página. No entanto, a ordenação de documentos dentro do arquivo não afeta fundamentalmente as informações que ele transmite.

Nota

Atualmente, o Document Intelligence não suporta vários documentos em uma única página.

O tipo de documento descreve documentos que compartilham um conjunto comum de campos semânticos, representados por um esquema estruturado, independente de seu modelo ou layout visual. Por exemplo, todos os documentos do tipo "recibo" podem conter o nome do comerciante, a data da transação e o total da transação, embora os recibos de restaurantes e hotéis geralmente sejam diferentes em aparência.

Um elemento de documento inclui a lista de campos reconhecidos entre os campos especificados pelo esquema semântico do tipo de documento detetado:

• Um campo de documento pode ser extraído ou inferido. Os campos extraídos são representados através do conteúdo extraído e, opcionalmente, do seu valor normalizado, se interpretável.

• Um campo inferido não tem propriedade content e é representado apenas por meio de seu valor.

• Um campo de matriz não inclui uma propriedade de conteúdo. O conteúdo pode ser concatenado a partir do conteúdo dos elementos da matriz.

• Um campo de objeto contém uma propriedade de conteúdo que especifica o conteúdo completo que representa o objeto que pode ser um superconjunto dos subcampos extraídos.

O esquema semântico de um tipo de documento é descrito através dos campos que ele contém. Cada esquema de campo é especificado por meio de seu nome canônico e tipo de valor. Os tipos de valor de campo incluem tipos básicos (ex. string), compostos (ex. endereço) e estruturados (ex. matriz, objeto). O tipo de valor de campo também especifica a normalização semântica executada para converter o conteúdo detetado em uma representação de normalização. A normalização pode ser dependente da localidade.

Tipos básicos

Tipo de valor de campo	Description	Representação normalizada	Exemplo (Conteúdo do campo -> Valor)
string	Texto simples	O mesmo que o conteúdo	MerchantName: "Contoso" → "Contoso"
data	Date	ISO 8601 - AAAA-MM-DD	Data da fatura: "07/05/2022" → "07/05/2022"
hora	Hora	ISO 8601 - hh:mm:ss	TransactionTime: "21:45" → "21:45:00"
phoneNumber	Número de telefone	E.164 - +{CountryCode}{Número do Assinante}	WorkPhone: "(800) 555-7676" → "+18005557676"
paísRegião	País/Região	ISO 3166-1 alfa-3	PaísRegião: "Estados Unidos" → "EUA"
seleçãoMarcar	Está selecionado	"assinado" ou "não assinado"	AcceptEula: ☑ → "selecionado"
assinatura	Está assinado	O mesmo que o conteúdo	LendeeSignature: {signature} → "assinado"
Número	Número de vírgula flutuante	Número de vírgula flutuante	Quantidade: "1.20" → 1.2
integer	Número inteiro	Número assinado de 64 bits	Contagem: "123" → 123
boolean	Valor booleano	verdadeiro/falso	IsStatutoryEmployee: ☑ → verdade

Tipos de compostos

• Moeda: Valor da moeda com unidade monetária opcional. Um valor, por exemplo: InvoiceTotal: $123.45

  {
      "amount": 123.45,
      "currencySymbol": "$"
  }
  

• Endereço: Endereço analisado. Por exemplo: ShipToAddress: 123 Main St., Redmond, WA 98052

  {
  "poBox": "PO Box 12",
  "houseNumber": "123",
  "streetName": "Main St.",
  "city": "Redmond",
  "state": "WA",
  "postalCode": "98052",
  "countryRegion": "USA",
  "streetAddress": "123 Main St."
  }
  

Tipos estruturados

• Matriz: Lista de campos do mesmo tipo

  "Items": {
      "type": "array",
      "valueArray": [
  
      ]
  }
  

• Objeto: Lista nomeada de subcampos de tipos potencialmente diferentes

  "InvoiceTotal": {
    "type": "currency",
    "valueCurrency": {
        "currencySymbol": "$",
        "amount": 110
    },
    "content": "$110.00",
    "boundingRegions": [
        {
            "pageNumber": 1,
            "polygon": [
                7.3842,
                7.465,
                7.9181,
                7.465,
                7.9181,
                7.6089,
                7.3842,
                7.6089
            ]
        }
    ],
    "confidence": 0.945,
    "spans": [
        {
            "offset": 806,
            "length": 7
        }
    ]
  }
  

Próximos passos

• Tente processar seus próprios formulários e documentos com o Document Intelligence Studio.

• Conclua um início rápido do Document Intelligence e comece a criar um aplicativo de processamento de documentos na linguagem de desenvolvimento de sua escolha.