הוספנו ל-Gemini 1.5 Pro 2M חלון הקשר, יכולות להפעלת קוד ו-Gemma 2. מידע נוסף

דף זה תורגם על ידי Cloud Translation API.

מדריך: תחילת העבודה עם Gemini API

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

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

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

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

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

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

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

Dat 3.2.0 ואילך

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

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

הגדרה של מפתח 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 לאפליקציית Drt או 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-1.5-flash מיועד לקלט מרובה מצבים). במדריך הזה מופיעות ההוראות לכל הטמעה, יחד עם רשימת המודל המומלץ לכל תרחיש לדוגמה.

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

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

אחרי שהפרויקט מוגדר, אתם יכולים להשתמש ב-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);
}

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

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

כשהקלט של ההנחיה כולל גם טקסט וגם תמונות, צריך להשתמש במודל Gemini 1.5 עם השיטה 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 עם ה-method 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 ל-method של בקשה למודל (כמו 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 מציע כמה וריאציות של מודלים כדי לענות על הצרכים של תרחישי שימוש שונים, כמו סוגי הקלט ומורכבות, הטמעות ל-Chat או למשימות שפה אחרות עם דיאלוגים והגבלות גודל. מידע על המודלים הזמינים של Gemini