บทแนะนำการเรียกใช้ฟังก์ชัน

การเรียกฟังก์ชันช่วยให้คุณได้รับเอาต์พุตของ Structured Data ได้ง่ายขึ้น โมเดล Generative จากนั้นคุณสามารถใช้เอาต์พุตเหล่านี้เพื่อเรียกใช้ API อื่นๆ และแสดงผล ข้อมูลการตอบสนองที่เกี่ยวข้องกับโมเดล กล่าวอีกนัยหนึ่งคือ การเรียกฟังก์ชันช่วยให้ คุณเชื่อมต่อโมเดล Generative กับระบบภายนอกเพื่อให้เนื้อหาที่สร้างขึ้น ประกอบด้วยข้อมูลล่าสุดและถูกต้อง

คุณสามารถจัดเตรียมคำอธิบายฟังก์ชันต่างๆ ให้กับโมเดล Gemini ได้ สิ่งเหล่านี้คือ ฟังก์ชันที่คุณเขียนในภาษาของแอป (กล่าวคือไม่ใช่ Google Cloud Functions) โมเดลอาจขอให้คุณเรียกใช้ฟังก์ชันแล้วส่งกลับ ผลลัพธ์เพื่อช่วยโมเดลจัดการข้อความค้นหาของคุณ

หากยังไม่ได้ดู โปรดไปที่ ข้อมูลเบื้องต้นเกี่ยวกับการเรียกใช้ฟังก์ชันเพื่อเรียนรู้ อีกมากมาย

ตัวอย่าง API สำหรับการควบคุมแสง

ลองนึกภาพว่าคุณมีระบบควบคุมแสงพื้นฐานที่มีการเขียนโปรแกรมแอปพลิเคชัน อินเทอร์เฟซ (API) และคุณต้องการให้ผู้ใช้ควบคุมแสงไฟผ่าน คำขอแชท คุณใช้ฟีเจอร์การเรียกใช้ฟังก์ชันเพื่อตีความแสงไฟได้ เปลี่ยนคำขอจากผู้ใช้และแปลเป็นการเรียก API เพื่อกำหนด ระบบควบคุมแสงสมมตินี้ช่วยให้คุณควบคุม ความสว่างของแสงและอุณหภูมิสี ระบุเป็น 2 แยกกัน ได้แก่

พารามิเตอร์ ประเภท ต้องระบุ คำอธิบาย
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}
}

สร้างการประกาศฟังก์ชัน

สร้างการประกาศฟังก์ชันที่คุณจะส่งไปยังโมเดล 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)
}