תחילת השימוש ב-Gemini API באפליקציות Dart או Flutter

המדריך הזה מדגים איך לגשת ל-Gemini API לאפליקציות ל-Dart או ל-Flutter באמצעות Google AI Dat SDK. אפשר להשתמש ב-SDK הזה אם אתם לא רוצים לעבוד ישירות עם ממשקי API ל-REST כדי לקבל גישה למודלים של Gemini באפליקציה.

במדריך הזה תלמדו כיצד לבצע את הפעולות הבאות:

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

דרישות מוקדמות

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

כדי להשלים את המדריך, ודאו שסביבת הפיתוח עומדת בדרישות הבאות:

  • Dart 3.2.0+

הגדרת הפרויקט

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

הגדרת מפתח ה-API

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

קבלת מפתח API

אבטחה של מפתח ה-API

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

כל קטעי הקוד במדריך הזה מניחים שאתם ניגשים למפתח ה-API בתור משתנה סביבת תהליך. אם אתם מפתחים אפליקציה של Flutter, תוכלו להשתמש ב-String.fromEnvironment ולהעביר את --dart-define=API_KEY=$API_KEY ל-flutter build או ל-flutter run כדי להדר אותו עם מפתח ה-API, כי סביבת התהליך תהיה שונה כשמפעילים את האפליקציה.

התקנה של חבילת ה-SDK

כדי להשתמש ב-Gemini API באפליקציה שלכם, צריך add את חבילת google_generative_ai לאפליקציית Dart או Flutter:

Dart 

dart pub add google_generative_ai

Flutter 

flutter pub add google_generative_ai

מאתחלים את המודל הגנרטיבי

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

import 'package:google_generative_ai/google_generative_ai.dart';

// Access your API key as an environment variable (see "Set up your API key" above)
final apiKey = Platform.environment['API_KEY'];
if (apiKey == null) {
  print('No \$API_KEY environment variable');
  exit(1);
}

final model = GenerativeModel(model: 'MODEL_NAME', apiKey: apiKey);

כשמציינים מודל, חשוב לשים לב לנקודות הבאות:

  • אתם צריכים להשתמש במודל שהוא ספציפי לתרחיש לדוגמה שלכם (לדוגמה, gemini-pro-vision הוא לקלט מרובה מצבים). במדריך הזה מפורט המודל המומלץ לכל תרחיש לדוגמה.

הטמעת תרחישים נפוצים לדוגמה

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

בקטע של תרחישים מתקדמים לדוגמה, תוכלו למצוא מידע על Gemini API ועל הטמעות.

יצירת טקסט מקלט טקסט בלבד

כשהקלט של הפרומפט כולל רק טקסט, משתמשים במודל gemini-pro עם השיטה generateContent כדי ליצור פלט טקסט:

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

void main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // For text-only input, use the gemini-pro model
  final model = GenerativeModel(model: 'gemini-pro', apiKey: apiKey);
  final content = [Content.text('Write a story about a magic backpack.')];
  final response = await model.generateContent(content);
  print(response.text);
}

יצירת טקסט מקלט טקסט ותמונה (ריבוי מצבים)

Gemini מספק מודל מרובה מצבים (gemini-pro-vision), כך שאפשר להזין בו גם טקסט וגם תמונות. חשוב לקרוא את הדרישות בנוגע לתמונות לקלט.

כשקלט הפרומפט כולל גם טקסט וגם תמונות, משתמשים במודל gemini-pro-vision עם השיטה generateContent כדי ליצור פלט טקסט:

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

void main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // For text-and-image input (multimodal), use the gemini-pro-vision model
  final model = GenerativeModel(model: 'gemini-pro-vision', apiKey: apiKey);
  final (firstImage, secondImage) = await (
    File('image0.jpg').readAsBytes(),
    File('image1.jpg').readAsBytes()
  ).wait;
  final prompt = TextPart("What's different between these pictures?");
  final imageParts = [
    DataPart('image/jpeg', firstImage),
    DataPart('image/jpeg', secondImage),
  ];
  final response = await model.generateContent([
    Content.multi([prompt, ...imageParts])
  ]);
  print(response.text);
}

פיתוח שיחות עם מספר פניות (צ'אט)

באמצעות Gemini, תוכל ליצור שיחות חופשיות בכמה תורים. ה-SDK מפשט את התהליך בכך שהוא מאפשר לנהל את מצב השיחה, כך שבניגוד ל-generateContent, אתם לא צריכים לשמור את היסטוריית השיחות בעצמכם.

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

יש שתי אפשרויות אפשריות ל-role שמשויך לתוכן בשיחה:

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

  • model: התפקיד שנותן את התשובות. אפשר להשתמש בתפקיד הזה כשקוראים ל-startChat() באמצעות history.

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

Future<void> main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // For text-only input, use the gemini-pro model
  final model = GenerativeModel(
      model: 'gemini-pro',
      apiKey: apiKey,
      generationConfig: GenerationConfig(maxOutputTokens: 100));
  // Initialize the chat
  final chat = model.startChat(history: [
    Content.text('Hello, I have 2 dogs in my house.'),
    Content.model([TextPart('Great to meet you. What would you like to know?')])
  ]);
  var content = Content.text('How many paws are in my house?');
  var response = await chat.sendMessage(content);
  print(response.text);
}

משתמשים בסטרימינג כדי לבצע אינטראקציות מהירות יותר

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

הדוגמה הבאה ממחישה איך להטמיע סטרימינג באמצעות השיטה generateContentStream כדי ליצור טקסט מבקשת קלט של טקסט ותמונה.

// ...

final response = model.generateContentStream([
  Content.multi([prompt, ...imageParts])
]);
await for (final chunk in response) {
  print(chunk.text);
}

// ...

אפשר לנקוט גישה דומה בתרחישים לדוגמה שבהם משתמשים בקלט טקסט בלבד ובצ'אט.

// Use streaming with text-only input
final response = model.generateContentStream(content);

// Use streaming with multi-turn conversations (like chat)
final response = chat.sendMessageStream(content);

הטמעת תרחישים מתקדמים לדוגמה

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

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

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

שימוש בהטמעות

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

משתמשים במודל embedding-001 עם השיטה embedContent (או עם השיטה batchEmbedContent) כדי ליצור הטמעות. הדוגמה הבאה יוצרת הטמעה עבור מחרוזת יחידה:

final model = GenerativeModel(model: 'embedding-001', apiKey: apiKey);
final content = Content.text('The quick brown fox jumps over the lazy dog.');
final result = await model.embedContent(content);
print(result.embedding.values);

ספירת אסימונים

כשמשתמשים בהנחיות ארוכות, כדאי לספור אסימונים לפני ששולחים תוכן למודל. הדוגמאות הבאות מראות איך להשתמש ב-countTokens() בתרחישים שונים:

// For text-only input
final tokenCount = await model.countTokens(Content.text(prompt));
print('Token count: ${tokenCount.totalTokens}');

// For text-and-image input (multimodal)
final tokenCount = await model.countTokens([
  Content.multi([prompt, ...imageParts])
]);
print('Token count: ${tokenCount.totalTokens}');

// For multi-turn conversations (like chat)
final prompt = Content.text(message);
final allContent = [...chat.history, prompt];
final tokenCount = await model.countTokens(allContent);
print('Token count: ${tokenCount.totalTokens}');

אפשרויות לשליטה ביצירת תוכן

אפשר לשלוט ביצירת התוכן על ידי הגדרת הפרמטרים של המודל ושימוש בהגדרות הבטיחות.

שימו לב שהעברה של generationConfig או safetySettings לשיטה של בקשה למודל (כמו generateContent) תבטל באופן מלא את אובייקט התצורה עם אותו שם שהועבר ב-getGenerativeModel.

הגדרת פרמטרים של מודלים

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

final generationConfig = GenerationConfig(
  stopSequences: ["red"],
  maxOutputTokens: 200,
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
);
final model = GenerativeModel(
  model: 'MODEL_NAME',
  apiKey: apiKey,
  generationConfig: generationConfig,
);

שימוש בהגדרות בטיחות

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

כך מגדירים הגדרת בטיחות:

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high)
];
final model = GenerativeModel(
  model: 'MODEL_NAME',
  apiKey: apiKey,
  safetySettings: safetySettings,
);

אתם יכולים גם להגדיר יותר מהגדרת בטיחות אחת:

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high),
  SafetySetting(HarmCategory.hateSpeech, HarmBlockThreshold.high),
];

המאמרים הבאים

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

  • ב-Gemini יש כמה וריאציות של מודלים כדי לענות על הצרכים בתרחישי שימוש שונים, כמו סוגי קלט ומורכבות, הטמעות בצ'אט או במשימות שפה אחרות בדיאלוג ומגבלות גודל. מידע נוסף על הדגמים הזמינים של Gemini.

  • ב-Gemini יש אפשרויות נוספות לשליחת בקשות להגדלה של מגבלת הקצב. מגבלת הקצב של יצירת הבקשות לדגמים של Gemini Pro היא 60 בקשות לדקה (RPM).