ירידה במחיר של Gemini 1.5 Flash, כוונון עדין של הגישה לכל המפתחים ועוד! מידע נוסף

דף זה תורגם על ידי Cloud Translation API.

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

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

כדי להפעיל את Gemini API, נדרש מפתח API. אם עדיין אין לכם מפתח, תוכלו ליצור מפתח ב-Google AI Studio.

קבלת מפתח API

מומלץ מאוד לא להטמיע מפתח API במערכת בקרת הגרסאות.

צריך לאחסן את מפתח ה-API במאגר סודות כמו Google Cloud Secret Manager.

במדריך הזה נניח שאתם ניגשים למפתח ה-API כמשתנה סביבה.

מייבאים את חבילת ה-SDK ומגדירים את מפתח ה-API

מבצעים את הפעולות הבאות באפליקציה:

בספריית המודול, get, חבילת Go SDK:
```
go get github.com/google/generative-ai-go
```

מייבאים את החבילה ומגדירים את השירות באמצעות מפתח ה-API:

import (
  // import standard libraries
  // Import the GenerativeAI package for Go
  "github.com/google/generative-ai-go/genai"
  "google.golang.org/api/option"
)

ctx := context.Background()
// Access your API key as an environment variable
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// ...

הגדרה של פונקציית 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)
}