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


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

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

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

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

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

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

  • (אופציונלי) 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 = "...";
      // Reminder: This should only be for local testing

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

      // ...

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

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

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

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

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

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

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

כשהקלט של ההנחיה כולל רק טקסט, צריך להשתמש במודל Gemini 1.5 או מודל Gemini 1.0 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() {
  // 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 יש כמה מודלים שיכולים לטפל בקלט מרובה מצבים (מודלים של Gemini 1.5) כך שאפשר להזין גם טקסט משני ותמונות. חשוב לבדוק את דרישות לגבי תמונות בהנחיות.

כשהקלט של ההנחיה כולל גם טקסט וגם תמונות, צריך להשתמש במודל Gemini 1.5 עם השיטה 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() {
  // 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 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 1.5 או מודל Gemini 1.0 Pro ומפעילים את הצ'אט בהתקשרות אל startChat(). אחר כך צריך להשתמש בתוסף sendMessage() כדי לשלוח הודעה חדשה למשתמש, והיא גם תצרף את הקוד את ההודעה ואת התשובה להיסטוריית הצ'אט.

יש שתי אפשרויות אפשריות עבור role שמשויכות לתוכן ב- call:

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

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

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

// 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