長解碼¶
Gemini 4 模型(gemini-4-carbon、gemini-4-argon 與 gemini-4-hydrogen)預設每次回應最多產生 64K 個權杖(65,536)的思考與輸出。長解碼可讓你將 max_output_tokens 提高到超過 64K,用於困難的推理、數學與程式設計任務,上限為統一的 100 萬權杖上下文視窗(1,048,576 個權杖,由輸入、思考與輸出共同使用)。在 Interactions API 上,你可以透過背景執行執行長解碼,讓我們的伺服器為你執行每一個躍點;也可以在前景透過用戶端接續執行。
長解碼如何運作¶
產生數十萬個權杖所需的時間,可能比單一 HTTP 請求能保持開啟的時間更長,因此長解碼會將生成過程拆分為連續的躍點,從前一個躍點停止的位置繼續:背景呼叫、串流呼叫,以及非串流的 gemini-4-hydrogen 呼叫,每個躍點最多 64K 個權杖(65,536);gemini-4-carbon 與 gemini-4-argon 的非串流躍點,每個躍點最多 32K 個權杖(32,768)。
當你在 Interactions API 上設定 background: true,且 max_output_tokens 大於 65,536 時:
- 請求會以非同步方式執行,並傳回
status="in_progress"的互動。 - 若回應在未完成前達到 64K 個權杖,伺服器會以目前已產生的權杖啟動一個接續躍點。
- 此過程會重複,直到模型完成或達到
max_output_tokens為止。 - 當你輪詢該互動時,會在單一互動中取得所有躍點合併後的思考與輸出。
若要改由你的用戶端執行接續躍點,請參閱選擇長解碼的執行方式。
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-carbon",
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-carbon",
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-carbon",
"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,未設定 max_output_tokens |
65,536 個權杖 |
background: false,max_output_tokens 大於 65,536,automatic_continuation: true(SDK 預設) |
你的 max_output_tokens,上限為 1,048,576 減去你的輸入 |
background: false,max_output_tokens 大於 65,536,automatic_continuation: false 或 REST |
每個串流躍點(或 gemini-4-hydrogen 的非串流躍點)65,536 個權杖,或 gemini-4-carbon 與 gemini-4-argon 每個非串流躍點 32,768 個權杖。使用 continuation_token 迴圈執行,即可產生最多達你的 max_output_tokens。 |
background: true,未設定 max_output_tokens |
65,536 個權杖 |
background: true,max_output_tokens 大於 65,536 |
你的 max_output_tokens,上限為 1,048,576 減去你的輸入 |
長解碼時,請務必將 max_output_tokens 設定為大於 65,536。同時也要檢查你的代理框架或評測工具中的設定值。過低的值(例如 8,192)會讓模型在思考完成前就停止。
何時使用長解碼¶
大多數請求都能在 64K 個權杖內完成。僅在單一回應需要超過該數量的思考與輸出時,才使用長解碼。
| 工作負載 | 是否使用長解碼? | 原因 |
|---|---|---|
| 困難的數學、科學、研究與形式證明 | 是 | 模型可使用超過 64K 個權杖來探索並檢查其推理。 |
| 最困難的程式設計與代理任務 | 是 | 有些任務在單一回應中需要超過 64K 個權杖的思考與程式碼。大多數程式設計與代理任務都能在 64K 內完成。 |
| 會在輸出上限處停止的評測工具 | 是 | 長解碼可避免模型將整個 64K 回應都用在思考上時,答案被截斷。 |
| 聊天、問答、摘要、分類與擷取 | 否 | 這些任務都能在 32K 個權杖內順利完成。 |
| 要求固定長度的請求,例如「寫一本 700,000 字的書」 | 否 | 模型不會遵循長度目標。 |
| 在許多短回合中呼叫工具的代理 | 否 | 每個回合都很短。每個回合的大量輸出會快速填滿共用的上下文視窗。 |
| 接近輸入上限的提示詞 | 否 | 輸出只能使用 1,048,576 個權杖減去你的輸入後的數量。 |
| 對延遲敏感的請求 | 否 | 長解碼可能執行數分鐘。 |
設定較高的 max_output_tokens,能讓模型在困難問題上有更多空間進行更長時間的思考,但模型仍會自行決定要寫多少內容。若要控制模型使用的推理努力程度,請設定 thinking_level。
選擇長解碼的執行方式¶
背景執行是在 Interactions API 上執行長解碼最簡單的方式。我們的伺服器會執行每一個躍點,因此用戶端連線中斷不會干擾生成過程。用戶端接續則是由 Google GenAI SDK 或你自己的程式碼啟動每個躍點,同樣可在 Interactions API 上用於前景呼叫、無狀態請求,或自行管理重試的韌性。
| 背景執行(Interactions API) | 用戶端接續(Interactions API) | |
|---|---|---|
| 誰啟動每個躍點 | 我們的伺服器 | Google GenAI SDK(預設),或你自己的程式碼 |
| 每個請求的權杖數 | 你的 max_output_tokens,在單一互動中(每個內部躍點最多 64K) |
每個串流 64K(gemini-4-hydrogen 的非串流亦同);gemini-4-carbon 與 gemini-4-argon 每個非串流請求 32K |
| 執行時間 | 最多 24 小時 | 每個串流躍點 20 分鐘,每個非串流躍點 10 分鐘 |
| 儲存 | 需要 store: true |
預設儲存(store: true),或以 store: false 設為無狀態 |
| 最適合 | 執行長解碼最簡單的方式 | 前景呼叫、無狀態應用程式,或對重試有更細緻的控制,以便建立你自己的退避、錯誤處理與韌性機制 |
若你改用 GenerateContent API,請參閱使用 GenerateContent API 的長解碼。
用戶端接續¶
以下章節適用於 background: false(預設)的情況。你的用戶端會驅動每個接續躍點,而非由我們的伺服器執行,可透過 Google GenAI SDK 自動完成,或使用你自己的迴圈。
使用 SDK 自動接續¶
用戶端接續需要 Google GenAI SDK 版本:Python 2.34.0 以上、JavaScript 2.32.0 以上、Go 1.77.0 以上、Java 1.80.0 以上,或 .NET 1.28.0 以上。
當 max_output_tokens 超過單一躍點上限時,Google GenAI SDK 會執行接續躍點,並傳回一個合併後的互動。如需使用 REST 或自訂迴圈控制,請參閱使用自訂迴圈的用戶端接續。
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-carbon",
input="Write a complete, rigorous proof of the prime number theorem.",
generation_config={
"max_output_tokens": 262144,
"thinking_level": "high",
},
)
print(interaction.output_text)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-4-carbon",
input: "Write a complete, rigorous proof of the prime number theorem.",
generation_config: {
max_output_tokens: 262144,
thinking_level: "high",
},
});
console.log(interaction.output_text);
console.log("Status:", interaction.status);
console.log("Usage:", interaction.usage);
請留意以下 SDK 行為:
- 儲存合併後的回應:
interactions.create會合併所有躍點的文字、步驟與用量,並使用最後一個躍點的id。由於每個躍點是分開儲存的,interactions.get只會傳回最後一個躍點的輸出,因此請儲存create的回應。在下一回合將該id以previous_interaction_id傳入,即可保留完整歷史記錄。 - 逾時: 用戶端的
http_options設定每個躍點的 HTTP 逾時。將timeout傳給interactions.create,可限制所有躍點的總時間。 - 中斷的執行: 若某個躍點在已有進度後失敗,SDK 會擲出
ContinuationInterruptedError。對於非串流呼叫,partial_interaction會保存已完成躍點合併後的輸出。若要繼續,請將錯誤中的互動 ID 與continuation_token傳給interactions.create(或重新傳送input,當store為false時)。
使用自訂迴圈的用戶端接續¶
若要直接呼叫 REST,或自行管理躍點之間的重試、退避與記錄,請在你的程式碼中執行接續迴圈(在 SDK 中停用 automatic_continuation)。每個躍點請保持相同的模型、工具、系統指令與生成設定;若已停用儲存,請重新傳送提示詞,而非前一個互動 ID。
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-carbon",
input="Write a complete, rigorous proof of the prime number theorem.",
automatic_continuation=False,
generation_config={
"max_output_tokens": 262144,
"thinking_level": "high",
},
)
full_text = interaction.output_text or ""
while interaction.status == "requires_continuation":
interaction = client.interactions.create(
model="gemini-4-carbon",
previous_interaction_id=interaction.id,
continuation_token=interaction.continuation_token,
automatic_continuation=False,
generation_config={
"max_output_tokens": 262144,
"thinking_level": "high",
},
)
full_text += interaction.output_text or ""
print(full_text)
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
let interaction = await client.interactions.create({
model: "gemini-4-carbon",
input: "Write a complete, rigorous proof of the prime number theorem.",
automatic_continuation: false,
generation_config: {
max_output_tokens: 262144,
thinking_level: "high",
},
});
let fullText = interaction.output_text ?? "";
while (interaction.status === "requires_continuation") {
interaction = await client.interactions.create({
model: "gemini-4-carbon",
previous_interaction_id: interaction.id,
continuation_token: interaction.continuation_token,
automatic_continuation: false,
generation_config: {
max_output_tokens: 262144,
thinking_level: "high",
},
});
fullText += interaction.output_text ?? "";
}
console.log(fullText);
RESP=$(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-carbon",
"input": "Write a complete, rigorous proof of the prime number theorem.",
"generation_config": {"max_output_tokens": 262144, "thinking_level": "high"}
}')
while [[ "$(echo "$RESP" | jq -r '.status')" == "requires_continuation" ]]; do
echo "$RESP" | jq -rj '[.steps[]? | select(.type == "model_output") | .content[]? | select(.type == "text") | .text] | join("")'
PREV_ID=$(echo "$RESP" | jq -r '.id')
TOKEN=$(echo "$RESP" | jq -r '.continuation_token')
RESP=$(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-carbon\",
\"previous_interaction_id\": \"$PREV_ID\",
\"continuation_token\": \"$TOKEN\",
\"generation_config\": {\"max_output_tokens\": 262144, \"thinking_level\": \"high\"}
}")
done
echo "$RESP" | jq -r '[.steps[]? | select(.type == "model_output") | .content[]? | select(.type == "text") | .text] | join("")'
串流長解碼¶
若要即時串流輸出與思考摘要,請加入 stream: true 與 thinking_summaries: "auto"。長時間的串流可能會中斷,因此你的用戶端必須重新連線。請遵循背景執行指南中的重新連線模式。長解碼另有以下規則:
- 儲存互動 ID: 從
interaction.created事件中讀取。 - 儲存每個
event_id:event_id可能出現在interaction.status_update事件上,不僅限於文字增量。 - 使用
last_event_id重新連線: 呼叫interactions.get,並帶入stream: true與最後的event_id。串流會在該事件之後繼續。 - 讀取到最後: 重新連線後,請先將串流讀取到最後,再檢查狀態。伺服器會重播錯過的事件,即使互動已完成亦然。
- 設定較長的逾時: 將每個串流的 HTTP 讀取逾時設定為 15 到 20 分鐘。
- 預期以 5K 權杖為單位的輸出區塊: 在
gemini-4-carbon與gemini-4-argon上的前 32K 個權杖之後(或在gemini-4-hydrogen上 64K 個權杖之後,從第二個躍點開始),串流會在每個檢查點以約 5,000 個權杖為單位傳送輸出。區塊之間的停頓屬正常現象。互動並未卡住,請保持連線開啟。
對於使用 Google GenAI SDK 的前景串流,SDK 會將接續躍點串連成單一串流:
- 跨躍點持續讀取: 每個躍點都是獨立的互動,會發出
interaction.created與interaction.completed事件。不要在interaction.created時重設你的串流剖析器,也不要在interaction.completed時停止(當狀態為requires_continuation時)。若要繼續對話,請儲存最後一個躍點的 ID。 - 處理躍點中途的斷線: 若連線在檢查點、新的增量到達前中斷,SDK 會為你重新連線。若串流在最新檢查點之後已產生增量,SDK 會擲出
ContinuationInterruptedError,以避免重複輸出。
互動狀態¶
背景互動最多可執行 24 小時。一旦狀態不再是 in_progress 或 queued,請使用下表處理互動狀態:
| 狀態 | 意義 | 處理方式 |
|---|---|---|
completed |
模型已完成。 | 合併 model_output 步驟(位於 steps 中)並讀取 usage。若要繼續對話,請將此互動的 id 以 previous_interaction_id 傳入。 |
requires_continuation |
前景躍點已達到其單一請求上限(串流與 gemini-4-hydrogen 非串流為 64K,gemini-4-carbon 與 gemini-4-argon 非串流為 32K),且仍有剩餘的權杖預算。 |
Google GenAI SDK 預設會為你接續。在 REST 中,請以 previous_interaction_id 與 continuation_token 傳送下一個躍點。 |
requires_action |
模型要求進行工具呼叫。 | 執行該工具。然後以此互動的 id 傳送結果。 |
incomplete |
模型已用完所有 max_output_tokens。若模型仍在思考,文字可能為空。 |
以 previous_interaction_id、continuation_token 與更高的 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 個權杖的思考與輸出,需要四個 64K 躍點(或在 gemini-4-carbon 與 gemini-4-argon 上七個 32K 非串流躍點):
| 躍點 | 傳送給模型的輸入 | 輸入權杖數 |
|---|---|---|
| 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 個權杖的思考與輸出。
total_input_tokens 是每個躍點輸入的總和,不是你的上下文大小。不要用它來決定何時摘要或修剪你的對話歷史記錄(上下文壓縮)。若要估計上下文大小,請將你的提示詞大小(或非串流 SDK 回應上的 usage.initial_input_tokens)加上 total_output_tokens 與 total_thought_tokens。
在串流期間,interaction.status_update 與 interaction.completed 事件會包含 usage(該躍點的累計值,或在背景模式下為整個互動的累計值)。在背景串流或單一前景躍點中,請讀取最新的 usage 值,而非將它們相加。在前景串流中,每個躍點都是獨立的互動,因此請將每個躍點最終的 usage 相加。
了解計費¶
你需要為每個躍點中的每個權杖付費,包括僅包含思考的躍點。
- 快取折扣: 隱含快取會將每個躍點中重複的輸入折扣 95%。在推廣期間,快取輸入的費用為每 100 萬個權杖 $0.10,而非 $2.00。
- 已取消與失敗的互動: 你需要為互動結束前已完成的所有工作付費。
疑難排解¶
| 症狀 | 原因與修正方式 |
|---|---|
| 輸出在 64K 停止 | 將 max_output_tokens 設定為大於 65,536,並使用背景執行或升級 Google GenAI SDK。 |
輸出以 requires_continuation 狀態停止 |
躍點已達到其單一請求上限,且仍有剩餘預算。請升級 SDK、啟用 automatic_continuation,或加入接續迴圈。 |
| 400:"store=true is required for background interactions" | 背景執行需要 store: true。 |
狀態為 incomplete 且文字為空 |
模型已將所有權杖用在思考上。請提高 max_output_tokens 或降低 thinking_level。 |
| 上下文壓縮太早開始 | 你的代理框架或評測工具讀取了 total_input_tokens。請參閱計算權杖數。 |
限制¶
- 較早的 SDK: 早於 Python 2.34.0、JavaScript 2.32.0、Go 1.77.0、Java 1.80.0 與 .NET 1.28.0 的版本,不會接續前景互動。
- 無長度目標: 模型不會遵循權杖長度或字數目標。