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