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

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

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 לאפליקציה:

1. ב-Xcode, לוחצים לחיצה ימנית על הפרויקט בניווט הפרויקט.

2. בוחרים באפשרות הוספת חבילות מתפריט ההקשר.

3. בתיבת הדו-שיח Add Packages (הוספת חבילות), מדביקים את כתובת ה-URL של החבילה בסרגל החיפוש:

   https://github.com/google/generative-ai-swift
   

4. לוחצים על הוספת חבילה. עכשיו Xcode יוסיף את החבילה GoogleGenerativeAI לפרויקט.

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

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

1. מייבאים את המודול GoogleGenerativeAI:

   import GoogleGenerativeAI
   

2. מפעילים את המודל הגנרטיבי:

   // Access your API key from your on-demand resource .plist file
   // (see "Set up your API key" above)
   let model = GenerativeModel(name: "MODEL_NAME", apiKey: APIKey.default)
   

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

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

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

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

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

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

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

import GoogleGenerativeAI

// For text-only input, use the gemini-pro model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-pro", 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)
}

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

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

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

import GoogleGenerativeAI

// For text-and-image input (multimodal), use the gemini-pro-vision model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-pro-vision", 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-pro ולאתחל את הצ'אט על ידי קריאה ל-startChat(). לאחר מכן השתמשו ב-sendMessage() כדי לשלוח הודעת משתמש חדשה, שגם תצרף את ההודעה ואת התגובה להיסטוריית הצ'אט.

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

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

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

import GoogleGenerativeAI

let config = GenerationConfig(
  maxOutputTokens: 100
)

// For text-only input, use the gemini-pro model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(
  name: "gemini-pro",
  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

// For text-and-image input (multimodal), use the gemini-pro-vision model
// Access your API key from your on-demand resource .plist file (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-pro-vision", 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 = 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(
  name: "MODEL_NAME",
  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(
  name: "MODEL_NAME",
  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(
  name: "MODEL_NAME",
  apiKey: APIKey.default,
    safetySettings: [harassmentSafety, hateSpeechSafety]
)

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

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

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

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