長解碼

Gemini 4 Argon 具備長解碼功能,可生成超過 64K 個詞元,用於深度推論工作,最多可達 100 萬個詞元的統一脈絡窗口 (輸入、思考和輸出共用 1,048,576 個詞元)。在 Interactions API 中,您可啟用背景執行長解碼功能,讓伺服器自動生成並將每個 64K 跳轉合併為單一互動。

解碼作業時間

單次模型呼叫最多可生成 64,000 個權杖。如果回覆需要超過 64K 個詞元,伺服器會以 64K 個躍點生成回覆,並從上一個躍點停止的位置繼續。每個躍點都會在相同互動 ID 下,將 model_output 步驟新增至 interaction.steps,因此請加入這些步驟來讀取完整的回覆:

  1. 您建立的互動,background: true 和 max_output_tokens 大於 65,536,最多 100 萬。
  2. 伺服器會產生第一個躍點,最多 64, 000 個權杖。
  3. 伺服器會從上次停止的位置開始下一個躍點,並重複這個過程,直到模型完成或用完所有 max_output_tokens。
  4. 您可以輪詢或串流互動,取得結果。

Python

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)

JavaScript

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);

REST

# 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

輸出限制

串流和非串流互動的輸出詞元預設上限為 64K,因此如果回覆不超過 64K 個詞元,就不需要變更程式碼。如要生成超過 64K 個權杖,請開啟背景執行功能並提高 max_output_tokens。

如何建立互動 輸出內容限制
background: false (串流或非串流) 65,536 個權杖。如果值大於 65,536,系統會傳回 400 錯誤。長解碼功能即將推出。
background: true,未設定max_output_tokens 65,536 個詞元
background: true,max_output_tokens大於 65,536 您的 max_output_tokens,最多 1,048,576 個字元,扣除您輸入的內容

使用長解碼的時機

大多數要求會在 64K 個權杖內完成。只有在一個回覆需要更多思考和輸出內容時,才使用長解碼。

工作負載 使用長解碼? 原因
艱深的數學、科學、研究和正式證明 是 模型可花費超過 64,000 個權杖來探索及檢查推理過程。
最困難的程式設計和代理工作 是 部分工作需要超過 64K 個詞元的思考和程式碼,才能在單一回覆中完成。大多數程式設計和代理型工作都會在 64K 內完成。
評估工具在輸出內容達到上限時停止 是 如果模型花費整個 64K 回覆來思考,長解碼功能可避免答案遭到截斷。
即時通訊、問與答、摘要、分類和擷取 否 這些工作完成時,使用的詞元數量遠低於 32,000 個。
要求固定長度,例如「撰寫一本 70 萬字的書」 否 模型未遵循長度目標。
代理會在許多短暫的輪流中呼叫工具 否 每回合都很短。每輪對話輸出大量內容,會快速填滿共用脈絡窗口。
提示接近輸入上限 否 輸出內容最多只能使用 1,048,576 個權杖,扣除輸入內容後剩餘的權杖數。
需要高度即時反應的要求 否 長時間解碼可能需要幾分鐘。

如果將 max_output_tokens 設為較高的值,模型就有更多時間思考困難的問題,但模型仍會自行決定要寫多少內容。如要控制模型要花多少資源進行推論,請設定 thinking_level。

選擇執行長解碼的方式

如要在 Interactions API 執行長時間的解碼作業,最簡單的方法是背景執行。GenerateContent API 提供用戶端接續功能,您的程式碼會啟動每個躍點。Interactions API 即將推出這項功能,提供更進階的選項,讓您自行管理復原能力。

背景執行 (Interactions API) 用戶端接續 (GenerateContent API)
誰會發起各個躍點 我們的伺服器 Google GenAI SDK 或您自己的程式碼
每項要求的詞元數 max_output_tokens,一次互動 每個串流 64K,每個非串流要求 32K
執行時間 長達 24 小時 20 分鐘
儲存空間 需要「store: true」欄 伺服器不會儲存任何內容。
適用情境 執行長時間解碼作業最簡單的方式 更精細地控管重試作業,以便自行建構輪詢、錯誤處理和彈性機制

如要使用用戶端接續功能,請參閱「使用 GenerateContent API 進行長解碼」。

串流長解碼

如要在輸出內容和思考摘要生成時即時串流,請新增 stream: true 和 thinking_summaries: "auto"。長時間的串流可能會中斷,因此用戶端必須重新連線。請按照背景執行指南中的重新連線模式操作。長解碼會新增下列規則:

  • 儲存互動 ID:從 interaction.created 事件讀取。
  • 儲存每個 event_id:event_id 可在 interaction.status_update 事件中送達,不限於文字差異。
  • 重新連結「last_event_id」:使用 stream: true 和最後一個 event_id 呼叫 interactions.get。該事件結束後,串流就會繼續。
  • 讀取到最後:重新連線後,請先讀取到串流結尾,再檢查狀態。即使互動完成,伺服器也會重播錯過的事件。
  • 設定較長的逾時時間:將 HTTP 讀取逾時時間設為每個串流 15 到 20 分鐘。
  • 輸出內容會以 5,000 個詞元為單位:前 64,000 個詞元 (約前 10 分鐘) 輸出後,串流會以約 5,000 個詞元為單位輸出內容。各段落之間有停頓是正常現象。互動並未卡住,因此請保持連線開啟。

背景狀態

背景互動最多可執行 24 小時。狀態不再是 in_progress 或 queued 時,請根據下表處理終端狀態:

狀態 意義 建議行動
completed 模型已完成。 加入 steps 中的 model_output 步驟,並閱讀 usage。如要繼續對話,請將這個互動的 id 傳遞為 previous_interaction_id。
requires_action 模型要求呼叫工具。 執行該工具。然後使用這項互動的 id 傳送結果。
incomplete 模型已用完所有 max_output_tokens。如果模型仍在思考,文字可能為空白。 請提高 max_output_tokens 並重新傳送要求。
failed 伺服器無法完成作業,或互動時間超過 24 小時。 重試要求。如果再次失敗,請將互動內容id提供給支援團隊。
cancelled 你已取消互動。 讀取 usage 即可查看計費詞元。

如要停止正在執行的互動,請在 Python 中呼叫 client.interactions.cancel(id=interaction.id)、在 JavaScript 中呼叫 client.interactions.cancel(interaction.id),或在 REST 中呼叫 POST /v1beta/interactions/{id}/cancel。

設定max_output_tokens

max_output_tokens 會為互動期間的思考和輸出內容設定合併限制。調低這個值不會讓模型更簡潔地思考,而是會提早截斷回覆。

您的工作負載 建議採用 max_output_tokens
現有應用程式的限制低於 32K 提高至 32,768。不需要背景執行。
長時間的程式設計和代理工作 從 65,536 (預設值) 開始。不需要背景執行。
複雜推論、困難數學、科學和證明 設定 background: true,從 262,144 開始,最多可達 1,048,576 減去輸入符記。

如要減少使用的權杖數量,請調低 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 個符記的思考和輸出內容需要四次跳轉:

躍點 傳送至模型的輸入內容 輸入內容詞元
1 提示詞 1,000
2 提示 + 躍點 1 66,536
3 提示詞 + 躍點 1 和 2 132,072
4 提示 + 1 到 3 個跳轉 197,608
總計 397,216

total_input_tokens 回報約 397,000 個詞元 (重複的躍點輸入會透過隱含快取自動折扣 95%),但實際的脈絡大小只有約 201,000 個詞元:1,000 個詞元的提示,加上 200,000 個詞元的思考和輸出。

在串流期間,step.stop 和 interaction.status_update 事件都會包含 usage (互動累計值)。讀取最新的 usage 值,而不是將這些值加總。

瞭解帳單

您需要為每個躍點中的每個詞元付費,包括僅含思考過程的躍點。

  • 快取折扣:隱含快取會在每個躍點中,將重複輸入的內容折扣 95%。新用戶優惠期間,快取輸入內容的費用為每 100 萬個詞元 $0.10 美元,而非 $2.00 美元。
  • 已取消和失敗的互動:您必須支付互動結束前完成的所有工作。

疑難排解

問題 原因和修正方式
輸出內容在 64K 處停止 background 為 false,或未設定 max_output_tokens。將 background: true 和 max_output_tokens 設為大於 65,536。
400: "max_output_tokens greater than 65536 is not yet supported with background=false." 目前還無法在不執行背景作業的情況下進行長時間解碼。設定 background: true。
400:「store=true is required for background interactions」 背景執行功能需要 store: true。
狀態 incomplete,文字為空白 模型在思考時用盡所有權杖。調高 max_output_tokens 或調低 thinking_level。
內容壓縮過早開始 代理架構或評估工具會讀取 total_input_tokens。請參閱「計算詞元數」。

限制

  • 不支援背景執行,無法解碼長內容:與 background: false 的互動會在 65,536 個詞元時停止。相關支援即將推出。
  • 不指定長度:模型不會遵循詞元長度或字數目標。

後續步驟