תחילת העבודה עם Gemini API באפליקציות Go

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

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

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

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

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

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

  • מעבר ל-1.20 ואילך

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

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

הגדרת מפתח ה-API

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

קבלת מפתח API

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

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

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

התקנה של חבילת ה-SDK

כדי להשתמש ב-Gemini API באפליקציה שלכם, תצטרכו get את חבילת Go SDK בספריית המודול:

go get github.com/google/generative-ai-go

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

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

import "github.com/google/generative-ai-go/genai"
import "google.golang.org/api/option"

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("MODEL_NAME")

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

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

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

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

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

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

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

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// For text-only input, use the gemini-pro model
model := client.GenerativeModel("gemini-pro")
resp, err := model.GenerateContent(ctx, genai.Text("Write a story about a magic backpack."))
if err != nil {
  log.Fatal(err)
}

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

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

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

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// For text-and-image input (multimodal), use the gemini-pro-vision model
model := client.GenerativeModel("gemini-pro-vision")

imgData1, err := os.ReadFile(pathToImage1)
if err != nil {
  log.Fatal(err)
}

imgData2, err := os.ReadFile(pathToImage1)
if err != nil {
  log.Fatal(err)
}

prompt := []genai.Part{
  genai.ImageData("jpeg", imgData1),
  genai.ImageData("jpeg", imgData2),
  genai.Text("What's different between these two pictures?"),
}
resp, err := model.GenerateContent(ctx, prompt...)

if err != nil {
  log.Fatal(err)
}

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

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

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

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

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

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

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// For text-only input, use the gemini-pro model
model := client.GenerativeModel("gemini-pro")
// Initialize the chat
cs := model.StartChat()
cs.History = []*genai.Content{
  &genai.Content{
    Parts: []genai.Part{
      genai.Text("Hello, I have 2 dogs in my house."),
    },
    Role: "user",
  },
  &genai.Content{
    Parts: []genai.Part{
      genai.Text("Great to meet you. What would you like to know?"),
    },
    Role: "model",
  },
}

resp, err := cs.SendMessage(ctx, genai.Text("How many paws are in my house?"))
if err != nil {
  log.Fatal(err)
}

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

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

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

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// For text-and-image input (multimodal), use the gemini-pro-vision model
model := client.GenerativeModel("gemini-pro-vision")

imageBytes, err := os.ReadFile(pathToImage)

img := genai.ImageData("jpeg", imageBytes)
prompt := genai.Text("Tell me a story about this animal")
iter := model.GenerateContentStream(ctx, img, prompt)

for {
  resp, err := iter.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }

  // ... print resp
}

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

prompt := genai.Text("Tell me a story about a lumberjack and his giant ox")
iter := model.GenerateContentStream(ctx, prompt)

prompt := genai.Text("And how do you feel about that?")
iter := cs.SendMessageStream(ctx, prompt)

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

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

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

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

משתמשים במודל embedding-001 עם השיטה EmbedContent (או עם השיטה BatchEmbedContent) כדי ליצור הטמעות. הדוגמה הבאה יוצרת הטמעה עבור מחרוזת יחידה:

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()
em := client.EmbeddingModel("embedding-001")
res, err := em.EmbedContent(ctx, genai.Text("The quick brown fox jumps over the lazy dog."))

if err != nil {
  panic(err)
}
fmt.Println(res.Embedding.Values)

הפעלת פונקציה

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

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

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

// For text-only input
text := "Parrots can be green and live a long time."
resp, err := model.CountTokens(ctx, genai.Text(text))
if err != nil {
  log.Fatal(err)
}
fmt.Println(resp.TotalTokens)

// For text-and-image input (multimodal)
text := "Parrots can be green and live a long time."
imageBytes, err := os.ReadFile(pathToImage)
if err != nil {
  log.Fatal(err)
}

resp, err := model.CountTokens(
    ctx,
    genai.Text(text),
    genai.ImageData("png", imageBytes))
  if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.TotalTokens)

אפשרויות לשליטה ביצירת תוכן

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

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

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

// ...

model := client.GenerativeModel("MODEL_NAME")

// Configure model parameters by invoking Set* methods on the model.
model.SetTemperature(0.9)
model.SetTopK(1)

// ...

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

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

כך מגדירים הגדרת בטיחות:

// ...

model := client.GenerativeModel("MODEL_NAME")

model.SafetySettings = []*genai.SafetySetting{
  {
    Category:  genai.HarmCategoryHarassment,
    Threshold: genai.HarmBlockOnlyHigh,
  },
}

// ...

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

// ...

model := client.GenerativeModel("MODEL_NAME")

model.SafetySettings = []*genai.SafetySetting{
  {
    Category:  genai.HarmCategoryHarassment,
    Threshold: genai.HarmBlockOnlyHigh,
  },
  {
    Category:  genai.HarmCategoryHateSpeech,
    Threshold: genai.HarmBlockMediumAndAbove,
  },
}

// ...

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

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

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

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