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

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

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

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

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

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

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

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

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

اتصل برقم countTokens مع إدخال الطلب.
تعرض هذه الدالة إجمالي عدد الرموز في الإدخال فقط. يمكنك إجراء هذا الطلب قبل إرسال الإدخال إلى النموذج للتحقّق من حجم طلباتك.
استخدِم السمة usageMetadata على عنصر response بعد استدعاء generate_content.
تعرض هذه الدالة إجمالي عدد الرموز المميّزة في كلّ من الإدخال والإخراج: 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 رمزًا. يتم اقتصاص الصور الأكبر حجمًا في أحد الأبعاد أو كليهما وتعديل حجمها كما هو مطلوب لتصبح مربّعات بحجم 768 × 768 بكسل، ويتم احتساب كل منها على أنّه 258 رمزًا. قبل الإصدار Gemini 2.0، كانت الصور تستخدم 258 رمزًا ثابتًا.
يتم تحويل ملفات الفيديو والصوت إلى وحدات ترميز بمعدّلات ثابتة كما يلي: يتم تحويل الفيديو بمعدّل 263 رمزًا في الثانية والصوت بمعدّل 32 رمزًا في الثانية.

ملفات الصور

في حال استدعاء 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 باستخدام إدخال نصي وفيديو/صوت، سيعرض 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.