Gemini API function calling: вызов инструментов в архитектурных сценариях

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

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

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

Требования

Для начала понадобятся API-ключ Gemini и среда, из которой можно отправлять API-запросы. В официальном руководстве для начинающих рассматриваются Python SDK, JavaScript SDK и REST; также приведены примеры для Java и Go. В этом руководстве используется Python.

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

При переходе на платный тариф для аккаунта открываются более высокие лимиты запросов; для этого необходимо настроить Cloud Billing. В руководстве Google указано, что для платных кредитов требуется предварительно внести не менее 5 долларов США или эквивалент в другой валюте. Это не оценка стоимости использования, а условие предоплаты, указанное в источнике. Перед переходом на платный тариф проверьте настройки аккаунта и платёжные данные.

Команда для установки Python SDK из официального руководства:

pip install -U google-genai

Пошаговое создание вызова функции

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

2. Определите, какие данные нужно запросить у модели. Например, запрос пользователя может выглядеть так:

Найди в каталоге материалов напольные покрытия светлых оттенков с фактурой камня для моего проекта.

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

1. Подготовьте схему функции. В примерах Google по вызову функций задаются её название, описание и схема параметров. Для параметров указывается тип, а обязательные поля добавляются в список required. search_materials и поле query в этом примере адаптированы для архитектурного каталога.

from google import genai

search_materials_function = {
    "type": "function",
    "name": "search_materials",
    "description": "Searches a project material catalog using a text query.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The material search query."
            }
        },
        "required": ["query"]
    }
}

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

1. Отправьте запрос в Gemini API и проверьте шаг вызова. В примерах руководства для начинающих используются клиент genai.Client(), запрос interactions.create и такие поля результата, как interaction.output_text. В документации по function calling показано, как проверить наличие шага типа function_call среди ответов и прочитать название функции и аргументы.

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Найди светлые напольные покрытия с фактурой камня для моего проекта.",
    tools=[search_materials_function],
)

for step in interaction.steps:
    if step.type == "function_call":
        print("Функция:", step.name)
        print("Аргументы:", step.arguments)

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

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

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

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

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

• Путаница между вызовом модели и выполнением операции: function calling формирует вызов и аргументы для взаимодействия с внешней системой. Выполнение функции в реальной системе зависит от подключённого приложения.

• Небрежное обращение с API-ключом: ключ связывает API-запросы с аккаунтом и помогает отслеживать использование. В руководстве для начинающих предлагается хранить его в переменной среды.

• Игнорирование стоимости и лимитов использования: при переходе на платный тариф меняются лимиты запросов и настройки биллинга. Перед началом работы проверьте сведения об использовании и оплате в AI Studio.

Влияние на архитектурные процессы и визуализацию

Этот подход может быть полезен командам, которые хотят направлять запросы на естественном языке к инструментам, определённым в приложении. Например, в проекте интерьера можно настроить преобразование запроса на поиск материала в структурированный запрос к каталогу. К числу описанных в источнике сценариев также относится получение данных из внешнего API или базы данных. Это не означает наличия готового подключения к Revit, 3ds Max или другой программе для проектирования: интеграцию необходимо настроить отдельно.

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

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

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

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

Руководство адаптировано на основе документации Google по Gemini API function calling и руководства для начинающих. Оба источника распространяются по лицензии CC BY 4.0. Материал переведён на русский язык и адаптирован для сценария с архитектурным каталогом материалов.