תחילת העבודה עם Gemini API באפליקציות אינטרנט

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

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

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

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

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

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

  • (אופציונלי) Node.js
  • דפדפן אינטרנט מודרני

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

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

הגדרת מפתח ה-API

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

קבלת מפתח API

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

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

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

לייבא את ה-SDK ולהפעיל את המודל הגנרטיבי

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

<html>
  <body>
    <!-- ... Your HTML and CSS -->

    <script type="importmap">
      {
        "imports": {
          "@google/generative-ai": "https://esm.run/@google/generative-ai"
        }
      }
    </script>
    <script type="module">
      import { GoogleGenerativeAI } from "@google/generative-ai";

      // Fetch your API_KEY
      const API_KEY = "...";

      // Access your API key (see "Set up your API key" above)
      const genAI = new GoogleGenerativeAI(API_KEY);

      // ...

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

      // ...
    </script>
  </body>
</html>

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

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

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

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

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

כשהקלט של הפרומפט כולל רק טקסט, משתמשים במודל gemini-pro עם השיטה generateContent כדי ליצור פלט טקסט:

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(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 כדי ליצור פלט טקסט:

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(API_KEY);

// Converts a File object to a GoogleGenerativeAI.Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // For text-and-images 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 fileInputEl = document.querySelector("input[type=file]");
  const imageParts = await Promise.all(
    [...fileInputEl.files].map(fileToGenerativePart)
  );

  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.

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(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. בקטע הזה מתוארים כמה תרחישים לדוגמה שעשויים להיחשב למתקדמים יותר.

הפעלת פונקציה

בזכות הקריאה של הפונקציות קל יותר לקבל פלט של נתונים מובְנים ממודלים גנרטיביים. לאחר מכן תוכלו להשתמש בפלטים האלה כדי לקרוא לממשקי 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 });

אפשרויות לשליטה ביצירת תוכן

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

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

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

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