Руководство: преобразование архитектурных изображений в JSON через Gemini API

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

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

В документации Google Gemini API понимание изображений описывается на примерах таких задач, как создание описаний, классификация и ответы на вопросы по изображению. Изображение можно передать по URL, как встроенные данные или через Files API. В примере используется название модели gemini-3.8-flash, встречающееся в примерах документации.

Что потребуется

• Клиент или REST-запрос для работы с Gemini API. В документации есть примеры для Python и JavaScript, а также для Java и Go.

• Способ передать изображение в API: встроенные данные в формате base64 для небольших изображений, Files API — для крупных файлов или изображений, которые будут использоваться повторно.

• Если нужен JSON-ответ — JSON Schema, описывающая его поля. В Google GenAI SDK схему можно задать с помощью Pydantic для Python и Zod для JavaScript.

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

Предположим, что мы хотим получить структурированный список видимых объектов и описаний их расположения на изображении интерьера. Ниже приведён пример простой схемы для этой задачи. Поля можно менять в соответствии с реальным рабочим процессом; важно, чтобы ожидаемый результат, описанный в запросе, соответствовал полям схемы.

{
  "type": "object",
  "properties": {
    "gozlemler": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "unsur": { "type": "string" },
          "konum": { "type": "string" },
          "gorunur_ozellik": { "type": "string" }
        },
        "required": ["unsur", "konum", "gorunur_ozellik"]
      }
    }
  },
  "required": ["gozlemler"]
}

Шаги настройки

1. Определите изображение и цель

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

2. Составьте чёткий запрос с ясными ограничениями

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

Görseli bir iç mekân sunum paftasını inceler gibi değerlendir. Yalnızca görüntüde açıkça seçilebilen unsurları listele. Her unsur için kısa bir konum tarifi ve görülebilir özelliğini yaz. Ölçü, marka veya malzeme türünü görüntüden kesin biçimde belirleyemiyorsan tahmin etme; bunu belirt. Yanıtı, tanımladığım JSON şemasındaki alanlara uygun biçimde ver.

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

3. Добавьте изображение в API-запрос

Небольшое изображение можно закодировать в base64 и отправить в поле data. В документации для этого способа используются данные изображения и MIME-тип вместе с текстовым запросом. Общий размер встроенных данных изображения, текста запроса и системных инструкций ограничен 20 МБ. Если этот предел может быть превышен, загрузите файл через Files API и добавьте в запрос полученный URI.

В документации Files API рекомендуется для крупных файлов и случаев, когда одно и то же изображение используется в нескольких запросах. Передавайте текст и изображение вместе, указав корректный MIME-тип изображения. Один из типов изображений, приведённых в документации в качестве примера, — image/jpeg.

4. Настройте формат JSON-ответа

При использовании функции Structured outputs задайте формат ответа JSON и добавьте схему в запрос. В REST-примере из документации для этого параметру mime_type присваивается значение application/json, а схема передаётся в поле schema. В примере для Python JSON Schema создаётся на основе модели Pydantic, а ответ проверяется с её помощью; в примере для JavaScript используется схема Zod.

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

5. Проверьте ответ перед использованием

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

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

Частые ошибки

• Запрашивать точные сведения, которых не видно на изображении: перспектива, разрешение или кадрирование могут скрывать некоторые детали. Попросите модель обозначать неопределённость, а не делать предположения.

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

• Передавать крупный файл как встроенные данные: для общего размера запроса со встроенным изображением действует ограничение в 20 МБ. Для крупных файлов используйте Files API.

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

• Считать первый вариант запроса окончательным: даже если задача и ограничения изложены чётко, запрос нужно улучшать, проверяя результат на реальных примерах.

Влияние на рабочие процессы в архитектуре и archviz

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

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

Что делать дальше

Сначала проверьте небольшую схему на нескольких репрезентативных изображениях. Определите, какие поля часто повторяются и действительно нужны в рабочем процессе, а неопределённые наблюдения отмечайте отдельно. Затем пересмотрите запрос, схему и способ передачи изображений. Если нужны более сложные структуры JSON, изучите примеры SDK в документации Gemini API по structured outputs, а для работы с изображениями — руководство Image understanding.

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

Материал адаптирован на турецкий язык на основе руководств Google AI for Developers «Structured outputs», «Image understanding» и «Prompt design strategies». Все три источника распространяются по лицензии CC BY 4.0.