Processar resposta
A resposta a uma solicitação de processamento contém um objeto Document
que contém tudo o que é conhecido sobre o documento processado, incluindo todas as
informações estruturadas que a Document AI conseguiu extrair.
Nesta página, explicamos o layout do objeto Document
com documentos de exemplo e mapeamos aspectos dos resultados do OCR para os elementos específicos do JSON do objeto Document
.
Ela também oferece exemplos de código de bibliotecas de cliente e do SDK da caixa de ferramentas da Document AI.
Esses exemplos de código usam o processamento on-line, mas a análise de objetos Document
funciona da mesma forma para o processamento em lote.
Use um visualizador ou utilitário de edição JSON projetado especificamente para expandir ou recolher elementos. Revisar JSON bruto em um utilitário de texto simples é ineficiente.
Texto, layout e pontuações de qualidade
Veja um exemplo de documento de texto:
Confira o objeto de documento completo retornado pelo processador Enterprise Document OCR:
Essa saída de OCR também é sempre incluída na saída do processador da Document AI, já que o OCR é executado pelos processadores. Ele usa os dados de OCR atuais. Por isso, é possível inserir esses dados JSON usando a opção de documento inline nos processadores da Document AI.
image=None, # all our samples pass this var
mime_type="application/json",
inline_document=document_response # pass OCR output to CDE input - undocumented
Confira alguns dos campos importantes:
Texto bruto
O campo text
contém o texto reconhecido pela Document AI.
Esse texto não contém nenhuma estrutura de layout além de espaços, tabulações e
quebras de linha. Esse é o único campo que armazena informações textuais de um documento e serve como fonte de verdade do texto do documento. Outros campos podem se referir a partes do campo de texto por posição (startIndex
e endIndex
).
{
text: "Sample Document\nHeading 1\nLorem ipsum dolor sit amet, ..."
}
Tamanho da página e idiomas
Cada page
no objeto do documento corresponde a uma página física do documento de amostra. O exemplo de saída JSON contém uma página porque é uma única imagem PNG.
{
"pages:" [
{
"pageNumber": 1,
"dimension": {
"width": 679.0,
"height": 460.0,
"unit": "pixels"
},
}
]
}
- O campo
pages[].detectedLanguages[]
contém os idiomas encontrados em uma determinada página, além da pontuação de confiança.
{
"pages": [
{
"detectedLanguages": [
{
"confidence": 0.98009938,
"languageCode": "en"
},
{
"confidence": 0.01990064,
"languageCode": "und"
}
]
}
]
}
Dados de OCR
O OCR da IA de documentos detecta texto com vários níveis de granularidade ou organização na página, como blocos de texto, parágrafos, tokens e símbolos (o nível de símbolo é opcional, se configurado para gerar dados desse nível). Todos são membros do objeto de página.
Cada elemento tem um layout
correspondente que descreve a posição e o texto dele. Elementos visuais que não são de texto (como caixas de seleção) também estão no nível da página.
{
"pages": [
{
"paragraphs": [
{
"layout": {
"textAnchor": {
"textSegments": [
{
"endIndex": "16"
}
]
},
"confidence": 0.9939527,
"boundingPoly": {
"vertices": [ ... ],
"normalizedVertices": [ ... ]
},
"orientation": "PAGE_UP"
}
}
]
}
]
}
O texto bruto é referenciado no objeto textAnchor
, que é indexado na string de texto principal com startIndex
e endIndex
.
Para
boundingPoly
, o canto superior esquerdo da página é a origem(0,0)
. Valores positivos de X estão à direita, e valores positivos de Y estão para baixo.O objeto
vertices
usa as mesmas coordenadas da imagem original, enquantonormalizedVertices
estão no intervalo[0,1]
. Há uma matriz de transformação que indica a correção de distorção e outros atributos da normalização da imagem.
- Para desenhar o
boundingPoly
, crie segmentos de linha de um vértice para o próximo. Em seguida, feche o polígono desenhando um segmento de linha do último vértice de volta ao primeiro. O elemento orientation do layout indica se o texto foi girado em relação à página.
Para ajudar você a visualizar a estrutura do documento, as imagens a seguir mostram polígonos de delimitação para page.paragraphs
, page.lines
e page.tokens
.
Parágrafos
Linhas
Tokens
Bloqueios
O processador Enterprise Document OCR pode fazer uma avaliação da qualidade de um documento com base na legibilidade dele.
- Defina o campo
processOptions.ocrConfig.enableImageQualityScores
comotrue
para receber esses dados na resposta da API.
Essa avaliação é um índice de qualidade em [0, 1]
, em que 1
significa qualidade perfeita.
O índice de qualidade é retornado no campo Page.imageQualityScores
.
Todos os defeitos detectados são listados como quality/defect_*
e classificados em ordem decrescente por valor de confiança.
Confira um PDF que está muito escuro e desfocado para ser lido com conforto:
Estas são as informações de qualidade do documento retornadas pelo processador Enterprise Document OCR:
{
"pages": [
{
"imageQualityScores": {
"qualityScore": 0.7811847,
"detectedDefects": [
{
"type": "quality/defect_document_cutoff",
"confidence": 1.0
},
{
"type": "quality/defect_glare",
"confidence": 0.97849524
},
{
"type": "quality/defect_text_cutoff",
"confidence": 0.5
}
]
}
}
]
}
Amostras de código
As amostras de código a seguir demonstram como enviar uma solicitação de processamento e, em seguida, ler e imprimir os campos no terminal:
Java
Para mais informações, consulte a documentação de referência da API Java da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para mais informações, consulte a documentação de referência da API Node.js da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para mais informações, consulte a documentação de referência da API Python da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Formulários e tabelas
Confira nosso formulário de exemplo:
Confira o objeto de documento completo retornado pelo analisador de formulários:
Confira alguns dos campos importantes:
O analisador de formulários consegue detectar FormFields
na página. Cada campo de formulário tem um nome e um valor. Também chamados de pares de chave-valor (KVP). As KVPs são diferentes das entidades (de esquema) em outros extratores:
Os nomes das entidades são configurados. As chaves em KVPs são literalmente o texto da chave no documento.
{
"pages:" [
{
"formFields": [
{
"fieldName": { ... },
"fieldValue": { ... }
}
]
}
]
}
- Document AI também pode detectar
Tables
na página.
{
"pages:" [
{
"tables": [
{
"layout": { ... },
"headerRows": [
{
"cells": [
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
},
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
}
]
}
],
"bodyRows": [
{
"cells": [
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
},
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
}
]
}
]
}
]
}
]
}
A extração de tabelas no Form Parser reconhece apenas tabelas simples,
ou seja, sem células que abrangem linhas ou colunas. Portanto, rowSpan
e colSpan
são sempre 1
.
A partir da versão
pretrained-form-parser-v2.0-2022-11-10
do processador, o analisador de formulários também pode reconhecer entidades genéricas. Para mais informações, consulte Form Parser.Para ajudar você a visualizar a estrutura do documento, as imagens a seguir mostram polígonos delimitadores para
page.formFields
epage.tables
.Caixas de seleção em tabelas. O analisador de formulários consegue digitalizar caixas de seleção de imagens e PDFs como pares de chave-valor. Exemplo de digitalização de caixa de seleção como um par de chave-valor.
Fora das tabelas, as caixas de seleção são representadas como elementos visuais no analisador de formulários. Destacando as caixas quadradas com marcas de seleção na UI e o unicode ✓ no JSON.
"pages:" [
{
"tables": [
{
"layout": { ... },
"headerRows": [
{
"cells": [
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
},
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
}
]
}
],
"bodyRows": [
{
"cells": [
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
},
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
}
]
}
]
}
]
}
]
}
Em tabelas, as caixas de seleção aparecem como caracteres Unicode, como ✓ (marcada) ou ☐ (desmarcada).
As caixas de seleção marcadas têm o valor filled_checkbox:
under pages > x > formFields > x > fieldValue > valueType.
. As caixas de seleção desmarcadas têm o valor unfilled_checkbox
.
Os campos de conteúdo mostram o valor do conteúdo da caixa de seleção destacado ✓ no caminho pages>formFields>x>fieldValue>textAnchor>content
.
Para ajudar você a visualizar a estrutura do documento, as imagens a seguir desenham polígonos delimitadores para page.formFields
e page.tables
.
Campos do formulário
Tabelas
Amostras de código
As amostras de código a seguir demonstram como enviar uma solicitação de processamento e, em seguida, ler e imprimir os campos no terminal:
Java
Para mais informações, consulte a documentação de referência da API Java da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para mais informações, consulte a documentação de referência da API Node.js da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para mais informações, consulte a documentação de referência da API Python da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Entidades, entidades aninhadas e valores normalizados
Muitos dos processadores especializados extraem dados estruturados baseados em um esquema bem definido. Por exemplo, o analisador de faturas detecta campos específicos, como invoice_date
e supplier_name
. Confira um exemplo de fatura:
Confira o objeto de documento completo retornado pelo analisador de faturas:
Confira algumas partes importantes do objeto de documento:
Campos detectados:
Entities
contém os campos que o processador conseguiu detectar, por exemplo, oinvoice_date
:{ "entities": [ { "textAnchor": { "textSegments": [ { "startIndex": "14", "endIndex": "24" } ], "content": "2020/01/01" }, "type": "invoice_date", "confidence": 0.9938466, "pageAnchor": { ... }, "id": "2", "normalizedValue": { "text": "2020-01-01", "dateValue": { "year": 2020, "month": 1, "day": 1 } } } ] }
Para alguns campos, o processador também normaliza o valor. Neste exemplo, a data foi normalizada de
2020/01/01
para2020-01-01
.Normalização: para muitos campos específicos compatíveis, o processador também normaliza o valor e retorna um
entity
. O camponormalizedValue
é adicionado ao campo extraído bruto obtido pelotextAnchor
de cada entidade. Assim, ele normaliza o texto literal, muitas vezes dividindo o valor de texto em subcampos. Por exemplo, uma data como 1º de setembro de 2024 seria representada como:
normalizedValue": {
"text": "2020-09-01",
"dateValue": {
"year": 2024,
"month": 9,
"day": 1
}
Neste exemplo, a data foi normalizada de 2020/01/01 para 2020-01-01, um formato padronizado para reduzir o pós-processamento e permitir a conversão para o formato escolhido.
Os endereços também são normalizados, o que divide os elementos do endereço em campos individuais. Os números são normalizados com um número inteiro ou de ponto flutuante como normalizedValue
.
- Enriquecimento: alguns processadores e campos também são compatíveis com o enriquecimento.
Por exemplo, o
supplier_name
original no documentoGoogle Singapore
foi normalizado no Enterprise Knowledge Graph paraGoogle Asia Pacific, Singapore
. Além disso, como o Enterprise Knowledge Graph contém informações sobre o Google, a Document AI infere osupplier_address
mesmo que ele não esteja presente no documento de exemplo.
{
"entities": [
{
"textAnchor": {
"textSegments": [ ... ],
"content": "Google Singapore"
},
"type": "supplier_name",
"confidence": 0.39170802,
"pageAnchor": { ... },
"id": "12",
"normalizedValue": {
"text": "Google Asia Pacific, Singapore"
}
},
{
"type": "supplier_address",
"id": "17",
"normalizedValue": {
"text": "70 Pasir Panjang Rd #03-71 Mapletree Business City II Singapore 117371",
"addressValue": {
"regionCode": "SG",
"languageCode": "en-US",
"postalCode": "117371",
"addressLines": [
"70 Pasir Panjang Rd",
"#03-71 Mapletree Business City II"
]
}
}
}
]
}
Campos aninhados: para criar um esquema (campos) aninhado, primeiro declare uma entidade como principal e depois crie entidades secundárias abaixo dela. A resposta de análise do elemento pai inclui os campos filhos no elemento
properties
do campo pai. No exemplo a seguir,line_item
é um campo parent que tem dois campos child:line_item/description
eline_item/quantity
.{ "entities": [ { "textAnchor": { ... }, "type": "line_item", "confidence": 1.0, "pageAnchor": { ... }, "id": "19", "properties": [ { "textAnchor": { "textSegments": [ ... ], "content": "Tool A" }, "type": "line_item/description", "confidence": 0.3461604, "pageAnchor": { ... }, "id": "20" }, { "textAnchor": { "textSegments": [ ... ], "content": "500" }, "type": "line_item/quantity", "confidence": 0.8077843, "pageAnchor": { ... }, "id": "21", "normalizedValue": { "text": "500" } } ] } ] }
Os seguintes analisadores seguem essa regra:
- Extrair (extrator personalizado)
- Legado
- Analisador de extrato bancário
- Analisador de despesas
- Analisador de faturas
- Analisador de holerite
- Analisador W2
Amostras de código
Os exemplos de código a seguir mostram como enviar uma solicitação de processamento e, em seguida, ler e imprimir os campos de um processador especializado no terminal:
Java
Para mais informações, consulte a documentação de referência da API Java da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para mais informações, consulte a documentação de referência da API Node.js da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para mais informações, consulte a documentação de referência da API Python da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Extrator de documentos personalizado
O processador do extrator de documentos personalizado pode extrair entidades personalizadas de documentos que não têm um processador pré-treinado disponível. Isso pode ser feito treinando um modelo personalizado ou usando modelos de fundação de IA generativa para extrair entidades nomeadas sem treinamento. Para mais informações, consulte Criar um extrator de documentos personalizados no console.
- Se você treinar um modelo personalizado, o processador poderá ser usado da mesma forma que um processador de extração de entidade pré-treinado.
- Se você usar um modelo de base, poderá criar uma versão do processador para extrair entidades específicas de cada solicitação ou configurar isso para cada solicitação.
Para informações sobre a estrutura de saída, consulte Entidades, entidades aninhadas e valores normalizados.
Amostras de código
Se você estiver usando um modelo personalizado ou tiver criado uma versão de processador usando um modelo de base, use as amostras de código de extração de entidade.
O exemplo de código a seguir demonstra como configurar entidades específicas para um extrator de documentos personalizados de modelo de base por solicitação e imprimir as entidades extraídas:
Python
Para mais informações, consulte a documentação de referência da API Python da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Resumo
O processador de resumo usa modelos de base da IA generativa para resumir o texto extraído de um documento. É possível personalizar o tamanho e o formato da resposta das seguintes maneiras:
- Duração
BRIEF
: um resumo breve de uma ou duas frasesMODERATE
: um resumo de um parágrafoCOMPREHENSIVE
: a opção mais longa disponível
- Formato
Você pode criar uma versão do processador para um comprimento e formato específicos ou configurar por solicitação.
O texto resumido aparece em Document.entities.normalizedValue.text
. Confira um exemplo completo de arquivo JSON de saída do processador em Exemplo de saída do processador.
Para mais informações, consulte Criar um resumo de documentos no console.
Amostras de código
O exemplo de código a seguir demonstra como configurar um comprimento e um formato específicos em uma solicitação de processamento e imprimir o texto resumido:
Python
Para mais informações, consulte a documentação de referência da API Python da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Divisão e classificação
Confira um PDF composto de 10 páginas com diferentes tipos de documentos e formulários:
Este é o objeto de documento completo retornado pelo classificador e divisor de documentos de empréstimo:
Cada documento detectado pelo divisor é representado por um
entity
. Exemplo:
{
"entities": [
{
"textAnchor": {
"textSegments": [
{
"startIndex": "13936",
"endIndex": "21108"
}
]
},
"type": "1040se_2020",
"confidence": 0.76257163,
"pageAnchor": {
"pageRefs": [
{
"page": "6"
},
{
"page": "7"
}
]
}
}
]
}
Entity.pageAnchor
indica que o documento tem duas páginas. Observe quepageRefs[].page
é baseado em zero e é o índice do campodocument.pages[]
.Entity.type
especifica que este documento é um formulário 1040 Schedule SE. Para ver uma lista completa de tipos de documentos que podem ser identificados, consulte Tipos de documentos identificados na documentação do processador.
Para mais informações, consulte Comportamento dos separadores de documentos.
Amostras de código
Os divisores identificam os limites da página, mas não dividem o documento de entrada para você. É possível usar a Caixa de ferramentas da Document AI para dividir fisicamente um arquivo PDF usando os limites de página. Os exemplos de código a seguir imprimem os intervalos de páginas sem dividir o PDF:
Java
Para mais informações, consulte a documentação de referência da API Java da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para mais informações, consulte a documentação de referência da API Node.js da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para mais informações, consulte a documentação de referência da API Python da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Document
processado.
Python
Para mais informações, consulte a documentação de referência da API Python da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Caixa de ferramentas da Document AI
A caixa de ferramentas da Document AI é um SDK para Python que oferece funções
de utilidade para gerenciar, manipular e extrair informações da resposta do documento.
Ele cria um objeto de documento "encapsulado" de uma resposta de documento processado de arquivos JSON no Cloud Storage, arquivos JSON locais ou saída diretamente do método process_document()
.
Ele pode realizar as seguintes ações:
- Combine arquivos JSON
Document
fragmentados do processamento em lote em um único documento "encapsulado". - Exportar fragmentos como um
Document
unificado. -
Receba a saída
Document
de: - Acesse texto de
Pages
,Lines
,Paragraphs
,FormFields
eTables
sem processar informações deLayout
. - Pesquise um
Pages
que contenha uma string de destino ou corresponda a uma expressão regular. - Pesquise
FormFields
pelo nome. - Pesquise
Entities
por tipo. - Converta
Tables
em um DataFrame do Pandas ou CSV. - Insira
Entities
eFormFields
em uma tabela do BigQuery. - Divida um arquivo PDF com base na saída de um processador de divisão/classificação.
- Extraia a imagem
Entities
deDocument
caixas delimitadoras. -
Converter
Documents
para e de formatos usados com frequência:- API Cloud Vision
AnnotateFileResponse
- hOCR
- Formatos de processamento de documentos de terceiros
- API Cloud Vision
- Crie lotes de documentos para processamento em uma pasta do Cloud Storage.
Exemplos de código
Os exemplos de código a seguir demonstram como usar a caixa de ferramentas da Document AI.