رمزگشایی طولانی

رمزگشایی طولانی به Gemini 4 Argon اجازه می‌دهد تا فراتر از حد خروجی تک‌درخواستی برای تکالیف استدلال عمیق، تا پنجره بافت یکپارچه ۱ میلیون داده‌واحدی (۱٬۰۴۸٬۵۷۶ داده‌واحد مشترک در ورودی، تفکر، و خروجی) تولید کند.

تغییر شناسه مدل به‌تنهایی باعث فعال شدن رمزگشایی طولانی نمی‌شود. بدون راه‌اندازی اضافی، خروجی در ۶۴ هزار توکن برای تماس‌های جاری‌سازی و ۳۲ هزار توکن برای تماس‌های غیرجاری‌سازی متوقف می‌شود. سریع‌ترین راه برای روشن کردن رمزگشایی طولانی، ارتقا دادن «کیت توسعه نرم‌افزار هوش مصنوعی زایای Google» و تنظیم max_output_tokens بزرگ‌تر از ۶۵۵۳۶ است. این راهنما توضیح می‌دهد که رمزگشایی طولانی چگونه کار می‌کند، چه زمانی باید از آن استفاده کنید، و چگونه آن را با generateContent روشن کنید.

رمزگشایی تا چه مدت کار می‌کند

یک درخواست جاری‌سازی یا SDK تکی حداکثر ۶۴ هزار توکن تولید می‌کند و یک درخواست REST غیرجاری‌سازی حداکثر ۳۲ هزار توکن تولید می‌کند. وقتی پاسخی به توکن‌های بیشتری نیاز دارد، مدل آن را در چندین جهش درخواست و پاسخ تولید می‌کند که هرکدام از جایی که جهش قبلی متوقف شده است ادامه می‌یابد.

• محدودیت یکپارچه برای ورودی و برونداد: ورودی، فکر کردن، فراخوانی تابع، و پاسخ نهایی از یک پنجره ۱ میلیون تایی استفاده می‌کنند. برونداد می‌تواند تا ۱٬۰۴۸٬۵۷۶ منهای کدهای ورودی شما استفاده کند.
• محدودیت برای هر گام: یک گام حداکثر ۶۵٬۵۳۶ توکن برونداد برمی‌گرداند. درخواست‌های REST غیرجاری‌سازی تا ۳۲٬۷۶۸ برمی‌گرداند.
• سیگنال ادامه: اگر مدل به حد مجاز برسد و توکن‌های باقی‌مانده داشته باشد، پاسخ با finish_reason: CONTINUATION و continuation_token پایان می‌یابد.
• پرش بعدی: مشتری همان درخواست را دوباره با کد ارسال می‌کند. مدل از جایی که متوقف شده بود ادامه می‌دهد.
• یک مجموع برای همه جهش‌ها: max_output_tokens مجموع توکن‌های اندیشگر و برونداد را برای همه جهش‌ها باهم تنظیم می‌کند.
• سیگنال توقف: وقتی مدل از همه max_output_tokens استفاده می‌کند، پاسخ با finish_reason: MAX_TOKENS به‌پایان می‌رسد.

در مسائل دشوار، یک گام می‌تواند همه ژتون‌هایش را صرف تفکر داخلی کند و نوشتار خالی با continuation_token برگرداند. این طبیعی است و پاسخ نهایی در گام‌های بعدی می‌رسد.

محدودیت‌های برونداد پیش‌فرض

بدون رمزگشایی طولانی، یک درخواست در این محدودیت‌های هر درخواست متوقف می‌شود:

• درخواست‌های جاری‌سازی و درخواست‌های غیرجاری‌سازی ازطریق «کیت توسعه نرم‌افزار Google GenAI» (generate_content): به‌طور پیش‌فرض تا ۶۴ هزار واحد برونداد.
• فراخوانی‌های REST غیرجاری‌سازی مستقیم (generateContent): به‌طور پیش‌فرض ۳۲ هزار توکن خروجی. تنظیم max_output_tokens بزرگ‌تر از ۳۲٬۷۶۸ در یک تماس REST غیر جاری‌سازی بدون continuation_token خطای 400 را برمی‌گرداند.

چه زمانی از رمزگشایی طولانی استفاده کنیم

اکثر درخواست‌ها در محدوده تک‌درخواستی (۶۴ هزار نمانه برای جاری‌سازی و فراخوانی‌های کیت توسعه نرم‌افزار، یا ۳۲ هزار نمانه برای فراخوانی‌های REST غیرجاری‌سازی) تکمیل می‌شوند. وقتی پاسخ به تعداد بیشتری از ترکیب اندیشیدن و نشانه‌های برونداد نسبت‌به آنچه یک درخواست اجازه می‌دهد نیاز دارد، از رمزگشایی طولانی استفاده کنید. افزایش max_output_tokens به مدل سقف بالاتری می‌دهد تا برای مسائل سخت استدلال کند، نه اینکه پاسخ‌های استاندارد را طولانی‌تر کند.

تنظیم کردن max_output_tokens بالا به مدل فرصت می‌دهد تا بیشتر درباره مسائل دشوار فکر کند، اما مدل همچنان تصمیم می‌گیرد که چقدر بنویسد. برای کنترل میزان تلاش استدلالی که مدل استفاده می‌کند، thinking_level را تنظیم کنید.

روشن کردن کدگشایی طولانی

می‌توانید رمزگشایی طولانی را به‌طور خودکار با Google GenAI SDK (گزینه ۱، توصیه‌شده برای اکثر برنامه‌ها) اجرا کنید یا حلقه ادامه خودتان را بنویسید (گزینه ۲). هر دو گزینه از پنجره زمینه‌ای ۱ میلیون داده‌واحد پشتیبانی می‌کنند.

‫continuation_token رمزگذاری‌شده وضعیت مدل را بین درخواست‌ها منتقل می‌کند، بنابراین چیزی در سرور ذخیره نمی‌شود.

گزینه ۱: استفاده از Google GenAI SDK (توصیه‌شده)

در جدیدترین «کیت توسعه نرم‌افزار هوش مصنوعی زایای Google»، automatic_continuation به‌طور پیش‌فرض برای تماس‌های جاری‌سازی و غیرجاری‌سازی فعال است، بنابراین نیازی به تنظیم آن ندارید. وقتی max_output_tokens را بالاتر از سقف هر درخواست تنظیم می‌کنید، کیت توسعه نرم‌افزار به‌طور خودکار جهش‌های ادامه را اجرا می‌کند و یک پاسخ ترکیبی برمی‌گرداند.

1. کیت توسعه نرم‌افزار را ارتقا دهید.

   Python

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

   JavaScript

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

2. ‫max_output_tokens را بیشتر از ۶۵٬۵۳۶ تنظیم کنید.

   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 (جاوا اسکریپت) نیز برای شما ادامه دارد. اگر جاری‌سازی پس‌از یک نقطه بازرسی قطع شود، کیت توسعه نرم‌افزار از آن نقطه بازرسی ازسر گرفته می‌شود.
• مهلت‌ها: مهلت‌ها و تلاش‌های مجدد برای هر پرش اعمال می‌شود، نه برای اجرای کامل.
• کنترل دستی: برای اجرای حلقه توسط خودتان، automatic_continuation=False (Python) یا automaticContinuation: false (JavaScript) را تنظیم کنید. سپس «گزینه ۲» را دنبال کنید.
• استفاده: فیلدهای استفاده مجموع همه جهش‌ها را نشان می‌دهد. برای دریافت اندازه پیام‌واره، initial_prompt_token_count را بخوانید. شمارش نشان‌ها را ببینید.

گزینه ۲: نوشتن حلقه خودتان

اگر مستقیماً REST را فراخوانی می‌کنید، از زبانی بدون جدیدترین کیت توسعه نرم‌افزار استفاده می‌کنید، یا به کنترل کامل نیاز دارید، حلقه خودتان را بنویسید. همچنین می‌توانید به پیاده‌سازی‌های Google GenAI SDK ما در Python و جاوا اسکریپت/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
  }
}

حلقه‌های جاری‌سازی به یک قانون دیگر نیاز دارند. پس‌از ۳۲٬۷۶۸ کد اول، جاری‌سازی هر ۵٬۰۰۰ کد یک کد ایست بازرسی ارسال می‌کند. بخش‌های جدید را در فهرست معلق نگه دارید. وقتی یک بخش دارای continuation_token است، بخش‌های معلق را به خروجی متعهدشده خود منتقل کنید و کد را ذخیره کنید. اگر جاری‌سازی قطع شد، تکه‌های معلقه را دور بریزید و از آخرین کد ازسر بگیرید. اگر جاری‌سازی قبل‌از اولین نقطه بازرسی قطع شد، درخواست اصلی را دوباره ارسال کنید.

دور max_output_tokens

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

برای استفاده از توکن‌های کمتر، thinking_level را کاهش دهید. از high برای سخت‌ترین تکالیف استدلالی استفاده کنید. از medium (پیش‌فرض) برای اکثر کارهای کدنویسی و عامل‌گرا استفاده کنید. از low برای کارهای کمتر پیچیده استفاده کنید.

رسیدگی به درخواست‌های طولانی‌مدت

ازآنجایی‌که Gemini 4 Argon برای مسائل سخت بیشتر از مدل‌های Gemini 3.x فکر می‌کند، باید زمان‌های اتمام مشتری خود را افزایش دهید تا درخواست‌های طولانی زود قطع نشوند.

• تماس‌های غیرجاری‌سازی: سرور اتصال را پس‌از ۱۰ دقیقه می‌بندد.
• تماس‌های جاری‌سازی: سرور پس‌از ۲۰ دقیقه جاری‌سازی را می‌بندد.
• مهلت‌های کارخواه: مهلت خواندن HTTP را روی ۲۰ دقیقه تنظیم کنید. مهلت زمانی ۳ یا ۵ دقیقه‌ای درخواست را زودتر متوقف می‌کند.

در Python، زمان اتمام مهلت را در کارخواه به میلی‌ثانیه تنظیم کنید:

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

برای کارهایی که مشتری شما نظرسنجی می‌کند، Interactions API رمزگشایی طولانی را در سرور اجرا می‌کند. اجرا در پس‌زمینه را ببینید.

وقتی مدل از همه نشان‌های برونداد استفاده می‌کند ازسر گرفته می‌شود

وقتی پاسخی با MAX_TOKENS تمام می‌شود، همچنان شامل continuation_token می‌شود. دو انتخاب دارید:

• ادامه: همان درخواست را با همان کد و max_output_tokens بالاتر ارسال کنید. مقدار باید بیشتر از تعداد ژتون‌های استفاده‌شده تاکنون باشد. درغیراین‌صورت، میانای برنامه‌سازی کاربردی خطای ۴۰۰ برمی‌گرداند.
• شروع مجدد: درخواست اصلی را با max_output_tokens بالاتر و بدون توکن ارسال کنید. هزینه هر دو اجرا را پرداخت می‌کنید.

شمارش داده‌واحدها

با ادامه خودکار، usage_metadata مجموع را در همه پرش‌ها گزارش می‌کند. کیت توسعه نرم‌افزار همه فیلدهای شمارش را جمع می‌زند: prompt_token_count، cached_content_token_count، candidates_token_count، thoughts_token_count، و total_token_count.

prompt_token_count کدهای ورودی هر گام را جمع می‌کند. هر پرش پیام‌واره شما و همه موارد تولیدشده تا آن زمان را به‌عنوان ورودی به مدل برمی‌گرداند، بنابراین همان نشان‌ها در هر پرش بعدی دوباره شمارش می‌شوند. برای مثال، با Google GenAI SDK، یک پیام‌واره ۱۰۰۰ تاکی که ۲۰۰٬۰۰۰ تاک تفکر و برونداد تولید می‌کند، چهار جهش دارد:

prompt_token_count حدود ۳۹۷٬۰۰۰ کد (با ورودی‌های تکراری که به‌طور خودکار ۹۵٪ توسط حافظه پنهان ضمنی تخفیف داده شده‌اند) و total_token_count حدود ۵۹۷٬۰۰۰ کد گزارش می‌دهد، هرچند اندازه واقعی بافت فقط حدود ۲۰۱٬۰۰۰ کد است: پیام‌واره ۱٬۰۰۰ کدی به‌علاوه ۲۰۰٬۰۰۰ کد تفکر و خروجی. یک حلقه REST غیرجاری‌سازی از ۳۲ هزار جهش استفاده می‌کند، بنابراین برای همان خروجی هفت جهش طول می‌کشد و ۶۹۵٬۱۲۸ توکن ورودی را گزارش می‌کند.

‫prompt_token_count و total_token_count مجموع هر پرش است، نه اندازه بافتار شما. از آن‌ها برای تصمیم‌گیری درباره زمان خلاصه کردن یا کوتاه کردن سابقه مکالمه (فشرده‌سازی بافت) یا برای اعمال محدودیت بافت استفاده نکنید. برای تخمین اندازه بافت، اندازه پیام‌واره‌تان را از جدول به candidates_token_count و thoughts_token_count اضافه کنید.

قبل‌از اجرای رمزگشایی طولانی، چارچوب کارگزار، ابزار ارزیابی، یا پراکسی خود را به‌روز کنید:

• عوامل و ابزارهای ارزیابی: اگر کد شما بافت را فشرده می‌کند یا اجرای کد را در حد مجاز کد متوقف می‌کند، به‌جای مجموع prompt_token_count از initial_prompt_token_count (یا اولین پرش prompt_token_count در REST) استفاده کنید. پاسخ‌هایی که در یک جهش تمام می‌شوند مقدار یکسانی را در هر دو فیلد گزارش می‌کنند، بنابراین آزمایش‌های کوتاه مشکل را نشان نمی‌دهند.
• پراکسی‌ها و دروازه‌هایی که REST را فراخوانی می‌کنند: هر پاسخ REST فقط جهش خودش را گزارش می‌کند. هر فیلد را در سراسر جهش‌ها برای هزینه اضافه کنید و promptTokenCount جهش اول را به‌عنوان اندازه پیام‌واره نگه دارید. درغیراین‌صورت، کاربران شما اعداد متفاوتی را نسبت‌به کاربران «کیت توسعه نرم‌افزار» برای درخواست یکسان می‌بینند.
• گزارش‌ها و پاسخ‌های سریالی: کیت توسعه نرم‌افزار initial_prompt_token_count را در کارخواه محاسبه می‌کند. این ویژگی در پاسخ REST یا در خروجی JSON کیت توسعه نرم‌افزار (مثل model_dump()) وجود ندارد. اگر بعداً به آن نیاز دارید، آن را به‌عنوان مقدار جداگانه‌ای ذخیره کنید.

اگر در حلقه خودتان جاری‌سازی کنید، usage_metadata در هر جاری‌سازی تجمعی است. فقط آخرین مقدار هر جریان را نگه دارید، سپس مقادیر را در سراسر پرش‌ها اضافه کنید.

آشنایی با صورت‌حساب

شما برای هر کد در هر گام، ازجمله گام‌هایی که فقط شامل تفکر هستند، هزینه پرداخت می‌کنید.

• تخفیف حافظه پنهان: ذخیره‌سازی ضمنی در حافظه پنهان، ورودی تکراری را در هر گام ۹۵٪ تخفیف می‌دهد. هزینه ورودی ذخیره‌شده در حافظه نهان درطول دوره مقدماتی به‌جای ۲٫۰۰ دلار، ۰٫۱۰ دلار به‌ازای هر ۱ میلیون داده‌واحد است.
• انقضای حافظه نهان: حافظه نهان پس‌از ۱۵ تا ۲۰ دقیقه عدم استفاده منقضی می‌شود. وقفه طولانی بین پرش‌ها باعث می‌شود نرخ ورودی کامل دوباره اعمال شود.
• گام‌های غیر جاری‌سازی ناموفق: فقط وقتی پاسخ تکمیل می‌شود پرداخت می‌کنید. هزینه درخواست ناموفق یا حذف‌شده ۰ دلار است.
• جاری‌سازی‌های رهاشده: جاری‌سازی‌ای که قبل‌از ۳۲ هزار توکن رها شود، هزینه آن ۰ دلار است. پس‌از آن، تا آخرین نشان ایست بازرسی پرداخت می‌کنید، زیرا می‌توانید از آنجا ازسر بگیرید.

عیب‌یابی

محدودیت‌ها

• نقطه پایانی سازگاری با OpenAI: رمزگشایی طولانی دردسترس نیست. برونداد در سقف هر درخواست متوقف می‌شود.
• کیت‌های توسعه نرم‌افزار قدیمی‌تر: نسخه‌های پایین‌تر از حداقل‌های ذکرشده در یادداشت به‌طور خودکار ادامه نمی‌یابند.
• طول: مدل از اهداف طول نشان یا تعداد کلمه پیروی نمی‌کند.

بازبینه

• «کیت توسعه نرم‌افزار Google GenAI» را به حداقل نسخه ارتقا دهید.
• ‫max_output_tokens را بزرگ‌تر از ۶۵۵۳۶ تنظیم کنید.
• از thinking_level (low، medium، یا high) استفاده کنید، نه thinking_budget.
• زمان اتمام مهلت خواندن HTTP را روی ۲۰ دقیقه تنظیم کنید.
• از initial_prompt_token_count برای اندازه بافت و فشرده‌سازی استفاده کنید.
• قبل‌از ارزیابی بزرگ، یک پیام‌واره را به‌عنوان آزمایش اجرا کنید.

مراحل بعدی

• تازه‌های Gemini 4 Argon
• درحال فکر کردن
• شمارش داده‌واحد