Google Cloud Document AI позволяет распознавать текст в PDF и изображениях, находить таблицы, пары ключ — значение, поля счетов и форм, разделять многостраничные пакеты и возвращать результат в структурированном виде. В веб-интерфейсе можно создать процессор, загрузить тестовый документ, проверить выделенные области, настроить схему полей, обучить собственную модель и оценить точность, а для рабочих потоков доступны синхронные и пакетные запросы через API.

Работа строится вокруг процессоров. Для обычного OCR выбирают Enterprise Document OCR, для форм — Form Parser, для смысловой структуры и фрагментов под поиск — Layout Parser, для типовых счетов, чеков и финансовых документов — специализированные парсеры. Когда готового шаблона недостаточно, создают Custom Extractor, описывают собственные поля и при необходимости добавляют размеченные примеры.

В консоли результат теста показывается рядом с исходной страницей: слева перечисляются извлеченные сущности или блоки, справа видны рамки на документе, а вкладка JSON раскрывает полный ответ. Такой режим удобен для быстрой проверки гипотезы, но промышленная обработка требует проекта Google Cloud, включенного API, корректных ролей IAM, выбранного региона и продуманного хранения входных файлов и результатов.

Как устроен рабочий процесс

Первое решение принимают не по расширению файла, а по требуемому выходу. Если нужен непрерывный текст с координатами слов, языками, страницами и оценкой качества, достаточно OCR-процессора. Если важны названия полей, значения, строки таблиц и нормализованные даты или суммы, нужен парсер. Если один PDF содержит несколько самостоятельных документов, перед извлечением ставят классификатор или разделитель. Такой порядок предотвращает типичную ошибку: попытку получить надежную структуру счета из одного только OCR-текста.

Процессор создается внутри выбранного проекта и привязывается к месту обработки. После создания консоль показывает его идентификатор, тип, состояние, регион, используемую версию модели и вкладки для тестирования или обучения. Для проверки можно загрузить один файл непосредственно из браузера. Для регулярного потока приложение отправляет содержимое документа в запросе либо указывает объект в Cloud Storage. Синхронный вызов возвращает объект Document сразу, а пакетный запускает длительную операцию и записывает JSON-файлы в указанный каталог Cloud Storage.

Практически полезно разделять три среды: экспериментальную, тестовую и рабочую. В экспериментальном проекте меняют схему и проверяют новые модели на обезличенных примерах. В тестовом фиксируют набор контрольных документов и интеграционные проверки. В рабочем проекте ограничивают права, задают квоты и наблюдение, а версии процессоров переключают только после сравнения метрик. Это уменьшает риск незаметно изменить состав полей или поведение модели в уже работающем конвейере.

Workbench и галерея процессоров

Страница Workbench предназначена для процессоров, которые настраиваются под собственные документы. На ней доступны Custom Extractor для извлечения сущностей, Custom Classifier для определения класса, Custom Splitter для поиска границ документов и Summarizer для подготовки краткого содержания. Карточка не является готовым обработчиком сама по себе: после нажатия Create processor задаются имя и регион, затем формируется схема, а для части режимов создается набор данных или выбирается базовая модель.

Processor Gallery содержит готовые варианты. В общей группе находятся Document OCR, Document Splitter, Form Parser и Layout Parser. Отдельные категории включают специализированные процессоры для счетов, расходов, удостоверений и финансовых форм. Доступность конкретного типа зависит от региона и стадии выпуска, поэтому реальный список лучше смотреть в галерее выбранного проекта или получать методом fetchProcessorTypes. Нельзя переносить предположение из одного региона в другой: процессор, доступный в US, может отсутствовать в отдельной европейской или азиатской локации.

Имя процессора используется для навигации и журналов, а не как тип модели. Два процессора с одинаковой задачей могут работать на разных версиях и давать различающиеся ответы. Поэтому в интеграции сохраняют не только читаемое имя, но и полный ресурсный идентификатор с проектом, локацией и processor ID. При воспроизводимых тестах запрос направляют на конкретную processor version; обращение только к процессору использует назначенную версию по умолчанию.

Создание процессора и выбор региона

В диалоге создания указывают понятное имя и регион хранения и обработки. Для большинства сценариев доступны мультирегионы US и EU; отдельные типы частично представлены в Mumbai, Singapore, Sydney, London, Frankfurt и Montréal. Локация входит в адрес API и в имя ресурса. Если процессор создан в EU, клиент должен обращаться к европейской конечной точке и использовать ресурс с locations/eu. Смешение конечной точки и локации приводит к ошибкам поиска ресурса или к обращению не в тот контур.

Выбор региона делают до загрузки производственных документов. Перенос готового набора, версии и интеграции между проектами или локациями требует отдельной процедуры, прав на оба проекта и доступа к Cloud Storage. Для регулируемых данных это не формальность: именно локация определяет, где сервис хранит и обрабатывает ресурс. Пользователи могут обращаться к консоли из разных стран, но сам процессор сохраняет выбранное размещение.

В дополнительных параметрах пользовательского экстрактора выбирается управляемое Google хранилище либо собственный bucket, а также вариант шифрования. При CMEK ключ создается в Cloud KMS, его локация должна соответствовать требованиям ресурса, а сервисному агенту Document AI выдается роль шифрования и расшифрования. Если ключ отключен, удален или у агента отозвана роль, операции с защищенным процессором перестают выполняться, поэтому смену ключей проверяют заранее на тестовом ресурсе.

Проверка документа в веб-интерфейсе

После создания готового процессора на странице деталей находится кнопка Upload Test Document. Файл передается на анализ, а консоль открывает экран результата. Для Form Parser слева видны key-value pairs, таблицы и сущности; для Layout Parser — текстовые, табличные и графические блоки; для специализированного парсера — поля его схемы. Выбор строки подсвечивает соответствующую область на странице, а рамки помогают понять, откуда взялось значение.

Тестовый просмотр не заменяет проверку JSON. Визуальная панель иногда сокращает длинные строки, объединяет элементы для удобства или показывает только поддерживаемые представления. Во вкладке JSON находятся текстовые якоря, координаты, confidence, normalizedValue, сведения о страницах, языках и дополнительные структуры конкретного процессора. При разработке интеграции сначала сохраняют полный ответ на контрольных документах, затем пишут преобразование в собственную схему и лишь после этого удаляют ненужные поля через FieldMask.

У тестовой загрузки есть практические ограничения по размеру, числу страниц и типу процессора. Демонстрационная страница допускает файлы до 20 МБ, а рабочие запросы подчиняются другим лимитам. Не стоит оценивать пакетную производительность по одному файлу в браузере: консоль предназначена для проверки качества и настройки, тогда как массовая очередь должна использовать API и Cloud Storage.

Enterprise Document OCR

Enterprise Document OCR извлекает печатный и рукописный текст, страницы, блоки, абзацы, строки, слова и при включенной детализации символы. Для каждого элемента возвращается привязка к общему тексту и геометрия на странице. Это позволяет не только искать слова, но и восстановить порядок чтения, подсветить найденный фрагмент в просмотрщике, определить колонку или передать координаты в систему контроля качества.

Для цифровых PDF можно включить извлечение встроенного текста. Такой режим сохраняет символы, которые уже присутствуют в файле, и помогает с повернутыми надписями, необычными размерами шрифта или частично перекрытым текстом. Для сканов полезна автоматическая коррекция поворота. Если документ поступает с камеры, перед отправкой все равно желательно проверить обрезку, резкость и блики: модель умеет оценивать качество, но не может восстановить отсутствующий край страницы или полностью засвеченную строку.

Опции OCR задаются в ProcessOptions. Можно включить оценки качества изображения и получить общий qualityScore вместе с обнаруженными дефектами, запросить распознавание selection marks, сведения о стилях шрифта или математические формулы в LaTeX. Эти возможности зависят от поколения OCR и могут относиться к премиальным функциям, поэтому клиент должен формировать параметры только для совместимой версии. Универсальный запрос со всеми флагами часто ломается при переключении на старую модель.

Языковые подсказки уместны, когда документ содержит ограниченный известный набор языков или похожие алфавиты. Жестко задавать один язык для смешанного пакета рискованно: модель может хуже интерпретировать иностранные фамилии, артикулы и адреса. Для архивов с разными источниками лучше сначала измерить качество без подсказок, затем сравнить отдельные группы. Enterprise OCR заявляет поддержку более двухсот языков, но точность для конкретного шрифта и качества скана проверяется на собственном наборе.

Когда OCR недостаточно

OCR сообщает, какие символы находятся на странице, но не всегда отвечает, что они означают. Строка Итого 18 450,00 будет распознана, однако без парсера приложение само должно определить, что число является итоговой суммой, отделить налог и связать значение с валютой. На стабильной форме это можно сделать правилами по координатам и словам. На счетах разных поставщиков правила быстро разрастаются, поэтому для сущностей, таблиц и нормализации выбирают Form Parser, специализированный парсер или Custom Extractor.

Form Parser и структурированные формы

Form Parser предназначен для документов, где данные выражены парами название поля — значение, таблицами, отметками выбора и обычным текстом. На медицинской анкете он может связать подписи Date, DOB, Name и Address с заполненными значениями, а в таблице определить строки и ячейки. Результат удобнее чистого OCR, потому что приложение получает логические пары и структуру таблицы, а не только последовательность слов.

Этот процессор предварительно обучен и не дообучается на пользовательском наборе. Если форма нестандартна, подписи неоднозначны или нужно извлекать доменные поля, которых нет в общем представлении, лучше перейти к Custom Extractor. Form Parser также не редактирует исходный PDF и не вписывает исправленные значения обратно. Корректировки выполняются в собственной системе, а новый документ формируется отдельным PDF-инструментом.

При тестировании форм следует включать пустые поля, несколько вариантов отметок, длинные многострочные значения и страницы с разным масштабом. Ошибка, которая не видна на идеальном образце, часто проявляется на рукописной анкете, где значение заходит на подпись, или в скане с перекосом. Проверяют не только наличие пары, но и правильность textAnchor, confidence и геометрии. Если одно поле иногда разбивается на две сущности, слой преобразования должен уметь объединить их по координатам и схеме.

Layout Parser для структуры и RAG

Layout Parser выделяет заголовки, абзацы, списки, таблицы и изображения, а затем может формировать контекстные chunks. Это полезно для поиска и Retrieval-Augmented Generation, где простой разрез текста через фиксированное число символов разрушает смысл: заголовок отделяется от раздела, строка таблицы — от шапки, примечание — от объекта. Layout Parser сохраняет больше информации о структуре и позволяет передавать в индекс фрагменты, связанные с исходными блоками.

В интерфейсе анализа доступны Text Blocks, Table Blocks и Image Blocks. На стороне API настраиваются размер фрагмента и включение заголовков-предков; для некоторых версий доступны аннотации таблиц и изображений. Размер chunk выбирают по задаче: слишком маленький увеличивает число фрагментов и теряет контекст, слишком большой ухудшает точность поиска и расходует контекст модели. Настройку проверяют на реальных вопросах, а не только по визуально аккуратному разбиению.

Document view в быстром тесте Layout Parser показывается для PDF. Сам процессор поддерживает конкретные MIME-типы, и набор может отличаться от общего списка Document AI. Поэтому нельзя считать, что любой файл, принятый OCR, подойдет Layout Parser. Перед запуском конвейера сверяют документацию выбранной версии и при необходимости преобразуют DOCX или презентации в PDF отдельным этапом.

Специализированные парсеры

Готовые парсеры ориентированы на конкретные классы документов и возвращают заранее определенные сущности. Для Invoice Parser это могут быть номер и дата счета, поставщик, покупатель, суммы, налоги и строки позиций; Expense Parser рассчитан на расходы и чеки; финансовые и идентификационные процессоры имеют собственные схемы. Преимущество состоит в быстром старте: не нужно проектировать все поля с нуля. Ограничение — набор сущностей и поддерживаемые языки или регионы задаются типом процессора.

Перед выбором готового парсера составляют таблицу обязательных полей. Если процессор извлекает 80 процентов нужной информации, оставшиеся поля нельзя просто ожидать в ответе. Возможны три стратегии: дополнить результат правилами, выбрать дообучаемый процессор или создать Custom Extractor. Решение зависит от стабильности документов и цены ошибки. Для платежных реквизитов обычно важнее контролируемая схема и тестовый набор, чем минимальное время первой демонстрации.

Нормализованные значения следует хранить вместе с исходным текстом. Например, дата может вернуться в унифицированном представлении, а сумма — как число и валюта. Исходная строка нужна для аудита и спорных случаев, normalizedValue — для расчетов и загрузки в базу. Если нормализация отсутствует или confidence ниже внутреннего порога, документ направляют на проверку, а не подставляют нулевое значение.

Custom Extractor: схема собственных полей

Custom Extractor нужен, когда структура документов специфична: договоры с нестандартными реквизитами, технические акты, заявления, анкеты компании, отчеты или комбинированные формы. В Get started создаются поля, у каждого задаются имя, тип данных, кратность и описание. Поддерживаются простые и вложенные сущности, а некоторые модели умеют работать с несколькими уровнями вложенности и полями, переходящими между страницами.

Имя поля влияет на генеративное извлечение. Оно должно точно описывать сущность и использовать язык, который встречается в документе. Неудачное сокращение вроде addr1 хуже сообщает модели смысл, чем employer_address. Пробелы в именах не используются; обычно применяют нижний регистр и подчеркивания. Описание поля добавляет контекст: формат, расположение, отличия от похожего значения, допустимые варианты. Описание не должно превращаться в сложную проверку бизнес-правил — для этого служит последующая валидация.

Occurrence определяет ожидаемое число значений. Required single подходит для обязательного единственного поля, optional multiple — для повторяющихся элементов. Неверная кратность создает проблемы на этапе разметки и в потребляющем коде. Если в части документов встречаются несколько адресов, нельзя объявлять поле строго одиночным только потому, что первый образец был простым. Схему проектируют по диапазону реальных вариантов и фиксируют контракт для API-клиентов.

Document-level prompt описывает документ целиком и ограничен по длине, поэтому в нем оставляют только сведения, полезные всем полям: тип документа, географический контекст, формат дат, единицы измерения, характер вложенных таблиц. Конкретные подсказки относятся в descriptions отдельных полей. Слишком длинная или противоречивая инструкция ухудшает воспроизводимость и усложняет диагностику, поэтому каждое изменение проверяют на неизменном тестовом наборе.

Набор данных: импорт и разбиение

Для обучения, дообучения и объективной оценки создается dataset. Документы импортируются из Cloud Storage или, в поддерживаемых сценариях, с локального компьютера через консоль. При импорте выбирается training, test или unassigned, либо автоматическое разбиение. Файлы с неподдерживаемыми символами в именах могут не импортироваться; доступ к bucket проверяется отдельно для пользователя и сервисного агента.

Обучающая и тестовая части решают разные задачи. Training показывает модели примеры, test остается независимым измерителем качества. Если один и тот же шаблон, поставщик или почти одинаковый документ попадает в обе части, метрики становятся завышенными. Для счетов разумно делить данные по поставщикам или временным периодам, а не случайными страницами одного пакета. Контрольный набор фиксируют до серии экспериментов и не подгоняют разметку под конкретную модель.

В Manage Dataset карточки документов фильтруются по статусу: labeled, auto-labeled, unlabeled, suggested, а также по data split. Несколько файлов можно перенести между Training, Test и Unassigned. Перед массовым перемещением полезно экспортировать текущую разметку. Удаление документа из внутреннего индекса и удаление исходного объекта Cloud Storage — разные операции, поэтому политика хранения должна явно определять обе.

Разметка, auto-labeling и контроль качества

Ручная разметка выполняется в просмотрщике документа. Пользователь выбирает поле схемы, выделяет значение рамкой или текстовым диапазоном и подтверждает сущность. Для таблиц и вложенных полей важно соблюдать одинаковые правила во всем наборе. Разные разметчики могут по-разному включать символ валюты, подпись поля или пробелы; такие расхождения воспринимаются моделью как шум. До начала работы готовят короткую инструкцию с примерами границ для каждого поля.

Auto-labeling использует существующую версию процессора, чтобы предварительно заполнить метки. Это ускоряет работу, но предсказания нужно просмотреть и исправить. Документ с автоматическими метками не должен автоматически считаться эталоном. Особенно внимательно проверяют редкие поля и случаи, где модель систематически пропускает значение: незамеченные ошибки закрепляются в следующем обучении и создают ложное ощущение прогресса.

Suggested documents помогают выбрать разнообразные примеры для разметки. Такой механизм полезен, когда в хранилище тысячи однотипных файлов и ручной случайный выбор дает много копий одного шаблона. Однако выборка остается инструментом, а не гарантией репрезентативности. Команда дополнительно контролирует доли языков, поставщиков, качества скана, числа страниц и необычных вариантов, которые важны для производственного потока.

Обучение и версии процессора

Новая версия создается из раздела Build или Train в зависимости от типа процессора. Доступные механизмы включают вызов foundation model без разметки, fine-tuning на размеченном наборе и обучение пользовательской модели. Требования к числу документов зависят от механизма и базовой версии. Для few-shot достаточно небольшого набора, но производственное качество все равно подтверждают независимым тестом; для fine-tuning официальные рекомендации могут требовать существенно больше примеров.

Версия проходит состояния подготовки и развертывания. Пока обучение не завершено, ее нельзя считать доступной для запросов. После развертывания версию можно протестировать, назначить по умолчанию или вызывать явно. В рабочем приложении предпочтительнее явный идентификатор: переключение default без изменения кода удобно, но способно незаметно изменить ответы. Если используется alias, его изменение должно сопровождаться журналом и автоматическими контрольными тестами.

Старую версию не удаляют сразу после появления новой. Сначала на одном и том же наборе сравнивают F1, precision, recall, долю документов, прошедших бизнес-валидацию, и фактические ошибки по ключевым полям. Затем часть трафика направляют на новую версию или выполняют параллельную обработку. Возможность быстро вернуть предыдущую версию важнее формального роста средней метрики, особенно когда редкое обязательное поле стало распознаваться хуже.

Оценка качества: F1, precision и recall

В Evaluate & Test отображаются агрегированные метрики и показатели по каждому полю. Precision отвечает на вопрос, какая доля предсказанных сущностей совпала с разметкой. Recall показывает, какая доля размеченных сущностей была найдена. F1 объединяет оба показателя и удобен для общего сравнения, но не заменяет анализ конкретных ошибок. Для поля номер счета пропуск и ложное значение могут иметь разную стоимость, поэтому пороги выбираются по бизнес-риску.

Ползунок confidence threshold позволяет увидеть компромисс между precision и recall. Повышение порога обычно уменьшает число сомнительных предсказаний и повышает точность оставшихся, но увеличивает пропуски. В системе с ручной проверкой можно направлять низкую уверенность оператору. В полностью автоматическом контуре лучше задать отдельные пороги по полям: адрес поставщика допускает исправление позже, а банковские реквизиты требуют более строгой проверки.

Метрики рассчитываются только для полей, которые модель умеет извлекать и которые представлены в тестовых аннотациях. Отсутствующий label не получает осмысленного показателя. Поэтому перед сравнением версий проверяют счетчики test documents, invalid documents, failed documents и число экземпляров каждого поля. Небольшой F1 на единичном редком примере не равен устойчивой оценке, а высокий показатель на повторяющемся шаблоне не гарантирует работу на новом поставщике.

Синхронная обработка через API

Синхронный метод process подходит для одного документа, когда ответ нужен в рамках пользовательского запроса. Клиент указывает ресурс процессора или версии и передает rawDocument с байтами и MIME-типом, gcsDocument со ссылкой на объект Cloud Storage либо inlineDocument для цепочки процессоров. Успешный ответ содержит Document. Размер файла, число страниц и скорость ограничены выбранным процессором; для некоторых сценариев imageless_mode расширяет лимит страниц при последовательной обработке с первой страницы.

Встроенные байты обычно используют для небольших файлов, уже полученных приложением. Base64 увеличивает размер JSON, поэтому крупные документы выгоднее предварительно помещать в Cloud Storage. Не следует записывать содержимое или токены доступа в обычный лог. Для диагностики достаточно request ID, ресурса процессора, MIME-типа, размера, количества страниц и кода ошибки; сами документы и полный ответ хранятся по правилам доступа к персональным данным.

Клиентские библиотеки доступны для нескольких языков и скрывают часть деталей REST, но региональную конечную точку и аутентификацию все равно настраивает разработчик. Application Default Credentials удобны в Cloud Run, Compute Engine и локальной разработке. Долгоживущие JSON-ключи сервисных аккаунтов требуют строгого хранения и ротации; в облачной среде предпочтительнее привязанный сервисный аккаунт без выгружаемого ключа.

Пакетная обработка и Cloud Storage

Метод batchProcess предназначен для большого числа документов и возвращает имя long-running operation. Вход задается отдельными объектами или префиксом Cloud Storage, выход — каталогом, куда сервис запишет JSON в формате Document. Пакетная операция не является низколатентной: она обрабатывается асинхронно, может находиться в очереди и должна отслеживаться до состояния done. Для пользовательского экрана ожидания лучше синхронный вызов, для ночного архива — пакетный.

Один запрос может охватывать тысячи файлов, но системные ограничения задают максимальный размер, число документов и параллельные операции. Разумный конвейер дробит вход на управляемые партии, сохраняет список объектов и operation ID, повторяет только неуспешные элементы и умеет продолжить после остановки. Простое повторение всего префикса может создать дубли и лишние расходы, поэтому каждому документу присваивают идемпотентный идентификатор.

Для чтения входа и записи результата нужны разные разрешения. Ошибка caller cannot get objects относится к вызывающей стороне, а сообщение о P4SA или сервисном агенте указывает на внутренний аккаунт Document AI. Выдавать Storage Admin всему проекту необязательно: лучше назначить Storage Object Viewer на входной bucket и Storage Object Creator на выходной, учитывая кросс-проектный доступ. Имя bucket и префикс проверяют отдельно, поскольку опечатка выглядит как проблема прав.

Структура ответа Document

Объект Document содержит общий текст и страницы. Элементы страницы ссылаются на текст через textAnchor, где индексы задают диапазон в общей строке. Layout хранит boundingPoly и confidence, detectedLanguages сообщает языки, а pageAnchor связывает сущность с фрагментом страницы. Парсеры добавляют entities, таблицы, formFields, chunks или специальные поля. Клиент не должен рассчитывать, что все разделы заполнены каждым процессором.

Для сущности полезно сохранять type, mentionText, normalizedValue, confidence, pageAnchor и свойства. Вложенные properties представляют строки счета или иерархическую схему. Порядок свойств не следует воспринимать как контракт; надежнее группировать их по type. Если бизнес-система требует один формат, создается адаптер версии: он валидирует обязательные поля, нормализует числа и даты, а неизвестные сущности сохраняет для анализа, не ломая обработку.

FieldMask уменьшает ответ, когда нужны только конкретные части, например text и entities. Это снижает сетевой объем, но слишком раннее сокращение мешает диагностике. На этапе разработки лучше собирать полный Document для контрольного набора. После стабилизации интеграции маску добавляют с автоматическим тестом, который подтверждает, что ни одно используемое поле не исчезло.

Поддерживаемые файлы и ограничения

Общий список Document AI включает PDF, GIF, TIFF, JPEG и PNG, а также BMP и WebP в отдельных режимах; часть процессоров поддерживает дополнительные форматы в preview. Конкретный процессор может принимать более узкий набор. MIME-тип должен соответствовать содержимому: переименование .jpg в .pdf не делает файл PDF и приводит к invalid argument. Для надежности приложение определяет тип по сигнатуре и сверяет его с разрешенным списком до отправки.

Системные лимиты отделяются от квот. Для онлайн-запроса максимальный размер файла составляет 40 МБ, для пакетного — 1 ГБ, а изображение ограничено 40 мегапикселями на страницу; для PDF ограничение по мегапикселям не применяется. Пакет может включать до 5000 файлов. Дополнительно каждый процессор задает предел страниц. Эти значения нельзя складывать произвольно: файл может проходить общий лимит, но превышать лимит выбранного парсера.

Большой PDF предварительно анализируют: считают страницы, проверяют защиту паролем, поврежденные объекты, вложения и необычный размер листов. При необходимости документ делят на части, сохраняя порядок и идентификатор исходника. Для юридического архива важно не менять содержимое незаметно; создают хеш исходного файла, фиксируют правила разбиения и связывают каждый выходной Document с диапазоном страниц.

Точность на сканах и рукописном тексте

Качество зависит от разрешения, контраста, поворота, сжатия, бликов, теней и целостности страницы. Слишком сильное JPEG-сжатие разрушает тонкие штрихи, а повышение разрешения не восстанавливает уже потерянные детали. Для камерных снимков полезны автоматическая обрезка и проверка четырех углов еще до загрузки. TIFF и PNG сохраняют больше деталей, но увеличивают объем; формат выбирают по пропускной способности и требованиям архива.

Рукописный текст поддерживается OCR, однако его точность сильно меняется между стилями письма и языками. Критичные рукописные поля проверяют отдельно от печатных. Если форма содержит подпись, не следует считать распознанную строку доказательством подлинности подписи: OCR извлекает видимые символы, а проверка подписи — отдельная задача. Поля с низкой уверенностью направляют человеку вместе с изображением соответствующей области.

Image quality score помогает отбраковывать нечитаемые страницы до бизнес-обработки. Сервис может сообщить дефекты вроде обрезки или блика. Порог качества определяют экспериментально: слишком высокий вызовет повторную съемку приемлемых документов, слишком низкий пропустит страницы, где ключевое поле потеряно. Лучше сочетать общий score с проверкой наличия обязательных сущностей и confidence конкретных полей.

Валидация и коррекция результата

Для Custom Extractor доступны правила validation and correction. В консоли включается Validation, при необходимости Correction, затем создаются правила. Естественное описание помогает сформулировать намерение, а поведение задается выражением CEL поддерживаемого диалекта. Правило может проверять диапазон, согласованность полей или формат и отмечать результат как прошедший или не прошедший.

Коррекция не отменяет необходимость теста. Измененное значение сравнивают с исходным, а в интерфейсе различаются созданные и измененные сущности. На Evaluate & Test появляются показатели до и после коррекции. Если общая метрика выросла, но правило ошибочно меняет редкие допустимые значения, его нельзя выпускать. Для каждого правила собирают положительные и отрицательные примеры и фиксируют ожидаемое действие.

Конфигурацию правил можно копировать между версиями процессора, но после копирования проверяют совместимость схемы. Переименованное или отключенное поле делает выражение бессмысленным. В производственном журнале сохраняют версию процессора и версию набора правил, чтобы объяснить, почему один и тот же документ в разные даты получил разные значения.

IAM, сервисные аккаунты и защита данных

Доступ строится на IAM. Пользователь, который создает процессоры, и приложение, которое только вызывает обработку, не должны иметь одинаковый набор прав. Администратору нужен доступ к управлению ресурсами, оператору разметки — к dataset и интерфейсу, рабочему сервисному аккаунту — только к вызову процессора и нужным объектам Cloud Storage. Принцип минимальных привилегий уменьшает последствия ошибки ключа или учетной записи.

При кросс-проектном хранении сервисный агент проекта с процессором получает доступ к bucket другого проекта. Это отдельный principal вида Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в вашем браузере должен быть включен Javascript.. Частая ошибка — выдать роль обычному сервисному аккаунту приложения, но забыть P4SA, или наоборот. Диагностика начинается с точного текста ошибки, имени аккаунта и операции чтения или записи.

CMEK дает контроль над ключом, но добавляет операционные обязанности: доступ агента, согласование локаций, ротацию, мониторинг отключения и план восстановления. Удаление ключа необратимо блокирует данные, защищенные им. Перед включением CMEK команда должна определить владельца ключа, срок ожидания удаления, процедуру аварийного доступа и тест восстановления, а не ограничиваться выбором пункта в диалоге.

Документы часто содержат персональные и финансовые данные. В журнал не помещают исходный PDF, полный распознанный текст и учетные токены. Для отладки создают обезличенный контрольный набор, а доступ к рабочим объектам ограничивают по ролям и времени хранения. Результат Document также является чувствительным: структурированные реквизиты нередко проще использовать злоумышленнику, чем исходный скан.

Наблюдение, квоты и управление нагрузкой

Квоты применяются на уровне проекта и могут разделяться всеми приложениями и IP-адресами. Есть ограничения на число запросов, онлайн-обработку по типу процессора, страницы в минуту для генеративных моделей, параллельные batch operations и число развернутых версий. Перед запуском считают пиковый поток, а не среднее суточное число документов. Очередь с ограничением параллелизма защищает от лавины 429 и позволяет плавно повторять запросы.

Monitoring dashboard показывает метрики на уровне проекта и процессора, включая успешно обработанные страницы и задержку синхронной обработки с разрезами по location, processor type и processor ID. Для эксплуатации добавляют собственные показатели: долю ошибок по кодам, время ожидания batch, число документов на ручной проверке, средний confidence ключевых полей и стоимость на бизнес-операцию. Один график количества запросов не показывает ухудшение качества.

Повтор после 429 или временной 5xx выполняют с экспоненциальной задержкой и случайным разбросом. Ошибки 400, несовместимый MIME-тип, превышение страниц и отсутствие прав повторять без изменения запроса бессмысленно. Клиент классифицирует ошибки на постоянные и временные, ограничивает число попыток и отправляет проблемный документ в отдельную очередь с причиной.

Типовые ошибки и способы исправления

403: API отключен или нет разрешения

Сообщение о том, что Document AI API не использовался или отключен, устраняется включением API в правильном проекте и ожиданием распространения настройки. Если API включен, проверяют активный проект в gcloud, principal, роль и полное имя ресурса. Переменная GOOGLE_APPLICATION_CREDENTIALS должна указывать на существующий JSON-файл, когда используется ключ; в управляемой среде проверяют привязанный сервисный аккаунт.

Ресурс не найден

Причиной бывает неверный project ID, processor ID, location или endpoint. Процессор из US не находится через ресурс locations/eu. При вызове конкретной версии дополнительно проверяют processorVersion ID и состояние развертывания. Полезно сначала выполнить get processor теми же учетными данными, а затем отправлять документ.

Ошибка записи batch-результата

Если операция завершилась ошибкой записи в каталог Cloud Storage, проверяют существование bucket и точность префикса и право storage.objects.create у сервисного агента. Для входного bucket требуется чтение. Политика uniform bucket-level access, условные IAM-выражения и VPC Service Controls могут ограничивать доступ даже при наличии широкой роли в другом месте.

Invalid argument

Проверяют MIME-тип, сигнатуру файла, размер, число страниц, параметры ProcessOptions и совместимость версии. Поврежденный или зашифрованный PDF следует открыть валидатором до отправки. Если ошибка появилась после включения selection marks или math OCR, повторный тест без дополнительного флага помогает отделить проблему файла от несовместимой опции.

Низкая точность одного поля

Сначала изучают рамки и mentionText: модель выбрала неверную область или область верна, но нормализация ошиблась. Затем проверяют описание поля, кратность, качество разметки и представленность случая в training. Изменение делают одно за раз и измеряют на фиксированном test. Добавление десятков почти одинаковых примеров редко помогает так же, как несколько разнообразных документов с правильной разметкой.

Практические сценарии

Счета поставщиков

Конвейер принимает PDF из почты или портала, сохраняет исходник в Cloud Storage, запускает Invoice Parser или Custom Extractor, проверяет supplier, invoice_id, invoice_date, total_amount, currency и line items, а затем сопоставляет поставщика с мастер-данными. Документ с отсутствующим номером или расхождением суммы строк и итога уходит на проверку. В бухгалтерскую систему передаются нормализованные значения и ссылка на исходный файл, а не только распознанный текст.

Многостраничный входящий пакет

Один скан может содержать заявление, удостоверение, справку и приложение. Сначала Custom Splitter находит границы, Custom Classifier определяет тип каждой части, затем соответствующий экстрактор извлекает поля. Идентификатор исходного пакета и диапазоны страниц проходят через все этапы. Если классификация сомнительна, пакет не отправляют случайному парсеру: оператор подтверждает класс или правила маршрутизации выбирают безопасную ветку.

Архив и полнотекстовый поиск

Enterprise OCR превращает сканы в текст и координаты, Layout Parser выделяет структуру и chunks, после чего фрагменты индексируются вместе с метаданными документа. В поисковой выдаче пользователь получает не только ответ, но и страницу и область, на которой найден фрагмент. Для повторной индексации сохраняют версию процессора и хеш файла; неизмененный документ не обрабатывают заново без причины.

Договоры и акты

Custom Extractor выделяет стороны, даты, суммы, сроки, предмет и идентификаторы приложений. Вложенные сущности подходят для повторяющихся разделов или нескольких сторон. Правила валидации проверяют, что дата окончания не предшествует дате начала, а сумма содержит валюту. Юридически значимые выводы остаются на проверке специалиста: модель помогает собрать данные, но не определяет действительность договора.

Как повысить качество без хаотичного дообучения

1. Соберите контрольный набор из реальных вариантов, включая плохие сканы, редкие шаблоны и несколько языков.
2. Зафиксируйте точное определение каждого поля и единые границы разметки.
3. Измерьте базовую версию и сохраните ответы, метрики и ошибки по документам.
4. Разделите проблемы OCR, выбора сущности, нормализации и бизнес-валидации.
5. Меняйте один фактор: описание поля, набор примеров, модель или порог confidence.
6. Сравнивайте не только средний F1, но и критичные поля и долю ручной проверки.
7. Развертывайте новую версию с возможностью быстрого отката.

Такой цикл эффективнее добавления случайных документов. Если проблема вызвана обрезанным изображением, обучение не вернет отсутствующий текст. Если ошибка в схеме, дополнительные метки закрепят неправильное определение. Если нормализация не поддерживает нужный формат, это решается адаптером или правилом после извлечения. Причина должна быть установлена до выбора инструмента исправления.

Что сервис не делает

Google Cloud Document AI не предназначен для ручного редактирования страниц PDF. В нем нет привычных инструментов изменения текста, перестановки объектов, рисования, объединения файлов с визуальным контролем или подготовки документа к печати. Консоль показывает результат анализа и разметки, но не является полнофункциональным PDF-редактором. Для исправления самого файла используют отдельное приложение, а Document AI оставляют в роли распознавания и структурирования.

Сервис также не заменяет бизнес-систему. Он возвращает вероятностные сущности и структуру, но сопоставление контрагента, проверка дублей, расчет налогов, утверждение платежа, права оператора и срок хранения реализуются вокруг него. Надежный проект включает очередь, хранилище, адаптер ответа, правила валидации, ручную проверку и наблюдение. Один успешный экран теста подтверждает только возможность распознать конкретный файл.

Сравнение Google Cloud Document AI с аналогами

Программа	Лучше подходит для	Главное ограничение
Google Cloud Document AI	Конвейеры OCR, извлечения, классификации и собственные процессоры в Google Cloud	Нужны проект, IAM и облачная интеграция
Amazon Textract	Извлечение текста, форм, таблиц и документов в инфраструктуре AWS	Ориентирован на сервисы и права AWS
Azure AI Document Intelligence	Готовые и пользовательские модели в экосистеме Microsoft Azure	Требует ресурса Azure и настройки модели
ABBYY Vantage	Корпоративное извлечение с настраиваемыми навыками и проверкой	Внедрение и лицензирование сложнее для малого потока
PDF Commander	Ручное редактирование, объединение и OCR отдельных PDF	Не строит облачный API-конвейер извлечения

Google Cloud Document AI логичен, когда данные уже хранятся в Google Cloud, нужны Cloud Storage, IAM, API и собственные процессоры. Amazon Textract удобнее командам, чья очередь, хранилище и функции работают в AWS. Azure AI Document Intelligence выбирают для тесной интеграции с Azure и Microsoft-стеком. ABBYY Vantage подходит предприятиям, которым важны специализированные навыки, управляемая проверка и сложные процессы внедрения. PDF Commander полезнее сотруднику, которому нужно визуально исправить или собрать PDF, а не извлекать тысячи документов через API.

Дополнительные практики эксплуатации

Планирование схемы ответа

До написания кода полезно сохранить по одному полному JSON для каждого типа документа и составить карту: какое поле Document используется, может ли оно отсутствовать, бывает ли множественным и в каком виде приходит normalizedValue. Для таблиц отдельно описывают строки, заголовки и итоговые поля. Такой контракт предотвращает ситуацию, когда фронтенд ожидает одну строку, а новая версия возвращает массив вложенных properties.

Идемпотентность повторной обработки

Хеш исходного файла, processor version и набор параметров образуют ключ результата. Если они не изменились, повторный запрос обычно не нужен. При изменении модели создается новая ревизия результата, а старая сохраняется для сравнения. Это особенно важно для batch: потеря ответа клиента не означает, что операция не была запущена, поэтому сначала проверяют operation ID и выходной префикс, а не создают новую партию.

Ручная проверка

Экран оператора должен показывать изображение страницы, извлеченное значение, confidence, название поля и причину маршрутизации. Исправление записывается отдельно от исходного предсказания. Нельзя заменять mentionText без журнала: иначе невозможно оценить качество модели и понять, кто изменил данные. Исправленные документы могут пополнять набор обучения только после контроля и удаления дублей.

Контроль изменений схемы

Добавление необязательного поля обычно совместимо с клиентами, а переименование, изменение кратности или типа данных является изменением контракта. Перед публикацией новой схемы адаптер должен принимать оба варианта или выпускаться одновременно с процессором. Вложенные сущности требуют особенно аккуратной миграции, потому что плоский экспорт в таблицу может потерять связь между родителем и строками.

Тестирование производительности

Нагрузочный тест включает документы разных размеров и число одновременных запросов, близкое к пику. Измеряют не только среднюю задержку, но и 95-й и 99-й перцентили, число 429, размер ответа и время записи Cloud Storage. Для batch отдельно фиксируют время в очереди и завершение последнего файла. Результаты используются для настройки параллелизма и размера партии.

Удаление и сроки хранения

Удаление процессора, dataset, объектов Cloud Storage и журналов выполняется разными действиями. Политика должна перечислять каждый слой и срок. Если документы используются для обучения, удаление исходного файла из входной папки не обязательно удаляет его представление из dataset. Перед выполнением запроса субъекта данных организация проверяет все копии и экспортированные наборы.

Обработка многоязычных документов

Для одного пакета можно сначала определить язык по страницам, затем маршрутизировать документ в совместимый процессор или использовать общую модель. Поля с именами собственными и кодами не переводят перед извлечением. Если последующая система требует единый язык, перевод выполняют после сохранения исходного mentionText, чтобы не потерять аудируемое значение.

Таблицы и строки позиций

Строки таблицы проверяют как связанные группы, а не как независимые слова. Номер позиции, описание, количество, цена и сумма должны оставаться в одном родителе. При переносе страницы заголовок может повторяться, а строка — разрываться. Адаптер объединяет части по геометрии и структуре, но не должен автоматически складывать значения, если confidence или соответствие колонок сомнительны.

Пороговые правила

Один глобальный confidence threshold удобен для демонстрации, но редко оптимален. Для номера документа можно требовать высокий порог и регулярный формат, для длинного описания — принимать более низкий confidence, если текст используется только для поиска. Порог пересматривают после смены модели, потому что шкала уверенности между версиями не обязана быть калибрована одинаково.

Разделение ответственности

Команда данных отвечает за набор, схему и метрики, команда платформы — за IAM, ключи, квоты и наблюдение, прикладная команда — за бизнес-валидацию и интерфейс проверки. Без явного владельца ошибки переходят между группами: низкое качество считают проблемой сети, а отсутствие доступа — проблемой модели. Карта ответственности ускоряет инциденты и выпуск новых версий.

Технические детали интеграции

Проверка координат

BoundingPoly может быть задан нормализованными или абсолютными вершинами. При отображении рамок клиент учитывает размер страницы и поворот, иначе подсветка смещается. Для PDF с разным размером листов коэффициент рассчитывается отдельно для каждой страницы. Тесты должны включать портретные и альбомные страницы.

Нормализация чисел

mentionText сохраняет разделители так, как они напечатаны, а normalizedValue может представить число в машиночитаемом виде. Перед записью в финансовую систему проверяют валюту, знак, локальный десятичный разделитель и скобки для отрицательных значений. Отсутствие нормализованного значения не должно превращаться в ноль.

Многоступенчатые процессоры

Классификатор и экстрактор вызываются последовательно через inlineDocument или сохраненный промежуточный результат. При этом важно не потерять исходные страницы и textAnchor. Каждый этап записывает собственную версию и статус, а итоговая ошибка указывает, на каком процессоре остановился документ.

Экспорт набора

Экспорт dataset создает разделы Train, Test и Unassigned с объектами Document JSON. Статус auto-labeled не переносится как полноценная ручная проверка. Экспорт используют для резервирования и миграции, но перед импортом в другой проект сверяют схему, регион, права сервисных агентов и совместимость базовой версии.

Расширенная настройка и надежность

Как выбирать процессор в галерее

Выбор начинают с контрольного документа и списка обязательных полей. Enterprise Document OCR подходит, когда конечная система сама интерпретирует текст и координаты. Form Parser разумен для разнообразных форм без собственной схемы, если достаточно общих пар ключ — значение и таблиц. Специализированный парсер выбирают для устойчивого набора сущностей конкретного класса документов. Custom Extractor нужен, когда названия, вложенность и кратность полей определяет организация. Перед закреплением решения один и тот же набор прогоняют через два наиболее близких варианта и сравнивают не визуальное впечатление, а полноту обязательных значений и число ручных исправлений.

Версия процессора и назначение по умолчанию

У процессора может быть несколько версий, но вызов без явного номера использует назначенную по умолчанию. Для эксперимента это удобно, а для воспроизводимого рабочего потока опасно: переключение default способно изменить извлечение без изменения кода клиента. Надежная интеграция хранит полный ресурс processorVersion в конфигурации, а смену выполняет как управляемый релиз. Сначала новая версия обрабатывает фиксированный тестовый набор, затем небольшой процент реального потока, и только после сравнения полей, задержки и ошибок становится основной. Возможность отката проверяют до переключения, а не после инцидента.

Синхронный запрос и пакетная операция

Синхронный метод process удобен для одного небольшого документа, когда ответ нужен в рамках пользовательской операции. Файл передают как байты или ссылку на объект, а ответ Document приходит в том же вызове. BatchProcess предназначен для больших очередей: вход задается списком либо префиксом Cloud Storage, сервис возвращает long-running operation, а результаты появляются в выходном каталоге. Клиент должен опрашивать состояние с увеличивающимся интервалом, учитывать частично успешную партию и сопоставлять каждый выходной JSON с исходным объектом. Размер партии выбирают так, чтобы повторный запуск после сбоя не создавал чрезмерную нагрузку.

Структура объекта Document

Поле text содержит объединенный текст документа, а элементы страниц и сущностей ссылаются на него через textAnchor. Индексы textSegments относятся к позициям в общей строке, поэтому нельзя бездумно обрезать или нормализовать текст до разрешения ссылок. Page хранит размеры, блоки, абзацы, строки, токены и визуальные области; Entity добавляет type, mentionText, confidence, normalizedValue и вложенные properties. Парсер приложения должен терпимо относиться к отсутствующим необязательным полям, пустым массивам и новым полям ответа. Полный исходный JSON полезно сохранять отдельно от упрощенной бизнес-модели.

Координаты и поворот страницы

Рамки могут приходить как vertices в пикселях либо normalizedVertices в долях ширины и высоты. Интерфейс проверки пересчитывает их для конкретной страницы и применяет detectedLanguages, orientation или обнаруженный поворот до рисования. Одна формула на весь PDF неверна, если листы различаются по размеру. Для отладки сохраняют номер страницы, исходные координаты и итоговый прямоугольник на экране. Контрольный набор должен содержать альбомные листы, страницы с поворотом на 90 и 180 градусов, фотографии под углом и документы с полями у самого края.

Нативный текст PDF и OCR

В цифровом PDF уже может быть текстовый слой. OCR-процессор способен использовать его вместе с визуальным анализом, что обычно сохраняет символы лучше, чем повторное распознавание отрисованной страницы. Однако поврежденный, скрытый или неверно закодированный слой может ухудшить результат. При подозрении сравнивают ответ на исходный PDF и на его качественный рендер. Выбор фиксируют для конкретного источника документов, а не меняют случайно от файла к файлу. Для архивных сканов особенно важны deskew, rotation correction и оценка качества изображения, поскольку нативного слоя там нет.

Таблицы без потери связи строк

Form Parser и специализированные процессоры могут возвращать таблицы, но бизнес-адаптер должен сохранить структуру заголовков, строк и ячеек. Простое объединение всех значений по колонкам разрушает связь между количеством, ценой и описанием позиции. На многостраничных счетах заголовок таблицы может повторяться, а строка — продолжаться на следующей странице. Правило объединения учитывает геометрию, порядок чтения и наличие родительской сущности. Если сумма строки не согласуется с количеством и ценой, документ отправляют на проверку, но исходное распознанное значение не заменяют автоматически вычисленным.

Пары ключ — значение в формах

Ключ и значение могут находиться далеко друг от друга, быть разделены линией, иметь несколько строк или повторяться в секциях. Form Parser возвращает найденные связи, но название поля остается таким, как напечатано. Для единой бизнес-схемы прикладной слой сопоставляет варианты вроде Invoice No., Invoice # и локализованных подписей с одним внутренним атрибутом. Это сопоставление версионируют отдельно от модели. Если один ключ встречается несколько раз, используют секцию, страницу и соседние заголовки, а не выбирают первое значение без проверки.

Типы и нормализованные значения

Схема Custom Extractor позволяет задавать смысл поля и его кратность, а ответ может содержать normalizedValue для дат, чисел, денег и адресов. Нормализация не отменяет mentionText: первое значение удобно для вычислений, второе необходимо для аудита. Дата без года, неоднозначный формат 03/04/2026 или сумма без валюты требуют дополнительного правила. При записи в базу нельзя превращать отсутствие normalised value в ноль или пустую дату. Ошибка преобразования должна сохранять исходный фрагмент и причину, чтобы оператор видел, что именно напечатано в документе.

Вложенные сущности и повторяющиеся группы

Для строк товаров, участников договора или нескольких адресов применяют повторяющуюся родительскую сущность с дочерними полями. Такая схема сохраняет принадлежность значений одной группе. Плоский набор labels создает неоднозначность: три количества и три цены невозможно надежно сопоставить после извлечения. В интерфейсе разметки сначала выделяют родителя, затем его свойства. В интеграции properties обходят рекурсивно и сохраняют индекс группы. Изменение вложенности считается изменением контракта и требует миграции экспорта, отчетов и интерфейса ручной проверки.

Описания полей и документная подсказка

Короткое имя сущности должно быть стабильным и машинно читаемым, а описание объясняет модели смысл и границы значения. В нем указывают, включать ли префикс, валютный знак, единицу измерения, подпись или только содержимое. Document-level prompt задает общие правила для всего документа: например, различие между адресом продавца и покупателя. Подсказка не заменяет качественную схему и примеры. После каждого изменения проверяют прежний тестовый набор, потому что более подробное правило способно улучшить один шаблон и ухудшить другой. Не следует помещать в prompt секреты или данные конкретного клиента.

Автоматическая разметка и ее проверка

Auto-labeling ускоряет подготовку набора, используя существующую версию процессора для предварительных меток. После импорта документы получают предсказания, но не становятся достоверной разметкой автоматически. Рецензент открывает каждый выбранный пример, исправляет границы и значения, удаляет ложные сущности и добавляет пропуски. Для контроля полезно измерять долю исправленных полей по типам: если конкретный label почти всегда меняют, его описание или схема требуют пересмотра. Документы, прошедшие только автоматическую разметку, не смешивают с вручную подтвержденным эталоном при оценке.

Train, Test и Unassigned

Dataset делит документы на обучающие, тестовые и не назначенные. Test должен оставаться независимым: в него не помещают копии файлов из Train, страницы одного пакета и почти одинаковые шаблоны с замененными реквизитами, если цель — проверить обобщение. Unassigned удобен как входная зона для новых примеров, которые еще не прошли проверку. После исправления документ переводят осознанно. Изменение состава Test фиксируют, иначе F1 между экспериментами нельзя сравнивать. Для редких классов сохраняют достаточное число примеров каждого важного варианта макета.

Как читать precision, recall и F1

Precision отвечает на вопрос, какая доля найденных сущностей оказалась правильной; recall — какая доля эталонных сущностей была найдена. F1 объединяет обе характеристики, но скрывает направление ошибки. Для поля, которое запускает платеж, ложное значение может быть опаснее пропуска, поэтому нужен высокий precision и ручная проверка сомнительных случаев. Для полнотекстового поиска важнее recall. Метрики смотрят по каждому label и на уровне документа, а не только общей строкой. Confidence threshold сдвигает баланс, поэтому его выбирают по стоимости ошибок и проверяют на неизменном тестовом наборе.

Утечки и дубликаты в тестовом наборе

Случайное разделение страниц может отправить соседние листы одного документа в Train и Test, а шаблонные формы с одинаковым фоном создают завышенную оценку. Перед обучением документы группируют по исходному пакету, поставщику, шаблону или периоду и делят целыми группами. Перцептивный хеш помогает найти визуальные копии, но не заменяет проверку метаданных. Если модель будет работать на новых поставщиках, часть поставщиков полностью оставляют для теста. Тогда метрика лучше показывает поведение на действительно незнакомом макете.

Классификация и разделение пакетов

Custom Classifier определяет тип документа, а Custom Splitter находит границы внутри многостраничного файла. В потоке входящий пакет сначала проходит разделение, затем каждый фрагмент направляется в экстрактор нужного типа. Ошибка на первом этапе влияет на все последующие, поэтому сохраняют predicted class, confidence, диапазон страниц и исходный пакет. При низкой уверенности фрагмент не отправляют вслепую в случайный парсер, а помещают в очередь проверки. После ручного исправления границ повторно запускают только затронутые части, сохраняя связь с первоначальным файлом.

Layout Parser и подготовка фрагментов

Layout Parser выделяет заголовки, абзацы, таблицы, списки и формирует логические chunks для поиска и генеративных сценариев. Размер фрагмента выбирают по задаче: слишком маленький теряет контекст, слишком большой ухудшает точность поиска и увеличивает стоимость последующей модели. Включение ancestor headings помогает сохранить название раздела у вложенного абзаца. Таблицы лучше хранить вместе с заголовками колонок. Перед индексацией удаляют служебные колонтитулы и дубли, но оставляют номера страниц и идентификаторы источника для последующего открытия оригинала.

Качество изображения как отдельный сигнал

Enterprise OCR может возвращать оценку качества и обнаруженные дефекты страницы. Эти сведения полезны не только для диагностики: правило маршрутизации может запросить повторное сканирование, когда текст размыт, затемнен или сильно обрезан. Порог проверяют на собственных устройствах, потому что телефонная фотография и поток офисного сканера дают разные распределения. Оператору показывают конкретную страницу и тип дефекта. Автоматическое повышение контраста применяют осторожно и сравнивают с оригиналом, чтобы не удалить тонкие линии таблиц и знаки препинания.

Региональные конечные точки

Локация процессора является частью имени ресурса и адреса сервиса. Запрос к глобальной или американской конечной точке с европейским processor ID приводит к ошибке, даже если проект и роли правильные. Клиент формирует endpoint из конфигурации региона, а не из догадки. Cloud Storage для входа и выхода выбирают с учетом требований к резидентности и задержки. При копировании решения между проектами проверяют доступность типа процессора в целевой локации, создают новый ресурс и обновляют полный идентификатор во всех заданиях и секретах развертывания.

IAM для пользователей и сервисных аккаунтов

Человеку, который создает и тестирует процессоры, и сервисному аккаунту приложения обычно нужны разные права. Принцип наименьших привилегий означает, что рабочий аккаунт получает вызов конкретных процессоров и доступ только к нужным каталогам Cloud Storage, но не право менять схему или удалять ресурсы. Роли назначают на минимально возможном уровне и проверяют через IAM Policy Troubleshooter. Передача ключевого JSON-файла между разработчиками хуже федерации рабочих нагрузок или управляемого аккаунта. Отозванное право должно проверяться тестом, а не предполагаться по интерфейсу.

Сервисный агент и доступ к Cloud Storage

Для некоторых операций Document AI использует управляемого сервисного агента проекта. Если входной или выходной bucket находится в другом проекте, одного доступа вызывающего пользователя недостаточно: права на объекты нужны также соответствующей служебной учетной записи. Ошибка часто выглядит как отказ записи после успешного запуска процессора. Диагностика начинается с журналов и точного principal, а не с выдачи роли Owner всему проекту. Отдельно проверяют ограничения организации, VPC Service Controls, условные роли и ключ шифрования, поскольку каждый слой может блокировать действие.

CMEK и жизненный цикл ключа

Customer-managed encryption key применяют, когда политика требует собственного контроля шифрования. Ключ должен находиться в совместимой локации, а сервисный агент получает разрешение на его использование. Отключение, удаление версии ключа или снятие роли делает связанные данные недоступными и может остановить обработку. Поэтому ротацию сначала проверяют на тестовом ресурсе, а удаление планируют с учетом срока хранения документов и моделей. В журнале изменений фиксируют имя ключа и дату переключения. CMEK не заменяет IAM и не скрывает данные от пользователей, у которых уже есть разрешение читать результат.

Чек-лист перед рабочим запуском

• Определен тип процессора и проверен список реально требуемых полей.
• Выбрана локация, соответствующая требованиям хранения и доступности модели.
• Синхронный и пакетный режимы используются для подходящих сценариев задержки.
• Входные файлы проверяются по сигнатуре, размеру, числу страниц и качеству.
• У приложения и сервисного агента выданы минимальные права на нужные buckets.
• Тестовый набор отделен от обучения и содержит редкие производственные случаи.
• Для критичных полей установлены пороги и маршрут ручной проверки.
• Версия процессора вызывается явно или переключается по контролируемому alias.
• Ошибки разделены на постоянные и временные, повторы имеют задержку и лимит.
• Логи не содержат документы, полный текст и секреты, а метрики показывают качество и нагрузку.
• Есть план отката версии и повторной обработки только затронутых документов.

После выполнения этих пунктов обработка становится воспроизводимой: любой результат можно связать с исходным файлом, регионом, версией процессора, параметрами и набором правил. Пользователь консоли видит понятную проверку на документе, разработчик получает стабильный объект Document, а оператор знает, какие случаи требуют вмешательства. Именно такая связка интерфейса, API, данных и контроля превращает распознавание из демонстрации в рабочий документный процесс.