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


המדריך הזה מדגים איך לגשת ל-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 את חבילת ה-SDK של Go בספריית המודולים:

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()

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

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

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

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

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

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

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

כשהקלט של ההנחיה כולל רק טקסט, צריך להשתמש במודל Gemini 1.5 או במודל Gemini 1.0 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()

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
model := client.GenerativeModel("gemini-1.5-flash")
resp, err := model.GenerateContent(ctx, genai.Text("Write a story about a magic backpack."))
if err != nil {
  log.Fatal(err)
}

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

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

כשהקלט של ההנחיה כולל גם טקסט וגם תמונות, צריך להשתמש במודל Gemini 1.5 עם השיטה 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()

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
model := client.GenerativeModel("gemini-1.5-flash")

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 1.5 או מודל Gemini 1.0 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()

// The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
model := client.GenerativeModel("gemini-1.5-flash")
// 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()

// The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
model := client.GenerativeModel("gemini-1.5-flash")

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 עם ה-method 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()
// For embeddings, use the embedding-001 model
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)

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

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

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

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

// ...

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

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

// ...

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

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

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

// ...

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

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

// ...

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

// ...

// The Gemini 1.5 models are versatile and work with most use cases
model := client.GenerativeModel("gemini-1.5-flash")

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

// ...

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

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

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