Resposta da API de análise do documento

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

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

Solicitar análise de documento

As APIs da Informação de Documentos analisam imagens, PDFs e outros arquivos de documento para extrair e detectar vários elementos de conteúdo, layout, estilo e semântica. A operação de análise é uma API assíncrona. Enviar um documento retorna um cabeçalho Operation-Location que contém a URL a ser sondada 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 da resposta

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

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

• Os elementos de estilo descrevem a fonte e a linguagem 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 da página (1–indexado). Eles também são classificados pela 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.

Observação

Atualmente, a Informação de Documentos não dá suporte à ordem de leitura nos limites de página. As marcas de seleção não estã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 na ordem de leitura. Todos os elementos especificam sua posição na ordem do leitor por meio de intervalos dentro dessa cadeia de caracteres de conteúdo. O conteúdo de alguns elementos nem sempre é contíguo.

Resposta de análises

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

Conteúdo da resposta	Descrição	API
páginas	Palavras, linhas e intervalos reconhecidos de cada página do documento de entrada.	Modelos de leitura, layout, documento geral, predefinidos e personalizados
parágrafos	Conteúdo reconhecido como parágrafos.	Modelos de leitura, layout, documento geral, predefinidos e personalizados
estilos	Propriedades de elemento de texto identificadas.	Modelos de leitura, layout, documento geral, predefinidos e personalizados
idiomas	Idioma identificado associado a cada intervalo do texto extraído	Ler
tables	Conteúdo tabular identificado e extraído do documento. Tabelas relacionadas a tabelas identificadas pelo modelo de layout pré-treinado. O conteúdo rotulado como tabelas é extraído como campos estruturados no objeto do documento.	Modelos de layout, documento geral, fatura e personalizados
figuras	Figuras (gráficos, imagens) identificadas e extraídas do documento, fornecendo representações visuais que ajudam na compreensão de informações complexas.	Modelo de layout
sections	Estrutura de documento hierárquica identificada e extraída do documento. Seção ou subseção com os elementos correspondentes (parágrafo, tabela, figura) anexados a ela.	Modelo de layout
keyValuePairs	Pares chave-valor reconhecidos por um modelo pré-treinado. A chave é um intervalo de texto do documento com o valor associado.	Modelos de documento geral e fatura
documentos	Os campos reconhecidos são retornados no dicionário fields dentro da lista de documentos	Modelos predefinidos, modelos personalizados.

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

Propriedades do elemento

Intervalos

Os intervalos especificam a posição lógica de cada elemento na ordem de leitura geral, com cada intervalo especificando um deslocamento de caractere e comprimento na propriedade de cadeia de caracteres de conteúdo de nível superior. Por padrão, os deslocamentos e comprimentos de caractere são retornados em unidades de caracteres percebidos pelo usuário (também conhecidos como elementos grapheme clusters ou de texto). Para acomodar diferentes ambientes de desenvolvimento que usam unidades de caracteres diferentes, o usuário pode especificar o parâmetro de consulta stringIndexIndex para retornar deslocamentos e comprimentos de intervalo 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 passam por várias páginas (no caso de tabelas), as posições da maioria dos elementos são descritas por meio de uma matriz de regiões delimitadoras. Cada região especifica o número da página (1–indexado) e o polígono delimitador. O polígono delimitador é descrito como uma sequência de pontos, no sentido horário da esquerda em relação à orientação natural do elemento. Para quadriláteros, os pontos de plotagem são os cantos superior esquerdo e direito, inferior direito e esquerdo. Cada ponto representa sua coordenada x, y na unidade de página especificada pela propriedade de unidade. Em geral, a unidade de medida para imagens é pixels, enquanto os PDFs usam polegadas.

Observação

Atualmente, a Informação de Documentos retorna apenas quadriláteros de 4 vértices como polígonos delimitadores. Versões futuras podem retornar um número diferente 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. Na Informação de Documentos, uma palavra é definida como uma sequência de caracteres adjacentes, com palavras separadas por espaços em branco. 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 de palavra semântica.

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, elas também são representadas por meio de botões de opção ou de uma célula desmarcada em um formulário visual. É possível selecionar ou não o estado de uma marca de seleção, usando representação visual diferente para indicar o estado.

Elementos de layout

Linha

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

Paragraph

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

Page

Uma página é um agrupamento de conteúdo que normalmente corresponde a um lado de uma folha de papel. Uma página renderizada é caracterizada por 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.

Observação

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

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 de tabela é especificada por seus índices de linha e coluna. Uma célula pode estender 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çalho de stub ou descrição:

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

• Uma célula de cabeçalho de coluna normalmente é a primeira célula em uma coluna que descreve as outras células na 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çalho stub normalmente é a célula na primeira linha e na primeira posição da coluna. Ela pode estar vazia 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, ela pode aparecer no meio de uma tabela para dividi-la em seções. Normalmente, as células de descrição alcançam várias células em uma única linha.

• Uma legenda de tabela especifica o conteúdo que explica a tabela. Uma tabela também pode ter uma legenda associada e um conjunto de notas de rodapé. Ao contrário de uma célula de descrição, uma barra de 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é, encontrado com frequência abaixo da grade de 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 meramente para layout visual e nem sempre contêm dados estruturados. O método para extrair dados estruturados de documentos com layout visual diversificado, como detalhes discriminados 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 predefinidos 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 tratar 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.

Figuras

Figuras (gráficos, imagens) em documentos desempenham um papel crucial na complementação e no aprimoramento do conteúdo textual, fornecendo representações visuais que ajudam na compreensão de informações complexas. O objeto figuras detectado pelo modelo layout tem propriedades importantes como boundingRegions (os locais espaciais da figura nas páginas do documento, incluindo o número da página e as coordenadas de polígono que descrevem o limite da figura), spans (detalha os intervalos de texto relacionados à figura, especificando seus deslocamentos e comprimentos dentro do texto do documento. Essa conexão ajuda na associação da figura com seu contexto textual relevante), elements (os identificadores de elementos de texto ou parágrafos dentro do documento relacionados ou descrevem a figura) e caption se houver algum.

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

Seções

A análise hierárquica da estrutura de documentos é 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 de RAG (geração aumentada de recuperação) na IA generativa do documento ressalta a importância da análise hierárquica da estrutura de documentos. O modelo layout dá suporte a seções e subseções na saída, que identifica a relação de seções e objeto em cada seção. A estrutura hierárquica é mantida em elements de cada seção.

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

Campo formulário (par chave-valor)

Um campo de formulário consiste em um rótulo de campo (chave) e valor. O rótulo de campo geralmente é uma cadeia de caracteres de texto descritiva do significado do campo. Geralmente, ele aparece à esquerda do valor, embora também possa aparecer sobre 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. Ele também pode estar vazio em 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 de campo à direita. O campo de documento é um conceito semelhante, porém distinto, dos campos de formulário geral. O rótulo de campo (chave) em um campo de formulário geral deve aparecer no documento. Portanto, ele geralmente não pode capturar informações como o nome do comerciante em um recibo. Os campos de 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, consultecampos de documento.

Elementos de estilo

Estilo

Um elemento de estilo descreve o estilo de fonte a ser aplicado ao conteúdo de texto. O conteúdo é especificado por meio de intervalos na propriedade de conteúdo global. Atualmente, o único estilo de fonte detectado é se o texto é manuscrito. À medida que outros estilos são adicionados, o texto pode ser descrito por vários objetos de estilo não conflitantes. Para densidade, 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
}

Idioma

Um elemento de idioma descreve o idioma detectado para o conteúdo especificado por meio de intervalos na propriedade de conteúdo global. O idioma detectado é especificado por meio de uma marca de idioma BCP-47 para indicar o idioma principal e as informações opcionais de script e região. Por exemplo, inglês e chinês tradicional são reconhecidos como "en" e zh-Hant, respectivamente. Diferenças ortográficas regionais no inglês do Reino Unido podem fazer o texto ser detectado como en-GB. Os elementos de idioma não abrangem texto sem um idioma dominante (por exemplo, números).

Elementos semânticos

Observação

Os elementos semânticos discutidos aqui se aplicam aos modelos predefinidos da Informação de Documentos. Seus modelos personalizados podem retornar as representações de diferentes dados. 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 no arquivo basicamente não afeta as informações que ele transmite.

Observação

Atualmente, a Informação de Documentos não dá suporte a 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, independentemente 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 tenham aparências diferentes.

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

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

• Os campos inferidos não têm propriedade de conteúdo e são representados apenas pelo seu valor.

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

• Os campos 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 pelos campos que ele têm. Cada esquema de campo é especificado por seu nome canônico e tipo de valor. Os tipos de valor de campo incluem tipos básicos (por exemplo, cadeia de caracteres), compostos (por exemplo, endereço) e estruturados (por exemplo, matriz, objeto). O tipo de valor de campo também especifica a normalização semântica executada para converter o conteúdo detectado em uma representação de normalização. A normalização pode depender da localidade.

Tipos básicos

Tipo de valor de campo	Descrição	Representação normalizada	Exemplo (Conteúdo do campo –> Valor)
string	Texto sem formatação	O mesmo que o conteúdo	MerchantName: "Contoso" → "Contoso"
data	Data	ISO 8601 – DD/MM/AAAA	InvoiceDate: "5/7/2022" → "2022-05-07"
time	Hora	ISO 8601 - hh:mm:ss	TransactionTime: "21h45" → "21h45m00"
phoneNumber	Número do telefone	E.164 - +{CountryCode}{SubscriberNumber}	WorkPhone: "(800) 555-7676" → "+18005557676"
countryRegion	País/Região	ISO 3166-1 alpha-3	CountryRegion: "Estados Unidos" → "EUA"
selectionMark	Está selecionada	"com sinal" ou "sem sinal"	AcceptEula: ☑ → "selecionado"
assinatura	Está com sinal	O mesmo que o conteúdo	LendeeSignature: {signature} → "com sinal"
número	Número de ponto flutuante	Número de ponto flutuante	Quantidade: "1,20" → 1,2
Número inteiro	Número inteiro	Número com sinal de 64 bits	Contagem: "123" → 123
booleano	Valor booliano	true/false	IsStatutoryEmployee: ☑ → true

Tipos compostos

• Moeda: valor de moeda com unidade de moeda 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óximas etapas

• Experimente processar seus próprios formulários e documentos com o Estúdio de Informação de Documentos.

• Execute um início rápido do serviço Informação de Documentos e comece a criar um aplicativo de processamento de documentos na linguagem de desenvolvimento de sua escolha.