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

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

async function setLightValues(brightness, colorTemp) {
  // This mock API returns the requested lighting values
  return {
    brightness: brightness,
    colorTemperature: colorTemp
  };
}

יצירת הצהרות לגבי פונקציות

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

// Function declaration, to pass to the model.
const controlLightFunctionDeclaration = {
  name: "controlLight",
  parameters: {
    type: "OBJECT",
    description: "Set the brightness and color temperature of a room light.",
    properties: {
      brightness: {
        type: "NUMBER",
        description: "Light level from 0 to 100. Zero is off and 100 is full brightness.",
      },
      colorTemperature: {
        type: "STRING",
        description: "Color temperature of the light fixture which can be `daylight`, `cool` or `warm`.",
      },
    },
    required: ["brightness", "colorTemperature"],
  },
};

// Executable function code. Put it in a map keyed by the function name
// so that you can call it once you get the name string from the model.
const functions = {
  controlLight: ({ brightness, colorTemp }) => {
    return setLightValues( brightness, colorTemp)
  }
};

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

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

<html>
  <body>
    <!-- ... Your HTML and CSS -->

    <script type="importmap">
      {
        "imports": {
          "@google/generative-ai": "https://esm.run/@google/generative-ai"
        }
      }
    </script>
    <script type="module">
      import { GoogleGenerativeAI } from "@google/generative-ai";

      // Fetch your API_KEY
      const API_KEY = "...";

      // Access your API key (see "Set up your API key" above)
      const genAI = new GoogleGenerativeAI(API_KEY);

      // ...

      const generativeModel = genAI.getGenerativeModel({
        // Use a model that supports function calling, like a Gemini 1.5 model
        model: "gemini-1.5-flash",

        // Specify the function declaration.
        tools: {
          functionDeclarations: [controlLightFunctionDeclaration],
        },
      });
    </script>
  </body>
</html>

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

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

const chat = generativeModel.startChat();
const prompt = "Dim the lights so the room feels cozy and warm.";

// Send the message to the model.
const result = await chat.sendMessage(prompt);

// For simplicity, this uses the first function call found.
const call = result.response.functionCalls()[0];

if (call) {
  // Call the executable function named in the function call
  // with the arguments specified in the function call and
  // let it call the hypothetical API.
  const apiResponse = await functions[call.name](call.args);

  // Send the API response back to the model so it can generate
  // a text response that can be displayed to the user.
  const result = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

  // Log the text response.
  console.log(result.response.text());
}