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


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

در مورد توکن ها

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

برای مدل های Gemini، یک توکن معادل حدود 4 کاراکتر است. 100 توکن برابر با 60-80 کلمه انگلیسی است.

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

توکن ها را بشمار

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

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

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

  • پس از فراخوانی generate_content از ویژگی usageMetadata روی شی response استفاده کنید.
    این تعداد کل توکن‌ها را هم در ورودی و هم در خروجی برمی‌گرداند: totalTokenCount .
    همچنین تعداد توکن های ورودی و خروجی را به طور جداگانه برمی گرداند: promptTokenCount (توکن های ورودی) و candidatesTokenCount (توکن های خروجی).

شمارش نشانه های متنی

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

گزینه دیگر فراخوانی generateContent و سپس استفاده از ویژگی usageMetadata در شیء response برای دریافت موارد زیر است:

  • تعداد توکن های جداگانه ورودی ( promptTokenCount ) و خروجی ( candidatesTokenCount )
  • تعداد کل توکن ها در ورودی و خروجی ( 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 ) و خروجی ( candidatesTokenCount )
  • تعداد کل توکن ها در ورودی و خروجی ( 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

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

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

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

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

فایل های تصویری

اگر countTokens با ورودی متن و تصویر فراخوانی کنید، تعداد توکن های ترکیبی متن و تصویر را فقط در ورودی ( totalTokens ) برمی گرداند. می توانید این تماس را قبل از تماس با generateContent انجام دهید تا اندازه درخواست های خود را بررسی کنید. همچنین می توانید به صورت اختیاری countTokens روی متن و فایل به طور جداگانه فراخوانی کنید.

گزینه دیگر فراخوانی generateContent و سپس استفاده از ویژگی usageMetadata در شیء response برای دریافت موارد زیر است:

  • تعداد توکن های جداگانه ورودی ( promptTokenCount ) و خروجی ( candidatesTokenCount )
  • تعداد کل توکن ها در ورودی و خروجی ( 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 ) برمی گرداند. می توانید این تماس را قبل از تماس با generateContent انجام دهید تا اندازه درخواست های خود را بررسی کنید. همچنین می توانید به صورت اختیاری countTokens روی متن و فایل به طور جداگانه فراخوانی کنید.

گزینه دیگر فراخوانی generateContent و سپس استفاده از ویژگی usageMetadata در شیء response برای دریافت موارد زیر است:

  • تعداد توکن های جداگانه ورودی ( promptTokenCount ) و خروجی ( candidatesTokenCount )
  • تعداد کل توکن ها در ورودی و خروجی ( 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 را منعکس کند.