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

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

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

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

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

ลองนึกภาพว่าคุณมีระบบควบคุมแสงพื้นฐานที่มีการเขียนโปรแกรมแอปพลิเคชัน อินเทอร์เฟซ (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)
}