Вызов функций и структурированный вывод в Gemini API: руководство для архитекторов

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

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

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

Требования

В документации Google по Gemini API приведены примеры для SDK Python и JavaScript, а также для Java, Go и REST. В примере Python используется клиент genai из пакета google, а в примере JavaScript — пакет @google/genai. В примере REST API-ключ передаётся через переменную GEMINI_API_KEY. Поскольку в исходных материалах не описаны шаги установки, стоимость и условия использования аккаунта, не следует делать предположений по этим вопросам; перед внедрением отдельно проверьте актуальные сведения о доступе к API и тарифах.

В примерах используется модель gemini-3.8-flash. Выбирайте модель с учётом требований приложения; здесь сохранено название модели из исходной документации. Командам, которые будут работать с кодом, понадобятся соответствующий SDK для выбранного языка и доступ к Gemini API. Для этого руководства не требуется конкретная IDE или плагин для архитектурного ПО.

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

Пошагово: вызов функций

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

from google import genai

get_room_data_function = {
    "type": "function",
    "name": "get_room_data",
    "description": "Returns room data for a project.",
    "parameters": {
        "type": "object",
        "properties": {
            "project_id": {"type": "string"}
        },
        "required": ["project_id"]
    }
}

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Mimari projedeki mekân verilerini getir.",
    tools=[{"type": "function", **get_room_data_function}]
)

for step in interaction.steps:
    if step.type == "function_call":
        print(step.name)
        print(step.arguments)

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

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

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

Пошагово: структурированный вывод

1. Определите необходимые поля данных. Например, для извлечения из проектной заметки названия помещения, площади и списка требований можно задать схему с объектом, массивом, текстом и целым числом. Выбирайте типы полей с учётом того, как приложение будет использовать эти данные. В исходной документации наряду с JSON Schema также описаны варианты задания схем с помощью Pydantic для Python и Zod для JavaScript.

2. Добавьте схему к запросу. В примере Python ниже показано, как запросить ответ в формате JSON и получить его из поля output_text. Названия полей приведены для учебного примера по архитектуре; какие сведения извлекать из проектных документов, следует определять исходя из требований задачи.

from google import genai

client = genai.Client()
room_schema = {
    "type": "object",
    "properties": {
        "rooms": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "room_name": {"type": "string"},
                    "area_m2": {"type": "integer"},
                    "requirements": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["room_name", "area_m2", "requirements"]
            }
        }
    },
    "required": ["rooms"]
}

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Proje notundaki mekânları çıkar: giriş holü 12 m²; doğal ışık gereksinimi var.",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": room_schema
    }
)

print(interaction.output_text)

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

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

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

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

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

Следующие шаги для архитектуры и archviz

Бюро могут рассмотреть эти подходы для процессов, в которых нужно распределять проектные заметки по заданным полям или получать данные из внутренних инструментов. Студентам они также помогают освоить извлечение структурированных данных из текста и базовые принципы интеграции с API. Однако в исходных материалах эти возможности не представлены как плагин, напрямую связывающий Gemini API с конкретным BIM-, CAD- или визуализационным ПО: такую интеграцию приложение должно настраивать отдельно.

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

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

Это руководство адаптировано на турецкий язык по материалам Google “Function calling with the Gemini API” и “Structured outputs”, посвящённым Gemini API. Оба источника опубликованы по лицензии CC BY 4.0. Примеры, ориентированные на архитектурные задачи, подготовлены специально для этого руководства.