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


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

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

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

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

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

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

  • מעבר לגרסה 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 שמשויכות לתוכן ב- call:

  • 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. בקטע הזה מתוארים כמה תרחישים לדוגמה שעשויים להיחשב למתקדמים יותר.

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

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