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