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

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

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

במדריך הזה נדגים איך לגשת ל-Gemini API ישירות מאפליקציית SWIFT באמצעות Google AI Swift SDK. אפשר להשתמש ב-SDK הזה אם אתם לא רוצים לעבוד ישירות עם ממשקי API ל-REST או עם קוד בצד השרת (כמו Python) כדי לגשת למודלים של Gemini באפליקציית Swift.

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

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

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

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

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

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

Xcode 15.0 ומעלה
אפליקציית Swift צריכה לטרגט ל-iOS 15 ואילך או ל-macOS מגרסה 12 ואילך.

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

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

הגדרה של מפתח API

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

קבלת מפתח API

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

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

אפשר להרחיב כדי לראות איך לאחסן ולקרוא את מפתח ה-API מקובץ .plist

enum APIKey {
  // Fetch the API key from `GenerativeAI-Info.plist`
  static var `default`: String {
    guard let filePath = Bundle.main.path(forResource: "GenerativeAI-Info", ofType: "plist")
    else {
      fatalError("Couldn't find file 'GenerativeAI-Info.plist'.")
    }
    let plist = NSDictionary(contentsOfFile: filePath)
    guard let value = plist?.object(forKey: "API_KEY") as? String else {
      fatalError("Couldn't find key 'API_KEY' in 'GenerativeAI-Info.plist'.")
    }
    if value.starts(with: "_") {
      fatalError(
        "Follow the instructions at https://ai.google.dev/tutorials/setup to get an API key."
      )
    }
    return value
  }
}

תוכלו גם לעיין באפליקציה לדוגמה כדי ללמוד איך לאחסן את מפתח ה-API בקובץ .plist.

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

הוספה של חבילת ה-SDK לפרויקט

כדי להשתמש ב-Gemini API באפליקציית Swift משלכם, מוסיפים את החבילה GoogleGenerativeAI לאפליקציה:

ב-Xcode, לוחצים לחיצה ימנית על הפרויקט בסרגל הניווט של הפרויקט.
בוחרים באפשרות הוספת חבילות מתפריט ההקשר.
בתיבת הדו-שיח הוספת חבילות, מדביקים את כתובת ה-URL של החבילה בסרגל החיפוש:
```
https://github.com/google/generative-ai-swift
```
לוחצים על Add Package (הוספת חבילה). עכשיו Xcode יוסיף את החבילה GoogleGenerativeAI לפרויקט שלכם.

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

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

מייבאים את המודול GoogleGenerativeAI:
```
import GoogleGenerativeAI
```

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

// Access your API key from your on-demand resource .plist file
// (see "Set up your API key" above)
// The Gemini 1.5 models are versatile and work with most use cases
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

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

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

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

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

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

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

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

כשהקלט של ההנחיה כולל רק טקסט, צריך להשתמש במודל Gemini 1.5 או במודל Gemini 1.0 Pro עם generateContent כדי ליצור פלט טקסט:

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

let prompt = "Write a story about a magic backpack."
let response = try await model.generateContent(prompt)
if let text = response.text {
  print(text)
}

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

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

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

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

let image1 = UIImage(...)
let image2 = UIImage(...)

let prompt = "What's different between these pictures?"

let response = try await model.generateContent(prompt, image1, image2)
if let text = response.text {
  print(text)
}

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

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

כדי ליצור שיחה במספר תורות (כמו צ'אט), צריך להשתמש במודל Gemini 1.5 או מודל Gemini 1.0 Pro, ולהתחיל את השיחה דרך startChat(). לאחר מכן משתמשים ב-sendMessage() כדי לשלוח הודעה חדשה למשתמש, והפעולה הזו תגרום גם לצירוף של ההודעה ושל התשובה להיסטוריית הצ'אט.

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

user: התפקיד שמספק את ההנחיות. הערך הזה הוא ברירת המחדל לקריאות ל-sendMessage.
model: התפקיד שמספק את התשובות. אפשר להשתמש בתפקיד הזה כשקוראים לפונקציה startChat() עם history קיים.

import GoogleGenerativeAI

let config = GenerationConfig(
  maxOutputTokens: 100
)

// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
  generationConfig: config
)

let history = [
  ModelContent(role: "user", parts: "Hello, I have 2 dogs in my house."),
  ModelContent(role: "model", parts: "Great to meet you. What would you like to know?"),
]

// Initialize the chat
let chat = model.startChat(history: history)
let response = try await chat.sendMessage("How many paws are in my house?")
if let text = response.text {
  print(text)
}

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

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

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

import GoogleGenerativeAI

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

let image1 = UIImage(named: "")!
let image2 = UIImage(named: "")!

let prompt = "What's different between these pictures?"
var fullResponse = ""
let contentStream = model.generateContentStream(prompt, image1, image2)
for try await chunk in contentStream {
  if let text = chunk.text {
    print(text)
    fullResponse += text
  }
}
print(fullResponse)

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

// Use streaming with text-only input
let contentStream = model.generateContentStream(prompt)

// Use streaming with multi-turn conversations (like chat)
let responseStream = chat.sendMessageStream(message)

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

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

שליחת פונקציות

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

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

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

// For text-only input
let response = try await model.countTokens("Why is the sky blue?")
print(response.totalTokens)

// For text-and-image input (multi-modal)
let response = try await model.countTokens(prompt, image1, image2)
print(response.totalTokens)

// For multi-turn conversations (like chat)
let chat = model.startChat()
let history = chat.history
let message = try ModelContent(role: "user", "Why is the sky blue?")
let contents = history + [message]
let response = try await model.countTokens(contents)
print(response.totalTokens)

אפשרויות להגדרת יצירת תוכן

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

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

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

let config = GenerationConfig(
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
  maxOutputTokens: 200,
  stopSequences: ["red"]
)

// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
  generationConfig: config
)

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

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

כך קובעים הגדרת בטיחות אחת:

// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
  safetySettings: [
    SafetySetting(harmCategory: .harassment, threshold: .blockOnlyHigh)
  ]
)

אפשר גם לקבוע יותר מהגדרת בטיחות אחת:

let harassmentSafety = SafetySetting(harmCategory: .harassment, threshold: .blockOnlyHigh)
let hateSpeechSafety = SafetySetting(harmCategory: .hateSpeech, threshold: .blockMediumAndAbove)

// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  // The Gemini 1.5 models are versatile and work with most use cases
  name: "gemini-1.5-flash",
  apiKey: APIKey.default,
    safetySettings: [harassmentSafety, hateSpeechSafety]
)

מה עושים אחר כך

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