تعالج نماذج Gemini والنماذج التوليدية الأخرى للذكاء الاصطناعي الإدخالات والإخراجات بدقة تُعرف باسم الرمز المميز.
في نماذج Gemini، يعادل الرمز المميز الواحد 4 أحرف تقريبًا. ويعادل 100 رمز مميز من 60 إلى 80 كلمة باللغة الإنجليزية تقريبًا.
لمحة عن الرموز المميزة
يمكن أن تكون الرموز المميزة أحرفًا مفردة، مثل z، أو كلمات كاملة، مثل cat. ويتم تقسيم الكلمات الطويلة إلى عدة رموز مميزة. تُعرف مجموعة جميع الرموز المميزة التي يستخدمها النموذج باسم المفردات، وتُعرف عملية تقسيم النص إلى رموز مميزة باسم التقسيم إلى رموز مميّزة.
عند تفعيل الفوترة، يتم تحديد تكلفة طلب إلى Gemini API جزئيًا حسب عدد الرموز المميزة للإدخال والإخراج، لذا قد يكون من المفيد معرفة كيفية عدّ الرموز المميزة.
يمكنك تجربة عدّ الرموز المميزة في Colab.
|
|
تجربة ورقة ملاحظات 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-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)
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-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.
Python
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))
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-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)
عدّ الرموز المميزة المتعددة الوسائط
يتم تقسيم جميع الإدخالات إلى 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-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)
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-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))
مثال يقدّم الصورة كبيانات مضمّنة:
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-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)
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-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))
ملفات الفيديو أو الصوت
يتم تحويل كل من الصوت والفيديو إلى رموز مميزة بالمعدّلات الثابتة التالية:
- الفيديو: 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-flash-preview", contents=[prompt, your_file]
)
)
response = client.models.generate_content(
model="gemini-3-flash-preview", 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-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 API قدرات استيعاب يتم قياسها بالرموز المميزة. تحدّد قدرة الاستيعاب حجم الإدخال الذي يمكنك تقديمه وحجم الإخراج الذي يمكن للنموذج إنشاؤه. يمكنك تحديد حجم قدرة الاستيعاب من خلال استدعاء نقطة النهاية models.getأو الاطّلاع على مستندات النماذج.
Python
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=}")
JavaScript
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)
تجربة ورقة ملاحظات Colab
عرض ورقة الملاحظات على GitHub