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

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

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

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

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

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

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

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

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