המדריך הזה מדגים איך לגשת ל-Gemini API לאפליקציות ל-Dart או ל-Flutter באמצעות Google AI Dat SDK. אפשר להשתמש ב-SDK הזה אם אתם לא רוצים לעבוד ישירות עם ממשקי API ל-REST כדי לקבל גישה למודלים של Gemini באפליקציה.
במדריך הזה תלמדו כיצד לבצע את הפעולות הבאות:
- הגדרת הפרויקט, כולל מפתח ה-API
- יצירת טקסט מקלט טקסט בלבד
- יצירת טקסט מקלט של טקסט ותמונה (ריבוי מצבים)
- יצירת שיחות מרובות פניות (צ'אט)
- שימוש בסטרימינג לאינטראקציות מהירות יותר
בנוסף, המדריך כולל קטעים לתרחישים מתקדמים (כמו הטמעות ואסימונים לספירה), וגם אפשרויות לשליטה ביצירת תוכן.
דרישות מוקדמות
המדריך הזה מתבסס על ההנחה שאתם מכירים את בניית אפליקציות עם Dut.
כדי להשלים את המדריך, ודאו שסביבת הפיתוח עומדת בדרישות הבאות:
- Dart 3.2.0+
הגדרת הפרויקט
לפני שמפעילים את Gemini API, צריך להגדיר את הפרויקט. הפרויקט כולל הגדרה של מפתח ה-API, הוספת ה-SDK ליחסי התלות של המפרסמים ואתחול המודל.
הגדרת מפתח ה-API
כדי להשתמש ב-Gemini API, תצטרכו מפתח API. אם עדיין אין לכם מפתח, עליכם ליצור מפתח ב-Google AI Studio.
אבטחה של מפתח ה-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 '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);
}
// The Gemini 1.5 models are versatile and work with most use cases
final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
}
כשמציינים מודל, חשוב לשים לב לנקודות הבאות:
אתם צריכים להשתמש במודל שהוא ספציפי לתרחיש לדוגמה שלכם (לדוגמה,
gemini-pro-vision
הוא לקלט מרובה מצבים). במדריך הזה מפורט המודל המומלץ לכל תרחיש לדוגמה.
הטמעת תרחישים נפוצים לדוגמה
עכשיו, כשהפרויקט שלכם מוגדר, אתם יכולים להתנסות ב-Gemini API כדי להטמיע תרחישים שונים לדוגמה:
- יצירת טקסט מקלט טקסט בלבד
- יצירת טקסט מקלט של טקסט ותמונה (ריבוי מצבים)
- יצירת שיחות מרובות פניות (צ'אט)
- שימוש בסטרימינג לאינטראקציות מהירות יותר
בקטע של תרחישים מתקדמים לדוגמה, תוכלו למצוא מידע על Gemini API ועל הטמעות.
יצירת טקסט מקלט טקסט בלבד
אם קלט ההנחיות כולל רק טקסט, צריך להשתמש במודל Gemini 1.5 או במודל Gemini 1.0 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);
}
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
final content = [Content.text('Write a story about a magic backpack.')];
final response = await model.generateContent(content);
print(response.text);
}
יצירת טקסט מקלט טקסט ותמונה (ריבוי מצבים)
Gemini מספק מגוון מודלים שיכולים להתמודד עם קלט מרובה מצבים (דגמי Gemini 1.5 ו-Gemini 1.0 Pro Vision), כדי שאפשר יהיה להזין גם טקסט וגם תמונות. חשוב לקרוא את הדרישות בנוגע לתמונות בהנחיות.
אם קלט ההנחיות כולל גם טקסט וגם תמונות, צריך להשתמש במודל Gemini 1.5 או במודל Gemini 1.0 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);
}
// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
final model = GenerativeModel(model: 'gemini-1.5-flash', 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 1.5 או
בדגם Gemini 1.0 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);
}
// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
final model = GenerativeModel(
model: 'gemini-1.5-flash',
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(
// The Gemini 1.5 models are versatile and work with most use cases
model: 'gemini-1.5-flash',
apiKey: apiKey,
generationConfig: generationConfig,
);
שימוש בהגדרות בטיחות
אפשר להשתמש בהגדרות הבטיחות כדי לשנות את הסבירות לקבלת תשובות שעשויות להיחשב כמזיקות. כברירת מחדל, הגדרות הבטיחות חוסמות תוכן בעל סבירות בינונית ו/או גבוהה לכך שהוא תוכן לא בטוח בכל המימדים. למידע נוסף על הגדרות בטיחות
כך מגדירים הגדרת בטיחות:
final safetySettings = [
SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high)
];
final model = GenerativeModel(
// The Gemini 1.5 models are versatile and work with most use cases
model: 'gemini-1.5-flash',
apiKey: apiKey,
safetySettings: safetySettings,
);
אתם יכולים גם להגדיר יותר מהגדרת בטיחות אחת:
final safetySettings = [
SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high),
SafetySetting(HarmCategory.hateSpeech, HarmBlockThreshold.high),
];
מה עושים אחר כך
עיצוב הנחיות הוא התהליך של יצירת הנחיות שמפיקות את התגובה הרצויה ממודלים של שפה. כדי להבטיח תשובות מדויקות ואיכותיות ממודל השפה, חשוב לכתוב הנחיות מובְנות היטב. שיטות מומלצות לניסוח הנחיות
ב-Gemini יש כמה וריאציות של מודלים כדי לענות על הצרכים בתרחישי שימוש שונים, כמו סוגי קלט ומורכבות, הטמעות בצ'אט או במשימות שפה אחרות בדיאלוג ומגבלות גודל. מידע נוסף על הדגמים הזמינים של Gemini.
ב-Gemini יש אפשרויות נוספות לשליחת בקשות להגדלה של מגבלת הקצב. מגבלת הקצב של יצירת הבקשות לדגמים של Gemini Pro היא 60 בקשות לדקה (RPM).