Как анализировать PDF в Gemini API: таблицы, диаграммы и структурированный ответ

Gemini обрабатывает PDF с помощью native vision, включая текст, изображения, диаграммы и таблицы. Inline-вход использует type document, Base64 data и mime_type application/pdf. Для больших или повторно используемых документов документация рекомендует Files API. Указан предел до 1000 страниц, который всё равно следует перепроверять перед запуском.

Документация подтверждает механизм, но не создаёт архитектуру безопасности. Авторизацию, allowlist, хранение секретов, приёмочные критерии и откат реализует приложение. Текстовый запрет в промпте полезен как контракт, однако критичное ограничение проверяется обычным кодом непосредственно перед действием.

Что подготовить

Создайте отдельный тестовый проект и ключ с минимальными правами. Секрет держите только в переменной окружения или менеджере секретов. Не помещайте его в браузерный bundle, промпт, Git, URL, скриншот и диагностический вывод.

До вызова заведите таблицу: case_id, input, expected_action, expected_output, actual_action, actual_output, source, status, error_type. Ожидаемый результат записывается заранее. Возьмите минимум десять обезличенных примеров: обычный, пустой, неполный, противоречивый, вредоносный, тайм-аут и повтор.

Для чисел храните единицы, исходное значение и правило округления. Для файлов — имя, MIME, размер, хеш и число страниц или кадров. Для внешнего действия — идентификатор, состояние до и после. Это конкретные единицы контроля, по которым можно доказать результат.

Пошаговая настройка

1. Проверьте, что файл действительно PDF, не зашифрован и открывается локальным валидатором. Сохраните число страниц и хеш.
2. Для короткого одноразового документа передайте Base64 inline как document; для большого или многошагового используйте Files API и его URI.
3. Попросите JSON с fact, value, unit, page и evidence. Запрещайте объединять строки разных таблиц без явной связи.
4. Сверьте все страницы, числа и единицы в исходнике. Формулы пересчитайте обычным кодом, особенно проценты и итоги.
5. Добавьте PDF с пустой таблицей, повернутой страницей и конфликтом текста с графиком. Конфликт должен получить needs_review.

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

Копируемый шаблон

Извлеки из PDF показатели выручки и операционных расходов по кварталам. Верни JSON {rows:[{period,revenue,opex,currency,page,evidence}],conflicts:[]}. Не вычисляй отсутствующие значения и не смешивай разные валюты.

Общие правила:
1. Используй только переданные источники и разрешённые инструменты.
2. Не угадывай отсутствующие значения.
3. Перед действием проверь путь, тип, идентификатор и права.
4. При конфликте верни status=needs_review и перечисли конфликтующие данные.
5. Не отправляй, не удаляй, не оплачивай и не раскрывай секрет без отдельного подтверждения.
6. Свяжи каждый изменяемый факт с источником, страницей, сегментом или tool result.

Шаблон следует дополнить схемой именно вашего объекта. Фразы «будь внимателен» недостаточно. Код должен отклонять неизвестные поля, запрещённые пути, недопустимые домены, неправильные координаты и действие без права.

Реалистичный пример входа и результата

На странице 4 таблица содержит Q1: revenue 12,4 млн ₽ и opex 8,1 млн ₽. На странице 6 график округляет выручку до 12 млн. Ожидается точное значение из таблицы и запись конфликта округления.

Это заранее определённый expected, а не выдуманная статистика. Реальный output сохраните рядом и отметьте расхождения. Если финальный текст правильный, но агент выполнил лишний вызов, открыл чужой домен или изменил файл, тест провален.

Проверка по уровням

Первый уровень — транспорт: ответ получен, идентификатор сохранён, payload читается. HTTP 200 не доказывает смысл. Тайм-аут не равен гарантированному отказу: перед повтором проверьте состояние операции.

Второй — структура: обязательные поля есть, типы совпадают, JSON разбирается, Base64 декодируется, файл открывается, координаты находятся внутри изображения. Неизвестное поле либо отклоняется, либо сохраняется отдельно.

Третий — смысл: каждый факт подтверждается входом, страницей, временным сегментом или tool result. Числа пересчитываются кодом, идентификаторы сравниваются посимвольно. Отсутствующее значение остаётся null, а не превращается в правдоподобную догадку.

Четвёртый — действие: проверьте внешний журнал, файловый diff, вкладки браузера или созданные записи. Для read-only сценария любое изменение означает провал независимо от красивого объяснения.