תחילת העבודה עם Gemini API ביישומי Node.js

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

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

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

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

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

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

  • Node.js v18+
  • נשימות בדקה

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

לפני שמפעילים את 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);

// ...

const model = genAI.getGenerativeModel({ model: "MODEL_NAME"});

// ...

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

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

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

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

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

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

כשהקלט של הפרומפט כולל רק טקסט, משתמשים במודל gemini-pro עם השיטה 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() {
  // For text-only input, use the gemini-pro model
  const model = genAI.getGenerativeModel({ model: "gemini-pro"});

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

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

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

כשקלט הפרומפט כולל גם טקסט וגם תמונות, משתמשים במודל gemini-pro-vision עם השיטה 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() {
  // For text-and-image input (multimodal), use the gemini-pro-vision model
  const model = genAI.getGenerativeModel({ model: "gemini-pro-vision" });

  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-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() {
  // For text-only input, use the gemini-pro model
  const model = genAI.getGenerativeModel({ model: "gemini-pro"});

  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 עם השיטה 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();

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

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

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

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

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

const model = genAI.getGenerativeModel({ model: "MODEL_NAME",  generationConfig });

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

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

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

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

// ...

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

const model = genAI.getGenerativeModel({ model: "MODEL_NAME", 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 יש כמה וריאציות של מודלים כדי לענות על הצרכים בתרחישי שימוש שונים, כמו סוגי קלט ומורכבות, הטמעות בצ'אט או במשימות שפה אחרות בדיאלוג ומגבלות גודל. מידע נוסף על הדגמים הזמינים של Gemini.

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