فك ترميز طويل

تتيح ميزة "فك الترميز الطويل" لنموذج Gemini 4 Argon إنشاء مخرجات تتجاوز الحد الأقصى المسموح به للطلب الواحد في مهام الاستدلال العميق، وذلك ضمن قدرة الاستيعاب الموحّدة التي تبلغ مليون رمز مميّز (1,048,576 رمزًا مميّزًا مشترَكًا بين الإدخال والتفكير والإخراج).

لا يؤدي تغيير رقم تعريف النموذج وحده إلى تفعيل ميزة "الترميز الطويل". بدون إعدادات إضافية، يتوقف الناتج عند 64 ألف رمز مميّز لطلبات البث و32 ألف رمز مميّز للطلبات غير المتعلّقة بالبث. أسرع طريقة لتفعيل ميزة فك الترميز الطويل هي ترقية حزمة تطوير البرامج (SDK) الخاصة بـ Google GenAI وضبط max_output_tokens على قيمة أعلى من 65,536. يشرح هذا الدليل طريقة عمل ميزة "فك التشفير الطويل"، وحالات استخدامها، وكيفية تفعيلها باستخدام generateContent.

مدة عمل فك الترميز

يؤدي طلب واحد للبث أو حزمة تطوير البرامج (SDK) إلى إنشاء ما يصل إلى 64 ألف رمز مميّز، بينما يؤدي طلب REST غير البث إلى إنشاء ما يصل إلى 32 ألف رمز مميّز. عندما يحتاج الردّ إلى المزيد من الرموز المميّزة، ينشئه النموذج عبر عدة عمليات انتقال بين الطلب والردّ، حيث يستمر كل منها من حيث توقفت العملية السابقة.

• الحدّ الأقصى لعدد الرموز المميزة الموحّدة للإدخال والإخراج: تشترك عمليات الإدخال والتفكير واستدعاء الدوال والردّ النهائي في نافذة واحدة تضم مليون رمز مميز. يمكن أن يستخدم الناتج ما يصل إلى 1,048,576 رمزًا مطروحًا منه الرموز المميّزة للإدخال.
• حد أقصى لكل قفزة: تعرض القفزة الواحدة ما يصل إلى 65,536 رمزًا مميزًا للناتج. تعرض طلبات REST غير المتدفقة ما يصل إلى 32,768 نتيجة.
• إشارة مواصلة: إذا بلغ النموذج الحد الأقصى وبقيت لديه رموز مميزة، ينتهي الرد بالرمز finish_reason: CONTINUATION والرمز continuation_token.
• الخطوة التالية: يرسل العميل الطلب نفسه مرة أخرى باستخدام الرمز المميّز. يواصل النموذج من حيث توقف.
• إجمالي واحد لجميع الخطوات: يضبط max_output_tokens إجمالي الرموز المميزة الخاصة بالتفكير والناتج لجميع الخطوات معًا.
• إشارة توقّف: عندما يستخدم النموذج كل max_output_tokens، ينتهي الرد بـ finish_reason: MAX_TOKENS.

في المشاكل الصعبة، يمكن أن تستخدم القفزة جميع الرموز المميزة في التفكير الداخلي وتعرض نصًا فارغًا مع continuation_token. هذا أمر طبيعي، وسيصل الرد النهائي في الخطوات اللاحقة.

حدود الإخراج التلقائية

بدون ميزة "فك الترميز الطويل"، يتوقف الطلب الواحد عند الحدود التالية لكل طلب:

• طلبات البث والطلبات غير المتعلقة بالبث من خلال حزمة تطوير البرامج (SDK) الخاصة بالذكاء الاصطناعي التوليدي من Google (generate_content): يتم ضبطها تلقائيًا على 64 ألف رمز مميز للناتج.
• طلبات REST المباشرة غير المتدفقة (generateContent): يتم ضبطها تلقائيًا على 32 ألف رمز مميز للناتج. إذا تم ضبط max_output_tokens على قيمة أعلى من 32,768 في طلب REST غير مستند إلى البث بدون continuation_token، سيظهر الخطأ 400.

حالات استخدام فك التشفير الطويل

تكتمل معظم الطلبات في حدود الطلب الفردي (64 ألف رمز مميز لطلبات البث المباشر وSDK، أو 32 ألف رمز مميز لطلبات REST غير المتعلقة بالبث المباشر). استخدِم ميزة "فك الترميز الطويل" عندما يتطلّب الردّ عددًا أكبر من الرموز المميّزة المخصّصة للتفكير والناتج مقارنةً بما يسمح به طلب واحد. من خلال رفع قيمة max_output_tokens، يمنح النموذج سقفًا أعلى للاستدلال على المسائل الصعبة، بدلاً من جعل الإجابات العادية أطول.

يمنح ضبط max_output_tokens على قيمة عالية النموذج مساحة للتفكير لفترة أطول في المشاكل الصعبة، ولكن يظل النموذج هو من يقرر مقدار الكتابة. للتحكّم في مقدار جهد الاستدلال الذي يستخدمه النموذج، اضبط thinking_level.

تفعيل فك الترميز الطويل

يمكنك تشغيل ميزة "فك الترميز الطويل" تلقائيًا باستخدام حزمة Google GenAI SDK (الخيار 1، يُنصح به لمعظم التطبيقات) أو كتابة حلقة تكرار خاصة بك (الخيار 2). يتيح كلا الخيارَين استخدام قدرة الاستيعاب الكاملة التي تبلغ مليون رمز مميّز.

يحمل continuation_token المشفّر حالة النموذج بين الطلبات، لذلك لا يتم تخزين أي بيانات على الخادم.

الخيار 1: استخدام حزمة تطوير البرامج (SDK) الخاصة بالذكاء الاصطناعي التوليدي من Google (يُنصح به)

في أحدث إصدار من حزمة Google GenAI SDK، يتم تفعيل automatic_continuation تلقائيًا لكل من الطلبات التي تستخدم ميزة "الاستجابة السريعة" وتلك التي لا تستخدمها، لذا لا حاجة إلى ضبطه. عند ضبط max_output_tokens على قيمة أعلى من الحدّ الأقصى لكل طلب، تُشغِّل حزمة تطوير البرامج (SDK) تلقائيًا عمليات المتابعة وتعرض ردًا واحدًا مجمّعًا.

1. ترقية حزمة تطوير البرامج (SDK)

   Python

   pip install -U "google-genai>=2.30.1"
   

   JavaScript

   npm install "@google/genai@>=2.29.1"
   

2. اضبط قيمة max_output_tokens على أكثر من 65,536.

   Python

   from google import genai
   from google.genai import types
   
   client = genai.Client()  # Reads GEMINI_API_KEY
   
   response = client.models.generate_content(
       model="gemini-4-argon",
       contents="Write a complete, rigorous proof of the prime number theorem.",
       config=types.GenerateContentConfig(
           max_output_tokens=262_144,  # Total thinking and output for all hops
           thinking_config=types.ThinkingConfig(thinking_level="high"),
           automatic_continuation=True,  # Default. Shown for clarity.
       ),
   )
   
   print(response.text)
   print("Finish reason:", response.candidates[0].finish_reason)
   print("Prompt size:", response.usage_metadata.initial_prompt_token_count)
   print("Billed tokens:", response.usage_metadata.total_token_count)
   

   JavaScript

   import { GoogleGenAI, ThinkingLevel } from "@google/genai";
   
   const ai = new GoogleGenAI({}); // Reads GEMINI_API_KEY
   
   const response = await ai.models.generateContent({
     model: "gemini-4-argon",
     contents: "Write a complete, rigorous proof of the prime number theorem.",
     config: {
       maxOutputTokens: 262144, // Total thinking and output for all hops
       thinkingConfig: { thinkingLevel: ThinkingLevel.HIGH },
       automaticContinuation: true, // Default. Shown for clarity.
     },
   });
   
   console.log(response.text);
   console.log("Finish reason:", response.candidates?.[0]?.finishReason);
   console.log("Prompt size:", response.usageMetadata?.initialPromptTokenCount);
   console.log("Billed tokens:", response.usageMetadata?.totalTokenCount);
   

يجب أخذ النقاط التالية في الاعتبار:

• البث: يستمر generate_content_stream (Python) وgenerateContentStream (JavaScript) أيضًا. إذا انقطع البث بعد نقطة تفتيش، تستأنف حزمة SDK البث من نقطة التفتيش تلك.
• مهلات: تنطبق المهلات وعمليات إعادة المحاولة على كل خطوة، وليس على عملية التشغيل الكاملة.
• التحكّم اليدوي: لتشغيل التكرار بنفسك، اضبط automatic_continuation=False (Python) أو automaticContinuation: false (JavaScript). بعد ذلك، اتّبِع الخيار 2.
• الاستخدام: تعرض حقول الاستخدام مجموع جميع عمليات الانتقال. لمعرفة حجم طلبك، يُرجى قراءة initial_prompt_token_count. يُرجى الاطّلاع على احتساب الرموز المميّزة.

الخيار 2: كتابة حلقة خاصة بك

اكتب حلقة خاصة بك إذا كنت تستدعي REST مباشرةً، أو تستخدم لغة بدون أحدث حزمة SDK، أو تحتاج إلى تحكّم كامل. يمكنك أيضًا الرجوع إلى عمليات تنفيذ حزمة تطوير البرامج (SDK) للذكاء الاصطناعي التوليدي من Google في Python وJavaScript/TypeScript كمرجع.

اتّبِع القواعد التالية:

1. أرسِل الطلب نفسه في كل قفزة. أرسِل contents وsystem_instruction وtools وgeneration_config الأصلية. إبقاء قيمة max_output_tokens كما هي
2. لا تُضِف نتائج جزئية إلى contents. تحمل continuation_token حالة النموذج، بما في ذلك طريقة تفكيره.
3. أرسِل الرمز المميّز الأخير فقط. ويحتوي كل رمز مميّز على جميع بيانات مستوى التقدّم السابقة.
4. يمكنك المتابعة عندما يكون finish_reason CONTINUATION. التوقّف عند أي سبب آخر للانتهاء
5. اجمع الأجزاء بعد الخطوة الأخيرة. اجمع الأجزاء من جميع القفزات في دورة نموذج واحدة لسجلّ المحادثات.

from google import genai
from google.genai import types

client = genai.Client()  # Reads GEMINI_API_KEY
PROMPT = "Write a complete, rigorous proof of the prime number theorem."
parts = []
token = None

while True:
    response = client.models.generate_content(
        model="gemini-4-argon",
        contents=PROMPT,  # The original contents on every request
        config=types.GenerateContentConfig(
            max_output_tokens=262_144,  # The same total on every request
            thinking_config=types.ThinkingConfig(thinking_level="high"),
            automatic_continuation=False,  # You run the loop
            continuation_token=token,
        ),
    )
    candidate = response.candidates[0]
    if candidate.content and candidate.content.parts:
        parts.extend(candidate.content.parts)
    token = candidate.continuation_token
    if candidate.finish_reason != types.FinishReason.CONTINUATION or not token:
        break

print("".join(p.text for p in parts if p.text and not p.thought))
print("Finish reason:", candidate.finish_reason)

import { GoogleGenAI, ThinkingLevel } from "@google/genai";

const ai = new GoogleGenAI({}); // Reads GEMINI_API_KEY
const PROMPT = "Write a complete, rigorous proof of the prime number theorem.";
const parts = [];
let token = undefined;
let candidate = undefined;

while (true) {
  const response = await ai.models.generateContent({
    model: "gemini-4-argon",
    contents: PROMPT, // The original contents on every request
    config: {
      maxOutputTokens: 262144, // The same total on every request
      thinkingConfig: { thinkingLevel: ThinkingLevel.HIGH },
      automaticContinuation: false, // You run the loop
      continuationToken: token,
    },
  });
  candidate = response.candidates?.[0];
  if (candidate?.content?.parts) {
    parts.push(...candidate.content.parts);
  }
  token = candidate?.continuationToken;
  if (candidate?.finishReason !== "CONTINUATION" || !token) {
    break;
  }
}

console.log(parts.filter((p) => p.text && !p.thought).map((p) => p.text).join(""));
console.log("Finish reason:", candidate?.finishReason);

# Hop 1: send the request with max_output_tokens.
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-argon:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Write a complete, rigorous proof of the prime number theorem."}]}],
    "generationConfig": {
      "maxOutputTokens": 262144,
      "thinkingConfig": {"thinkingLevel": "high"}
    }
  }'

# Hop 2: if finishReason is CONTINUATION, send the same request plus the token.
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-argon:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Write a complete, rigorous proof of the prime number theorem."}]}],
    "generationConfig": {
      "maxOutputTokens": 262144,
      "thinkingConfig": {"thinkingLevel": "high"}
    },
    "continuationToken": "TOKEN_FROM_HOP_1"
  }'

إذا تم استخدام القفزة بالكامل للتفكير، سيتم عرض text مع finishReason: "CONTINUATION". تعامَل مع هذا على أنّه تقدّم عادي واطلب القفزة التالية:

{
  "candidates": [{
    "content": {"role": "model", "parts": [{"text": ""}]},
    "finishReason": "CONTINUATION",
    "continuationToken": "CiQ4ZmQ3..."
  }],
  "usageMetadata": {
    "promptTokenCount": 142,
    "candidatesTokenCount": 0,
    "thoughtsTokenCount": 32768,
    "totalTokenCount": 32910
  }
}

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

المجموعة max_output_tokens

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

لاستخدام عدد أقل من الرموز المميّزة، يمكنك خفض قيمة thinking_level. استخدِم high لتنفيذ أصعب مهام الاستدلال. استخدِم medium (الخيار التلقائي) لمعظم أعمال الترميز والذكاء الاصطناعي الوكيل. استخدِم low للمهام البسيطة.

التعامل مع الطلبات الطويلة المدى

بما أنّ Gemini 4 Argon يستغرق وقتًا أطول من نماذج Gemini 3.x في حلّ المشاكل الصعبة، ننصحك بزيادة مهلة العميل كي لا تنقطع الطلبات الطويلة قبل اكتمالها.

• المكالمات غير المتعلّقة بالبث: يغلق الخادم الاتصال بعد 10 دقائق.
• طلبات البث: يغلق الخادم البث بعد 20 دقيقة.
• مهلة العميل: اضبط مهلة قراءة HTTP على 20 دقيقة. تؤدي مهلة الـ 3 دقائق أو الـ 5 دقائق إلى إيقاف الطلب مبكرًا.

في Python، اضبط مهلة العميل بالمللي ثانية:

client = genai.Client(http_options=types.HttpOptions(timeout=1_200_000))  # 20 minutes

بالنسبة إلى المهام التي يطلبها العميل، تنفّذ واجهة Interactions API عملية فك ترميز طويلة على الخادم. يُرجى الاطّلاع على التنفيذ في الخلفية.

الاستئناف عندما يستخدم النموذج جميع الرموز المميّزة الناتجة

عندما ينتهي الردّ بـ MAX_TOKENS، سيظلّ يتضمّن continuation_token. لديك خياران:

• متابعة: أرسِل الطلب نفسه مع الرمز المميز وقيمة max_output_tokens أعلى. يجب أن تكون القيمة أعلى من الرموز المميزة المستخدَمة حتى الآن. وفي الحالات الأخرى، تعرض واجهة برمجة التطبيقات الخطأ 400.
• البدء من جديد: أرسِل الطلب الأصلي مع قيمة أعلى لـ max_output_tokens وبدون رمز مميّز. عليك الدفع مقابل كلتا عمليتَي التشغيل.

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

عند تفعيل ميزة "المتابعة التلقائية"، يعرض usage_metadata الإجماليات في جميع عمليات النقل. تضيف حزمة تطوير البرامج (SDK) كل حقل من حقول العدد: prompt_token_count وcached_content_token_count وcandidates_token_count وthoughts_token_count وtotal_token_count.

يجمع prompt_token_count الرموز المميّزة للإدخال في كل خطوة. في كل قفزة، يتم إرسال طلبك وكل ما تم إنشاؤه حتى الآن إلى النموذج كمدخلات، لذلك يتم احتساب الرموز المميزة نفسها مرة أخرى في كل قفزة لاحقة. على سبيل المثال، باستخدام حزمة تطوير البرامج (SDK) لـ Google GenAI، يتطلّب الطلب الذي يتضمّن 1,000 رمز مميّز وينتج عنه 200,000 رمز مميّز للتفكير والمخرجات أربع قفزات:

يُبلغ prompt_token_count عن حوالي 397,000 رمز مميّز (مع خصم تلقائي بنسبة% 95 من مدخلات الخطوات المتكررة من خلال التخزين المؤقت الضمني)، ويُبلغ total_token_count عن حوالي 597,000 رمز مميّز، على الرغم من أنّ حجم السياق الفعلي يبلغ حوالي 201,000 رمز مميّز فقط: الطلب المكوّن من 1,000 رمز مميّز بالإضافة إلى 200,000 رمز مميّز للتفكير والمخرجات. تستخدم حلقة REST غير المتدفقة 32 ألف قفزة، لذا تستغرق سبع قفزات للحصول على الناتج نفسه وتسجّل 695,128 رمز إدخال.

prompt_token_count وtotal_token_count هما مجموع كل خطوة، وليس حجم السياق. لا تستخدِمها لتحديد وقت تلخيص سجلّ المحادثات أو اقتطاعه (ضغط السياق)، أو لفرض حدّ أقصى للسياق. لتقدير حجم السياق، أضِف حجم الطلب من الجدول إلى candidates_token_count وthoughts_token_count.

عدِّل إطار عمل الوكيل أو أداة التقييم أو الخادم الوكيل قبل تنفيذ عملية فك ترميز طويلة:

• الوكلاء وأدوات التقييم: إذا كان الرمز البرمجي يضغط السياق أو يوقف عملية التشغيل عند حدّ معيّن للرموز المميّزة، استخدِم initial_prompt_token_count (أو prompt_token_count للخطوة الأولى في REST) بدلاً من مجموع prompt_token_count. الردود التي تنتهي في قفزة واحدة تُبلغ عن القيمة نفسها في كلا الحقلين، لذلك لا تظهر المشكلة في الاختبارات القصيرة.
• الخوادم الوكيلة وبوابات الوصول التي تستدعي REST: يعرض كل ردّ من REST قفزته فقط. أضِف كل حقل في جميع الخطوات للحصول على التكلفة، واحتفظ بقيمة promptTokenCount للخطوة الأولى كحجم الطلب. وإلا، ستظهر للمستخدمين أرقام مختلفة عن تلك التي تظهر لمستخدمي حزمة تطوير البرامج (SDK) للطلب نفسه.
• السجلّات والردود المتسلسلة: تحسب حزمة تطوير البرامج (SDK) قيمة initial_prompt_token_count على العميل. ولا تظهر في استجابة REST أو في مخرجات JSON الخاصة بحزمة تطوير البرامج (SDK)، مثل model_dump(). احفظها كقيمة منفصلة إذا كنت بحاجة إليها لاحقًا.

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

التعرّف على الفوترة

يتم تحصيل رسوم منك مقابل كل رمز مميز في كل خطوة، بما في ذلك الخطوات التي تتضمّن التفكير فقط.

• خصم التخزين المؤقت: يقلّل التخزين المؤقت الضمني من الإدخال المتكرر في كل خطوة بنسبة %95. تبلغ تكلفة الإدخال المخزَّن مؤقتًا 0.10 دولار أمريكي لكل مليون رمز مميّز بدلاً من 2.00 دولار أمريكي خلال الفترة التمهيدية.
• انتهاء صلاحية ذاكرة التخزين المؤقت: تنتهي صلاحية ذاكرة التخزين المؤقت بعد مرور 15 إلى 20 دقيقة بدون استخدام. يؤدي التوقف المؤقت الطويل بين عمليات النقل إلى فرض رسوم معدّل الإدخال الكامل مرة أخرى.
• الخطوات غير المكتملة في وضع العرض التدريجي: لا تدفع إلا عند اكتمال الردّ. وتبلغ تكلفة الطلب الذي تعذّر إكماله أو تم إسقاطه 0 دولار أمريكي.
• عمليات البث التي تم إيقافها: لا يتم تحصيل أي رسوم مقابل عمليات البث التي تم إيقافها قبل بلوغها 32,000 رمز مميز. بعد ذلك، يمكنك الدفع مقابل الرمز المميز الخاص بآخر نقطة تحقّق، لأنّه يمكنك استئناف التدريب من هذه النقطة.

تحديد المشاكل وحلّها

القيود

• نقطة نهاية التوافق مع OpenAI: لا تتوفّر ميزة فك الترميز الطويل. يتوقف الردّ عند الحدّ الأقصى لكل طلب.
• حِزم SDK القديمة: لا تستمر الإصدارات الأقل من الحد الأدنى المذكور في الملاحظة تلقائيًا.
• الطول: لا يتّبع النموذج أهداف طول الرموز المميّزة أو عدد الكلمات.

قائمة التحقق

• يجب ترقية حزمة تطوير البرامج (SDK) من Google GenAI إلى الحد الأدنى من الإصدار.
• اضبط قيمة max_output_tokens على أكثر من 65,536.
• استخدِم thinking_level (low أو medium أو high)، وليس thinking_budget.
• اضبط مهلة قراءة HTTP على 20 دقيقة.
• استخدِم initial_prompt_token_count لحجم السياق والضغط.
• نفِّذ طلبًا واحدًا كاختبار قبل إجراء تقييم كبير.

الخطوات التالية

• الميزات الجديدة في Gemini 4 Argon
• التفكير
• احتساب الرموز المميّزة