긴 디코딩

긴 디코드를 사용하면 Gemini 4 Argon이 통합된 100만 토큰 컨텍스트 창 (입력, 사고,출력 전반에서 공유되는 1,048, 576개 토큰)까지 심층 추론 작업을 위해 64, 000개 이상의 토큰을 생성할 수 있습니다. Interactions API에서 백그라운드 실행으로 긴 디코드를 사용 설정하면 서버에서 각 64, 000개 홉을 자동으로 생성하고 단일 상호작용으로 결합합니다.

긴 디코드 작동 방식

단일 모델 호출은 최대 64,000개 토큰을 생성합니다. 응답에 64,000개 이상의 토큰이 필요한 경우 서버는 이전 홉이 중지된 지점에서 계속되는 64,000개 홉으로 생성합니다. 각 홉은 동일한 상호작용 ID 아래의 interaction.steps에 model_output 단계를 추가하므로 이러한 단계를 조인하여 전체 응답을 읽습니다.

1. background: true 및 65,536보다 큰 max_output_tokens(최대 100만)로 상호작용을 만듭니다.
2. 서버는 최대 64, 000개 토큰의 첫 번째 홉을 생성합니다.
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,000개 출력 토큰 한도로 설정되므로 최대 64,000개 토큰의 응답에는 코드 변경이 필요하지 않습니다. 64, 000개 이상의 토큰을 생성하려면 백그라운드 실행을 사용 설정하고 max_output_tokens를 늘립니다.

긴 디코드를 사용하는 경우

대부분의 요청은 64,000개 토큰 내에서 완료됩니다. 하나의 응답에 그보다 더 많은 사고와 출력이 필요한 경우에만 긴 디코드를 사용하세요.

높은 max_output_tokens를 설정하면 모델이 어려운 문제에 대해 더 오래 생각할 수 있지만 모델은 여전히 작성할 양을 결정합니다. 모델이 사용하는 추론 노력을 제어하려면 thinking_level을 설정하세요.

긴 디코드 실행 방법 선택

백그라운드 실행은 Interactions API에서 긴 디코드를 실행하는 가장 쉬운 방법입니다. 코드에서 각 홉을 시작하는 클라이언트 측 연속은 GenerateContent API에서 사용할 수 있습니다. 자체 복원력을 관리하는 고급 옵션으로 Interactions API에 곧 출시될 예정입니다.

클라이언트 측 연속을 사용하려면 GenerateContent API를 사용한 긴 디코드를 참고하세요.

긴 디코드 스트리밍

출력 및 사고 요약을 도착하는 대로 스트리밍하려면 stream: true 및 thinking_summaries: "auto"를 추가하세요. 긴 스트림은 삭제될 수 있으므로 클라이언트가 다시 연결해야 합니다. 백그라운드 실행 가이드의 다시 연결 패턴을 따르세요. 긴 디코드는 다음 규칙을 추가합니다.

• 상호작용 ID 저장: interaction.created 이벤트에서 읽습니다.
• 모든 event_id 저장: event_id는 텍스트 델타뿐만 아니라 interaction.status_update 이벤트에서도 도착할 수 있습니다.
• last_event_id로 다시 연결: interactions.get 및 마지막 event_id로 stream: true을 호출합니다. 스트림은 해당 이벤트 후에 계속됩니다.
• 끝까지 읽기: 다시 연결한 후 상태를 확인하기 전에 스트림을 끝까지 읽습니다. 서버는 상호작용이 완료된 후에도 누락된 이벤트를 재생합니다.
• 긴 제한 시간 설정: 스트림당 HTTP 읽기 제한 시간을 15~20분으로 설정합니다.
• 5,000개 토큰 청크로 출력 예상: 처음 64,000개 토큰 (약 처음 10분) 후 스트림은 약 5,000개 토큰의 청크로 출력을 전송합니다. 청크 간의 일시중지는 정상입니다. 상호작용이 중지되지 않으므로 연결을 열어 두세요.

백그라운드 상태

백그라운드 상호작용은 최대 24시간 동안 실행될 수 있습니다. 상태가 더 이상 in_progress 또는 queued가 아니면 이 표를 사용하여 최종 상태를 처리합니다.

실행 중인 상호작용을 중지하려면 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는 상호작용 전반에서 사고 및 출력의 결합된 한도를 설정합니다. 이를 낮춘다고 해서 모델이 더 간결하게 사고하는 것은 아니며 대신 응답이 더 빨리 잘립니다.

토큰을 더 적게 사용하려면 thinking_level을 낮추세요. 가장 어려운 추론 작업에는 high를 사용하세요. 대부분의 코딩 및 에이전트 작업에는 medium (기본값)을 사용하세요.

토큰 집계

interaction.usage는 모든 홉의 합계를 보고합니다. total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens 필드를 읽습니다.

total_input_tokens는 모든 홉의 입력 토큰을 합산합니다. 각 홉은 프롬프트와 지금까지 생성된 모든 항목을 입력으로 모델에 다시 전송하므로 동일한 토큰이 이후의 모든 홉에서 다시 집계됩니다. 예를 들어 200,000개 토큰의 사고 및 출력을 생성하는 1,000개 토큰 프롬프트는 4개의 홉을 사용합니다.

total_input_tokens는 실제 컨텍스트 크기가 1,000개 토큰 프롬프트와 200,000개 토큰의 사고 및 출력인 약 201,000개 토큰에 불과하지만 약 397,000개 토큰 (반복되는 홉 입력은 암시적 캐싱으로 95% 자동 할인)을 보고합니다.

스트림 중에 step.stop 및 interaction.status_update 이벤트 모두 usage (상호작용의 누적)를 포함합니다. 이를 함께 추가하는 대신 최신 usage 값을 읽으세요.

청구 이해

사고만 포함된 홉을 포함하여 모든 홉의 모든 토큰에 대해 비용을 지불합니다.

• 캐시 할인: 암시적 캐싱은 각 홉에서 반복되는 입력을 95% 할인합니다. 캐시된 입력 비용은 프로모션 기간 동안 200만 토큰당 2달러가 아닌 100만 토큰당 0.10달러입니다.
• 취소되고 실패한 상호작용: 상호작용이 종료되기 전에 완료된 모든 작업에 대해 비용을 지불합니다.

문제 해결

제한사항

• 백그라운드 실행이 없는 긴 디코드 없음: background: false가 있는 상호작용은 65,536개 토큰에서 중지됩니다. 곧 지원될 예정입니다.
• 길이 타겟 없음: 모델은 토큰 길이 또는 단어 수 타겟을 따르지 않습니다.

다음 단계

• Gemini 4 Argon의 새로운 기능
• 백그라운드 실행
• 사고
• GenerateContent API를 사용한 긴 디코드