فك ترميز طويل

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

آلية عمل ميزة "فك التشفير الطويل"

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

1. يمكنك إنشاء تفاعل باستخدام background: true وmax_output_tokens أكبر من 65,536، بما يصل إلى مليون.
2. ينشئ الخادم المجموعة الأولى، بما يصل إلى 64 ألف رمز مميّز.
3. يبدأ الخادم المجموعة التالية من حيث توقّفت المجموعة الأخيرة، ويكرّر هذه العملية إلى أن ينتهي النموذج أو يستخدم كل max_output_tokens.
4. يمكنك إجراء استطلاع حول التفاعل أو بثّه للحصول على النتيجة.

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Write a complete, rigorous proof of the prime number theorem.",
    background=True,
    generation_config={
        "max_output_tokens": 262144,
        "thinking_level": "high",
    },
)

while interaction.status in ("in_progress", "queued"):
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

# Each hop adds a model_output step, so join the text of all of them.
text = "".join(
    content.text
    for step in interaction.steps
    if step.type == "model_output"
    for content in step.content
    if content.type == "text"
)
print(text)
print("Status:", interaction.status)
print("Usage:", interaction.usage)

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

const client = new GoogleGenAI({});

let interaction = await client.interactions.create({
  model: "gemini-4-argon",
  input: "Write a complete, rigorous proof of the prime number theorem.",
  background: true,
  generation_config: {
    max_output_tokens: 262144,
    thinking_level: "high",
  },
});

while (interaction.status === "in_progress" || interaction.status === "queued") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await client.interactions.get(interaction.id);
}

// Each hop adds a model_output step, so join the text of all of them.
const text = interaction.steps
  .filter((step) => step.type === "model_output")
  .flatMap((step) => step.content ?? [])
  .filter((content) => content.type === "text")
  .map((content) => content.text)
  .join("");
console.log(text);
console.log("Status:", interaction.status);
console.log("Usage:", interaction.usage);

# 1. Create the background interaction. It returns an ID right away.
ID=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-argon",
    "input": "Write a complete, rigorous proof of the prime number theorem.",
    "background": true,
    "generation_config": {"max_output_tokens": 262144, "thinking_level": "high"}
  }' | jq -r '.id')

# 2. Poll until the status is no longer in_progress or queued.
#    The REST response has no output_text field, so join the text of every model_output step.
while true; do
  RESP=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$ID" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
  STATUS=$(echo "$RESP" | jq -r '.status')
  if [[ "$STATUS" != "in_progress" && "$STATUS" != "queued" ]]; then
    echo "$RESP" | jq -r '[.steps[]? | select(.type == "model_output") | .content[]? | select(.type == "text") | .text] | join("")'
    echo "$RESP" | jq '{status, usage}'
    break
  fi
  sleep 5
done

الحدود القصوى للناتج

تكون القيمة التلقائية للتفاعلات التي يتم بثّها وتلك التي لا يتم بثّها هي 64 ألف رمز مميّز كحد أقصى للناتج، لذا لا تحتاج الردود التي تصل إلى 64 ألف رمز مميّز إلى أي تغييرات في الرموز البرمجية. لإنشاء أكثر من 64 ألف رمز مميّز، فعِّل ميزة "التنفيذ في الخلفية" وارفع قيمة max_output_tokens.

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

تكتمل معظم الطلبات في غضون 64 ألف رمز مميّز. لا تستخدِم ميزة "فك التشفير الطويل" إلا عندما يحتاج ردّ واحد إلى المزيد من التفكير والناتج.

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

اختيار كيفية تشغيل ميزة "فك التشفير الطويل"

تُعد ميزة "التنفيذ في الخلفية" أسهل طريقة لتشغيل ميزة "فك التشفير الطويل" على Interactions API. تتوفّر ميزة "المتابعة من جهة العميل"، حيث يبدأ الرمز البرمجي كل مجموعة، مع GenerateContent API. ستتوفّر هذه الميزة قريبًا في Interactions API كخيار أكثر تقدّمًا لإدارة قدرتك على الصمود.

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

بث ميزة "فك التشفير الطويل"

لبث النواتج وملخّصات الأفكار عند وصولها، أضِف stream: true وthinking_summaries: "auto". يمكن أن تنقطع عمليات البث الطويلة، لذا على العميل إعادة الاتصال. اتّبِع نمط إعادة الاتصال في دليل "التنفيذ في الخلفية". تضيف ميزة "فك التشفير الطويل" هذه القواعد:

• حفظ معرّف التفاعل: يمكنك قراءته من حدث interaction.created.
• حفظ كل event_id: يمكن أن يصل event_id في أحداث interaction.status_update، وليس فقط في التغييرات النصية.
• إعادة الاتصال باستخدام last_event_id: يمكنك استدعاء interactions.get باستخدام stream: true وآخر event_id. يستمر البث بعد هذا الحدث.
• القراءة حتى النهاية: بعد إعادة الاتصال، اقرأ البث حتى النهاية قبل التحقّق من الحالة. يعيد الخادم تشغيل الأحداث التي لم يتم تلقّيها، حتى بعد اكتمال التفاعل.
• ضبط مهلات طويلة: اضبط مهلات قراءة HTTP على 15 إلى 20 دقيقة لكل بث.
• توقّع الناتج في أجزاء من 5 آلاف رمز مميّز: بعد أول 64 ألف رمز مميّز (حوالي أول 10 دقائق)، يرسل البث الناتج في أجزاء من حوالي 5,000 رمز مميّز. من الطبيعي أن تحدث فترات توقّف مؤقت بين الأجزاء. لا يتوقّف التفاعل، لذا يجب إبقاء الاتصال مفتوحًا.

حالة "التنفيذ في الخلفية"

يمكن أن يستمر التفاعل في الخلفية لمدة تصل إلى 24 ساعة. عندما لا تعود الحالة in_progress أو queued، يمكنك معالجة الحالة النهائية باستخدام هذا الجدول:

لإيقاف تفاعل قيد التشغيل، استدعِ client.interactions.cancel(id=interaction.id) في Python أو client.interactions.cancel(interaction.id) في JavaScript أو POST /v1beta/interactions/{id}/cancel في REST.

ضبط max_output_tokens

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

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

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

تعرض interaction.usage الإجماليات على مستوى جميع المجموعات. اقرأ هذه الحقول: total_input_tokens وtotal_cached_tokens وtotal_output_tokens وtotal_thought_tokens وtotal_tokens.

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

تعرض total_input_tokens حوالي 397,000 رمز مميّز (مع خصم تلقائي لعمليات الإدخال المتكرّرة للمجموعة بنسبة% 95 من خلال التخزين المؤقت الضمني)، على الرغم من أنّ حجم السياق الفعلي يبلغ حوالي 201,000 رمز مميّز فقط: الطلب من 1,000 رمز مميّز بالإضافة إلى 200,000 رمز مميّز من التفكير والناتج.

أثناء البث، يتضمّن كل من حدثَي step.stop وinteraction.status_update السمة usage (تراكمية للتفاعل). اقرأ أحدث قيمة لـ usage بدلاً من جمعها.

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

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

• خصم التخزين المؤقت: يخصم التخزين المؤقت الضمني الإدخال المتكرّر في كل مجموعة بنسبة %95. تبلغ تكلفة الإدخال المخزّن مؤقتًا 0.10 دولار أمريكي لكل مليون رمز مميّز بدلاً من 2.00 دولار أمريكي خلال الفترة التمهيدية.
• التفاعلات الملغاة والفاشلة: يتم تحصيل رسوم منك مقابل كل العمل الذي تم إكماله قبل انتهاء التفاعل.

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

القيود

• لا يمكن استخدام ميزة "فك التشفير الطويل" بدون ميزة "التنفيذ في الخلفية": تتوقّف التفاعلات التي تتضمّن background: false عند 65,536 رمزًا مميّزًا. ستتوفّر هذه الميزة قريبًا.
• لا توجد أهداف للطول: لا يتّبع النموذج أهداف طول الرموز المميّزة أو عدد الكلمات.

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

• الميزات الجديدة في Gemini 4 Argon
• التنفيذ في الخلفية
• التفكير
• ميزة "فك التشفير الطويل" باستخدام GenerateContent API