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


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

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

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

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

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

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

  • Node.js גרסה 18 ואילך
  • NPM

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

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

הגדרה של מפתח API

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

קבלת מפתח API

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

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

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

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

כדי להשתמש ב-Gemini API באפליקציה שלכם, אתם צריכים להתקין את החבילה GoogleGenerativeAI ל-Node.js:

npm install @google/generative-ai

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

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

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// ...

// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

// ...

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

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

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

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

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

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

כשהקלט של ההנחיה כולל רק טקסט, משתמשים במודל Gemini 1.5 עם generateContent כדי ליצור פלט טקסט:

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

async function run() {
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

  const prompt = "Write a story about a magic backpack."

  const result = await model.generateContent(prompt);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

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

Gemini 1.5 Flash ו-Pro 1.5 Pro יכולים להתמודד עם קלט רב-אופני, כך שתוכלו להזין גם טקסט וגם תמונות. חשוב לבדוק את הדרישות לתמונות של הנחיות.

כשהקלט של ההנחיה כולל גם טקסט וגם תמונות, צריך להשתמש במודלים של Gemini 1.5 עם השיטה generateContent כדי ליצור פלט טקסט:

const { GoogleGenerativeAI } = require("@google/generative-ai");
const fs = require("fs");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// Converts local file information to a GoogleGenerativeAI.Part object.
function fileToGenerativePart(path, mimeType) {
  return {
    inlineData: {
      data: Buffer.from(fs.readFileSync(path)).toString("base64"),
      mimeType
    },
  };
}

async function run() {
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

  const prompt = "What's different between these pictures?";

  const imageParts = [
    fileToGenerativePart("image1.png", "image/png"),
    fileToGenerativePart("image2.jpeg", "image/jpeg"),
  ];

  const result = await model.generateContent([prompt, ...imageParts]);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

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

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

כדי ליצור שיחה במספר תורות (כמו צ'אט), צריך להשתמש במודל Gemini 1.5 או מודל Gemini 1.0 Pro, ולהתחיל את השיחה דרך startChat(). לאחר מכן משתמשים ב-sendMessage() כדי לשלוח הודעה חדשה למשתמש, והפעולה הזו תגרום גם לצירוף של ההודעה ושל התשובה להיסטוריית הצ'אט.

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

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

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

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

async function run() {
  // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

  const chat = model.startChat({
    history: [
      {
        role: "user",
        parts: [{ text: "Hello, I have 2 dogs in my house." }],
      },
      {
        role: "model",
        parts: [{ text: "Great to meet you. What would you like to know?" }],
      },
    ],
    generationConfig: {
      maxOutputTokens: 100,
    },
  });

  const msg = "How many paws are in my house?";

  const result = await chat.sendMessage(msg);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

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

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

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

//...

const result = await model.generateContentStream([prompt, ...imageParts]);

let text = '';
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  console.log(chunkText);
  text += chunkText;
}

//...

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

// Use streaming with text-only input
const result = await model.generateContentStream(prompt);

ראו דוגמה לצ'אט למעלה כדי ללמוד איך ליצור chat.

// Use streaming with multi-turn conversations (like chat)
const result = await chat.sendMessageStream(msg);

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

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

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

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

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

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

async function run() {
  // For embeddings, use the embedding-001 model
  const model = genAI.getGenerativeModel({ model: "embedding-001"});

  const text = "The quick brown fox jumps over the lazy dog."

  const result = await model.embedContent(text);
  const embedding = result.embedding;
  console.log(embedding.values);
}

run();

שליחת פונקציות

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

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

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

// For text-only input
const { totalTokens } = await model.countTokens(prompt);

// For text-and-image input (multimodal)
const { totalTokens } = await model.countTokens([prompt, ...imageParts]);

// For multi-turn conversations (like chat)
const history = await chat.getHistory();
const msgContent = { role: "user", parts: [{ text: msg }] };
const contents = [...history, msgContent];
const { totalTokens } = await model.countTokens({ contents });

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

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

שימו לב שהעברה של generationConfig או safetySettings ל-method של בקשה למודל (כמו generateContent) תבטל באופן מלא את אובייקט ההגדרה עם אותו שם שמועבר ב-getGenerativeModel.

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

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

const generationConfig = {
  stopSequences: ["red"],
  maxOutputTokens: 200,
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
};

// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash",  generationConfig });

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

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

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

import { HarmBlockThreshold, HarmCategory } from "@google/generative-ai";

// ...

const safetySettings = [
  {
    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
    threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
  },
];

// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash", safetySettings });

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

const safetySettings = [
  {
    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
    threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
  },
  {
    category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
    threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
  },
];

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

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

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