فهم الرموز المميّزة وعدّها

تعالج نماذج Gemini وغيرها من نماذج الذكاء الاصطناعي التوليدي المدخلات والمخرجات بدقة تُعرف باسم الرمز المميز.

في نماذج Gemini، يعادل الرمز المميز حوالي 4 أحرف. يساوي 100 رمز مميز حوالي 60 إلى 80 كلمة باللغة الإنجليزية.

لمحة عن الرموز المميزة

يمكن أن تكون الرموز المميزة أحرفًا مفردة مثل z أو كلمات كاملة مثل cat. يتم تقسيم الكلمات الطويلة إلى عدة رموز مميزة. تُعرف مجموعة الرموز المميزة التي يستخدمها النموذج باسم المفردات، وتُعرف عملية تقسيم النص إلى رموز مميزة باسم التقطيع إلى رموز مميزة.

عند تفعيل الفوترة، يتم تحديد تكلفة طلب البيانات من Gemini API جزئيًا من خلال عدد الرموز المميزة للإدخال والإخراج، لذا قد يكون من المفيد معرفة كيفية عدّ الرموز المميزة.

احتساب الرموز المميّزة

يتم تقسيم جميع المدخلات والمخرجات من Gemini API إلى رموز مميزة، بما في ذلك النصوص وملفات الصور وغيرها من الوسائط غير النصية.

يمكنك احتساب الرموز المميزة بالطرق التالية:

اتّصِل بالرقم countTokens مع إدخال طلبك.
تعرض هذه السمة إجمالي عدد الرموز المميزة في الإدخال فقط. يمكنك إجراء هذه المكالمة قبل إرسال الإدخال إلى النموذج للتحقّق من حجم طلباتك.
استخدِم السمة usageMetadata على العنصر response بعد استدعاء generate_content.
تعرض هذه السمة إجمالي عدد الرموز المميزة في كل من الإدخال والإخراج: totalTokenCount.
تعرض أيضًا عدد الرموز المميّزة لكل من الطلب والرد بشكل منفصل: promptTokenCount (رموز الطلب) وcandidatesTokenCount (رموز الرد). وفي حال استخدام التخزين المؤقت للسياق، سيظهر عدد الرموز المميزة المخزّنة مؤقتًا في cachedContentTokenCount.

إذا كنت تستخدم نموذجًا للتفكير مثل النماذج 2.5، سيتم عرض الرموز المميزة المستخدَمة أثناء عملية التفكير في 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

عدّ الرموز المميّزة المتعددة الوسائط

يتم تقسيم جميع المدخلات إلى رموز مميزة في Gemini API، بما في ذلك النصوص وملفات الصور وغيرها من الوسائط غير النصية. في ما يلي النقاط الرئيسية العالية المستوى حول تقسيم الإدخال المتعدّد الوسائط إلى رموز مميزة أثناء معالجته بواسطة Gemini API:

باستخدام Gemini 2.0، يتم احتساب مدخلات الصور التي يقل فيها كلا البُعدين عن 384 بكسل أو يساويهما على أنّها 258 رمزًا مميزًا. يتم اقتصاص الصور الأكبر في أحد البُعدَين أو كليهما وتغيير حجمها حسب الحاجة إلى مربّعات بحجم 768 × 768 بكسل، ويتم احتساب كل مربّع على أنّه 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). يمكنك إجراء هذا الطلب قبل طلب 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.