توکن ها را بفهمید و بشمارید

Gemini و دیگر مدل‌های هوش مصنوعی مولد، ورودی و خروجی را با جزئیاتی به نام توکن پردازش می‌کنند.

برای مدل‌های Gemini، یک توکن معادل حدود ۴ کاراکتر است. ۱۰۰ توکن معادل حدود ۶۰ تا ۸۰ کلمه انگلیسی است.

درباره توکن‌ها

توکن‌ها می‌توانند کاراکترهای تکی مانند z یا کلمات کاملی مانند cat باشند. کلمات طولانی به چندین توکن تقسیم می‌شوند. مجموعه تمام توکن‌های مورد استفاده توسط مدل، واژگان نامیده می‌شود و فرآیند تقسیم متن به توکن‌ها، توکن‌سازی نامیده می‌شود.

وقتی صورتحساب فعال باشد، هزینه تماس با API جمینی تا حدودی توسط تعداد توکن‌های ورودی و خروجی تعیین می‌شود، بنابراین دانستن نحوه شمارش توکن‌ها می‌تواند مفید باشد.

پایتون جاوا اسکریپت گو

تعداد توکن‌ها

تمام ورودی‌ها و خروجی‌های API جمینی، از جمله متن، فایل‌های تصویری و سایر موارد غیرمتنی، توکن‌سازی شده‌اند.

شما می‌توانید توکن‌ها را به روش‌های زیر بشمارید:

• تابع countTokens با ورودی درخواست فراخوانی کنید.
  این فقط تعداد کل توکن‌های موجود در ورودی را برمی‌گرداند. می‌توانید قبل از ارسال ورودی به مدل، این فراخوانی را انجام دهید تا اندازه درخواست‌های خود را بررسی کنید.

• از ویژگی usageMetadata روی شیء response پس از فراخوانی generate_content استفاده کنید.
  این تابع تعداد کل توکن‌ها را هم در ورودی و هم در خروجی برمی‌گرداند: totalTokenCount .
  همچنین تعداد توکن‌های ورودی و خروجی را به صورت جداگانه برمی‌گرداند: promptTokenCount (توکن‌های ورودی) و candidatesTokenCount (توکن‌های خروجی). و اگر از Context caching استفاده می‌کنید، تعداد توکن‌های ذخیره شده در cachedContentTokenCount قرار خواهد گرفت.

  اگر از یک مدل تفکر مانند مدل‌های ۲.۵ استفاده می‌کنید، توکن مورد استفاده در طول فرآیند تفکر در thoughtsTokenCount بازگردانده می‌شود.

شمارش توکن‌های متنی

اگر تابع countTokens با ورودی فقط متنی فراخوانی کنید، تعداد توکن‌های متن موجود در ورودی ( totalTokens ) را برمی‌گرداند. می‌توانید این فراخوانی را قبل از فراخوانی 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

شمارش توکن‌های چندوجهی

تمام ورودی‌های API مربوط به Gemini، شامل متن، فایل‌های تصویری و سایر داده‌های غیرمتنی، توکنیزه می‌شوند. به نکات کلیدی سطح بالای زیر در مورد توکنیزه کردن ورودی‌های چندوجهی در طول پردازش توسط API Gemini توجه کنید:

• با Gemini 2.0، ورودی‌های تصویر با هر دو بعد <=384 پیکسل، به عنوان 258 توکن شمارش می‌شوند. تصاویر بزرگتر در یک یا هر دو بعد، در صورت نیاز برش داده شده و به کاشی‌های 768x768 پیکسلی مقیاس‌بندی می‌شوند که هر کدام 258 توکن شمارش می‌شوند. قبل از Gemini 2.0، تصاویر از 258 توکن ثابت استفاده می‌کردند.

• فایل‌های ویدیویی و صوتی با نرخ‌های ثابت زیر به توکن تبدیل می‌شوند: ویدیو با سرعت ۲۶۳ توکن در ثانیه و صدا با سرعت ۳۲ توکن در ثانیه.

قطعنامه‌های رسانه‌ای

پیش‌نمایش 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

فایل‌های ویدیویی یا صوتی

صدا و تصویر هر کدام با نرخ‌های ثابت زیر به توکن تبدیل می‌شوند:

• ویدیو: ۲۶۳ توکن در ثانیه
• صدا: ۳۲ توکن در ثانیه

اگر تابع countTokens با ورودی متن و ویدیو/صوت فراخوانی کنید، تعداد توکن‌های ترکیبی متن و فایل ویدیویی/صوتی فقط در ورودی ( totalTokens ) را برمی‌گرداند. می‌توانید این فراخوانی را قبل از فراخوانی 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 باشد.