Gemini 3 시작하기

Gemini 3 는 최첨단 추론을 기반으로 구축된, 현재까지 가장 지능적인 모델 제품군입니다. 이 모델은 에이전트형 워크플로, 자율 코딩, 복잡한 멀티모달 작업을 정교하게 처리하여 어떠한 아이디어든 실현할 수 있도록 설계되었습니다.

이 가이드에서는 Gemini Enterprise Agent Platform에서 Gemini 3를 시작하기 위한 통합적이고 실용적인 경로를 제공하며, Gemini 3의 핵심 기능과 권장사항을 강조합니다.

빠른 시작

시작하기 전에 API 키 또는 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용해 Gemini Enterprise Agent Platform에 인증해야 합니다. 자세한 내용은 인증 방법 을 참조하세요.

Google 생성형 AI SDK 설치

Gemini 3 API 기능을 사용하려면 Python용 Google 생성형 AI SDK 버전 1.51.0 이상이 필요합니다.

pip install --upgrade google-genai

Gemini Enterprise Agent Platform에서 Google 생성형 AI SDK를 사용하도록 환경 변수를 설정합니다.

GOOGLE_CLOUD_PROJECT 값을 Google Cloud 프로젝트 ID로 바꿉니다. Gemini 3.1 Pro 모델 gemini-3.1-pro-preview 및 Gemini 3 Flash 모델 gemini-3-flash-preview는 글로벌 엔드포인트에서만 사용할 수 있습니다.

export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

첫 번째 요청하기

기본적으로 Gemini 3 모델과 Gemini 3 Flash는 동적 사고를 사용하여 프롬프트를 통해 추론합니다. 복잡한 추론이 필요하지 않은 경우 더 빠르고 지연 시간이 짧은 대답을 위해 모델의 thinking_level을 제한할 수 있습니다. 낮은 사고 수준은 속도가 최우선인 고처리량 작업에 적합합니다.

빠르고 지연 시간이 짧은 응답을 위해서는 다음을 수행하세요.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.6-flash",
   contents="How does AI work?",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.LOW # For fast and low latency response
       )
   ),
)
print(response.text)

복잡한 추론 작업 시도

Gemini 3는 고급 추론에서 뛰어난 성능을 보입니다. 다단계 계획, 검증된 코드 생성, 심층적인 도구 사용과 같은 복잡한 작업에는 높은 사고 수준을 사용하세요. 이 구성은 이전에는 전문적인 추론 모델이 필요했던 작업에 적합합니다.

더 느리지만 고급 추론이 필요한 작업의 경우 다음을 수행하세요.

from google import genai
from google.genai import types

client = genai.Client()

prompt = """
You are tasked with implementing the classic Thread-Safe Double-Checked Locking (DCL) Singleton pattern in modern C++. This task is non-trivial and requires specialized concurrency knowledge to prevent memory reordering issues.

Write a complete, runnable C++ program named `dcl_singleton.cpp` that defines a class `Singleton` with a private constructor and a static `getInstance()` method.

Your solution MUST adhere to the following strict constraints:
1. The Singleton instance pointer (`static Singleton*`) must be wrapped in `std::atomic` to correctly manage memory visibility across threads.
2. The `getInstance()` method must use `std::memory_order_acquire` when reading the instance pointer in the outer check.
3. The instance creation and write-back must use `std::memory_order_release` when writing to the atomic pointer.
4. A standard `std::mutex` must be used only to protect the critical section (the actual instantiation).
5. The `main` function must demonstrate safe, concurrent access by launching at least three threads, each calling `Singleton::getInstance()`, and printing the address of the returned instance to prove all threads received the same object.
"""

response = client.models.generate_content(
  model="gemini-3.6-flash",
  contents=prompt,
  config=types.GenerateContentConfig(
      thinking_config=types.ThinkingConfig(
          thinking_level=types.ThinkingLevel.HIGH # Dynamic thinking for high reasoning tasks
      )
  ),
)
print(response.text)

기타 사고 수준

Gemini 3 Flash는 모델이 복잡한 추론 작업을 처리하는 방식을 더욱 세밀하게 제어할 수 있도록 두 가지 새로운 사고 수준(MINIMAL 및 MEDIUM)을 도입합니다.

MINIMAL 은 추론이 아닌 처리량에 최적화된 작업에 대해 사고 예산 옵션을 0에 가깝게 제공합니다. MEDIUM 은 속도와 추론 간의 균형을 제공하여 어느 정도의 추론 기능을 허용하면서도 지연 시간이 짧은 작업을 우선시합니다.

새로운 API 기능

Gemini 3는 개발자가 성능(지연 시간, 비용), 모델 동작, 멀티모달 충실도를 보다 세밀하게 제어할 수 있도록 설계된 강력한 API 개선사항과 새로운 파라미터를 제공합니다.

다음 표에서는 사용 가능한 핵심 신규 기능과 매개변수를 요약하고, 각 기능의 상세 문서 링크를 제공합니다.

신규 기능/API 변경사항 문서
모델: gemini-3.1-pro-preview 모델 카드
Model Garden
사고 수준 사고
미디어 해상도 이미지 이해
동영상 이해
오디오 이해
문서 이해
생각 서명 생각 서명
온도 API 참조
멀티모달 함수 응답 함수 호출: 멀티모달 함수 응답
스트리밍 함수 호출 함수 호출: 스트리밍 함수 호출

사고 수준

thinking_level 파라미터를 사용하면 모델이 응답을 생성할 때 사용할 사고 예산을 지정할 수 있습니다. 두 가지 상태 중 하나를 선택하여 응답 품질과 추론 복잡성, 지연 시간과 비용 간의 균형을 명확하게 조정할 수 있습니다.

  • MINIMAL: (Gemini 3 Flash 및 Gemini 3.1 Flash-Lite만 해당) 모델이 사고에 가능한 한 적은 토큰을 사용하도록 제한하며 광범위한 추론의 이점을 누릴 수 없는 복잡성이 낮은 작업에 가장 적합합니다. MINIMAL은 사고 예산이 0에 최대한 가깝지만 여전히 생각 서명이 필요합니다.
  • LOW: 모델이 사고에 더 적은 토큰을 사용하도록 제한하며 광범위한 추론이 필요하지 않은 간단한 작업에 적합합니다. LOW 는 속도가 중요한 고처리량 작업에 적합합니다.
  • MEDIUM: (Gemini 3 Flash, Gemini 3.1 Pro, Gemini 3.1 Flash-Lite만 해당) 추론의 이점을 누릴 수 있지만 심층적인 다단계 계획이 필요하지 않은 적당한 복잡성의 작업에 적합한 균형 잡힌 접근 방식을 제공합니다. HIGH보다 지연 시간이 짧으면서도 LOW보다 더 많은 추론 기능을 제공합니다.
  • HIGH: 모델이 사고에 더 많은 토큰을 사용할 수 있도록 하며 다단계 계획, 검증된 코드 생성 또는 고급 함수 호출 시나리오와 같이 심층적인 추론이 필요한 복잡한 프롬프트에 적합합니다. Gemini 3 모델 및 Gemini 3 Flash의 기본 수준입니다. 이전에는 전문 추론 모델을 사용했을 수 있는 작업을 대체할 때 이 구성을 사용하세요.

Google 생성형 AI SDK 예시

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.6-flash",
   contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH # Default, dynamic thinking
       )
   ),
)
print(response.text)

OpenAI 호환성 예시

OpenAI 호환성 레이어를 사용하는 경우, 표준 파라미터는 자동으로 Gemini 3에 상응하는 파라미터로 매핑됩니다.

  • reasoning_effort는 thinking_level로 매핑됩니다.
  • none: thinking_level 최소값 (Gemini 3 Flash만 해당)으로 매핑됩니다.
  • medium: 모든 Gemini 3 모델의 thinking_level 중간값으로 매핑됩니다.
import openai
from google.auth import default
from google.auth.transport.requests import Request

credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])

client = openai.OpenAI(
    base_url=f"https://aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/global/endpoints/openapi",
    api_key=credentials.token,
)

prompt = """
Write a bash script that takes a matrix represented as a string with
format '[1,2],[3,4],[5,6]' and prints the transpose in the same format.
"""

response = client.chat.completions.create(
    model="gemini-3.6-flash",
    reasoning_effort="medium", # Map to thinking_level high.
    messages=[{"role": "user", "content": prompt}],
)

print(response.choices[0].message.content)

미디어 해상도

Gemini 3는 media_resolution 파라미터를 통해 멀티모달 비전 처리에 대한 세밀한 제어 기능을 제공합니다. 해상도가 높을수록 모델이 작은 텍스트를 읽거나 세부 요소를 식별하는 능력을 향상시키지만, 토큰 사용량과 지연 시간이 증가합니다. media_resolution 파라미터는 입력 이미지, PDF 페이지 또는 동영상 프레임당 할당되는 최대 토큰 수 를 결정합니다.

해상도는 전역적으로(generation_config 사용) 또는 개별 미디어 파트별로 low, medium, high로 설정할 수 있습니다. ultra_high 해상도는 개별 미디어 파트에만 설정할 수 있습니다. 지정하지 않으면 모델이 미디어 유형에 따라 최적의 기본값을 사용합니다.

토큰 수

이 표에는 각 media_resolution 값과 미디어 유형의 대략적인 토큰 수가 요약되어 있습니다.

미디어 해상도 이미지 동영상 PDF
UNSPECIFIED (기본값) 1120 70 560
LOW 280 70 280 + 텍스트
MEDIUM 560 70 560 + 텍스트
HIGH 1120 280 1120 + 텍스트
ULTRA_HIGH 2240 해당 사항 없음 해당 사항 없음
미디어 해상도 최대 토큰 수 사용 안내
ultra_high 2240 화면 녹화 스틸 또는 고해상도 사진 처리와 같이 이미지의 세부정보 분석이 필요한 작업
high 1120 최대 품질을 보장하기 위한 이미지 분석 작업
medium 560
low 이미지: 280 동영상: 70 대부분의 태스크에 충분합니다. 참고: 동영상의 경우 low는 프레임당 최대 70개 토큰입니다.
LOW

개별 파트별로 media_resolution 설정

개별 미디어 파트별로 media_resolution을 설정할 수 있습니다.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3.6-flash",
  contents=[
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
              mime_type="image/jpeg",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_HIGH # High resolution
          ),
      ),
      Part(
          file_data=types.FileData(
             file_uri="gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4",
            mime_type="video/mp4",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_LOW # Low resolution
          ),
      ),
      "When does the image appear in the video? What is the context?",
  ],
)
print(response.text)

전역적으로 media_resolution 설정

또한 GenerateContentConfig를 사용하여 media_resolution을 전역적으로 설정할 수도 있습니다.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3.6-flash",
  contents=[
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
              mime_type="image/jpeg",
          ),
      ),
      "What is in the image?",
  ],
  config=types.GenerateContentConfig(
      media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW, # Global setting
  ),
)
print(response.text)

생각 서명

생각 서명은 멀티턴 대화, 특히 함수 호출을 사용할 때 모델의 추론 상태를 보존하는 암호화된 토큰입니다.

사고 모델이 외부 도구를 호출하기로 결정하면 내부 추론 프로세스가 일시중지됩니다. 생각 서명은 "저장 상태"처럼 동작하여, 함수 결과를 제공하면 모델이 자신의 추론 흐름을 자연스럽게 이어갈 수 있도록 해줍니다.

자세한 내용은 생각 서명을 참조하세요.

생각 서명이 중요한 이유는 무엇인가요?

생각 서명이 없으면 모델은 도구 실행 단계에서 자신의 구체적인 추론 단계를 "잊어버리게" 됩니다. 서명을 다시 전달하면 다음을 보장할 수 있습니다.

  • 컨텍스트 연속성: 모델은 도구를 호출한 이유를 그대로 유지합니다.
  • 복잡한 추론: 한 도구의 출력이 다음 단계의 추론에 반영되는 다단계 작업을 가능하게 합니다.

생각 서명은 어디에서 반환되나요?

Gemini 3 모델과 Gemini 3 Flash는 Gemini 2.5에서 처음 도입된 생각 서명에 대해 더 엄격한 검증과 업데이트된 처리 방식을 적용합니다. 모델이 여러 턴의 대화에서 컨텍스트를 유지하도록 하려면 후속 요청에서 생각 서명을 반드시 반환해야 합니다.

  • MINIMAL 사고 수준을 사용하는 경우에도 함수 호출이 포함된 모델 응답에는 항상 생각 서명이 반환됩니다.
  • 병렬 함수 호출이 있는 경우 모델 응답에서 반환되는 첫 번째 함수 호출 파트에 생각 서명이 포함됩니다.
  • 순차적(다단계) 함수 호출이 있는 경우, 각 함수 호출에는 서명이 포함되며, 클라이언트는 이를 다시 전달해야 합니다.
  • 함수 호출이 없는 모델 응답의 경우, 모델에서 반환된 마지막 파트 내부에 생각 서명이 포함되어 반환됩니다.

생각 서명을 처리하는 방법

생각 서명을 처리하는 방법은 두 가지입니다. Google 생성형 AI SDK 또는 OpenAI API를 사용해 자동으로 처리하거나 API와 직접 상호작용할 경우 수동으로 처리할 수 있습니다.

자동 처리 (권장)

Google 생성형 AI SDK (Python, Node.js, Go, Java) 또는 OpenAI Chat Completions API를 사용하고 표준 채팅 기록 기능을 사용하거나 모델 응답 전체를 그대로 전달하는 경우, thought_signatures는 자동으로 처리됩니다. 코드를 변경할 필요가 없습니다.

수동 함수 호출 예시

Google 생성형 AI SDK를 사용할 때는, 순차적 모델 요청에 모델 응답 전체를 추가함으로써 생각 서명이 자동으로 처리됩니다.

from google import genai
from google.genai import types

client = genai.Client()

# 1. Define your tool
get_weather_declaration = types.FunctionDeclaration(
   name="get_weather",
   description="Gets the current weather temperature for a given location.",
   parameters={
       "type": "object",
       "properties": {"location": {"type": "string"}},
       "required": ["location"],
   },
)
get_weather_tool = types.Tool(function_declarations=[get_weather_declaration])

# 2. Send a message that triggers the tool
prompt = "What's the weather like in London?"
response = client.models.generate_content(
   model="gemini-3.6-flash",
   contents=prompt,
   config=types.GenerateContentConfig(
       tools=[get_weather_tool],
       thinking_config=types.ThinkingConfig(include_thoughts=True)
   ),
)

# 4. Handle the function call
function_call = response.function_calls[0]
location = function_call.args["location"]
print(f"Model wants to call: {function_call.name}")

# Execute your tool (e.g., call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {location}")
function_response_data = {
   "location": location,
   "temperature": "30C",
}

# 5. Send the tool's result back
# Append this turn's messages to history for a final response.
# The `content` object automatically attaches the required thought_signature behind the scenes.
history = [
    types.Content(role="user", parts=[types.Part(text=prompt)]),
    response.candidates[0].content, # Signature preserved here
    types.Content(
        role="user",
        parts=[
            types.Part.from_function_response(
                name=function_call.name,
                response=function_response_data,
            )
        ],
    )
]

response_2 = client.models.generate_content(
   model="gemini-3.6-flash",
   contents=history,
   config=types.GenerateContentConfig(
        tools=[get_weather_tool],
        thinking_config=types.ThinkingConfig(include_thoughts=True)
   ),
)

# 6. Get the final, natural-language answer
print(f"\nFinal model response: {response_2.text}")
자동 함수 호출 예시

Google 생성형 AI SDK에서 자동 함수 호출을 사용할 때도 생각 서명은 자동으로 처리됩니다.


from google import genai
from google.genai import types

def get_current_temperature(location: str) -> dict:
    """Gets the current temperature for a given location.

    Args:
        location: The city and state, for example San Francisco, CA

    Returns:
        A dictionary containing the temperature and unit.
    """
    # ... (implementation) ...
    return {"temperature": 25, "unit": "Celsius"}

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="What's the temperature in Boston?",
    config=types.GenerateContentConfig(
            tools=[get_current_temperature],
    )
)

print(response.text) # The SDK handles the function call and thought signature, and returns the final text
OpenAI 호환성 예시

OpenAI Chat Completions API를 사용할 때도, 연속 모델 요청에 모델 응답 전체를 추가하여 생각 서명이 자동으로 처리됩니다.

...
# Append user prompt and assistant response including thought signatures
messages.append(response1.choices[0].message)

# Execute the tool
tool_call_1 = response1.choices[0].message.tool_calls[0]
result_1 = get_current_temperature(**json.loads(tool_call_1.function.arguments))

# Append tool response to messages
messages.append(
    {
        "role": "user",
        "tool_call_id": tool_call_1.id,
        "content": json.dumps(result_1),
    }
)

response2 = client.chat.completions.create(
    model="gemini-3.6-flash",
    messages=messages,
    tools=tools,
    extra_body={
        "extra_body": {
            "google": {
                "thinking_config": {
                    "include_thoughts": True,
                },
            },
        },
    },
)

print(response2.choices[0].message.tool_calls)

전체 코드 예시를 참조하세요.

수동 처리

API와 직접 상호작용하거나 원시 JSON 페이로드를 관리하는 경우, 모델의 턴에 포함된 thought_signature를 올바르게 처리해야 합니다.

대화 기록을 다시 보낼 때는 이 서명을 수신했던 바로 그 파트에 정확히 반환해야 합니다.

올바른 서명이 반환되지 않으면, Gemini 3는 400 오류 "<콘텐츠 색인 배열> 콘텐츠 블록의 <Function Call>에 thought_signature가 없습니다"를 반환합니다.

멀티모달 함수 응답

멀티모달 함수 호출을 사용하면, 사용자 함수 응답에 멀티모달 객체를 포함할 수 있어, 모델의 함수 호출 기능을 더욱 효과적으로 활용할 수 있습니다. 표준 함수 호출은 텍스트 기반 함수 응답만 지원합니다.

from google import genai
from google.genai import types

client = genai.Client()

# This is a manual, two turn multimodal function calling workflow:

# 1. Define the function tool
get_image_declaration = types.FunctionDeclaration(
   name="get_image",
   description="Retrieves the image file reference for a specific order item.",
   parameters={
       "type": "object",
       "properties": {
            "item_name": {
                "type": "string",
                "description": "The name or description of the item ordered (e.g., 'green shirt')."
            }
       },
       "required": ["item_name"],
   },
)
tool_config = types.Tool(function_declarations=[get_image_declaration])

# 2. Send a message that triggers the tool
prompt = "Show me the green shirt I ordered last month."
response_1 = client.models.generate_content(
    model="gemini-3.6-flash",
    contents=[prompt],
    config=types.GenerateContentConfig(
        tools=[tool_config],
    )
)

# 3. Handle the function call
function_call = response_1.function_calls[0]
requested_item = function_call.args["item_name"]
print(f"Model wants to call: {function_call.name}")

# Execute your tool (e.g., call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {requested_item}")

function_response_data = {
  "image_ref": {"$ref": "dress.jpg"},
}

function_response_multimodal_data = types.FunctionResponsePart(
   file_data=types.FunctionResponseFileData(
      mime_type="image/png",
      display_name="dress.jpg",
      file_uri="gs://cloud-samples-data/generative-ai/image/dress.jpg",
   )
)

# 4. Send the tool's result back
# Append this turn's messages to history for a final response.
history = [
  types.Content(role="user", parts=[types.Part(text=prompt)]),
  response_1.candidates[0].content,
  types.Content(
    role="user",
    parts=[
        types.Part.from_function_response(
            name=function_call.name,
            response=function_response_data,
            parts=[function_response_multimodal_data]
        )
    ],
  )
]

response_2 = client.models.generate_content(
  model="gemini-3.6-flash",
  contents=history,
  config=types.GenerateContentConfig(
      tools=[tool_config],
      thinking_config=types.ThinkingConfig(include_thoughts=True)
  ),
)

print(f"\nFinal model response: {response_2.text}")

스트리밍 함수 호출

도구 사용 시 스트리밍 경험을 개선하기 위해, 부분 함수 호출 인수를 스트리밍 방식으로 사용할 수 있습니다. 이 기능은 stream_function_call_arguments를 true로 명시적으로 설정하여 사용 설정할 수 있습니다.

from google import genai
from google.genai import types

client = genai.Client()

get_weather_declaration = types.FunctionDeclaration(
  name="get_weather",
  description="Gets the current weather temperature for a given location.",
  parameters={
      "type": "object",
      "properties": {"location": {"type": "string"}},
      "required": ["location"],
  },
)
get_weather_tool = types.Tool(function_declarations=[get_weather_declaration])


for chunk in client.models.generate_content_stream(
   model="gemini-3.6-flash",
   contents="What's the weather in London and New York?",
   config=types.GenerateContentConfig(
       tools=[get_weather_tool],
       tool_config = types.ToolConfig(
           function_calling_config=types.FunctionCallingConfig(
               mode=types.FunctionCallingConfigMode.AUTO,
               stream_function_call_arguments=True,
           )
       ),
   ),
):
   function_call = chunk.function_calls[0]
   if function_call and function_call.name:
       print(f"{function_call.name}")
       print(f"will_continue={function_call.will_continue}")

모델 응답 예시:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "functionCall": {
              "name": "get_weather",
              "willContinue": true
            }
          }
        ]
      }
    }
  ]
}

온도

  • Range for Gemini 3: 0.0 - 2.0 (default: 1.0)

Gemini 3에서는 temperature 파라미터를 기본값인 1.0으로 유지하는 것이 가장 좋습니다.

이전 모델에서는 창의성과 결정성 간 균형을 위해 온도 조정이 도움이 되었지만, Gemini 3의 추론 기능은 기본 설정에 최적화되어 있습니다.

온도를 변경하여(1.0 미만으로 설정) 복잡한 수학적 또는 추론 작업에서 루핑이나 성능 저하와 같은 예기치 않은 동작이 발생할 수 있습니다.

지원되는 기능

Gemini 3 모델은 다음 기능도 지원합니다.

프롬프트 권장사항

Gemini 3는 추론 모델이므로 프롬프트 작성 방식에도 변화가 필요합니다.

  • 정확한 지시: 입력 프롬프트는 간결하게 작성하세요. Gemini 3는 직접적이고 명확한 지시에 가장 잘 반응합니다. 이전 모델에서 사용되던 장황하거나 지나치게 복잡한 프롬프트 엔지니어링 기법은 과분석을 유발할 수 있습니다.
  • 출력 장황도: 기본적으로 Gemini 3는 덜 장황하며, 직접적이고 효율적인 답변을 제공하는 것을 선호합니다. 보다 대화형이거나 "수다스러운" 스타일의 응답이 필요하다면, 프롬프트에서 명시적으로 모델을 유도해야 합니다 (예: "친근하고 말이 많은 조수처럼 설명해 주세요").
  • 그라운딩: 그라운딩 사용 사례의 경우 다음 개발자 안내를 사용하는 것이 좋습니다. You are a strictly grounded assistant limited to the information provided in the User Context. In your answers, rely **only** on the facts that are directly mentioned in that context. You must **not** access or utilize your own knowledge or common sense to answer. Do not assume or infer from the provided facts; simply report them exactly as they appear. Your answer must be factual and fully truthful to the provided text, leaving absolutely no room for speculation or interpretation. Treat the provided context as the absolute limit of truth; any facts or details that are not directly mentioned in the context must be considered **completely untruthful** and **completely unsupported**. If the exact answer is not explicitly written in the context, you must state that the information is not available.
  • Google 검색 도구 사용: Google 검색 도구를 사용할 때 Gemini 3 Flash는 2024년의 이벤트에 대한 현재 날짜 / 시간을 혼동할 수 있습니다. 이로 인해 모델이 잘못된 연도의 검색어를 작성할 수 있습니다. 모델이 올바른 기간을 사용하도록 하려면 system instructions에서 현재 날짜를 명시적으로 강화하세요. For time-sensitive user queries that require up-to-date information, you MUST follow the provided current time (date and year) when formulating search queries in tool calls. Remember it is 2025 this year.
  • 지식 단절 시점: 특정 쿼리의 경우 Gemini 3 Flash는 지식 단절 시점을 명시적으로 알려주는 것이 좋습니다. 이는 Google 검색 도구가 사용 중지되고 쿼리에서 모델이 매개변수 지식에서 단절 데이터를 식별할 수 있어야 하는 경우에 해당합니다. 권장사항: system instructions에 다음 절을 추가합니다. Your knowledge cutoff date is January 2025.
  • media_resolution 사용: media_resolution 파라미터를 사용하여 모델이 이미지 또는 동영상의 프레임을 나타내는 데 사용하는 최대 토큰 수를 제어합니다. 해상도가 높으면 모델이 이미지의 세부정보를 캡처할 수 있으며 프레임당 더 많은 토큰을 사용할 수 있는 반면, 해상도가 낮으면 시각적 세부정보가 적은 이미지의 비용과 지연 시간을 최적화할 수 있습니다.
  • 동영상 분석 개선: 빠른 액션 이해 또는 고속 모션 추적과 같이 세분화된 시간 분석이 필요한 동영상의 경우 초당 프레임 수 (FPS) 샘플링 레이트를 높게 사용합니다.

마이그레이션 고려사항

마이그레이션할 때 다음 기능과 제약 조건을 고려하세요.

  • 사고 수준: Gemini 3 모델은 thinking_level 파라미터를 사용해 모델이 수행하는 내부 추론량 (낮음 또는 높음)을 제어하고, 응답 품질, 추론 복잡성, 지연 시간, 비용 간의 균형을 맞춥니다.
  • 온도 설정: 기존 코드에서 temperature를 명시적으로 설정하고 있다면 (특히 결정적 출력을 위해 낮은 값으로 설정한 경우), 해당 파라미터를 삭제하고 Gemini 3의 기본값인 1.0을 사용하는 것이 좋습니다. 이는 복잡한 작업에서 잠재적인 루핑 문제나 성능 저하를 방지하는 위함입니다.
  • 생각 서명: Gemini 3 모델에서는 특정 턴에 생각 서명이 필요함에도 제공되지 않으면 모델에서 경고 대신 오류가 반환됩니다.
  • 미디어 해상도 및 토큰화: Gemini 3 모델은 팬 및 스캔 방식 대신 가변 시퀀스 길이를 사용해 미디어를 토큰화하며, 이미지, PDF, 동영상에 대해 새로운 기본 해상도와 토큰 비용을 적용합니다.
  • 멀티모달 입력의 토큰 수 계산: 멀티모달 입력 (이미지, 동영상, 오디오)의 토큰 계산은 선택한 media_resolution을 기반으로 한 추정치입니다. 따라서 count_tokens API 호출의 결과가 실제 소비된 최종 토큰 수와 일치하지 않을 수 있습니다. 청구에 사용되는 정확한 사용량은 실행 후 응답의 usage_metadata에서만 확인할 수 있습니다.
  • 토큰 소비량: Gemini 3 기본값으로 마이그레이션하면 이미지 및 PDF의 토큰 사용량은 증가 할 수 있지만 동영상의 토큰 사용량은 감소 할 수 있습니다. 기본 해상도 상승으로 인해 요청이 컨텍스트 윈도우를 초과한다면 미디어 해상도를 명시적으로 낮추는 것이 좋습니다.
  • PDF 및 문서 이해: PDF의 기본 OCR 해상도가 변경되었습니다. 밀도 높은 문서 파싱을 위해 특정 동작에 의존하고 있었다면, 정확도를 유지하기 위해 새로운 media_resolution: "high" 설정을 테스트해 보세요. Gemini 3 모델에서는 usage_metadata에서 PDF 토큰 수가 DOCUMENT가 아니라 IMAGE 모달리티로 보고됩니다.
  • 이미지 분할: Gemini 3 모델에서는 이미지 분할 기능이 지원되지 않습니다. 기본 제공되는 이미지 분할 기능이 필요한 워크로드의 경우, 사고를 끈 상태의 Gemini 2.5 Flash를 계속 사용하는 것이 좋습니다.
  • 멀티모달 함수 응답: Gemini 3 모델에서는 함수 응답에 이미지 및 PDF 데이터를 포함할 수 있습니다.

FAQ

  1. Google Cloud에서 gemini-3.1-pro-preview 는 어느 리전에서 사용할 수 있나요? 전역에서 사용할 수 있습니다.

  2. 컨텍스트 윈도우 한도는 어떻게 되나요? Gemini 3 모델은 최대 100만 토큰의 입력 컨텍스트 윈도우와 최대 64,000의 토큰 출력을 지원합니다.

  3. gemini-3.1-pro-preview는 이미지 출력을 지원하나요? 아니요.

  4. gemini-3.1-pro-preview는 Gemini Live API를 지원하나요? 아니요.

다음 단계