<ph type="x-smartling-placeholder">
函数调用可让您更轻松地从 Google Cloud 控制台获取结构化数据输出 生成模型。然后,您可以使用这些输出来调用其他 API 并返回 将相关的响应数据提供给模型。换句话说,函数调用有助于 将生成模型连接到外部系统, 可提供最新、最准确的信息。
您可以为 Gemini 模型提供函数说明。这些是 以应用语言编写的函数(也就是说,它们 Google Cloud Functions)。模型可能会要求您调用一个函数并返回 帮助模型处理您的查询。
如果您还没看过 函数调用简介(用于学习相关知识)
照明控制示例 API
假设您有一个带有应用编程接口 (API) 的基本照明控制系统,并且希望允许用户通过简单的文本请求控制灯具。您可以使用函数调用功能来解读用户发来的照明更改请求,并将其转换为 API 调用以设置照明值。通过这个假想的照明控制系统,您可以控制灯的亮度和色温,这两个参数定义如下:
参数 | 类型 | 是否必需 | 说明 |
---|---|---|---|
brightness |
number | 是 | 光级范围为 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)
}