Создание структурированного JSON из архитектурных текстов с Gemini API

Что вы узнаете из этого руководства?

Бриф проекта, заметки о материалах или описание помещения часто приходят в виде произвольного текста. Если из них нужно регулярно извлекать такие данные, как название комнаты, материал и назначение, ответы только на естественном языке могут усложнить дальнейшую обработку. Функция структурированного вывода Gemini API позволяет запросить ответ модели в соответствии с заранее заданной JSON Schema.

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

Требования и область применения

В документации Google говорится о поддержке JSON Schema в REST API для структурированного вывода. В Google GenAI SDK в качестве способов определения схемы указаны Pydantic для Python и Zod для JavaScript. В источнике также есть примеры для Java, Go и других языков; в этом руководстве вместо кода мы используем переносимый черновик JSON Schema.

В документации отмечено, что для JavaScript необходимо установить Zod, однако сведения о версии SDK, требованиях к аккаунту или стоимости в этих источниках не приведены. Поэтому перед началом проекта проверьте актуальные требования к выбранным SDK и модели в документации Gemini API. В верхней части документации указано, что доступна Gemini 4 Argon, тогда как в примере кода фигурирует название модели gemini-3.8-flash. Не считайте название модели в примере автоматически актуальным или подходящим для любого сценария использования.

1. Определите извлекаемые поля

Прежде чем создавать схему, решите, какие данные нужно извлечь из текста и к какому типу относится каждое поле. Например, приведённый ниже черновик предназначен для извлечения из брифа интерьера названия помещения, указанного материала и описания назначения. Базовые конструкции JSON Schema, такие как object, properties, string и required, соответствуют примерам из источника.

{
  "type": "object",
  "properties": {
    "mekan_adi": { "type": "string" },
    "malzeme": { "type": "string" },
    "islev": { "type": "string" }
  },
  "required": ["mekan_adi", "malzeme", "islev"]
}

Здесь все три поля обязательны. Если в исходном тексте какое-то поле не указано, отдельно объясните в запросе, что делать в таком случае; например, попросите оставить поле пустым или написать «не указано». Выбор зависит от того, как будут обрабатываться данные проекта; если принять это решение заранее при создании схемы, команде будет проще получать последовательные результаты.

2. Чётко опишите задачу и входные данные

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

Aşağıdaki iç mekân proje brief’inden mekân adını, açıkça belirtilen malzemeyi ve mekânın işlevini çıkar. Yalnızca verilen metindeki bilgilere dayan. Bir bilgi metinde yoksa bunu “belirtilmemiş” olarak yaz. Yanıtı, sağlanan JSON şemasındaki alanlarla uyumlu bir JSON nesnesi olarak üret.

Brief: Zemin katta yer alan okuma alanında meşe kaplama yüzeyler ve ortak çalışma masaları bulunuyor.

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

3. Уточните ограничения с учётом задачи проекта

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

Bu mahal açıklamasında adı geçen kaplama ve yüzey malzemelerini çıkar. Yeni malzeme önerme, eş anlamlı veya marka tahmini ekleme. Sonucu yalnızca malzeme adlarından oluşan bir liste olarak ver.

Açıklama: Giriş holünde terrazzo döşeme ve boyalı alçı duvar yüzeyi kullanılacaktır.

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

4. Покажите формат на примере ответа

Если запрашиваемую классификацию или шаблон формулировки можно истолковать по-разному, краткие примеры помогут точнее задать формат. В руководстве Google говорится, что при использовании few-shot-подхода модели можно показать пример входных данных и ожидаемый формат ответа; примеры полезно делать наглядными и разнообразными.

Aşağıdaki örnekteki alanları kullanarak yeni mahal notunu sınıflandır.

Örnek not: “Mutfak tezgâhı kuvars kompozit, dolap kapakları mat lake.”
Örnek çıktı: {"mekan": "Mutfak", "malzemeler": ["kuvars kompozit", "mat lake"]}

Yeni not: “Çalışma odasında ahşap parke ve sıva üzeri boya bulunuyor.”
Yalnızca aynı alan düzeninde yanıt ver.

Этот пример показывает структуру ответа, однако схему, которая будет использоваться в реальном API-запросе, необходимо определить отдельно. В руководстве источника указано, что можно начать с небольшого количества примеров и при необходимости подобрать их число с учётом конкретного сценария. Также отмечается, что избыток примеров может привести к переобучению модели.

Распространённые ошибки

Одна из самых частых проблем — описать требования только в запросе, но не указать схему на стороне API. Google отмечает, что простой формат JSON можно запросить на естественном языке, а для более сложных требований к JSON Schema рекомендует использовать функцию структурированного вывода. Вторая проблема — когда схема и запрос требуют разных полей или форматов ответа. Сначала определите поля и типы данных, а затем составьте запрос в соответствии с этой структурой.

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

Применение в архитектурных рабочих процессах и визуализации

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

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

Следующие шаги

Для начала выберите одну задачу — например, извлечение материалов из заметки о помещении. Определите поля и создайте схему, затем проверьте результат с помощью запроса с ясными инструкциями. Сверьте ответы с исходным текстом, отметьте повторяющиеся ошибки и добавляйте примеры в запрос только при реальной необходимости. Если вы работаете с Python, рассмотрите вариант определения схемы с помощью Pydantic, а для JavaScript — с помощью Zod. Использование REST API также поддерживается согласно документации.

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

Источники и лицензия

Это руководство адаптировано на турецкий язык по материалам Google «Structured outputs» и «Prompt design strategies». Оба источника распространяются по лицензии CC BY 4.0.