Gemini가 생각 중

Gemini 3 및 2.5 시리즈 모델은 추론 및 다단계 계획 수립 능력을 크게 향상시키는 내부 '사고 과정'을 사용하므로 코딩, 고급 수학, 데이터 분석과 같은 복잡한 작업에 매우 효과적입니다.

이 가이드에서는 Gemini API를 사용하여 Gemini의 사고 기능을 사용하는 방법을 보여줍니다.

생각을 통해 콘텐츠 생성

사고 모델로 요청을 시작하는 것은 다른 콘텐츠 생성 요청과 유사합니다. 주요 차이점은 model 필드에 사고 지원 모델 중 하나를 지정하는 데 있습니다.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain the concept of Occam's Razor and provide a simple, everyday example."
)
print(interaction.steps[-1].content[0].text)

자바스크립트

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Explain the concept of Occam's Razor and provide a simple, everyday example."
});
console.log(interaction.steps.at(-1).content[0].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Explain the concept of Occam'\''s Razor and provide a simple example."
  }'

사고 요약

사고 요약은 모델의 내부 추론 과정에 대한 유용한 정보를 제공합니다. 기본적으로 최종 출력만 반환됩니다. thinking_summaries로 생각 요약을 사용 설정할 수 있습니다.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the sum of the first 50 prime numbers?",
    generation_config={
        "thinking_summaries": "auto"
    }
)

for step in interaction.steps:
    if step.type == "thought":
        print("Thought summary:")
        for content_block in step.summary:
            if content_block.type == "text":
                print(content_block.text)
        print()
    elif step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print("Answer:")
                print(content_block.text)
                print()

자바스크립트

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What is the sum of the first 50 prime numbers?",
    generationConfig: {
        thinkingSummaries: "auto"
    }
});

for (const step of interaction.steps) {
    if (step.type === "thought") {
        console.log("Thought summary:");
        for (const contentBlock of step.summary) {
            if (contentBlock.type === "text") console.log(contentBlock.text);
        }
    } else if (step.type === "model_output") {
        for (const contentBlock of step.content) {
            if (contentBlock.type === "text") {
                console.log("Answer:");
                console.log(contentBlock.text);
            }
        }
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "What is the sum of the first 50 prime numbers?",
    "generationConfig": {
      "thinkingSummaries": "auto"
    }
  }'

생각을 담아 스트리밍

생성 중에 스트리밍을 사용하여 증분 생각 요약을 수신합니다. 그러면 다음과 같이 생성되는 대로 롤링 증분 요약이 반환됩니다.

Python

from google import genai

client = genai.Client()

prompt = """
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?
"""

thoughts = ""
answer = ""

stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    generation_config={
        "thinking_summaries": "auto"
    },
    stream=True
)

thoughts = ""
answer = ""

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "thought":
            if not thoughts:
                print("Thinking...")
            summary_text = getattr(event.delta, 'text', '')
            print(f"[Thought] {summary_text}", end="")
            thoughts += summary_text
        elif event.delta.type == "text" and event.delta.text:
            if not answer:
                print("\nAnswer:")
            print(event.delta.text, end="")
            answer += event.delta.text

자바스크립트

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

const client = new GoogleGenAI({});

const prompt = `Alice, Bob, and Carol each live in a different house on the same
street: red, green, and blue. Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?`;

let thoughts = "";
let answer = "";

const stream = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: prompt,
    generationConfig: {
        thinkingSummaries: "auto"
    },
    stream: true
});

for await (const event of stream) {
    if (event.type === "step.delta") {
        if (event.delta.type === "thought") {
            if (!thoughts) console.log("Thinking...");
            process.stdout.write(`[Thought] ${event.delta.text || ""}`);
            thoughts += event.delta.text || "";
        } else if (event.delta.type === "text" && event.delta.text) {
            if (!answer) console.log("\nAnswer:");
            process.stdout.write(event.delta.text);
            answer += event.delta.text;
        }
    }
}

사고 제어

Gemini 모델은 기본적으로 동적 사고를 수행하여 요청의 복잡성에 따라 추론 노력의 양을 자동으로 조정합니다. 하지만 구성 매개변수를 사용하여 이 동작을 제어할 수 있습니다.

사고 수준 (Gemini 3)

Gemini 3 모델 이상에 권장되는 thinking_level 파라미터를 사용하면 추론 동작을 제어할 수 있습니다.

사고 수준 Gemini 3.1 Pro Gemini 3 Pro (지원 중단됨) Gemini 3 Flash 설명
minimal 지원되지 않음 지원되지 않음 지원됨 대부분의 질문에 대해 '생각하지 않음' 설정과 일치합니다. 모델이 복잡한 코딩 작업에 대해 매우 최소한으로 생각할 수 있습니다. 채팅 또는 높은 처리량 애플리케이션의 지연 시간을 최소화합니다. minimal는 사고가 꺼져 있음을 보장하지 않습니다.
low 지원됨 지원됨 지원됨 지연 시간과 비용을 최소화합니다. 지시 수행, 채팅 또는 고처리량 애플리케이션에 가장 적합합니다.
medium 지원됨 지원되지 않음 지원됨 대부분의 작업에 균형 잡힌 사고를 제공합니다.
high 지원됨 (기본값, 동적) 지원됨 (기본값, 동적) 지원됨 (기본값, 동적) 추론 깊이를 극대화합니다. 모델이 첫 번째 (사고하지 않는) 출력 토큰에 도달하는 데 시간이 훨씬 더 오래 걸릴 수 있지만, 출력은 더 신중하게 추론됩니다.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Provide a list of 3 famous physicists and their key contributions",
    generation_config={
        "thinking_level": "low"
    }
)
print(interaction.steps[-1].content[0].text)

자바스크립트

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Provide a list of 3 famous physicists and their key contributions",
    generationConfig: {
        thinkingLevel: "low"
    }
});
console.log(interaction.steps.at(-1).content[0].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Provide a list of 3 famous physicists and their key contributions",
    "generation_config": {
      "thinking_level": "low"
    }
  }'

Gemini 3 Pro에서는 사고를 사용 중지할 수 없습니다. Gemini 3 Flash는 완전한 사고 기능 끄기를 지원하지 않지만 minimal 설정은 모델이 사고하지 않을 가능성이 높다는 것을 의미합니다 (여전히 사고할 수 있음).

생각 서명

Gemini API는 스테이트리스(Stateless)이므로 모델은 모든 API 요청을 독립적으로 처리하며 멀티턴 상호작용에서 이전 턴의 생각 컨텍스트에 액세스할 수 없습니다.

여러 턴의 상호작용에서 생각 컨텍스트를 유지할 수 있도록 Gemini는 모델의 내부 사고 과정을 암호화한 표현인 생각 서명을 반환합니다.

  • Gemini 2.5 모델은 사고가 사용 설정되고 요청에 함수 호출, 특히 함수 선언이 포함된 경우 생각 서명을 반환합니다.
  • Gemini 3 모델은 모든 유형의 파트에 대해 생각 서명을 반환할 수 있습니다. 서명을 수신한 대로 모두 다시 전달하는 것이 좋지만 함수 호출 서명의 경우 필수입니다. 자세한 내용은 생각 서명 페이지를 참고하세요.
  • 서명은 응답의 다른 부분(예: 함수 호출 또는 텍스트 부분) 내에서 모델로부터 반환됩니다. 후속 턴에서 모든 파트가 포함된 전체 대답을 반환합니다.
  • 서명이 있는 부분을 함께 연결하지 마세요.
  • 서명이 있는 부분을 서명이 없는 부분과 병합하지 마세요.

가격 책정

사고가 사용 설정된 경우 대답 가격은 출력 토큰과 사고 토큰의 합계입니다. 생성된 사고 토큰의 총수는 total_thought_tokens 필드에서 확인할 수 있습니다.

Python

# ...
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)

자바스크립트

// ...
console.log(`Thoughts tokens: ${interaction.usage.totalThoughtTokens}`);
console.log(`Output tokens: ${interaction.usage.totalOutputTokens}`);

사고 모델은 최종 대답의 품질을 개선하기 위해 전체 사고를 생성한 다음 요약을 출력하여 사고 과정에 대한 통계를 제공합니다. 가격은 API에서 요약만 출력되더라도 모델이 생성해야 하는 전체 생각 토큰을 기준으로 합니다.

토큰에 관한 자세한 내용은 토큰 수 계산 가이드를 참고하세요.

권장사항

이 섹션에는 사고 모델을 효율적으로 사용하는 방법에 관한 안내가 포함되어 있습니다.

디버그 및 조종

  • 추론 검토: 사고 모델에서 예상한 대답을 얻지 못하는 경우 Gemini의 사고 요약을 주의 깊게 분석하는 것이 도움이 될 수 있습니다. 작업을 어떻게 분류하고 결론에 도달했는지 확인하고 이 정보를 사용하여 올바른 결과로 수정할 수 있습니다.

  • 추론에 관한 안내 제공: 특히 긴 출력을 원하는 경우 프롬프트에 안내를 제공하여 모델이 사용하는 사고량을 제한하는 것이 좋습니다. 이렇게 하면 대답에 더 많은 토큰 출력을 예약할 수 있습니다.

작업 복잡성

  • 간단한 작업 (사고 모델을 사용하지 않아도 됨): 복잡한 추론이 필요하지 않은 간단한 요청의 경우 사고 모델이 필요하지 않습니다. 예를 들면 다음과 같습니다.
    • 'DeepMind는 어디에서 설립되었어?'
    • '이 이메일은 회의를 요청하는 건가요, 아니면 정보를 제공하는 건가요?'
  • 중간 작업 (기본값/약간의 사고): 많은 일반적인 요청은 단계별 처리 또는 더 깊은 이해가 필요합니다. 예를 들면 다음과 같습니다.
    • 광합성과 성장을 비유해 줘.
    • 전기 자동차와 하이브리드 자동차를 비교 및 대조하세요.
  • 어려운 작업 (최대 사고 능력): 매우 복잡한 문제의 경우 높은 사고 예산을 설정하는 것이 좋습니다. 이러한 유형의 작업에는 모델이 전체 추론 및 계획 기능을 활용해야 합니다. 예를 들면 다음과 같습니다.
    • AIME 2025의 문제 1을 풀어 보세요. 9보다 큰 모든 정수 밑 b의 합을 구하세요.
    • 사용자 인증을 포함하여 실시간 주식 시장 데이터를 시각화하는 웹 애플리케이션용 Python 코드를 작성하세요. 가능한 한 효율적으로 만드세요.

지원되는 모델

모델 기본 사고방식 지원되는 수준
gemini-3.1-pro-preview 사용 설정 (높음) 낮음, 중간, 높음
gemini-3-flash-preview 사용 설정 (높음) 최소, 낮음, 중간, 높음
gemini-3-pro-preview 켜짐 (높음) 낮음, 높음
gemini-2.5-pro 사용 예산: 128~32768
gemini-2.5-flash 사용 예산: 0~24576
gemini-2.5-flash-lite 사용 안함 예산: 0~24576

사고 모델은 Gemini의 모든 도구 및 기능과 호환됩니다. 이를 통해 모델은 외부 시스템과 상호작용하고, 코드를 실행하고, 실시간 정보에 액세스하여 결과를 추론에 통합할 수 있습니다.

다음 단계