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

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

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

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

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

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

می‌توانید شمارش توکن‌ها را در Colab ما امتحان کنید.

مشاهده در ai.google.dev یک دفترچه یادداشت Colab را امتحان کنید مشاهده دفترچه یادداشت در گیت‌هاب

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

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

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

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

  • از ویژگی usage_metadata روی شیء response پس از فراخوانی generate_content استفاده کنید.
    این تابع تعداد کل توکن‌ها را هم در ورودی و هم در خروجی برمی‌گرداند: total_token_count .
    همچنین تعداد توکن‌های ورودی و خروجی را به صورت جداگانه برمی‌گرداند: prompt_token_count (توکن‌های ورودی) و candidates_token_count (توکن‌های خروجی).

    اگر از یک مدل تفکر استفاده می‌کنید، توکن مورد استفاده در طول فرآیند تفکر در thoughts_token_count بازگردانده می‌شود. و اگر از ذخیره‌سازی Context استفاده می‌کنید، تعداد توکن‌های ذخیره شده در 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 )

پایتون

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-flash-preview", contents=prompt
)
print("total_tokens: ", total_tokens)

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

print(response.usage_metadata)

جاوا اسکریپت

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-flash-preview",
    contents: prompt,
  });
  console.log(countTokensResponse.totalTokens);

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

await main();

برو

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-flash-preview", contents, nil)
if err != nil {
  return err
}
fmt.Println("total_tokens:", countResp.TotalTokens)

response, err := client.Models.GenerateContent(ctx, "gemini-3-flash-preview", 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 آن را به تاریخچه اضافه کنید.

پایتون

from google import genai
from google.genai import types

client = genai.Client()

chat = client.chats.create(
    model="gemini-3-flash-preview",
    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-flash-preview", 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-flash-preview", contents=history))

جاوا اسکریپت

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-flash-preview",
    history: history,
  });

  const countTokensResponse = await ai.models.countTokens({
    model: "gemini-3-flash-preview",
    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-flash-preview",
    contents: combinedHistory,
  });
  console.log(
    "Combined history token count:",
    combinedCountTokensResponse.totalTokens,
  );
}

await main();

برو

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-flash-preview", nil, history)
if err != nil {
  log.Fatal(err)
}

firstTokenResp, err := client.Models.CountTokens(ctx, "gemini-3-flash-preview", 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-flash-preview", hist, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println(secondTokenResp.TotalTokens)

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

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

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

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

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

مدل‌های Gemini 3 Pro و 3 Flash Preview با پارامتر 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 استفاده می‌کند:

پایتون

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-flash-preview", contents=[prompt, your_image_file]
    )
)

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

جاوا اسکریپت

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

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

await main();

برو

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

file, err := client.Files.UploadFromPath(
  ctx, 
  filepath.Join(getMedia(), "organ.jpg"), 
  &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-flash-preview", contents, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Multimodal image token count:", tokenResp.TotalTokens)

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

مثالی که تصویر را به عنوان داده درون خطی ارائه می‌دهد:

پایتون

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-flash-preview", contents=[prompt, your_image_file]
    )
)

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

جاوا اسکریپت

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-flash-preview",
    contents: contents,
  });
  console.log(countTokensResponse.totalTokens);

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

await main();

برو

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"),
  {
        InlineData: &genai.Blob{
              MIMEType: "image/jpeg",
              Data:     imageBytes,
        },
  },
}
contents := []*genai.Content{
  genai.NewContentFromParts(parts, genai.RoleUser),
}

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

response, err := client.Models.GenerateContent(ctx, "gemini-3-flash-preview", 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 ) را برمی‌گرداند. می‌توانید این فراخوانی را قبل از فراخوانی 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 ).

پایتون

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-flash-preview", contents=[prompt, your_file]
    )
)

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

جاوا اسکریپت

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

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

await main();

برو

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-flash-preview", 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-flash-preview", contents, nil)
if err != nil {
  log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println(string(usageMetadata))

پنجره‌های زمینه

مدل‌های موجود از طریق رابط برنامه‌نویسی نرم‌افزار Gemini دارای پنجره‌های زمینه‌ای هستند که با توکن اندازه‌گیری می‌شوند. پنجره زمینه‌ای مشخص می‌کند که چه مقدار ورودی می‌توانید ارائه دهید و چه مقدار خروجی می‌توانید توسط مدل تولید کنید. می‌توانید اندازه پنجره زمینه‌ای را با فراخوانی نقطه پایانی models.get یا با مراجعه به مستندات مدل‌ها تعیین کنید.

پایتون

from google import genai

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

جاوا اسکریپت

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

const ai = new GoogleGenAI({});

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

await main();

برو

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