教程：函数调用

借助函数调用，您可以更轻松地从生成式模型获取结构化数据输出。然后，您可以使用这些输出来调用其他 API，并将相关响应数据返回给模型。换句话说，函数调用可帮助您将生成式模型连接到外部系统，以便生成的内容包含最新、最准确的信息。

您可以为 Gemini 模型提供函数说明。这些函数是使用应用所用语言编写的（即它们不是 Google Cloud Functions 函数）。模型可能会要求您调用函数并发回结果，以帮助模型处理您的查询。

如果您尚未了解，请参阅函数调用简介了解详情。

用于照明控制的 API 示例

假设您有一个带有应用编程接口 (API) 的基本照明控制系统，并且希望允许用户通过简单的文本请求控制灯具。您可以使用函数调用功能来解读用户发来的照明更改请求，并将其转换为 API 调用以设置照明值。通过这个假想的照明控制系统，您可以控制灯的亮度和色温，这两个参数定义如下：

参数 类型 是否必需 说明
brightness 数值 是 亮度级别，介于 0 到 100 之间。0 表示关闭，100 表示全亮度。
colorTemperature 字符串 是 灯具的色温，可以是 daylight、cool 或 warm。

为简单起见，这个虚构的照明系统只有一个灯，因此用户无需指定房间或位置。以下是一个 JSON 请求示例，您可以将其发送到照明控制 API，以使用日光色温将亮度更改为 50%：

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

本教程介绍了如何为 Gemini API 设置函数调用，以解读用户的照明请求并将其映射到 API 设置，从而控制灯具的亮度和色温值。

开始前须知：设置项目和 API 密钥

在调用 Gemini API 之前，您需要设置项目并配置 API 密钥。

定义 API 函数

创建用于发出 API 请求的函数。此函数应在应用代码中定义，但可以调用应用之外的服务或 API。Gemini API 不会直接调用此函数，因此您可以通过应用代码控制此函数的执行方式和时间。出于演示目的，本教程定义了一个模拟 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)
}