Cómo controlar la respuesta de procesamiento
La respuesta a una solicitud de procesamiento contiene un objeto Document
que contiene todo lo que se conoce acerca del documento procesado, incluida toda la información estructurada que Document AI pudo extraer.
En esta página, se explica el diseño del objeto Document
a través de la entrega de documentos de muestra y la asignación de aspectos de los resultados del OCR a los elementos específicos del objeto Document
en formato JSON.
También proporciona muestras de código de las bibliotecas cliente y del SDK de Document AI Toolbox.
Estas muestras de código usan el procesamiento en línea, pero el análisis de objetos Document
funciona de la misma manera para el procesamiento por lotes.
Usa un visor o una utilidad de edición de JSON diseñados específicamente para expandir o contraer elementos. Revisar el código JSON sin procesar en una utilidad de texto sin formato es ineficiente.
Texto, diseño y niveles de calidad
Este es un ejemplo de un documento de texto:
Este es el objeto de documento completo que devuelve el procesador de OCR empresarial para documentos:
Esta salida de OCR también se incluye siempre en la salida del procesador de Document AI, ya que los procesadores ejecutan el OCR. Utiliza los datos de OCR existentes, por lo que puedes ingresar esos datos JSON con la opción de documento intercalado en los procesadores de 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
Estos son algunos de los campos importantes:
Texto sin procesar
El campo text
contiene el texto que reconoce Document AI.
Este texto no contiene ninguna estructura de diseño, excepto espacios, tabulaciones y avances de línea. Este es el único campo que almacena la información textual de un documento y sirve como fuente de información del texto del documento. Otros campos pueden hacer referencia a partes del campo de texto por posición (startIndex
y endIndex
).
{
text: "Sample Document\nHeading 1\nLorem ipsum dolor sit amet, ..."
}
Tamaño de la página e idiomas
Cada page
del objeto del documento corresponde a una página física del documento de muestra. El ejemplo de salida JSON contiene una página porque es una sola imagen PNG.
{
"pages:" [
{
"pageNumber": 1,
"dimension": {
"width": 679.0,
"height": 460.0,
"unit": "pixels"
},
}
]
}
- El campo
pages[].detectedLanguages[]
contiene los idiomas que se encontraron en una página determinada, junto con la puntuación de confianza.
{
"pages": [
{
"detectedLanguages": [
{
"confidence": 0.98009938,
"languageCode": "en"
},
{
"confidence": 0.01990064,
"languageCode": "und"
}
]
}
]
}
Datos de OCR
El OCR de Document AI detecta texto con varios niveles de detalle u organización en la página, como los bloques de texto, los párrafos, los tokens y los símbolos (el nivel de símbolos es opcional si se configura para generar datos a nivel de símbolos). Todos estos son miembros del objeto de página.
Cada elemento tiene un layout
correspondiente que describe su posición y texto. Los elementos visuales que no son de texto (como las casillas de verificación) también se encuentran a nivel de la página.
{
"pages": [
{
"paragraphs": [
{
"layout": {
"textAnchor": {
"textSegments": [
{
"endIndex": "16"
}
]
},
"confidence": 0.9939527,
"boundingPoly": {
"vertices": [ ... ],
"normalizedVertices": [ ... ]
},
"orientation": "PAGE_UP"
}
}
]
}
]
}
Se hace referencia al texto sin procesar en el objeto textAnchor
, que se indexa en la cadena de texto principal con startIndex
y endIndex
.
Para
boundingPoly
, la esquina superior izquierda de la página es el origen(0,0)
. Los valores de X positivos están a la derecha y los valores de Y positivos están hacia abajo.El objeto
vertices
usa las mismas coordenadas que la imagen original, mientras quenormalizedVertices
se encuentra en el rango[0,1]
. Hay una matriz de transformación que indica la corrección de la distorsión y otros atributos de la normalización de la imagen.
- Para dibujar el
boundingPoly
, dibuja segmentos de línea de un vértice al siguiente. Luego, cierra el polígono dibujando un segmento de línea desde el último vértice hasta el primero. El elemento orientation del diseño indica si el texto se rotó en relación con la página.
Para ayudarte a visualizar la estructura del documento, las siguientes imágenes dibujan polígonos delimitadores para page.paragraphs
, page.lines
y page.tokens
.
Párrafos
Líneas
Tokens
Bloqueos
El procesador Enterprise Document OCR puede realizar una evaluación de la calidad de un documento según su legibilidad.
- Debes establecer el campo
processOptions.ocrConfig.enableImageQualityScores
entrue
para obtener estos datos en la respuesta de la API.
Esta evaluación de calidad es una puntuación de calidad en [0, 1]
, en la que 1
significa calidad perfecta.
El nivel de calidad se muestra en el campo Page.imageQualityScores
.
Todos los defectos detectados se enumeran como quality/defect_*
y se ordenan de forma descendente según el valor de confianza.
Este es un PDF demasiado oscuro y borroso para leerlo con comodidad:
A continuación, se muestra la información de calidad del documento que devuelve el procesador 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
}
]
}
}
]
}
Muestras de código
En los siguientes ejemplos de código, se muestra cómo enviar una solicitud de procesamiento y, luego, leer e imprimir los campos en la terminal:
Java
Para obtener más información, consulta la documentación de referencia de la API de Document AI Java.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para obtener más información, consulta la documentación de referencia de la API de Document AI Node.js.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para obtener más información, consulta la documentación de referencia de la API de Document AI Python.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Formularios y tablas
Este es nuestro formulario de ejemplo:
Este es el objeto de documento completo que devuelve el analizador de formularios:
Estos son algunos de los campos importantes:
El Analizador de formularios puede detectar FormFields
en la página. Cada campo del formulario tiene un nombre y un valor. También se conocen como pares clave-valor (KVP). Ten en cuenta que los KVP son diferentes de las entidades (de esquema) en otros extractores:
Se configuran los nombres de las entidades. Las claves en los KVP son literalmente el texto de la clave en el documento.
{
"pages:" [
{
"formFields": [
{
"fieldName": { ... },
"fieldValue": { ... }
}
]
}
]
}
- Document AI también puede detectar
Tables
en la 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
}
]
}
]
}
]
}
]
}
La extracción de tablas en el Analizador de formularios solo reconoce tablas simples, es decir, aquellas que no tienen celdas que abarcan filas o columnas. Por lo tanto, rowSpan
y colSpan
siempre son 1
.
A partir de la versión
pretrained-form-parser-v2.0-2022-11-10
del procesador, Form Parser también puede reconocer entidades genéricas. Para obtener más información, consulta Form Parser.Para ayudarte a visualizar la estructura del documento, las siguientes imágenes dibujan polígonos delimitadores para
page.formFields
ypage.tables
.Casillas de verificación en tablas El analizador de formularios puede digitalizar casillas de verificación de imágenes y PDFs como pares clave-valor. Proporciona un ejemplo de digitalización de casillas de verificación como un par clave-valor.
Fuera de las tablas, las casillas de verificación se representan como elementos visuales dentro del Analizador de formularios. Se destacan las casillas de verificación en la IU y el carácter Unicode ✓ en el 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
}
]
}
]
}
]
}
]
}
En las tablas, las casillas de verificación aparecen como caracteres Unicode, como ✓ (marcada) o ☐ (sin marcar).
Las casillas de verificación completadas tienen el valor filled_checkbox:
under pages > x > formFields > x > fieldValue > valueType.
. Las casillas de verificación sin marcar tienen el valor unfilled_checkbox
.
Los campos de contenido muestran el valor de contenido de la casilla de verificación como ✓ destacado en la ruta de acceso pages>formFields>x>fieldValue>textAnchor>content
.
Para ayudarte a visualizar la estructura del documento, las siguientes imágenes dibujan polígonos delimitadores para page.formFields
y page.tables
.
Campos del formulario
Tablas
Muestras de código
En los siguientes ejemplos de código, se muestra cómo enviar una solicitud de procesamiento y, luego, leer e imprimir los campos en la terminal:
Java
Para obtener más información, consulta la documentación de referencia de la API de Document AI Java.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para obtener más información, consulta la documentación de referencia de la API de Document AI Node.js.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para obtener más información, consulta la documentación de referencia de la API de Document AI Python.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Entidades, entidades anidadas y valores normalizados
Muchos de los procesadores especializados extraen datos estructurados que se basan en un esquema bien definido. Por ejemplo, el analizador de facturas detecta campos específicos, como invoice_date
y supplier_name
. Aquí tienes un ejemplo de factura:
Este es el objeto del documento completo que devuelve el analizador de facturas:
Estas son algunas de las partes importantes del objeto document:
Campos detectados:
Entities
contiene los campos que el procesador pudo detectar, por ejemplo,invoice_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 } } } ] }
En el caso de ciertos campos, el procesador también normaliza el valor. En este ejemplo, la fecha se normalizó de
2020/01/01
a2020-01-01
.Normalización: Para muchos campos específicos admitidos, el procesador también normaliza el valor y devuelve un
entity
. El camponormalizedValue
se agrega al campo sin procesar extraído que se obtiene a través deltextAnchor
de cada entidad. Por lo tanto, normaliza el texto literal y, a menudo, divide el valor de texto en subcampos. Por ejemplo, una fecha como el 1 de septiembre de 2024 se representaría de la siguiente manera:
normalizedValue": {
"text": "2020-09-01",
"dateValue": {
"year": 2024,
"month": 9,
"day": 1
}
En este ejemplo, la fecha se normalizó de 2020/01/01 a 2020-01-01, un formato estandarizado para reducir el procesamiento posterior y permitir la conversión al formato elegido.
Las direcciones también se suelen normalizar, lo que desglosa los elementos de la dirección en campos individuales. Los números se normalizan con un número entero o de punto flotante como normalizedValue
.
- Enriquecimiento: Algunos procesadores y campos también admiten el enriquecimiento.
Por ejemplo, el
supplier_name
original en el documentoGoogle Singapore
se normalizó en relación con Enterprise Knowledge Graph aGoogle Asia Pacific, Singapore
. También observa que, como Enterprise Knowledge Graph contiene información sobre Google, Document AI infiere elsupplier_address
, aunque no estaba presente en el documento de muestra.
{
"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 anidados: Los esquemas (campos) anidados se pueden crear declarando primero una entidad como principal y, luego, creando entidades secundarias debajo de la principal. La respuesta de análisis del elemento principal incluye los campos secundarios en el elemento
properties
del campo principal. En el siguiente ejemplo,line_item
es un campo principal que tiene dos campos secundarios:line_item/description
yline_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" } } ] } ] }
Los siguientes analizadores sí lo siguen:
- Extract (Extractor personalizado)
- Heredado
- Analizador de estados de cuenta
- Analizador de gastos
- Analizador de facturas
- Analizador de comprobantes de pago
- Analizador W2
Muestras de código
En las siguientes muestras de código, se muestra cómo enviar una solicitud de procesamiento y, luego, leer e imprimir los campos de un procesador especializado en la terminal:
Java
Para obtener más información, consulta la documentación de referencia de la API de Document AI Java.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para obtener más información, consulta la documentación de referencia de la API de Document AI Node.js.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para obtener más información, consulta la documentación de referencia de la API de Document AI Python.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Extractor de documentos personalizado
El procesador de extractor de documentos personalizado puede extraer entidades personalizadas de documentos que no tienen un procesador previamente entrenado disponible. Esto se puede lograr entrenando un modelo personalizado o usando modelos de base de IA generativa para extraer entidades nombradas sin ningún entrenamiento. Para obtener más información, consulta Crea un extractor de documentos personalizado en la consola.
- Si entrenas un modelo personalizado, el procesador se puede usar exactamente de la misma manera que un procesador de extracción de entidades previamente entrenado.
- Si usas un modelo de base, puedes crear una versión del procesador para extraer entidades específicas para cada solicitud o configurarlo por solicitud.
Para obtener información sobre la estructura de salida, consulta Entidades, entidades anidadas y valores normalizados.
Muestras de código
Si usas un modelo personalizado o creaste una versión del procesador con un modelo de base, usa los ejemplos de código de extracción de entidades.
En el siguiente muestra de código, se muestra cómo configurar entidades específicas para un extractor de documentos personalizado de un modelo fundamental por solicitud y cómo imprimir las entidades extraídas:
Python
Para obtener más información, consulta la documentación de referencia de la API de Document AI Python.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Resúmenes
El procesador de resúmenes usa modelos básicos de IA generativa para resumir el texto extraído de un documento. La longitud y el formato de la respuesta se pueden personalizar de las siguientes maneras:
- Longitud
BRIEF
: Un breve resumen de una o dos oracionesMODERATE
: Un resumen de un párrafoCOMPREHENSIVE
: La opción más larga disponible
- Formato
Puedes crear una versión del procesador para una longitud y un formato específicos, o bien configurarla para cada solicitud.
El texto resumido aparece en Document.entities.normalizedValue.text
. Puedes encontrar un archivo JSON de salida de muestra completo en Salida de muestra del procesador.
Para obtener más información, consulta Cómo compilar un resumidor de documentos en la consola.
Muestras de código
En la siguiente muestra de código, se muestra cómo configurar una longitud y un formato específicos en una solicitud de procesamiento y cómo imprimir el texto resumido:
Python
Para obtener más información, consulta la documentación de referencia de la API de Document AI Python.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
División y clasificación
Aquí tienes un PDF compuesto de 10 páginas que contiene diferentes tipos de documentos y formularios:
Este es el objeto del documento completo que devuelve el divisor y clasificador de documentos de préstamos:
Cada documento que detecta el divisor se representa con un entity
. Por ejemplo:
{
"entities": [
{
"textAnchor": {
"textSegments": [
{
"startIndex": "13936",
"endIndex": "21108"
}
]
},
"type": "1040se_2020",
"confidence": 0.76257163,
"pageAnchor": {
"pageRefs": [
{
"page": "6"
},
{
"page": "7"
}
]
}
}
]
}
Entity.pageAnchor
indica que este documento tiene 2 páginas. Ten en cuenta quepageRefs[].page
se basa en cero y es el índice del campodocument.pages[]
.Entity.type
especifica que este documento es un formulario del Anexo SE del 1040. Para obtener una lista completa de los tipos de documentos que se pueden identificar, consulta Tipos de documentos identificados en la documentación del procesador.
Para obtener más información, consulta Comportamiento de los divisores de documentos.
Muestras de código
Los divisores identifican los límites de las páginas, pero no dividen el documento de entrada. Puedes usar la caja de herramientas de Document AI para dividir físicamente un archivo PDF con los límites de página. En los siguientes ejemplos de código, se imprimen los rangos de páginas sin dividir el PDF:
Java
Para obtener más información, consulta la documentación de referencia de la API de Document AI Java.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para obtener más información, consulta la documentación de referencia de la API de Document AI Node.js.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para obtener más información, consulta la documentación de referencia de la API de Document AI Python.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Document
procesado.
Python
Para obtener más información, consulta la documentación de referencia de la API de Document AI Python.
Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Caja de herramientas de Document AI
Document AI Toolbox es un SDK para Python que proporciona funciones de utilidad para administrar, manipular y extraer información de la respuesta del documento.
Crea un objeto de documento "ajustado" a partir de una respuesta de documento procesado de archivos JSON en Cloud Storage, archivos JSON locales o salida directamente del método process_document()
.
Puede realizar las siguientes acciones:
- Combina archivos JSON
Document
fragmentados del procesamiento por lotes en un solo documento "ajustado". - Exporta fragmentos como un
Document
unificado. -
Obtén el resultado de
Document
de lo siguiente: - Accede al texto de
Pages
,Lines
,Paragraphs
,FormFields
yTables
sin controlar la información deLayout
. - Busca un
Pages
que contenga una cadena objetivo o que coincida con una expresión regular. - Busca
FormFields
por su nombre. - Busca
Entities
por tipo. - Convierte
Tables
en un DataFrame de Pandas o en un archivo CSV. - Inserta
Entities
yFormFields
en una tabla de BigQuery. - Divide un archivo PDF según el resultado de un procesador de Splitter/Classifier.
- Extrae la imagen
Entities
de losDocument
cuadros de límite. -
Convierte
Documents
a formatos de uso frecuente y viceversa:- API de Cloud Vision
AnnotateFileResponse
- hOCR
- Formatos de procesamiento de documentos de terceros
- API de Cloud Vision
- Crea lotes de documentos para procesarlos desde una carpeta de Cloud Storage.
Muestras de código
En las siguientes muestras de código, se muestra cómo usar Document AI Toolbox.