Lệnh gọi hàm giúp bạn dễ dàng nhận được đầu ra dữ liệu có cấu trúc từ các mô hình tạo sinh. Sau đó, bạn có thể sử dụng các kết quả này để gọi các API khác và trả về dữ liệu phản hồi có liên quan cho mô hình. Nói cách khác, lệnh gọi hàm giúp bạn kết nối các mô hình tạo sinh với các hệ thống bên ngoài để nội dung được tạo có thông tin mới nhất và chính xác nhất.
Bạn có thể cung cấp cho các mô hình Gemini nội dung mô tả về các hàm. Đây là các hàm mà bạn viết bằng ngôn ngữ của ứng dụng (tức là không phải là Hàm trên Google Cloud). Mô hình có thể yêu cầu bạn gọi một hàm và gửi lại kết quả để giúp mô hình xử lý truy vấn của bạn.
Nếu chưa, hãy xem bài viết Giới thiệu về lệnh gọi hàm để tìm hiểu thêm.
Ví dụ về API để điều khiển ánh sáng
Hãy tưởng tượng bạn có một hệ thống điều khiển ánh sáng cơ bản với giao diện lập trình ứng dụng (API) và bạn muốn cho phép người dùng điều khiển ánh sáng thông qua các yêu cầu văn bản đơn giản. Bạn có thể sử dụng tính năng Gọi hàm để diễn giải các yêu cầu thay đổi ánh sáng của người dùng và dịch các yêu cầu đó thành lệnh gọi API để đặt các giá trị ánh sáng. Hệ thống điều khiển ánh sáng giả định này cho phép bạn kiểm soát độ sáng của ánh sáng và nhiệt độ màu của ánh sáng, được xác định là hai thông số riêng biệt:
| Thông số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
brightness |
số | có | Mức độ sáng từ 0 đến 100. 0 là tắt và 100 là độ sáng tối đa. |
colorTemperature |
chuỗi | có | Nhiệt độ màu của thiết bị chiếu sáng có thể là daylight, cool hoặc warm. |
Để đơn giản, hệ thống chiếu sáng tưởng tượng này chỉ có một đèn, vì vậy, người dùng không cần chỉ định phòng hoặc vị trí. Dưới đây là một yêu cầu JSON mẫu mà bạn có thể gửi đến API điều khiển ánh sáng để thay đổi độ sáng thành 50% bằng cách sử dụng nhiệt độ màu ban ngày:
{
"brightness": "50",
"colorTemperature": "daylight"
}
Hướng dẫn này cho bạn biết cách thiết lập Lệnh gọi hàm cho API Gemini để diễn giải các yêu cầu chiếu sáng của người dùng và liên kết các yêu cầu đó với chế độ cài đặt API để kiểm soát độ sáng và nhiệt độ màu của ánh sáng.
Trước khi bắt đầu: Thiết lập dự án và khoá API
Trước khi gọi API Gemini, bạn cần thiết lập dự án và định cấu hình khoá API.
Xác định hàm API
Tạo một hàm tạo yêu cầu API. Bạn nên xác định hàm này trong mã của ứng dụng, nhưng có thể gọi các dịch vụ hoặc API bên ngoài ứng dụng. API Gemini không gọi trực tiếp hàm này, vì vậy, bạn có thể kiểm soát cách thức và thời điểm thực thi hàm này thông qua mã ứng dụng. Để minh hoạ, hướng dẫn này xác định một hàm API mô phỏng chỉ trả về các giá trị ánh sáng được yêu cầu:
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}
}
Tạo phần khai báo hàm
Tạo nội dung khai báo hàm mà bạn sẽ truyền vào mô hình tạo sinh. Khi khai báo một hàm để mô hình sử dụng, bạn nên đưa vào nội dung mô tả hàm và tham số càng chi tiết càng tốt. Mô hình tạo sinh sử dụng thông tin này để xác định hàm cần chọn và cách cung cấp giá trị cho các tham số trong lệnh gọi hàm. Đoạn mã sau đây cho biết cách khai báo hàm điều khiển ánh sáng:
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"},
},
}},
}
Khai báo hàm trong quá trình khởi chạy mô hình
Khi muốn sử dụng lệnh gọi hàm với một mô hình, bạn phải cung cấp nội dung khai báo hàm khi khởi tạo đối tượng mô hình. Bạn khai báo các hàm bằng cách đặt tham số Tools của mô hình:
// ...
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}
Tạo lệnh gọi hàm
Sau khi khởi chạy mô hình bằng các nội dung khai báo hàm, bạn có thể nhắc mô hình bằng hàm đã xác định. Bạn nên sử dụng lệnh gọi hàm bằng lời nhắc trò chuyện (SendMessage()), vì lệnh gọi hàm thường có lợi khi có ngữ cảnh của các lời nhắc và phản hồi trước đó.
// 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)
}