Gemini Deep Research를 이제 공동 계획, 시각화, MCP 지원 등과 함께 미리보기로 이용할 수 있습니다.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Gemini 3.5 Flash의 새로운 기능

참고: generateContent를 보고 있습니다. 새 프로젝트의 경우 에이전트 워크플로, 백그라운드 작업, 향후 Gemini 기능을 위해 빌드된 새로운 Interactions API (베타)를 사용하는 것이 좋습니다.

Gemini 3.5 Flash는 정식 버전 (GA)으로 출시되었으며 안정적이고 확장된 프로덕션 환경에서 사용할 수 있습니다. 가장 지능적인 Flash 모델인 Gemini 2.5 Flash는 에이전트형 실행, 코딩, 장기적 작업에서 지속적으로 최첨단 성능을 대규모로 제공합니다.

이 가이드에는 Gemini 3.5 Flash의 개선사항, API 변경사항, 이전 안내가 포함되어 있습니다.

새 모델

모델	모델 ID	설명
Gemini 3.5 Flash	`gemini-3.5-flash`	에이전트형 및 코딩 작업에서 지속적으로 최첨단 성능을 발휘하는 가장 지능적인 모델입니다.

Gemini 3.5 Flash는 100만 토큰 컨텍스트 윈도우, 최대 65,000개의 출력 토큰, 사고, Gemini 3 Flash와 동일한 도구 및 플랫폼 기능을 지원합니다. 컴퓨터 사용은 현재 지원되지 않습니다.

전체 사양은 모델 개요를 참고하세요. 가격은 가격 책정 페이지를 참고하세요.

빠른 시작

이 가이드의 모든 예시에서는 GenerateContent API를 사용합니다. Interactions API도 지원되며 동일한 구성 옵션과 권장사항이 적용됩니다.

Python

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain how parallel agentic execution works in three sentences.",
)
print(response.text)

자바스크립트

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Explain how parallel agentic execution works in three sentences.",
  });
  console.log(response.text);
}

main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Explain how parallel agentic execution works in three sentences."}]
    }]
  }'

새로운 소식

지속적인 최첨단 성능: 대규모 에이전트형 및 코딩 작업에 최적화된 Google의 가장 지능적인 Flash 모델입니다.
에이전트 실행: 하위 에이전트 배포, 문제 해결, 대규모의 빠른 에이전트 루프
코딩: 대체 경로를 테스트하고 솔루션을 동적으로 탐색하기 위한 반복적인 코딩 주기, 신속한 탐색, 프로토타입 제작
장기: 대규모 다단계 워크플로 및 도구 사용
사고 보존: 모델은 멀티턴 대화에서 중간 추론을 자동으로 유지합니다. API를 변경할 필요가 없습니다.
새 기본 노력 수준: 기본 사고 노력이 high에서 medium로 변경되었습니다. 자세한 내용은 새 기본 노력 수준을 참고하세요.
low 사고방식 개선: 이제 low이 단계가 적게 필요한 코드 및 에이전트 작업에 대해 크게 개선되어 낮은 지연 시간과 비용으로 강력한 품질을 제공합니다.
GA 출시: 확장된 프로덕션 사용을 위한 안정 모델입니다.

동작 변경사항

새 기본 노력 수준: `medium`

이제 기본 사고 노력은 Gemini 3 Flash 프리뷰의 high에서 medium로 변경되었습니다. medium는 다양한 작업에서 매우 우수한 결과를 제공하면서도 더 빠르고 비용 효율적입니다. 복잡한 문제의 경우 high는 모델이 더 깊이 생각하도록 유도합니다.

노력 수준	용도
`minimal`	응답 속도에 최적화되어 있습니다. 채팅과 유사한 사용 사례, 빠른 사실 기반 답변, 더 간단한 도구 호출
`low`	지연 시간이 짧고 단계가 적은 코드 및 에이전트 작업 또한 어느 정도의 사고가 필요한 분석 및 글쓰기 작업에도 적합합니다.
`medium` (기본값)	대부분의 작업에 가장 적합한 품질입니다. 복잡한 코드 및 에이전트 사용 사례에 권장됩니다.
`high`	모델의 사고 및 도구 사용 능력을 극대화합니다. 복잡한 추론, 어려운 수학, 가장 어려운 코드 또는 에이전트 작업에 적합합니다. 확장된 생각과 함수 호출을 허용합니다.

기본값을 재정의하려면 구성에서 thinking_level를 설정하세요.

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Prove that the square root of 2 is irrational.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high")
    ),
)

print(response.text)

자바스크립트

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Prove that the square root of 2 is irrational.",
    config: {
      thinkingConfig: {
        thinkingLevel: "HIGH",
      },
    },
  });
  console.log(response.text);
}

main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Prove that the square root of 2 is irrational."}]
    }],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingLevel": "HIGH"
      }
    }
  }'

생각 보존

모델은 멀티턴 대화에서 중간 추론을 자동으로 유지합니다. 추론 컨텍스트는 대화 기록에 있는 경우 전달되므로 반복적인 디버깅 및 코드 리팩터링과 같은 복잡한 다단계 작업의 성능이 향상됩니다. API 변경이 필요하지 않습니다.

상호작용 API: 생각이 이미 자동으로 보존됩니다. 동작이 변경되지 않습니다.
GenerateContent API: Gemini 3.5 Flash부터 모델은 대화 기록에 생각 서명이 있는 경우 이전 모든 턴의 추론 컨텍스트를 사용합니다. 이 기능을 사용 설정하려면 contents에 수정되지 않은 전체 대화 기록 (사고 서명 포함)을 전달하세요. SDK는 이 작업을 자동으로 처리합니다.

Gemini 3.x의 파라미터 업데이트 및 권장사항

다음은 Gemini 3.5 Flash를 비롯한 모든 Gemini 3.x 모델에 적용됩니다.

temperature, top_p, top_k: 기본값을 변경하지 않는 것이 좋습니다. Gemini 3의 추론 기능은 기본 설정에 최적화되어 있습니다.
thinking_budget 대신 thinking_level를 사용합니다.
함수 호출 응답 일치: id, name, 응답 수가 이전 호출과 일치해야 합니다.
멀티모달 함수 응답: 함수 응답 외부에 아닌 내부에 멀티모달 콘텐츠를 포함합니다.
함수 응답의 인라인 안내: 별도의 부분이 아닌 함수 응답 텍스트에 추가합니다.
불필요한 도구 호출 줄이기: 낮은 사고 수준을 사용하거나 시스템 프롬프트를 실험하여 에이전트 워크플로에서 도구 호출을 줄입니다.

코드를 업데이트하는 방법은 아래 섹션을 참고하세요.

샘플링 매개변수 (더 이상 권장되지 않음)

temperature, top_p, top_k는 더 이상 모든 Gemini 3.x 모델에 권장되지 않습니다. Gemini 3의 추론 기능은 기본 설정에 최적화되어 있습니다. 모든 요청에서 이러한 매개변수를 삭제합니다.

# ⚠️ Remove these parameters (not recommended)
config = types.GenerateContentConfig(
    temperature=0.7,
    top_p=0.9,
    top_k=40
)

결정성을 보장하려면 특정 사용 사례에 대한 명시적 규칙이 포함된 시스템 명령어를 정의하는 것이 좋습니다.

`thinking_budget` (더 이상 권장되지 않음)

이제 모든 Gemini 3.x 모델에서 원시 숫자 thinking_budget 매개변수를 사용하는 것이 권장되지 않습니다. 대신 thinking_level 문자열 enum을 사용하세요.

# ⚠️ Before (not recommended)
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_budget=7500)
)

# ✅ After
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="medium")
)

사용 가능한 값: minimal, low, medium (기본값), high

함수 호출: 엄격한 응답 일치

상호작용 API는 이미 불일치 함수 응답에 대해 오류를 발생시킵니다. GenerateContent API는 아직 오류를 발생시키지 않지만, 불일치하는 대답으로 인해 모델이 대부분의 경우 finish_reason: STOP이 포함된 빈 대답을 반환합니다. 항상 다음 규칙을 따르세요.

요구사항	세부정보
`id` 포함	모든 `FunctionResponse`에는 해당 `FunctionCall`의 `id`이 포함되어야 합니다.
`name`차전	대답의 `name`은 호출의 `name`과 일치해야 합니다.
일치 항목 수	수신된 각 `FunctionCall`에 대해 정확히 하나의 `FunctionResponse` 반환

Python

# ✅ Include matching id and name in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result},
                id=tool_call.id,
            )
        ]),
    ],
)

자바스크립트

// ✅ Include matching id and name in the function response
const functionResponsePart = {
  functionResponse: {
    name: toolCall.name,
    response: { result: result },
    id: toolCall.id,
  },
};

const finalResponse = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: [
    ...previousContents,
    { role: "model", parts: [{ functionCall: toolCall }] },
    { role: "user", parts: [functionResponsePart] },
  ],
  config: config,
});

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "..."}]},
      {"role": "model", "parts": [{"functionCall": {"name": "my_function", "args": {...}}}]},
      {"role": "user", "parts": [{"functionResponse": {"name": "my_function", "id": "call_id", "response": {"result": "..."}}}]}
    ]
  }'

멀티모달 함수 응답

클라이언트가 함수 응답 외부에 이미지를 제공하는 경우가 많습니다. 이로 인해 예기치 않은 모델 동작 (예: 생각 누출)이 발생하고 출력 품질이 저하될 수 있습니다. 대신 멀티모달 함수 응답 API 문서의 권장사항을 따르고 모델에 전송하는 함수 응답 부분에 멀티모달 콘텐츠를 포함하세요. 모델은 다음 차례에 이 멀티모달 콘텐츠를 처리하여 더 많은 정보를 바탕으로 응답을 생성할 수 있습니다.

Python

# ✅ Include multimodal content in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={
                    "result": "instrument.jpg",
                    "image": base64_image_data,
                },
                id=tool_call.id,
            )
        ]),
    ],
)

자바스크립트

// ✅ Include multimodal content in the function response
const finalResponse = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: [
    ...previousContents,
    { role: "model", parts: [{ functionCall: toolCall }] },
    {
      role: "user",
      parts: [{
        functionResponse: {
          name: toolCall.name,
          id: toolCall.id,
          response: {
            result: "instrument.jpg",
            image: base64ImageData,
          },
        },
      }],
    },
  ],
  config: config,
});

함수 응답의 인라인 명령어

클라이언트는 함수 응답과 함께 추가 안내를 후속 Parts로 제공하는 경우가 많습니다. 이로 인해 예기치 않은 모델 동작 (예: 생각 누출)이 발생하고 출력 품질이 저하될 수 있습니다. 대신, 추가 지침을 함수 응답 텍스트 끝에 두 개의 줄바꿈으로 구분하여 추가하세요.

Python

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result_text},
                id=tool_call.id,
            )
        ]),
    ],
)

자바스크립트

// ✅ Append inline instructions to the end of the function response separated by two newlines
const resultText = `${JSON.stringify(result)}\n\n<your inline instructions>`;

const finalResponse = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: [
    ...previousContents,
    { role: "model", parts: [{ functionCall: toolCall }] },
    {
      role: "user",
      parts: [{
        functionResponse: {
          name: toolCall.name,
          id: toolCall.id,
          response: { result: resultText },
        },
      }],
    },
  ],
  config: config,
});

불필요한 도구 호출 줄이기

도구 호출이 과도하게 사용되는 경우 다음 두 가지 기법을 사용하면 도구 호출을 최소화할 수 있습니다.

사고 수준 낮추기 (medium, low 또는 minimal): 사고 수준이 높을수록 모델이 더 많은 도구를 사용하여 탐색하고 검증하므로 수준을 낮추면 도구 호출을 줄일 수 있습니다.
시스템 안내 추가: 사고 수준을 조정한 후에도 과도한 사용이 지속되면 도구 사용을 제한하는 프롬프트를 고려하세요. 예를 들면 다음과 같습니다.
```
You have a limited action budget of <n> tool calls. Use them efficiently.
```

마이그레이션 체크리스트

Gemini 3 Flash 프리뷰에서 마이그레이션

모델 이름 업데이트: gemini-3-flash-preview → gemini-3.5-flash
가격 책정 검토 Gemini 3.5 Flash는 Gemini 3 Flash 프리뷰보다 가격이 비쌉니다. 자세한 내용은 가격 책정 페이지를 참고하세요.
구성에서 temperature, top_p, top_k를 삭제합니다 (더 이상 권장되지 않음).
thinking_budget를 thinking_level로 바꿉니다.
모든 FunctionResponse 파트에 id 및 일치하는 name 추가
프롬프트를 테스트합니다. 기본 노력이 high에서 medium로 변경되었습니다. 품질, 속도, 비용을 확인하세요.
이제 생각 보존이 기본적으로 사용 설정되어 있습니다. 추론 컨텍스트는 턴을 거치면서 전달되므로 성능이 향상되지만 토큰 사용량이 증가할 수 있습니다.
불필요한 도구 호출 줄이기: 사고 수준(medium, low 또는 minimal)을 줄이는 것부터 시작하고, 과도한 사용이 지속되면 도구 사용을 제한하는 시스템 명령어를 추가합니다.
현재 Gemini 3.5 Flash에서는 컴퓨터 사용이 지원되지 않습니다. 컴퓨터 사용 워크로드의 경우 Gemini 3 Flash 프리뷰를 계속 사용하세요.

Gemini 2.5에서 마이그레이션

위의 모든 항목과 다음 항목을 포함

프롬프트 간소화 연쇄적 사고 프롬프트 엔지니어링을 사용하여 추론을 강제한 경우 대신 더 간단한 프롬프트로 thinking_level: "medium" 또는 "high"를 사용해 보세요.
PDF 및 미디어 워크로드를 테스트합니다. 밀도 높은 문서 파싱을 위해 특정 동작에 의존하고 있었다면, 정확도를 유지하기 위해 media_resolution_high 설정을 테스트해 보세요. Gemini 3 기본값으로 마이그레이션하면 PDF의 토큰 사용량은 증가할 수 있지만 동영상의 토큰 사용량은 감소할 수 있습니다. 요청이 컨텍스트 윈도우를 초과하는 경우 media_resolution를 명시적으로 줄이세요. 자세한 내용은 미디어 해상도 문서를 참고하세요.
결합된 도구 사용을 활용합니다. Google 검색, URL 컨텍스트, 코드 실행, 맞춤 함수는 동일한 요청에서 사용할 수 있습니다.
멀티모달 함수 응답을 사용하는 경우 멀티모달 콘텐츠를 함수 응답 부분 내부에 배치하세요.
함수 응답과 함께 인라인 명령어를 사용하는 경우 별도의 부분으로가 아닌 두 개의 줄바꿈으로 구분된 함수 응답 텍스트에 추가합니다.
Gemini 3.x에서는 이미지 분할이 지원되지 않습니다. 분할 워크로드의 경우 사고가 사용 중지된 Gemini 2.5 Flash 또는 Gemini Robotics-ER 1.6을 계속 사용하세요.

Gemini 3 제품군 기능

Gemini 3.5 Flash는 Computer Use를 제외한 모든 Gemini 3 제품군 기능을 상속합니다. Gemini 3에서 도입되어 계속 사용되는 기능:

생각: API 호출 전반에 걸쳐 유지되는 암호화된 추론 컨텍스트입니다. Interactions API에서는 자동입니다. GenerateContent에서는 암시적입니다.
도구를 사용한 구조화된 출력: JSON 모드를 기본 제공 도구 (검색, URL 컨텍스트, 코드 실행, 함수 호출)와 결합합니다.
멀티모달 함수 응답: 함수 호출 결과에 이미지, 오디오, 기타 미디어를 반환합니다.
이미지를 사용한 코드 실행: 이미지를 처리하고 생성하는 코드를 실행합니다.
결합된 도구 사용: 동일한 요청에서 기본 제공 도구와 맞춤 함수 호출을 사용합니다.

다음 단계

Gemini 3 개발자 가이드에서 Gemini 3 제품군에 대해 자세히 알아보세요.
프롬프트 엔지니어링 가이드에서 프롬프트 설계 전략에 대해 자세히 알아보세요.
Gemini 3 Cookbook 시작하기
Gemini API 최적화 및 추론 알아보기

Gemini 3.5 Flash의 새로운 기능

새 모델

빠른 시작

Python

자바스크립트

REST

새로운 소식

동작 변경사항

새 기본 노력 수준: medium

Python

자바스크립트

REST

생각 보존

Gemini 3.x의 파라미터 업데이트 및 권장사항

샘플링 매개변수 (더 이상 권장되지 않음)

thinking_budget (더 이상 권장되지 않음)

함수 호출: 엄격한 응답 일치

Python

자바스크립트

REST

멀티모달 함수 응답

Python

자바스크립트

함수 응답의 인라인 명령어

Python

자바스크립트

불필요한 도구 호출 줄이기

마이그레이션 체크리스트

Gemini 3 Flash 프리뷰에서 마이그레이션

Gemini 2.5에서 마이그레이션

Gemini 3 제품군 기능

다음 단계

새 기본 노력 수준: `medium`

`thinking_budget` (더 이상 권장되지 않음)