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


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

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

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

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

המדריך הזה מניח שאתם מכירים היטב את פיתוח אפליקציות עם 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 שמשויכות לתוכן ב- call:

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

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

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