การเรียกใช้ฟังก์ชันช่วยให้คุณรับเอาต์พุต Structured Data จากโมเดล Generative ได้ง่ายขึ้น จากนั้นคุณก็ใช้เอาต์พุตเหล่านี้เพื่อเรียก API อื่นๆ และส่งข้อมูลการตอบกลับที่เกี่ยวข้องกลับไปยังโมเดลได้ กล่าวคือ การเรียกใช้ฟังก์ชันจะช่วยคุณเชื่อมต่อโมเดล Generative กับระบบภายนอกเพื่อให้เนื้อหาที่สร้างขึ้นมีข้อมูลล่าสุดและถูกต้อง
คุณสามารถระบุคำอธิบายฟังก์ชันให้กับโมเดล Gemini ได้ ฟังก์ชันเหล่านี้คือฟังก์ชันที่คุณเขียนในภาษาของแอป (ไม่ใช่ฟังก์ชัน Google Cloud) โมเดลอาจขอให้คุณเรียกใช้ฟังก์ชันและส่งผลลัพธ์กลับเพื่อช่วยโมเดลจัดการการค้นหาของคุณ
หากยังไม่ได้อ่าน โปรดดูข้อมูลเบื้องต้นเกี่ยวกับการเรียกใช้ฟังก์ชันเพื่อดูข้อมูลเพิ่มเติม
ตัวอย่าง API สำหรับการควบคุมแสง
สมมติว่าคุณมีระบบควบคุมแสงพื้นฐานที่มี Application Programming Interface (API) และต้องการอนุญาตให้ผู้ใช้ควบคุมไฟผ่านคําขอแบบข้อความง่ายๆ คุณสามารถใช้ฟีเจอร์การเรียกฟังก์ชันเพื่อตีความคําขอเปลี่ยนแปลงแสงจากผู้ใช้และแปลเป็นคําเรียก API เพื่อตั้งค่าแสงได้ ระบบควบคุมแสงสมมตินี้ช่วยให้คุณควบคุมความสว่างของแสงและอุณหภูมิสีของแสงได้ ซึ่งกำหนดเป็น 2 พารามิเตอร์แยกกัน ดังนี้
พารามิเตอร์ | ประเภท | ต้องระบุ | คำอธิบาย |
---|---|---|---|
brightness |
ตัวเลข | ใช่ | ระดับแสงจาก 0 ถึง 100 0 คือปิดและ 100 คือความสว่างเต็มที่ |
colorTemperature |
สตริง | ใช่ | อุณหภูมิสีของอุปกรณ์ให้แสงสว่าง ซึ่งอาจเป็น daylight , cool หรือ warm |
ระบบแสงสว่างสมมตินี้จะมีเพียงหลอดไฟเดียวเพื่อความง่ายดาย ผู้ใช้จึงไม่ต้องระบุห้องหรือตำแหน่ง ต่อไปนี้คือตัวอย่างคําขอ JSON ที่คุณสามารถส่งไปยัง API การควบคุมแสงเพื่อเปลี่ยนระดับแสงเป็น 50% โดยใช้อุณหภูมิสีของแสงแดด
{
"brightness": "50",
"colorTemperature": "daylight"
}
บทแนะนำนี้จะแสดงวิธีตั้งค่าการเรียกฟังก์ชันสําหรับ Gemini API เพื่อตีความคําขอแสงของผู้ใช้และจับคู่กับการตั้งค่า API เพื่อควบคุมค่าความสว่างและอุณหภูมิสีของแสง
ก่อนเริ่มต้น: ตั้งค่าโปรเจ็กต์และคีย์ API
คุณต้องตั้งค่าโปรเจ็กต์และกำหนดค่าคีย์ API ก่อนเรียกใช้ Gemini 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}
}
สร้างประกาศฟังก์ชัน
สร้างการประกาศฟังก์ชันที่จะส่งไปยังโมเดล Generative เมื่อประกาศฟังก์ชันให้โมเดลใช้ คุณควรระบุรายละเอียดให้มากที่สุดในคำอธิบายฟังก์ชันและพารามิเตอร์ โมเดล Generative ใช้ข้อมูลนี้เพื่อพิจารณาว่าควรเลือกฟังก์ชันใดและวิธีระบุค่าสำหรับพารามิเตอร์ในการเรียกใช้ฟังก์ชัน โค้ดต่อไปนี้แสดงวิธีประกาศฟังก์ชันการควบคุมแสง
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)
}