Учебное пособие по вызову функций

Python Node.js Go Dart (Flutter) Android Swift Web REST

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

Вы можете предоставить модели Gemini описания функций. Это функции, которые вы пишете на языке вашего приложения (то есть они не являются функциями Google Cloud). Модель может попросить вас вызвать функцию и отправить результат обратно, чтобы помочь модели обработать ваш запрос.

Если вы еще этого не сделали, ознакомьтесь с разделом «Введение в вызов функций», чтобы узнать больше.

Пример API для управления освещением

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

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

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

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

Прежде чем начать: настройте проект и ключ API.

Прежде чем вызывать API Gemini, вам необходимо настроить проект и ключ API.

Определить функцию API

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

func setLightValues(brightness int, colorTemp string) map[string]any {
    // This mock API returns the requested lighting values
    return map[string]any{
        "brightness":       brightness,
        "colorTemperature": colorTemp}
}

Создайте объявление функции

Создайте объявление функции, которое вы передадите в генеративную модель. Когда вы объявляете функцию для использования моделью, вам следует включить как можно больше подробностей в описания функций и параметров. Генеративная модель использует эту информацию, чтобы определить, какую функцию выбрать и как предоставить значения параметров при вызове функции. Следующий код показывает, как объявить функцию управления освещением:

lightControlTool := &genai.Tool{
    FunctionDeclarations: []*genai.FunctionDeclaration{{
        Name:        "controlLight",
        Description: "Set the brightness and color temperature of a room light.",
        Parameters: &genai.Schema{
            Type: genai.TypeObject,
            Properties: map[string]*genai.Schema{
                "brightness": {
                    Type:        genai.TypeString,
                    Description: "Light level from 0 to 100. Zero is off and"+
                        " 100 is full brightness.",
                },
                "colorTemperature": {
                    Type:        genai.TypeString,
                    Description: "Color temperature of the light fixture which" +
                        " can be `daylight`, `cool` or `warm`.",
                },
            },
            Required: []string{"brightness", "colorTemperature"},
        },
    }},
}

Объявляйте функции во время инициализации модели

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

// ...

lightControlTool := &genai.Tool{
    // ...
}

// Use a model that supports function calling, like a Gemini 1.5 model
model := client.GenerativeModel("gemini-1.5-flash")

// Specify the function declaration.
model.Tools = []*genai.Tool{lightControlTool}

Создать вызов функции

После того как вы инициализировали модель с объявлениями функций, вы можете запросить модель с определенной функцией. Вам следует использовать вызов функций с использованием подсказок чата ( SendMessage() ), поскольку вызов функций обычно выигрывает от наличия контекста предыдущих запросов и ответов.

// Start new chat session.
session := model.StartChat()

prompt := "Dim the lights so the room feels cozy and warm."

// Send the message to the generative model.
resp, err := session.SendMessage(ctx, genai.Text(prompt))
if err != nil {
    log.Fatalf("Error sending message: %v\n", err)
}

// Check that you got the expected function call back.
part := resp.Candidates[0].Content.Parts[0]
funcall, ok := part.(genai.FunctionCall)
if !ok {
    log.Fatalf("Expected type FunctionCall, got %T", part)
}
if g, e := funcall.Name, lightControlTool.FunctionDeclarations[0].Name; g != e {
    log.Fatalf("Expected FunctionCall.Name %q, got %q", e, g)
}
fmt.Printf("Received function call response:\n%q\n\n", part)

apiResult := map[string]any{
    "brightness":  "30",
    "colorTemperature":  "warm" }

// Send the hypothetical API result back to the generative model.
fmt.Printf("Sending API result:\n%q\n\n", apiResult)
resp, err = session.SendMessage(ctx, genai.FunctionResponse{
    Name:     lightControlTool.FunctionDeclarations[0].Name,
    Response: apiResult,
})
if err != nil {
    log.Fatalf("Error sending message: %v\n", err)
}

// Show the model's response, which is expected to be text.
for _, part := range resp.Candidates[0].Content.Parts {
    fmt.Printf("%v\n", part)
}