מדריך להפעלת פונקציות

קריאה לפונקציות מאפשרת לכם לקבל בקלות פלט של נתונים מובְנים ממודלים גנרטיביים. לאחר מכן תוכלו להשתמש בפלט הזה כדי לבצע קריאה לממשקי API אחרים ולהחזיר את נתוני התגובה הרלוונטיים למודל. במילים אחרות, קריאה לפונקציה עוזרת לכם לחבר מודלים גנרטיביים למערכות חיצוניות, כך שהתוכן שנוצר יכלול את המידע העדכני והמדויק ביותר.

אפשר לספק למודלים של Gemini תיאורים של פונקציות. אלה פונקציות שכותבים בשפת האפליקציה (כלומר, הן לא Google Cloud Functions). יכול להיות שהמודל יבקש מכם להפעיל פונקציה ולשלוח בחזרה את התוצאה כדי לעזור לו לטפל בשאילתה.

אם עדיין לא עשיתם זאת, כדאי לעיין במאמר מבוא לקריאה של פונקציות כדי לקבל מידע נוסף.

דוגמה ל-API לבקרת תאורה

נניח שיש לכם מערכת בסיסית לבקרת תאורה עם ממשק תכנות יישומים (API), ואתם רוצים לאפשר למשתמשים לשלוט בתאורה באמצעות בקשות טקסט פשוטות. אפשר להשתמש בתכונה Function Calling כדי לפרש בקשות של משתמשים לשינוי התאורה ולתרגם אותן לקריאות API להגדרת ערכי התאורה. מערכת הבקרה ההיפותטית הזו מאפשרת לשלוט בהירות התאורה ובטמפרטורת הצבע שלה, שמוגדרות כשני פרמטרים נפרדים:

פרמטר סוג נדרש תיאור
brightness number כן רמת התאורה מ-0 עד 100. אפס הוא כיבוי ו-100 הוא בהירות מלאה.
colorTemperature מחרוזת כן טמפרטורת הצבע של גוף התאורה. הערכים האפשריים הם daylight, ‏ cool או warm.

כדי לפשט את העניין, מערכת התאורה הדמיונית הזו כוללת רק נורית אחת, כך שהמשתמש לא צריך לציין חדר או מיקום. זוהי דוגמה לבקשת JSON שאפשר לשלוח ל-API לבקרת התאורה כדי לשנות את רמת התאורה ל-50% באמצעות טמפרטורת הצבע של אור יום:

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

במדריך הזה תלמדו איך להגדיר קריאה לפונקציה של Gemini API כדי לפרש בקשות של משתמשים לגבי התאורה ולמפות אותן להגדרות API, כדי לשלוט בערכי הבהירות וטמפרטורת הצבע של התאורה.

לפני שמתחילים: מגדירים את הפרויקט ומפתח ה-API

לפני שמפעילים את Gemini API, צריך להגדיר את הפרויקט ולהגדיר את מפתח ה-API.

הגדרת פונקציית API

יוצרים פונקציה שמבצעת בקשת API. צריך להגדיר את הפונקציה הזו בקוד של האפליקציה, אבל היא יכולה להפעיל שירותים או ממשקי API מחוץ לאפליקציה. ממשק ה-API של Gemini לא קורא לפונקציה הזו ישירות, כך שתוכלו לקבוע איך ומתי הפונקציה הזו תתבצע באמצעות קוד האפליקציה. למטרות הדגמה, במדריך הזה מוגדר פונקציית 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}
}

יצירת הצהרה על פונקציה

יוצרים את ההצהרה על הפונקציה שתעבירו למודל הגנרטיבי. כשמגדירים פונקציה לשימוש במודל, כדאי לכלול כמה שיותר פרטים בתיאורים של הפונקציה והפרמטרים. המודל הגנרטיבי משתמש במידע הזה כדי לקבוע איזו פונקציה לבחור ואיך לספק ערכים לפרמטרים בקריאה לפונקציה. הקוד הבא מראה איך מגדירים את פונקציית בקרת התאורה:

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)
}