הסבר על אסימונים וספירה שלהם

‫Gemini ומודלים אחרים של AI גנרטיבי מעבדים קלט ופלט ברמת פירוט שנקראת טוקן.

במודלים של Gemini, טוקן שווה בערך ל-4 תווים. ‫100 טוקנים שווים בערך ל-60-80 מילים באנגלית.

מידע על טוקנים

אסימונים יכולים להיות תווים בודדים כמו z או מילים שלמות כמו cat. מילים ארוכות מפוצלות לכמה טוקנים. קבוצת כל האסימונים שבהם נעשה שימוש במודל נקראת אוצר מילים, והתהליך של פיצול טקסט לאסימונים נקרא tokenization.

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


ספירת טוקנים

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

אפשר לספור טוקנים בדרכים הבאות:

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

  • צריך להשתמש במאפיין usageMetadata באובייקט response אחרי הקריאה ל-generate_content.
    הפונקציה מחזירה את המספר הכולל של הטוקנים גם בקלט וגם בפלט: totalTokenCount.‫
    בנוסף, הפונקציה מחזירה את מספר האסימונים של הקלט והפלט בנפרד: promptTokenCount (אסימוני קלט) ו-candidatesTokenCount (אסימוני פלט). אם אתם משתמשים בContext caching, מספר הטוקנים שנשמרו במטמון יהיה ב-cachedContentTokenCount.

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

ספירת טוקנים של טקסט

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

אפשרות נוספת היא להתקשר אל generateContent ואז להשתמש במאפיין usageMetadata באובייקט response כדי לקבל את הפרטים הבאים:

  • מספר הטוקנים הנפרד של הקלט (promptTokenCount), התוכן שנשמר במטמון (cachedContentTokenCount) והפלט (candidatesTokenCount)
  • מספר הטוקנים בתהליך החשיבה (thoughtsTokenCount)
  • המספר הכולל של הטוקנים גם בקלט וגם בפלט (totalTokenCount)
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "The quick brown fox jumps over the lazy dog.";
const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: prompt,
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: prompt,
});
console.log(generateResponse.usageMetadata);
count_tokens.js

ספירת טוקנים של שיחות עם זיכרון

אם מתקשרים אל countTokens עם היסטוריית הצ'אט, הפונקציה מחזירה את המספר הכולל של הטוקנים בטקסט מכל תפקיד בצ'אט (totalTokens).

אפשרות נוספת היא להתקשר אל sendMessage ואז להשתמש במאפיין usageMetadata באובייקט response כדי לקבל את הפרטים הבאים:

  • מספר הטוקנים הנפרד של הקלט (promptTokenCount), התוכן שנשמר במטמון (cachedContentTokenCount) והפלט (candidatesTokenCount)
  • מספר הטוקנים בתהליך החשיבה (thoughtsTokenCount)
  • המספר הכולל של הטוקנים גם בקלט וגם בפלט (totalTokenCount)

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

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
// Initial chat history.
const history = [
  { role: "user", parts: [{ text: "Hi my name is Bob" }] },
  { role: "model", parts: [{ text: "Hi Bob!" }] },
];
const chat = ai.chats.create({
  model: "gemini-2.0-flash",
  history: history,
});

// Count tokens for the current chat history.
const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: chat.getHistory(),
});
console.log(countTokensResponse.totalTokens);

const chatResponse = await chat.sendMessage({
  message: "In one sentence, explain how a computer works to a young child.",
});
console.log(chatResponse.usageMetadata);

// Add an extra user message to the history.
const extraMessage = {
  role: "user",
  parts: [{ text: "What is the meaning of life?" }],
};
const combinedHistory = chat.getHistory();
combinedHistory.push(extraMessage);
const combinedCountTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: combinedHistory,
});
console.log(
  "Combined history token count:",
  combinedCountTokensResponse.totalTokens,
);
count_tokens.js

ספירת טוקנים של multimodal

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

  • עם Gemini 2.0, תמונות קלט ששני הממדים שלהן הם ‎ <=384 פיקסלים נספרות כ-258 טוקנים. תמונות Google שגדולות יותר באחד מהממדים או בשניהם נחתכות ומשתנות בהתאם לצורך לאריחים בגודל 768x768 פיקסלים, וכל אחת מהן נספרת כ-258 טוקנים. לפני Gemini 2.0, תמונות השתמשו ב-258 טוקנים קבועים.

  • קבצים של וידאו ואודיו מומרים לטוקנים בשיעורים הקבועים הבאים: וידאו ב-263 טוקנים לשנייה ואודיו ב-32 טוקנים לשנייה.

רזולוציות של מדיה

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

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

קובצי תמונות

אם מתקשרים אל countTokens עם קלט של טקסט ותמונה, הפונקציה מחזירה את מספר הטוקנים המשולב של הטקסט והתמונה בקלט בלבד (totalTokens). אפשר להתקשר אל הפונקציה הזו לפני שמתקשרים אל generateContent כדי לבדוק את גודל הבקשות. אפשר גם לקרוא ל-countTokens על הטקסט ועל הקובץ בנפרד.

אפשרות נוספת היא להתקשר אל generateContent ואז להשתמש במאפיין usageMetadata באובייקט response כדי לקבל את הפרטים הבאים:

  • מספר הטוקנים הנפרד של הקלט (promptTokenCount), התוכן שנשמר במטמון (cachedContentTokenCount) והפלט (candidatesTokenCount)
  • מספר הטוקנים בתהליך החשיבה (thoughtsTokenCount)
  • המספר הכולל של הטוקנים גם בקלט וגם בפלט (totalTokenCount)

דוגמה לשימוש בתמונה שהועלתה מ-File API:

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Tell me about this image";
const organ = await ai.files.upload({
  file: path.join(media, "organ.jpg"),
  config: { mimeType: "image/jpeg" },
});

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(organ.uri, organ.mimeType),
  ]),
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(organ.uri, organ.mimeType),
  ]),
});
console.log(generateResponse.usageMetadata);
count_tokens.js

דוגמה שמציגה את התמונה כנתונים מוטבעים:

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Tell me about this image";
const imageBuffer = fs.readFileSync(path.join(media, "organ.jpg"));

// Convert buffer to base64 string.
const imageBase64 = imageBuffer.toString("base64");

// Build contents using createUserContent and createPartFromBase64.
const contents = createUserContent([
  prompt,
  createPartFromBase64(imageBase64, "image/jpeg"),
]);

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: contents,
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: contents,
});
console.log(generateResponse.usageMetadata);
count_tokens.js

קובצי וידאו או אודיו

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

  • סרטון: 263 טוקנים לשנייה
  • אודיו: 32 טוקנים לשנייה

אם מתקשרים אל countTokens עם קלט של טקסט וסרטון או אודיו, המודל מחזיר את מספר הטוקנים המשולב של הטקסט ושל קובץ הווידאו או האודיו בקלט בלבד (totalTokens). אפשר להתקשר אל countTokens לפני שמתקשרים אל generateContent כדי לבדוק את גודל הבקשות. אפשר גם להפעיל את countTokens על הטקסט ועל הקובץ בנפרד.

אפשרות נוספת היא להתקשר אל generateContent ואז להשתמש במאפיין usageMetadata באובייקט response כדי לקבל את הפרטים הבאים:

  • מספר הטוקנים הנפרד של הקלט (promptTokenCount), התוכן שנשמר במטמון (cachedContentTokenCount) והפלט (candidatesTokenCount)
  • מספר הטוקנים בתהליך החשיבה (thoughtsTokenCount)
  • המספר הכולל של הטוקנים גם בקלט וגם בפלט (totalTokenCount)
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Tell me about this video";
let videoFile = await ai.files.upload({
  file: path.join(media, "Big_Buck_Bunny.mp4"),
  config: { mimeType: "video/mp4" },
});

// Poll until the video file is completely processed (state becomes ACTIVE).
while (!videoFile.state || videoFile.state.toString() !== "ACTIVE") {
  console.log("Processing video...");
  console.log("File state: ", videoFile.state);
  await sleep(5000);
  videoFile = await ai.files.get({ name: videoFile.name });
}

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(videoFile.uri, videoFile.mimeType),
  ]),
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(videoFile.uri, videoFile.mimeType),
  ]),
});
console.log(generateResponse.usageMetadata);
count_tokens.js

הוראות וכלים של המערכת

ההוראות והכלים של המערכת נספרים גם הם בספירת הטוקנים הכוללת של הקלט.

אם משתמשים בהוראות מערכת, המספר של totalTokens גדל כדי לשקף את ההוספה של systemInstruction.

אם משתמשים בהפעלת פונקציות, הערך של totalTokens גדל כדי לשקף את ההוספה של tools.