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

Python Node.js Go Dart‏ (Flutter) Android Swift אינטרנט REST

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

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

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

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

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

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

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

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

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

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

dart pub add google_generative_ai

flutter pub add google_generative_ai

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

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

Future<Map<String, Object?>> setLightValues(
  Map<String, Object?> arguments,
) async =>
    // This mock API returns the requested lighting values
    {
      'brightness': arguments['brightness'],
      'colorTemperature': arguments['colorTemp'],
    };

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

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

final lightControlTool = FunctionDeclaration(
    'setLightValues',
    'Set the brightness and color temperature of a room light.',
    Schema(SchemaType.object, properties: {
      'brightness': Schema(SchemaType.number,
          description: 'Light level from 0 to 100. '
              'Zero is off and 100 is full brightness.'),
      'colorTemperature': Schema(SchemaType.string,
          description: 'Color temperature of the light fixture, '
              'which can be `daylight`, `cool` or `warm`.'),
    }, requiredProperties: [
      'brightness',
      'colorTemperature'
    ]));

הצהרת פונקציות במהלך האינטוליזציה של המודל

כשרוצים להשתמש בקריאה לפונקציה עם מודל, צריך לספק את הצהרות הפונקציות בזמן שמפעילים את אובייקט המודל. כדי להצהיר על פונקציות, מגדירים את הפרמטר tools של המודל. ב-Dart SDK יש גם תמיכה בהצהרה על הפונקציות כארגומנטים לממשקי ה-API generateContent או generateContentStream.

final model = GenerativeModel(
  model: 'gemini-1.5-flash',
  apiKey: apiKey,

  // Specify the function declaration.
  tools: [
    Tool(functionDeclarations: [lightControlTool])
  ],
);

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

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

final chat = model.startChat(); final prompt =
  'Dim the lights so the room feels cozy and warm.';

// Send the message to the generative model.
var response = await chat.sendMessage(Content.text(prompt));

final functionCalls = response.functionCalls.toList();
// When the model response with a function call, invoke the function.
if (functionCalls.isNotEmpty) {
  final functionCall = functionCalls.first;
  final result = switch (functionCall.name) {
    // Forward arguments to the hypothetical API.
    'setLightValues' => await setLightValues(functionCall.args),
    // Throw an exception if the model attempted to call a function that was
    // not declared.
    _ => throw UnimplementedError(
        'Function not implemented: ${functionCall.name}')
  };
  // Send the response to the model so that it can use the result to generate
  // text for the user.
  response = await chat
      .sendMessage(Content.functionResponse(functionCall.name, result));
}
// When the model responds with non-null text content, print it.
if (response.text case final text?) {
  print(text);
}