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

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

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

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

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

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, colorTemperature }) => {
    return setLightValues( brightness, colorTemperature)
  }
};

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

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

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.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],
  },
});

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

אחרי שמפעילים את המודל באמצעות הצהרות הפונקציות, אפשר להציג לו הודעה עם הפונקציה שהוגדרה. צריך להשתמש בקריאות לפונקציה באמצעות הנחיות בצ'אט (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 result2 = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

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