1. Обзор
Что такое ИИ документов?
Document AI — это платформа, которая позволяет извлекать ценную информацию из ваших документов. По сути, он предлагает растущий список обработчиков документов (также называемых парсерами или сплиттерами, в зависимости от их функциональности).
Существует два способа управления процессорами Document AI:
- вручную, из веб-консоли;
- программно, используя API Document AI.
Вот пример снимка экрана, показывающий список ваших процессоров, как из веб-консоли, так и из кода Python:
В этой лабораторной работе вы сосредоточитесь на программном управлении процессорами Document AI с помощью клиентской библиотеки Python.
Что ты увидишь
- Как настроить свою среду
- Как получить типы процессоров
- Как создавать процессоры
- Как составить список обработчиков проекта
- Как использовать процессоры
- Как включить/отключить процессоры
- Как управлять версиями процессора
- Как удалить процессоры
Что вам понадобится
Опрос
Как вы будете использовать этот урок?
Как бы вы оценили свой опыт работы с Python?
Как бы вы оценили свой опыт работы с сервисами Google Cloud?
2. Настройка и требования
Самостоятельная настройка среды
- Войдите в Google Cloud Console и создайте новый проект или повторно используйте существующий. Если у вас еще нет учетной записи Gmail или Google Workspace, вам необходимо ее создать .
- Имя проекта — это отображаемое имя для участников этого проекта. Это строка символов, не используемая API Google. Вы всегда можете обновить его.
- Идентификатор проекта уникален для всех проектов Google Cloud и является неизменяемым (невозможно изменить после его установки). Cloud Console автоматически генерирует уникальную строку; обычно тебя не волнует, что это такое. В большинстве лабораторий кода вам потребуется указать идентификатор проекта (обычно идентифицируемый как
PROJECT_ID). Если вам не нравится сгенерированный идентификатор, вы можете создать другой случайный идентификатор. Альтернативно, вы можете попробовать свой собственный и посмотреть, доступен ли он. Его нельзя изменить после этого шага и он сохраняется на протяжении всего проекта. - К вашему сведению, есть третье значение — номер проекта , которое используют некоторые API. Подробнее обо всех трех этих значениях читайте в документации .
- Затем вам необходимо включить выставление счетов в Cloud Console, чтобы использовать облачные ресурсы/API. Прохождение этой кодовой лаборатории не будет стоить много, если вообще что-то стоить. Чтобы отключить ресурсы и избежать выставления счетов за пределами этого руководства, вы можете удалить созданные вами ресурсы или удалить проект. Новые пользователи Google Cloud имеют право на участие в программе бесплатной пробной версии стоимостью 300 долларов США .
Запустить Cloud Shell
Хотя Google Cloud можно управлять удаленно с вашего ноутбука, в этой лабораторной работе вы используете Cloud Shell — среду командной строки, работающую в облаке.
Активировать Cloud Shell
- В Cloud Console нажмите «Активировать Cloud Shell».
.
Если вы запускаете Cloud Shell впервые, вы увидите промежуточный экран с описанием того, что это такое. Если вам был представлен промежуточный экран, нажмите «Продолжить» .
Подготовка и подключение к Cloud Shell займет всего несколько минут.
Эта виртуальная машина загружена всеми необходимыми инструментами разработки. Он предлагает постоянный домашний каталог объемом 5 ГБ и работает в Google Cloud, что значительно повышает производительность сети и аутентификацию. Большую часть, если не всю, работу в этой лаборатории кода можно выполнить с помощью браузера.
После подключения к Cloud Shell вы увидите, что вы прошли аутентификацию и что для проекта установлен идентификатор вашего проекта.
- Выполните следующую команду в Cloud Shell, чтобы подтвердить, что вы прошли аутентификацию:
gcloud auth list
Вывод команды
Credentialed Accounts
ACTIVE ACCOUNT
* <my_account>@<my_domain.com>
To set the active account, run:
$ gcloud config set account `ACCOUNT`
- Выполните следующую команду в Cloud Shell, чтобы убедиться, что команда gcloud знает о вашем проекте:
gcloud config list project
Вывод команды
[core] project = <PROJECT_ID>
Если это не так, вы можете установить это с помощью этой команды:
gcloud config set project <PROJECT_ID>
Вывод команды
Updated property [core/project].
3. Настройка среды
Прежде чем начать использовать Document AI, выполните следующую команду в Cloud Shell, чтобы включить Document AI API:
gcloud services enable documentai.googleapis.com
Вы должны увидеть что-то вроде этого:
Operation "operations/..." finished successfully.
Теперь вы можете использовать Document AI!
Перейдите в свой домашний каталог:
cd ~
Создайте виртуальную среду Python, чтобы изолировать зависимости:
virtualenv venv-docai
Активируйте виртуальную среду:
source venv-docai/bin/activate
Установите IPython, клиентскую библиотеку Document AI и python-tabulate (который вы будете использовать для печати результатов запроса):
pip install ipython google-cloud-documentai tabulate
Вы должны увидеть что-то вроде этого:
... Installing collected packages: ..., tabulate, ipython, google-cloud-documentai Successfully installed ... google-cloud-documentai-2.15.0 ...
Теперь вы готовы использовать клиентскую библиотеку Document AI!
Установите следующие переменные среды:
export PROJECT_ID=$(gcloud config get-value core/project)
# Choose "us" or "eu" export API_LOCATION="us"
С этого момента все шаги должны выполняться за один сеанс.
Убедитесь, что переменные среды определены правильно:
echo $PROJECT_ID
echo $API_LOCATION
На следующих шагах вы будете использовать интерактивный интерпретатор Python под названием IPython , который вы только что установили. Запустите сеанс, запустив ipython в Cloud Shell:
ipython
Вы должны увидеть что-то вроде этого:
Python 3.9.2 (default, Feb 28 2021, 17:03:44) Type 'copyright', 'credits' or 'license' for more information IPython 8.14.0 -- An enhanced Interactive Python. Type '?' for help. In [1]:
Скопируйте следующий код в свой сеанс IPython:
import os
from typing import Iterator, MutableSequence, Optional, Sequence, Tuple
import google.cloud.documentai_v1 as docai
from tabulate import tabulate
PROJECT_ID = os.getenv("PROJECT_ID", "")
API_LOCATION = os.getenv("API_LOCATION", "")
assert PROJECT_ID, "PROJECT_ID is undefined"
assert API_LOCATION in ("us", "eu"), "API_LOCATION is incorrect"
# Test processors
document_ocr_display_name = "document-ocr"
form_parser_display_name = "form-parser"
test_processor_display_names_and_types = (
(document_ocr_display_name, "OCR_PROCESSOR"),
(form_parser_display_name, "FORM_PARSER_PROCESSOR"),
)
def get_client() -> docai.DocumentProcessorServiceClient:
client_options = {"api_endpoint": f"{API_LOCATION}-documentai.googleapis.com"}
return docai.DocumentProcessorServiceClient(client_options=client_options)
def get_parent(client: docai.DocumentProcessorServiceClient) -> str:
return client.common_location_path(PROJECT_ID, API_LOCATION)
def get_client_and_parent() -> Tuple[docai.DocumentProcessorServiceClient, str]:
client = get_client()
parent = get_parent(client)
return client, parent
Вы готовы сделать свой первый запрос и получить типы процессоров.
4. Получение типов процессоров
Прежде чем создавать процессор на следующем этапе, выберите доступные типы процессоров. Вы можете получить этот список с помощью fetch_processor_types .
Добавьте следующие функции в ваш сеанс IPython:
def fetch_processor_types() -> MutableSequence[docai.ProcessorType]:
client, parent = get_client_and_parent()
response = client.fetch_processor_types(parent=parent)
return response.processor_types
def print_processor_types(processor_types: Sequence[docai.ProcessorType]):
def sort_key(pt):
return (not pt.allow_creation, pt.category, pt.type_)
sorted_processor_types = sorted(processor_types, key=sort_key)
data = processor_type_tabular_data(sorted_processor_types)
headers = next(data)
colalign = next(data)
print(tabulate(data, headers, tablefmt="pretty", colalign=colalign))
print(f"→ Processor types: {len(sorted_processor_types)}")
def processor_type_tabular_data(
processor_types: Sequence[docai.ProcessorType],
) -> Iterator[Tuple[str, str, str, str]]:
def locations(pt):
return ", ".join(sorted(loc.location_id for loc in pt.available_locations))
yield ("type", "category", "allow_creation", "locations")
yield ("left", "left", "left", "left")
if not processor_types:
yield ("-", "-", "-", "-")
return
for pt in processor_types:
yield (pt.type_, pt.category, f"{pt.allow_creation}", locations(pt))
Перечислите типы процессоров:
processor_types = fetch_processor_types()
print_processor_types(processor_types)
У вас должно получиться что-то вроде следующего:
+---------------------------------+-------------+----------------+------------+ | type | category | allow_creation | locations | +---------------------------------+-------------+----------------+------------+ | CUSTOM_CLASSIFICATION_PROCESSOR | CUSTOM | True | eu, us... | | CUSTOM_EXTRACTION_PROCESSOR | CUSTOM | True | eu, us... | | FORM_PARSER_PROCESSOR | GENERAL | True | eu, us... | | OCR_PROCESSOR | GENERAL | True | eu, us... | | EXPENSE_PROCESSOR | SPECIALIZED | True | eu, us... | ... +---------------------------------+-------------+----------------+------------+ → Processor types: 40
Теперь у вас есть вся информация, необходимая для создания процессоров на следующем этапе.
5. Создание процессоров
Чтобы создать процессор, вызовите create_processor , указав отображаемое имя и тип процессора.
Добавьте следующую функцию:
def create_processor(display_name: str, type: str) -> docai.Processor:
client, parent = get_client_and_parent()
processor = docai.Processor(display_name=display_name, type_=type)
return client.create_processor(parent=parent, processor=processor)
Создайте тестовые процессоры:
separator = "=" * 80
for display_name, type in test_processor_display_names_and_types:
print(separator)
print(f"Creating {display_name} ({type})...")
try:
create_processor(display_name, type)
except Exception as err:
print(err)
print(separator)
print("Done")
Вы должны получить следующее:
================================================================================ Creating document-ocr (OCR_PROCESSOR)... ================================================================================ Creating form-parser (FORM_PARSER_PROCESSOR)... ================================================================================ Done
Вы создали новые процессоры!
Далее посмотрим, как составить список процессоров.
6. Листинг обработчиков проекта
list_processors возвращает список всех процессоров, принадлежащих вашему проекту.
Добавьте следующие функции:
def list_processors() -> MutableSequence[docai.Processor]:
client, parent = get_client_and_parent()
response = client.list_processors(parent=parent)
return list(response.processors)
def print_processors(processors: Optional[Sequence[docai.Processor]] = None):
def sort_key(processor):
return processor.display_name
if processors is None:
processors = list_processors()
sorted_processors = sorted(processors, key=sort_key)
data = processor_tabular_data(sorted_processors)
headers = next(data)
colalign = next(data)
print(tabulate(data, headers, tablefmt="pretty", colalign=colalign))
print(f"→ Processors: {len(sorted_processors)}")
def processor_tabular_data(
processors: Sequence[docai.Processor],
) -> Iterator[Tuple[str, str, str]]:
yield ("display_name", "type", "state")
yield ("left", "left", "left")
if not processors:
yield ("-", "-", "-")
return
for processor in processors:
yield (processor.display_name, processor.type_, processor.state.name)
Вызовите функции:
processors = list_processors()
print_processors(processors)
Вы должны получить следующее:
+--------------+-----------------------+---------+ | display_name | type | state | +--------------+-----------------------+---------+ | document-ocr | OCR_PROCESSOR | ENABLED | | form-parser | FORM_PARSER_PROCESSOR | ENABLED | +--------------+-----------------------+---------+ → Processors: 2
Чтобы получить процессор по его отображаемому имени, добавьте следующую функцию:
def get_processor(
display_name: str,
processors: Optional[Sequence[docai.Processor]] = None,
) -> Optional[docai.Processor]:
if processors is None:
processors = list_processors()
for processor in processors:
if processor.display_name == display_name:
return processor
return None
Проверьте функцию:
processor = get_processor(document_ocr_display_name, processors)
assert processor is not None
print(processor)
Вы должны увидеть что-то вроде этого:
name: "projects/PROJECT_NUM/locations/LOCATION/processors/PROCESSOR_ID" type_: "OCR_PROCESSOR" display_name: "document-ocr" state: ENABLED ...
Теперь вы знаете, как составить список процессоров вашего проекта и получить их по отображаемым именам. Далее посмотрим, как использовать процессор.
7. Использование процессоров
Документы можно оформить двумя способами:
- Синхронно : вызовите
process_documentдля анализа одного документа и непосредственного использования результатов. - Асинхронно : вызов
batch_process_documentsдля запуска пакетной обработки нескольких или больших документов.
Ваш тестовый документ ( PDF ) представляет собой отсканированную анкету, заполненную рукописными ответами. Загрузите его в свой рабочий каталог прямо из сеанса IPython:
!gsutil cp gs://cloud-samples-data/documentai/form.pdf .
Проверьте содержимое вашего рабочего каталога:
!ls
У вас должно быть следующее:
... form.pdf ... venv-docai ...
Вы можете использовать синхронный process_document для анализа локального файла. Добавьте следующую функцию:
def process_file(
processor: docai.Processor,
file_path: str,
mime_type: str,
) -> docai.Document:
client = get_client()
with open(file_path, "rb") as document_file:
document_content = document_file.read()
document = docai.RawDocument(content=document_content, mime_type=mime_type)
request = docai.ProcessRequest(raw_document=document, name=processor.name)
response = client.process_document(request)
return response.document
Поскольку ваш документ представляет собой анкету, выберите парсер форм. Помимо извлечения текста (печатного и рукописного), который выполняют все процессоры, этот общий процессор обнаруживает поля формы.
Проанализируйте документ:
processor = get_processor(form_parser_display_name)
assert processor is not None
file_path = "./form.pdf"
mime_type = "application/pdf"
document = process_file(processor, file_path, mime_type)
Все процессоры сначала выполняют процедуру оптического распознавания символов (OCR). Просмотрите текст, обнаруженный проходом OCR:
document.text.split("\n")
Вы должны увидеть что-то вроде следующего:
['FakeDoc M.D.',
'HEALTH INTAKE FORM',
'Please fill out the questionnaire carefully. The information you provide will be used to complete',
'your health profile and will be kept confidential.',
'Date:',
'Sally',
'Walker',
'Name:',
'9/14/19',
'DOB: 09/04/1986',
'Address: 24 Barney Lane City: Towaco State: NJ Zip: 07082',
'Email: Sally, waller@cmail.com Phone #: (906) 917-3486',
'Gender: F',
'Single Occupation: Software Engineer',
'Referred By: None',
'Emergency Contact: Eva Walker Emergency Contact Phone: (906) 334-8976',
'Marital Status:',
...
]
Добавьте следующие функции для распечатки обнаруженных полей формы:
def print_form_fields(document: docai.Document):
sorted_form_fields = form_fields_sorted_by_ocr_order(document)
data = form_field_tabular_data(sorted_form_fields, document)
headers = next(data)
colalign = next(data)
print(tabulate(data, headers, tablefmt="pretty", colalign=colalign))
print(f"→ Form fields: {len(sorted_form_fields)}")
def form_field_tabular_data(
form_fields: Sequence[docai.Document.Page.FormField],
document: docai.Document,
) -> Iterator[Tuple[str, str, str]]:
yield ("name", "value", "confidence")
yield ("right", "left", "right")
if not form_fields:
yield ("-", "-", "-")
return
for form_field in form_fields:
name_layout = form_field.field_name
value_layout = form_field.field_value
name = text_from_layout(name_layout, document)
value = text_from_layout(value_layout, document)
confidence = value_layout.confidence
yield (name, value, f"{confidence:.1%}")
Также добавьте эти служебные функции:
def form_fields_sorted_by_ocr_order(
document: docai.Document,
) -> MutableSequence[docai.Document.Page.FormField]:
def sort_key(form_field):
# Sort according to the field name detected position
text_anchor = form_field.field_name.text_anchor
return text_anchor.text_segments[0].start_index if text_anchor else 0
fields = (field for page in document.pages for field in page.form_fields)
return sorted(fields, key=sort_key)
def text_from_layout(
layout: docai.Document.Page.Layout,
document: docai.Document,
) -> str:
full_text = document.text
segs = layout.text_anchor.text_segments
text = "".join(full_text[seg.start_index : seg.end_index] for seg in segs)
if text.endswith("\n"):
text = text[:-1]
return text
Распечатайте обнаруженные поля формы:
print_form_fields(document)
Вы должны получить распечатку, подобную следующей:
+--------------+-------------------------+------------+ | name | value | confidence | +--------------+-------------------------+------------+ | Date: | 9/14/19 | 100.0% | | Name: | Sally | 99.7% | | | Walker | | | DOB: | 09/04/1986 | 100.0% | | Address: | 24 Barney Lane | 99.9% | | City: | Towaco | 99.8% | | State: | NJ | 99.7% | | Zip: | 07082 | 99.5% | | Email: | Sally, waller@cmail.com | 99.6% | | Phone #: | (906) 917-3486 | 100.0% | | Gender: | F | 100.0% | | Occupation: | Software Engineer | 100.0% | | Referred By: | None | 100.0% | ... +--------------+-------------------------+------------+ → Form fields: 17
Просмотрите имена и значения полей, которые были обнаружены ( PDF ). Вот верхняя половина анкеты:
Вы проанализировали форму, содержащую как печатный, так и рукописный текст. Вы также с высокой уверенностью обнаружили его поля. В результате ваши пиксели преобразуются в структурированные данные!
8. Включение и отключение процессоров
С помощью disable_processor и enable_processor вы можете контролировать, можно ли использовать процессор.
Добавьте следующие функции:
def update_processor_state(processor: docai.Processor, enable_processor: bool):
client = get_client()
if enable_processor:
request = docai.EnableProcessorRequest(name=processor.name)
operation = client.enable_processor(request)
else:
request = docai.DisableProcessorRequest(name=processor.name)
operation = client.disable_processor(request)
operation.result() # Wait for operation to complete
def enable_processor(processor: docai.Processor):
update_processor_state(processor, True)
def disable_processor(processor: docai.Processor):
update_processor_state(processor, False)
Отключите процессор синтаксического анализатора форм и проверьте состояние ваших процессоров:
processor = get_processor(form_parser_display_name)
assert processor is not None
disable_processor(processor)
print_processors()
Вы должны получить следующее:
+--------------+-----------------------+----------+ | display_name | type | state | +--------------+-----------------------+----------+ | document-ocr | OCR_PROCESSOR | ENABLED | | form-parser | FORM_PARSER_PROCESSOR | DISABLED | +--------------+-----------------------+----------+ → Processors: 2
Снова включите процессор синтаксического анализатора форм:
enable_processor(processor)
print_processors()
Вы должны получить следующее:
+--------------+-----------------------+---------+ | display_name | type | state | +--------------+-----------------------+---------+ | document-ocr | OCR_PROCESSOR | ENABLED | | form-parser | FORM_PARSER_PROCESSOR | ENABLED | +--------------+-----------------------+---------+ → Processors: 2
Далее посмотрим, как управлять версиями процессора.
9. Управление версиями процессора
Процессоры могут быть доступны в нескольких версиях. Узнайте, как использовать методы list_processor_versions и set_default_processor_version .
Добавьте следующие функции:
def list_processor_versions(
processor: docai.Processor,
) -> MutableSequence[docai.ProcessorVersion]:
client = get_client()
response = client.list_processor_versions(parent=processor.name)
return list(response)
def get_sorted_processor_versions(
processor: docai.Processor,
) -> MutableSequence[docai.ProcessorVersion]:
def sort_key(processor_version: docai.ProcessorVersion):
return processor_version.name
versions = list_processor_versions(processor)
return sorted(versions, key=sort_key)
def print_processor_versions(processor: docai.Processor):
versions = get_sorted_processor_versions(processor)
default_version_name = processor.default_processor_version
data = processor_versions_tabular_data(versions, default_version_name)
headers = next(data)
colalign = next(data)
print(tabulate(data, headers, tablefmt="pretty", colalign=colalign))
print(f"→ Processor versions: {len(versions)}")
def processor_versions_tabular_data(
versions: Sequence[docai.ProcessorVersion],
default_version_name: str,
) -> Iterator[Tuple[str, str, str]]:
yield ("version", "display name", "default")
yield ("left", "left", "left")
if not versions:
yield ("-", "-", "-")
return
for version in versions:
mapping = docai.DocumentProcessorServiceClient.parse_processor_version_path(
version.name
)
processor_version = mapping["processor_version"]
is_default = "Y" if version.name == default_version_name else ""
yield (processor_version, version.display_name, is_default)
Перечислите доступные версии процессора OCR:
processor = get_processor(document_ocr_display_name)
assert processor is not None
print_processor_versions(processor)
Вы получаете версии процессоров:
+--------------------------------+--------------------------+---------+ | version | display name | default | +--------------------------------+--------------------------+---------+ | pretrained-ocr-v1.0-2020-09-23 | Google Stable | Y | | pretrained-ocr-v1.1-2022-09-12 | Google Release Candidate | | | pretrained-ocr-v1.2-2022-11-10 | Google Release Candidate | | +--------------------------------+--------------------------+---------+ → Processor versions: 3
Теперь добавьте функцию для изменения версии процессора по умолчанию:
def set_default_processor_version(processor: docai.Processor, version_name: str):
client = get_client()
request = docai.SetDefaultProcessorVersionRequest(
processor=processor.name,
default_processor_version=version_name,
)
operation = client.set_default_processor_version(request)
operation.result() # Wait for operation to complete
Переключитесь на последнюю версию процессора:
processor = get_processor(document_ocr_display_name)
assert processor is not None
versions = get_sorted_processor_versions(processor)
new_version = versions[-1] # Latest version
set_default_processor_version(processor, new_version.name)
# Update the processor info
processor = get_processor(document_ocr_display_name)
assert processor is not None
print_processor_versions(processor)
Вы получаете конфигурацию новой версии:
+--------------------------------+--------------------------+---------+ | version | display name | default | +--------------------------------+--------------------------+---------+ | pretrained-ocr-v1.0-2020-09-23 | Google Stable | | | pretrained-ocr-v1.1-2022-09-12 | Google Release Candidate | | | pretrained-ocr-v1.2-2022-11-10 | Google Release Candidate | Y | +--------------------------------+--------------------------+---------+ → Processor versions: 3
И далее, окончательный метод управления процессором (удаление).
10. Удаление процессоров
Наконец, узнайте, как использовать метод delete_processor .
Добавьте следующую функцию:
def delete_processor(processor: docai.Processor):
client = get_client()
operation = client.delete_processor(name=processor.name)
operation.result() # Wait for operation to complete
Удалите свои тестовые процессоры:
processors_to_delete = [dn for dn, _ in test_processor_display_names_and_types]
print("Deleting processors...")
for processor in list_processors():
if processor.display_name not in processors_to_delete:
continue
print(f" Deleting {processor.display_name}...")
delete_processor(processor)
print("Done\n")
print_processors()
Вы должны получить следующее:
Deleting processors... Deleting form-parser... Deleting document-ocr... Done +--------------+------+-------+ | display_name | type | state | +--------------+------+-------+ | - | - | - | +--------------+------+-------+ → Processors: 0
Вы рассмотрели все методы управления процессором! Вы почти закончили...
11. Поздравляем!
Вы узнали, как управлять процессорами Document AI с помощью Python!
Очистить
Чтобы очистить среду разработки из Cloud Shell:
- Если вы все еще находитесь в сеансе IPython, вернитесь в оболочку:
exit - Прекратите использовать виртуальную среду Python:
deactivate - Удалите папку виртуальной среды:
cd ~ ; rm -rf ./venv-docai
Чтобы удалить проект Google Cloud из Cloud Shell:
- Получите текущий идентификатор проекта:
PROJECT_ID=$(gcloud config get-value core/project) - Убедитесь, что это именно тот проект, который вы хотите удалить:
echo $PROJECT_ID - Удалить проект:
gcloud projects delete $PROJECT_ID
Узнать больше
- Попробуйте Document AI в своем браузере: https://cloud.google.com/document-ai/docs/drag-and-drop
- Документация об процессоре AI: https://cloud.google.com/document-ai/docs/processors-list.
- Python в Google Cloud: https://cloud.google.com/python
- Облачные клиентские библиотеки для Python: https://github.com/googleapis/google-cloud-python.
Лицензия
Эта работа распространяется под лицензией Creative Commons Attribution 2.0 Generic License.