Gemini 3.5 Flash의 새로운 기능

Gemini 3.5 Flash의 새로운 기능 (What's new)

Gemini 3.5 Flash는 일반 공급(GA) 상태로 안정적이며, 규모 있는 프로덕션 사용에 준비된 모델이에요. 가장 지능적인 Flash 모델로서 에이전트 실행, 코딩, 장기 지평(long-horizon) 작업에서 지속적인 프런티어 성능을 제공해요.

이 가이드는 Gemini 3.5 Flash의 개선 사항, API 변경, 마이그레이션 지침 개요를 담고 있어요.

출처: 원문

본문

새 모델 (New model)

모델	모델 ID	설명
Gemini 3.5 Flash	gemini-3.5-flash	에이전트·코딩 작업에서 지속적인 프런티어 성능을 제공하는 가장 지능적인 모델.

Gemini 3.5 Flash는 1M 토큰 컨텍스트 창, 65k 최대 출력 토큰, 추론(thinking), 그리고 Computer Use (Preview)를 포함한 Gemini 3 Flash와 동일한 도구·플랫폼 기능 집합을 지원해요. 전체 사양은 모델 개요를, 가격은 가격 페이지를 참고하세요.

Quickstart

이 가이드의 모든 예시는 GenerateContent API를 사용해요. Interactions API도 지원되며, 동일한 구성 옵션과 권장 사항이 적용돼요.

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();

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

새로운 기능 (What's new)

지속적인 프런티어 성능(Sustained frontier performance): 규모 있는 에이전트·코딩 작업에 최적화된 가장 지능적인 Flash 모델.
에이전트 실행(Agentic execution): 하위 에이전트 배포, 문제 해결, 규모 있는 빠른 에이전트 루프.
코딩(Coding): 대체 경로를 테스트하고 솔루션을 동적으로 탐색하기 위한 반복 코딩 사이클, 빠른 탐색, 프로토타이핑.
장기 지평(Long horizon): 규모 있는 다단계 워크플로와 도구 사용.
생각 보존(Thought preservation): 모델이 다중 턴 대화에서 중간 추론을 자동으로 유지해요. API 변경이 필요 없어요.
새 기본 노력 수준: 기본 추론 노력이 high에서 medium으로 바뀌었어요. 자세한 내용은 새 기본 노력 수준 참고.
개선된 저수준 추론(Improved low thinking): low가 단계가 적은 코드·에이전트 작업에서 크게 개선되어, 더 낮은 지연 시간과 비용으로 강력한 품질을 제공해요.
GA 릴리스: 규모 있는 프로덕션 사용을 위한 안정 모델.

올바른 Flash 모델 선택하기 (Choosing the right Flash model)

Gemini 3.5 Flash는 가장 지능적이고 유능한 Flash 모델이에요. 하지만 사용 사례마다 비용과 지연 시간 요구 사항이 다를 수 있어요.

Gemini 3.1 Flash-Lite: 3.5 Flash의 고급 추론 깊이가 필요 없는 저비용·고볼륨 작업에는 Gemini 3.1 Flash-Lite를 권장해요. 효율성에 최적화된 안정적 장기 모델이죠. 자세한 내용은 Flash-Lite 개발자 가이드를 참고하세요.
Gemini 3 Flash Preview: GA 안정성과 개선된 추론을 위해 3.5 Flash로 마이그레이션하기를 권장하지만, 미리보기 모델로 계속 테스트하려는 개발자를 위해 Gemini 3 Flash (Preview)는 계속 사용할 수 있어요.

동작 변화 (Behavioral changes)

새 기본 노력 수준: `medium`

기본 추론 노력은 이제 medium이에요. Gemini 3 Flash Preview에서 high에서 바뀐 거죠. medium은 넓은 범위의 작업에서 매우 좋은 결과를 내면서도 더 빠르고 비용 효율적이에요. 복잡한 문제에서는 high가 모델이 더 깊이 생각하도록 유도해요.

노력 수준	사용 시점
minimal	응답 속도에 최적화. 채팅형 사용 사례, 빠른 사실 답변, 더 간단한 도구 호출.
low	더 낮은 지연 시간과 더 적은 단계가 필요한 코드·에이전트 작업. 약간의 추론이 필요한 분석·작성 작업에도 잘 맞음.
medium (기본값)	대부분 작업에서 최고 품질. 복잡한 코드·에이전트 사용 사례에 권장.
high	모델의 추론·도구 사용 능력을 극대화. 복잡한 추론, 어려운 수학, 가장 어려운 코드·에이전트 작업에 최적. 확장된 생각과 함수 호출 허용.

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

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();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-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"
      }
    }
  }'

팁: medium으로 시작하세요. 대부분 작업에서 최고 품질을 제공해요. 더 빠르고 저렴한 경험을 원하면 low를, 복잡한 추론·어려운 수학·어려운 코딩 문제에는 high로 전환하세요. 단순한 질문에서 속도에 최적화하려면 minimal을 사용하세요.

다음 표는 모델별 지원되는 추론 수준을 보여줘요:

추론 수준	Gemini 3.5 Flash	Gemini 3.1 Pro	Gemini 3.1 Flash-Lite	Gemini 3 Flash	설명
minimal	지원	미지원	지원(기본값)	지원	대부분 질문에서 "생각 없음" 설정과 일치. 참고로 minimal은 생각이 꺼짐을 보장하지 않아, 복잡한 작업에서는 모델이 최소한으로만 추론할 수 있어요.
low	지원	지원	지원	지원	지연 시간과 비용 최소화.
medium	지원(기본값)	지원	지원	지원	대부분 작업에 대한 균형 잡힌 추론.
high	지원(동적)	지원(기본값, 동적)	지원(동적)	지원(기본값, 동적)	추론 깊이 극대화.

중요: 같은 요청에서 thinking_level과 레거시 thinking_budget 매개변수를 함께 사용할 수 없어요. 함께 쓰면 400 오류가 반환돼요.

생각 보존 (Thought preservation)

모델은 다중 턴 대화에서 중간 추론을 자동으로 유지해요. 대화 기록에 추론 컨텍스트가 있으면 앞으로 전달되어, 반복 디버깅이나 코드 리팩터링 같은 복잡한 다단계 작업에서 성능이 향상돼요. API 변경이 필요 없어요:

Interactions API: 생각이 이미 자동으로 보존돼요. 동작 변화 없음.
GenerateContent API: Gemini 3.5 Flash부터 모델은 생각 서명(thought signatures)이 대화 기록에 있을 때 이전 턴의 추론 컨텍스트를 사용해요. 활성화하려면 전체 수정되지 않은 대화 기록(생각 서명 포함)을 contents로 전달하세요. SDK가 자동으로 처리해요.

참고: GenerateContent API 사용 시 보존된 생각은 여러 턴에 걸쳐 입력 토큰 수를 늘려요. 단순한 질문에서는 지워 비용을 줄일 수 있어요. 자세한 내용은 생각 서명 가이드를 참고하세요.

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` (더 이상 권장하지 않음)

숫자 기반의 원시 thinking_budget 매개변수는 모든 Gemini 3.x 모델에서 더 이상 권장되지 않아요. 대신 thinking_level 문자열 열거형을 사용하세요.

# ⚠️ 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.

함수 호출: 엄격한 응답 매칭

Interactions API는 이미 불일치 함수 응답에서 오류를 반환해요. GenerateContent API는 아직 오류를 내지 않지만, 불일치 응답은 대부분의 경우 finish_reason: STOP으로 빈 응답을 반환하게 해요. 항상 다음 규칙을 따르세요:

요구 사항	세부 사항
id 포함	모든 FunctionResponse는 해당 FunctionCall의 id를 포함해야 해요
name 매칭	응답의 name이 호출의 name과 일치해야 해요
수 일치	받은 각 FunctionCall에 대해 정확히 하나의 FunctionResponse를 반환해야 해요

# ✅ 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,
});

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-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": "..."}}}]}
    ]
  }'

멀티모달 함수 응답 (Multimodal function responses)

우리는 종종 클라이언트가 함수 응답 밖에 이미지를 제공하는 것을 봐요. 이는 예기치 않은 모델 동작(예: 생각 누출)을 유발하고 출력 품질을 낮출 수 있어요. 멀티모달 함수 응답 API 문서의 권장 사항 대신 멀티모달 콘텐츠를 모델로 보내는 함수 응답 파트에 포함하세요. 모델은 다음 턴에서 이 멀티모달 콘텐츠를 처리해 더 정보에 기반한 응답을 만들 수 있어요.

# ✅ 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,
});

함수 응답의 인라인 지시 (Inline instructions in function responses)

우리는 종종 클라이언트가 함수 응답과 함께 추가 지시를 별도의 Parts로 제공하는 것을 봐요. 이는 예기치 않은 모델 동작(생각 누출 등)을 유발하고 출력 품질을 낮출 수 있어요. 대신 추가 지시를 두 개의 줄바꿈으로 구분해 함수 응답 텍스트 끝에 추가하세요.

# ✅ 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.

마이그레이션 체크리스트 (Migration checklist)

Gemini 3 Flash Preview에서 마이그레이션

모델 이름 업데이트: gemini-3-flash-preview → gemini-3.5-flash
가격을 검토하세요. Gemini 3.5 Flash는 Gemini 3 Flash Preview보다 비싸요. 비용에 매우 민감한 사용 사례라면 Gemini 3.1 Flash-Lite로 마이그레이션하는 걸 고려하세요. 자세한 내용은 가격 페이지 참고.
구성에서 temperature, top_p, top_k를 제거하세요(더 이상 권장되지 않음).
thinking_budget을 thinking_level로 교체하세요.
모든 FunctionResponse 파트에 id와 일치하는 name을 추가하세요.
프롬프트를 테스트하세요. 기본 노력이 high → medium으로 바뀌었으므로 품질·속도·비용을 검증하세요.
생각 보존이 이제 기본적으로 켜져 있어요. 추론 컨텍스트가 턴을 넘어 전달되어 성능은 좋아지지만 토큰 사용량이 늘 수 있어요.
불필요한 도구 호출 줄이기: 먼저 추론 수준을 낮추고(medium, low, minimal), 지속되면 시스템 지시어로 도구 사용을 제한하세요.
Computer Use가 지원돼요.

Gemini 2.5에서 마이그레이션

위의 모든 사항에 더해:

프롬프트를 단순화하세요. 추론을 강제하기 위해 사고 사슬(chain-of-thought) 프롬프트 엔지니어링을 썼다면 thinking_level: "medium"이나 "high"를 더 단순한 프롬프트와 함께 시도하세요.
PDF와 미디어 워크로드를 테스트하세요. 밀집 문서 파싱의 특정 동작에 의존했다면 media_resolution_high 설정을 테스트해 정확도가 유지되는지 확인하세요. Gemini 3 기본값으로 마이그레이션하면 PDF 토큰 사용량은 늘지만 비디오는 줄 수 있어요. 요청이 컨텍스트 창을 초과하면 media_resolution을 명시적으로 낮추세요. 자세한 내용은 미디어 해상도 문서 참고.
결합 도구 사용을 활용하세요. Google 검색, URL 컨텍스트, 코드 실행, 커스텀 함수를 같은 요청에서 쓸 수 있어요.
멀티모달 함수 응답을 사용한다면, 멀티모달 콘텐츠를 함수 응답 파트 안으로 옮기세요(곁에 두지 말고).
함수 응답과 함께 인라인 지시를 쓴다면, 별도의 파트가 아니라 두 개의 줄바꿈으로 구분해 함수 응답 텍스트에 추가하세요.
이미지 분할(segmentation)은 Gemini 3.x에서 지원되지 않아요. 분할 워크로드는 추론을 끈 Gemini 2.5 Flash를 계속 사용하세요.
구성에서 candidate_count를 제거하세요(Gemini 3.x에서 지원되지 않음).

Gemini 3 계열 기능 (Gemini 3 family features)

Gemini 3.5 Flash는 Computer Use를 포함해 모든 Gemini 3 계열 기능을 물려받아요. Gemini 3에서 도입되어 이어지는 기능:

추론(Thinking): API 호출을 가로질러 보존되는 암호화된 추론 컨텍스트. Interactions API에서는 자동, GenerateContent에서는 암묵적.
도구와 구조화된 출력: JSON 모드를 내장 도구(검색, URL 컨텍스트, 코드 실행, 함수 호출)와 결합.
멀티모달 함수 응답: 함수 호출 결과에 이미지, 오디오, 기타 미디어 반환.
이미지가 있는 코드 실행: 이미지를 처리·생성하는 코드 실행.
결합 도구 사용: 내장 도구와 커스텀 함수 호출을 같은 요청에서 사용.
미디어 해상도: 이미지·비디오·PDF 입력에 대한 토큰 할당의 세밀한 제어. Gemini 3 모델은 혼합 충실도 프롬프트를 위한 콘텐츠 항목별 해상도 설정(low, medium, high, ultra_high)을 지원해요.
생각 서명(Thought signatures): 모델 내부 추론의 암호화된 표현. 다중 턴 함수 호출에 필요하며 공식 SDK가 자동으로 관리해요.

프롬프팅 모범 사례 (Prompting best practices)

Gemini 3.x 모델은 추론 모델이라 프롬프트 방식이 달라져요.

정밀한 지시(Precise instructions): 간결하게 하세요. Gemini 3.x는 직접적이고 명확한 지시에 가장 잘 응답해요. 이전 모델용으로 설계된 장황하거나 복잡한 프롬프트 엔지니어링 기법은 모델이 과도하게 분석하게 할 수 있어요.
출력 장황함(Output verbosity): 기본적으로 Gemini 3.x는 장황하지 않고 직접적이고 효율적인 답변을 선호해요. 대화형 톤이 필요하면 프롬프트에서 명시적으로 유도하세요(예: "친근하고 수다스러운 어시스턴트처럼 설명해 줘").
컨텍스트 관리(Context management): 대규모 데이터셋(전체 책, 코드베이스, 긴 비디오 등)을 다룰 때는 데이터 컨텍스트 뒤, 프롬프트 끝에 구체적인 지시나 질문을 두세요. "앞의 정보를 바탕으로..." 같은 표현으로 질문을 시작해 모델의 추론을 고정하세요.

프롬프트 설계 전략에 대해 더 알고 싶다면 프롬프트 엔지니어링 가이드를 참고하세요.

제한 사항 (Limitations)

이미지 분할(segmentation)은 Gemini 3.x에서 지원되지 않아요. 분할 워크로드는 추론을 끈 Gemini 2.5 Flash나 Gemini Robotics ER 2를 계속 사용하세요.

FAQ

Gemini 3.5 Flash의 지식 컷오프는 언제인가요? Gemini 3.5 Flash의 지식 컷오프는 2025년 1월이에요. 더 최신 정보는 Search Grounding 도구를 사용하세요.
컨텍스트 창 한도는 어떻게 되나요? Gemini 3.5 Flash는 1백만 토큰 입력 컨텍스트 창과 최대 65k 출력 토큰을 지원해요.
기존 thinking_budget 코드가 여전히 작동하나요? 네, thinking_budget은 하위 호환성을 위해 계속 지원되지만, 더 예측 가능한 성능을 위해 thinking_level로 마이그레이션할 것을 권장해요. 같은 요청에서 둘을 함께 쓰지 마세요.
Gemini 3.5 Flash가 Batch API를 지원하나요? 네. 자세한 내용은 Batch API 가이드를 참고하세요.
컨텍스트 캐싱이 지원되나요? 네, 컨텍스트 캐싱이 지원돼요.
어떤 도구가 지원되나요? Gemini 3.5 Flash는 Google Search, Google 지도 접지, 파일 검색, 코드 실행, URL 컨텍스트, 표준 함수 호출, 결합 도구 사용, 그리고 Computer Use를 지원해요.

다음 단계 (Next steps)

프롬프트 엔지니어링 가이드에서 프롬프트 설계 전략을 더 배우세요.
Gemini 3 Cookbook으로 시작하세요.
Gemini API 최적화 및 추론에 대해 알아보세요.

더 알아보기 (Learn more)

Gemini 3.5 Flash 모델 개요 — 전체 사양.
가격 페이지 — Gemini 3.5 Flash 가격.
프롬프트 엔지니어링 가이드 — 3.x 프롬프팅 전략.

Gemini 3.5 Flash의 새로운 기능