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

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

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

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

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

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

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

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

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

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

Dat 3.2.0 ואילך

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

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

הגדרה של מפתח 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 שמשויכות לתוכן ב- call:

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

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

הטמעה היא שיטה לייצוג מידע כרשימה של מספרי נקודה צפה (floating-point) במערך. בעזרת 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 לבקשה של מודל (למשל 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