Учебное пособие. Вызов функций с помощью Gemini API

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

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

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

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

Настройте свой проект

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

go get github.com/google/generative-ai-go

import "github.com/google/generative-ai-go/genai"
import "google.golang.org/api/option"

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// Use a model that supports function calling, like Gemini 1.0 Pro.
// See "Supported models" in the "Introduction to function calling" page.
model := client.GenerativeModel("MODEL_NAME")

Настройка вызова функции

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

Пример запроса API

{
  "currencyDate": "2024-04-17",
  "currencyFrom": "USD",
  "currencyTo": "SEK"
}

Пример ответа API

{
  "base": "USD",
  "date": "2024-04-17",
  "rates": {"SEK": 0.091}
}

Шаг 1. Создайте функцию, которая выполняет запрос API.

Если вы еще этого не сделали, начните с создания функции, которая отправляет запрос к API.

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

func exchangeRate(currencyDate string,
    currencyFrom string, currencyTo string) map[string]any {
    // This hypothetical API returns a JSON such as:
    // {"base":"USD","date":"2024-04-17","rates":{"SEK": 0.091}}
    return map[string]any{
        "base":  currencyFrom,
        "date":  currencyDate,
        "rates": map[string]any{currencyTo: 0.091}}
}

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

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

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

currencyExchangeTool := &genai.Tool{
    FunctionDeclarations: []*genai.FunctionDeclaration{{
        Name:        "exchangeRate",
        Description: "Lookup currency exchange rates by date",
        Parameters: &genai.Schema{
            Type: genai.TypeObject,
            Properties: map[string]*genai.Schema{
                "currencyDate": {
                    Type:        genai.TypeString,
                    Description: "A date that must always be in YYYY-MM-DD format" +
                        " or the value 'latest' if a time period is not specified",
                },
                "currencyFrom": {
                    Type:        genai.TypeString,
                    Description: "Currency to convert from",
                },
                "currencyTo": {
                    Type:        genai.TypeString,
                    Description: "Currency to convert to",
                },
            },
            Required: []string{"currencyDate", "currencyFrom"},
        },
    }},
}

Шаг 3. Укажите объявление функции во время инициализации модели.

Укажите объявление функции при инициализации генеративной модели, передав его в параметр Tools модели:

// ...

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

// Use a model that supports function calling, like Gemini 1.0 Pro.
// See "Supported models" in the "Introduction to function calling" page.
model := client.GenerativeModel("gemini-1.0-pro")

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

Шаг 4. Создайте вызов функции.

Теперь вы можете запросить модель с определенной функцией.

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

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

prompt := "How much is 50 US dollars worth in Swedish krona?"

// 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, currencyExchangeTool.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{
    "base":  "USD",
    "date":  "2024-04-17",
    "rates": map[string]any{"SEK": 0.091}}

// 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:     currencyExchangeTool.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)
}