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

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

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

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

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

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

يمكنك تجربة احتساب الرموز المميزة في Colab.

عرض على ai.google.dev تجربة ورقة ملاحظات Colab عرض ورقة الملاحظات على GitHub

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

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

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

  • استدعِ الدالة count_tokens مع إدخال الطلب.
    تعرض هذه الدالة إجمالي عدد الرموز المميزة في الإدخال فقط. يمكنك إجراء هذه المكالمة قبل إرسال الإدخال إلى النموذج للتحقّق من حجم طلباتك.

  • استخدِم السمة usage_metadata على العنصر response بعد استدعاء generate_content.
    تعرض هذه الدالة إجمالي عدد الرموز المميزة في كلّ من الإدخال والإخراج: total_token_count.
    تعرض هذه السمة أيضًا عدد الرموز المميّزة لكل من الطلب والرد بشكل منفصل: prompt_token_count (الرموز المميّزة للطلب) وcandidates_token_count (الرموز المميّزة للرد).

    إذا كنت تستخدم نموذجًا للتفكير، يتم عرض الرموز المميزة المستخدَمة أثناء عملية التفكير في thoughts_token_count. وفي حال استخدام التخزين المؤقت للسياق، سيكون عدد الرموز المميزة المخزّنة مؤقتًا في cached_content_token_count.

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

إذا استدعيت الدالة count_tokens باستخدام إدخال نصي فقط، ستعرض عدد الرموز المميّزة للنص في الإدخال فقط (total_tokens). يمكنك إجراء هذا الاستدعاء قبل استدعاء الدالة generate_content للتحقّق من حجم طلباتك.

هناك خيار آخر وهو الاتصال بـ generate_content ثم استخدام السمة usage_metadata في الكائن response للحصول على ما يلي:

  • عدد الرموز المميزة المنفصلة لكل من الإدخال (prompt_token_count) والمحتوى المخزّن مؤقتًا (cached_content_token_count) والإخراج (candidates_token_count)
  • عدد الرموز المميّزة لعملية التفكير (thoughts_token_count)
  • إجمالي عدد الرموز المميّزة في كل من الطلب والرد (total_token_count)

Python

from google import genai

client = genai.Client()
prompt = "The quick brown fox jumps over the lazy dog."

total_tokens = client.models.count_tokens(
    model="gemini-3.6-flash", contents=prompt
)
print("total_tokens: ", total_tokens)

response = client.models.generate_content(
    model="gemini-3.6-flash", contents=prompt
)

print(response.usage_metadata)

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";

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

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

await main();

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)

// Convert prompt to a slice of *genai.Content using the helper.
contents := []*genai.Content{
  genai.NewContentFromText(prompt, genai.RoleUser),
}
countResp, err := client.Models.CountTokens(ctx, "gemini-3.6-flash", contents, nil)
if err != nil {
  return err
}
fmt.Println("total_tokens:", countResp.TotalTokens)

response, err := client.Models.GenerateContent(ctx, "gemini-3.6-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println(string(usageMetadata))
    ```

احتساب الرموز المميزة للمحادثات المترابطة

إذا طلبت من count_tokens عرض سجلّ المحادثة، سيعرض إجمالي عدد الرموز المميزة للنص من كل دور في المحادثة (total_tokens).

هناك خيار آخر وهو الاتصال بـ send_message ثم استخدام السمة usage_metadata في الكائن response للحصول على ما يلي:

  • عدد الرموز المميزة المنفصلة للإدخال (prompt_token_count) والمحتوى المخزّن مؤقتًا (cached_content_token_count) والناتج (candidates_token_count)
  • عدد الرموز المميّزة لعملية التفكير (thoughts_token_count)
  • إجمالي عدد الرموز المميّزة في كل من الطلب والرد (total_token_count)

لمعرفة حجم الدور التالي في المحادثة، عليك إلحاقه بالسجلّ عند طلب count_tokens.

Python

from google import genai
from google.genai import types

client = genai.Client()

chat = client.chats.create(
    model="gemini-3.6-flash",
    history=[
        types.Content(
            role="user", parts=[types.Part(text="Hi my name is Bob")]
        ),
        types.Content(role="model", parts=[types.Part(text="Hi Bob!")]),
    ],
)

print(
    client.models.count_tokens(
        model="gemini-3.6-flash", contents=chat.get_history()
    )
)

response = chat.send_message(
    message="In one sentence, explain how a computer works to a young child."
)
print(response.usage_metadata)

extra = types.UserContent(
    parts=[
        types.Part(
            text="What is the meaning of life?",
        )
    ]
)
history = [*chat.get_history(), extra]
print(client.models.count_tokens(model="gemini-3.6-flash", contents=history))

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function main() {
  const history = [
    { role: "user", parts: [{ text: "Hi my name is Bob" }] },
    { role: "model", parts: [{ text: "Hi Bob!" }] },
  ];
  const chat = ai.chats.create({
    model: "gemini-3.6-flash",
    history: history,
  });

  const countTokensResponse = await ai.models.countTokens({
    model: "gemini-3.6-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);

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

await main();

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)

history := []*genai.Content{
  {Role: genai.RoleUser, Parts: []*genai.Part({Text: "Hi my name is Bob"})},
  {Role: genai.RoleModel, Parts: []*genai.Part({Text: "Hi Bob!"})},
}
chat, err := client.Chats.Create(ctx, "gemini-3.6-flash", nil, history)
if err != nil {
  log.Fatal(err)
}

firstTokenResp, err := client.Models.CountTokens(ctx, "gemini-3.6-flash", chat.History(false), nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println(firstTokenResp.TotalTokens)

resp, err := chat.SendMessage(ctx, genai.NewPartFromText("In one sentence, explain how a computer works to a young child."))
if err != nil {
  log.Fatal(err)
}
fmt.Printf("%#v\n", resp.UsageMetadata)

extra := genai.NewContentFromText("What is the meaning of life?", genai.RoleUser)
hist := chat.History(false)
hist = append(hist, extra)

secondTokenResp, err := client.Models.CountTokens(ctx, "gemini-3.6-flash", hist, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println(secondTokenResp.TotalTokens)

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

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

  • يتم احتساب مدخلات الصور التي يقل فيها كلا البُعدين عن 384 بكسل أو يساويهما على أنّها 258 رمزًا مميزًا. يتم اقتصاص الصور التي تكون أكبر في أحد البُعدَين أو كليهما وتغيير حجمها حسب الحاجة إلى مربّعات بحجم 768 × 768 بكسل، ويتم احتساب كل مربّع على أنّه 258 رمزًا مميزًا.

  • يتم تحويل ملفات الفيديو والصوت إلى رموز مميزة بالأسعار الثابتة التالية: الفيديو: 263 رمزًا مميزًا في الثانية، والصوت: 32 رمزًا مميزًا في الثانية.

درجات دقة الوسائط

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

لمزيد من التفاصيل حول المَعلمة وكيفية تأثيرها في احتساب الرموز المميّزة، راجِع دليل دقة الوسائط.

ملفات الصور

إذا طلبت count_tokens باستخدام نص وصورة كمدخلات، سيعرض عدد الرموز المميزة المجمّعة للنص والصورة في المدخلات فقط (total_tokens). يمكنك إجراء هذا الطلب قبل طلب generate_content للتحقّق من حجم طلباتك. يمكنك أيضًا استدعاء count_tokens بشكل اختياري على النص والملف بشكل منفصل.

هناك خيار آخر وهو الاتصال بـ generate_content ثم استخدام السمة usage_metadata في الكائن response للحصول على ما يلي:

  • عدد الرموز المميزة المنفصلة لكل من الإدخال (prompt_token_count) والمحتوى المخزّن مؤقتًا (cached_content_token_count) والإخراج (candidates_token_count)
  • عدد الرموز المميّزة لعملية التفكير (thoughts_token_count)
  • إجمالي عدد الرموز المميّزة في كل من الطلب والرد (total_token_count)

مثال يستخدم صورة تم تحميلها من File API:

Python

from google import genai

client = genai.Client()
prompt = "Tell me about this image"
your_image_file = client.files.upload(file=media / "organ.jpg")

print(
    client.models.count_tokens(
        model="gemini-3.6-flash", contents=[prompt, your_image_file]
    )
)

response = client.models.generate_content(
    model="gemini-3.6-flash", contents=[prompt, your_image_file]
)
print(response.usage_metadata)

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const prompt = "Tell me about this image";

async function main() {
  const organ = await ai.files.upload({
    file: path.join(media, "organ.jpg"),
    config: { mimeType: "image/jpeg" },
  });

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

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

await main();

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)

file, err := client.Files.UploadFromPath(
  ctx, 
  filepath.Join(getMedia(), "organ.jpg&q&uot;), 
  genai.UploadFileConfig{
    MIMEType : "image/jpeg",
  },
)
if err != nil {
  log.Fatal(err)
}
parts := []*genai.Part{
  genai.NewPartFromText("Tell me about this image"),
  genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
  genai.NewContentFromParts(parts, genai.RoleUser),
}

tokenResp, err := client.Models.CountTokens(ctx, "gemini-3.6-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Multimodal image token count:", tokenResp.TotalTokens)

response, err := client.Models.GenerateContent(ctx, "gemini-3.6-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println(string(usageMetadata))

مثال يقدّم الصورة كبيانات مضمّنة:

Python

from google import genai
import PIL.Image

client = genai.Client()
prompt = "Tell me about this image"
your_image_file = PIL.Image.open(media / "organ.jpg")

print(
    client.models.count_tokens(
        model="gemini-3.6-flash", contents=[prompt, your_image_file]
    )
)

response = client.models.generate_content(
    model="gemini-3.6-flash", contents=[prompt, your_image_file]
)
print(response.usage_metadata)

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const prompt = "Tell me about this image";
const imageBuffer = fs.readFileSync(path.join(media, "organ.jpg"));

const imageBase64 = imageBuffer.toString("base64");

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

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

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

await main();

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)

imageBytes, err := os.ReadFile("organ.jpg")
if err != nil {
    log.Fatalf("Failed to read image file: %v", err)
}
parts := []*genai.Part{
  genai.NewPartFromText("Tell me about this image&qu&ot;),
  {
        InlineData: genai.Blob{
              MIMEType: "image/jpeg",
              Data:     imageBytes,
        },
  },
}
contents := []*genai.Content{
  genai.NewContentFromParts(parts, genai.RoleUser),
}

tokenResp, err := client.Models.CountTokens(ctx, "gemini-3.6-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Multimodal image token count:", tokenResp.TotalTokens)

response, err := client.Models.GenerateContent(ctx, "gemini-3.6-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println(string(usageMetadata))

ملفات الفيديو أو الصوت

يتم تحويل كل من الصوت والفيديو إلى رموز مميزة بالأسعار الثابتة التالية:

  • الفيديو: 263 رمزًا مميزًا في الثانية
  • الصوت: 32 رمزًا مميزًا في الثانية

إذا أجريت طلبًا إلى count_tokens باستخدام إدخال نصي ومرئي/صوتي، سيعرض عدد الرموز المميزة المجمّع للنص وملف الفيديو/الصوت في الإدخال فقط (total_tokens). يمكنك إجراء هذا الطلب قبل طلب generate_content للتحقّق من حجم طلباتك. يمكنك أيضًا اختياريًا استدعاء count_tokens على النص والملف بشكل منفصل.

هناك خيار آخر وهو الاتصال بـ generate_content ثم استخدام السمة usage_metadata في الكائن response للحصول على ما يلي:

  • عدد الرموز المميزة المنفصلة لكل من الإدخال (prompt_token_count) والمحتوى المخزّن مؤقتًا (cached_content_token_count) والإخراج (candidates_token_count)
  • عدد الرموز المميّزة لعملية التفكير (thoughts_token_count)
  • إجمالي عدد الرموز المميّزة في كلّ من الطلب والرد (total_token_count)

Python

from google import genai
import time

client = genai.Client()
prompt = "Tell me about this video"
your_file = client.files.upload(file=media / "Big_Buck_Bunny.mp4")

while not your_file.state or your_file.state.name != "ACTIVE":
    print("Processing video...")
    print("File state:", your_file.state)
    time.sleep(5)
    your_file = client.files.get(name=your_file.name)

print(
    client.models.count_tokens(
        model="gemini-3.6-flash", contents=[prompt, your_file]
    )
)

response = client.models.generate_content(
    model="gemini-3.6-flash", contents=[prompt, your_file]
)
print(response.usage_metadata)

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const prompt = "Tell me about this video";

async function main() {
  let videoFile = await ai.files.upload({
    file: path.join(media, "Big_Buck_Bunny.mp4"),
    config: { mimeType: "video/mp4" },
  });

  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-3.6-flash",
    contents: createUserContent([
      prompt,
      createPartFromUri(videoFile.uri, videoFile.mimeType),
    ]),
  });
  console.log(countTokensResponse.totalTokens);

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

await main();

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)

file, err := client.Files.UploadFromPath(
  ctx,
  filepath.Join(getMedia(), "Big_Buck_Bunny.mp4&"),
  genai.UploadFileConfig{
    MIMEType : "video/mp4",
  },
)
if err != nil {
  log.Fatal(err)
}

for file.State == genai.FileStateUnspecified || file.State != genai.FileStateActive {
  fmt.Println("Processing video...")
  fmt.Println("File state:", file.State)
  time.Sleep(5 * time.Second)

  file, err = client.Files.Get(ctx, file.Name, nil)
  if err != nil {
    log.Fatal(err)
  }
}

parts := []*genai.Part{
  genai.NewPartFromText("Tell me about this video"),
  genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
  genai.NewContentFromParts(parts, genai.RoleUser),
}

tokenResp, err := client.Models.CountTokens(ctx, "gemini-3.6-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Multimodal video/audio token count:", tokenResp.TotalTokens)
response, err := client.Models.GenerateContent(ctx, "gemini-3.6-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println(string(usageMetadata))

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

عند تفعيل ميزة "التفكير"، يكون سعر الردّ هو مجموع الرموز المميزة للناتج ورموز التفكير المميزة. يمكنك استرداد إجمالي عدد الرموز المميزة التي تم إنشاؤها من الحقل thoughtsTokenCount (أو ما يعادله في حزمة تطوير البرامج (SDK)).

Python

# ...
print("Thoughts tokens:", response.usage_metadata.thoughts_token_count)
print("Output tokens:", response.usage_metadata.candidates_token_count)

JavaScript

// ...
console.log(`Thoughts tokens: ${response.usageMetadata.thoughtsTokenCount}`);
console.log(`Output tokens: ${response.usageMetadata.candidatesTokenCount}`);

Go

// ...
fmt.Println("Thoughts tokens:", response.UsageMetadata.ThoughtsTokenCount)
fmt.Println("Output tokens:", response.UsageMetadata.CandidatesTokenCount)

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

يمكنك الاطّلاع على مزيد من المعلومات حول كيفية ضبط "التفكير" في دليل تفكير Gemini.

قدرات الاستيعاب

تتضمّن النماذج المتوفّرة من خلال Gemini API قدرات استيعاب يتم قياسها بالرموز المميّزة. تحدّد قدرة الاستيعاب حجم الإدخال الذي يمكنك تقديمه وحجم الإخراج الذي يمكن للنموذج إنشاؤه. يمكنك تحديد حجم قدرة الاستيعاب من خلال استدعاء نقطة النهاية models.get أو الرجوع إلى مستندات النماذج.

Python

from google import genai

client = genai.Client()
model_info = client.models.get(model="gemini-3.6-flash")
print(f"{model_info.input_token_limit=}")
print(f"{model_info.output_token_limit=}")

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function main() {
  const modelInfo = await ai.models.get({model: 'gemini-3.6-flash'});
  console.log(modelInfo.inputTokenLimit);
  console.log(modelInfo.outputTokenLimit);
}

await main();

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
  log.Fatal(err)
}
modelInfo, err := client.ModelInfo(ctx, "models/gemini-3.6-flash")
if err != nil {
  log.Fatal(err)
}
fmt.Println("input token limit:", modelInfo.InputTokenLimit)
fmt.Println("output token limit:", modelInfo.OutputTokenLimit)