Gemini 3.5 Flash 개발자 가이드

Gemini 3.5 Flash는 Gemini 3 제품군의 고속, 비용 효율적인 강력한 모델입니다. 성능이나 가치를 저하시키지 않으면서 프로급 에이전트 기능을 제공하도록 설계된 이 모델은 이제 Gemini API를 사용하는 개발자와 Gemini Enterprise Agent Platform을 사용하는 기업을 대상으로 정식 버전 (GA)으로 제공됩니다.

이 문서에서는 3.5 Flash의 새로운 기능, 사용 시기, 3.5 Flash로 이전하는 방법, 3.5 Flash 사용을 위한 빠른 시작을 설명합니다.

Gemini 제품군에서 어떤 역할을 하나요?

다음 표는 3.5 Flash, 3.1 Pro, 3.1 Flash-Lite 간의 사양을 비교한 것입니다.

지원되는 기능, 도구, 소비 옵션의 전체 목록은 3.5 Flash 모델 페이지를 참고하세요.

사용 사례 분석

Agentic Workflows에 권장되는 전략은 품질, 속도, 비용을 최적화하기 위해 계층화된 접근 방식을 사용합니다.

• Gemini Pro: 초기 경로 계획, 복잡한 문제 해결, 어려운 코딩, 중요한 의사결정과 같이 심층적인 추론이 필요한 복잡한 인지 작업에 사용합니다.
• Gemini Flash: 실행 작업, 도구 호출, 중간 추론 단계의 기본 '작업용'으로 사용하여 성능과 효율성의 균형을 최적화합니다.
• Gemini Flash-Lite: 의도 라우팅, 데이터 추출, 태그 지정, 분류와 같이 속도와 비용이 중요한 대용량의 짧은 지연 시간 사전 처리 및 구조적 작업에 배포합니다.

Gemini 3.5 Flash의 새로운 기능

Gemini 3.5 Flash는 Gemini 모델 라인업에 다음과 같은 변경사항과 개선사항을 제공합니다.

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

자세한 내용은 주요 변경사항 섹션을 참고하세요.

빠른 시작

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

다음 코드 블록에서 PROJECT_ID를 프로젝트 ID로 바꿉니다.

설치

최신 google-genai SDK를 사용하고 있는지 확인합니다.

pip install --upgrade google-genai

기본 요청

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
  model="gemini-3.5-flash",
  contents="How does AI work?",
)
print(response.text)

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

주요 변경사항

이 섹션에서는 Gemini 3.5 Flash에 도입된 다음 변경사항을 자세히 설명합니다.

• 새 기본 사고 수준 (MEDIUM)
• 추론 과정 보존
• 지원 중단됨: 샘플링 매개변수
• 지원 중단됨: thinking_budget

새 기본 사고 수준

이제 Gemini 3 모델의 기본 사고 수준이 MEDIUM로 변경되었습니다. Gemini 3 Flash 프리뷰 버전에서는 HIGH였습니다. 사고 수준 MEDIUM는 다양한 작업에서 강력한 결과를 제공하면서도 더 빠르고 비용 효율적입니다.

지원되는 사고 수준은 다음과 같습니다.

• MINIMAL: 대부분의 질문에 '생각하지 않음' 설정과 일치합니다. 모델이 코딩과 같은 복잡한 작업에 대해 매우 최소한으로 생각할 수 있습니다. 채팅 또는 높은 처리량 애플리케이션의 지연 시간을 최소화합니다.
• LOW: 대부분의 작업에 대해 빠른 속도와 낮은 비용으로 가벼운 추론을 제공합니다.
• MEDIUM: (기본값) 추론이 필요한 대부분의 작업에 적합한 균형 설정입니다.
• HIGH: 작업 성능을 최적화하기 위해 추론을 최대화합니다. 모델이 첫 번째 토큰을 생성하는 데 MEDIUM 설정보다 오래 걸릴 수 있지만 출력은 더 철저합니다.

예를 들어 모델이 여러 단계를 거쳐 추론해야 하는 논리 퍼즐, 수학 단어 문제 또는 까다로운 시나리오에는 HIGH를 사용합니다.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="A farmer has chickens and rabbits. There are 35 heads and 94 legs. How many chickens and how many rabbits does he have? Show your step-by-step logic.",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH
       )
   ),
)
print(response.text)

thinking_level 파라미터는 선택사항입니다. 생략하면 3.5 Flash는 기본 설정 (MEDIUM)을 사용합니다.

추론 과정 보존

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

이제 이전 턴의 생각이 기본적으로 보존됩니다. 서비스는 모델에 전달하기 전에 더 이상 대화 컨텍스트에서 사고 기록을 지우지 않습니다.

대화 기록을 전송할 때는 이전 턴과 일관성을 유지하세요. 전체 컨텍스트 (생각, 함수 호출, 응답)를 포함하거나 완전히 생략하세요. 부분 컨텍스트는 모델 성능을 저하시킬 수 있습니다.

지원 중단됨: 샘플링 파라미터

다음 샘플링 파라미터는 더 이상 Gemini 3 모델에 권장되지 않습니다.

• temperature
• top_p
• top_k

모델은 최적의 결과를 위해 자체 샘플링을 관리합니다. 모든 요청에서 이러한 매개변수를 삭제합니다. 결정성을 보장하려면 특정 사용 사례에 대한 명시적 규칙이 포함된 시스템 명령어를 정의하세요.

지원 중단됨: thinking_budget

원시 숫자 thinking_budget 파라미터는 더 이상 모든 Gemini 3 모델에서 지원되지 않습니다. 대신 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")
)

권장사항

이 섹션에서는 3.5 플래시 사용에 관한 다음 권장사항을 설명합니다.

• 함수 호출에 엄격한 응답 일치 사용
• 함수 응답 parts에 멀티모달 콘텐츠 포함
• 함수 응답에 인라인 안내 사용
• 불필요한 도구 호출 줄이기

함수 호출에 엄격한 응답 일치 사용

대답이 일치하지 않으면 대부분의 경우 모델이 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,
            )
        ]),
    ],
)

함수 응답 parts에 멀티모달 콘텐츠 포함

함수 응답 외부에 이미지를 제공하면 생각 누출과 같은 예기치 않은 모델 동작이 발생하고 품질이 저하될 수 있습니다. 함수 호출 소개에 포함된 권장사항에 따라 모델에 전송하는 함수 응답 부분에 멀티모달 콘텐츠를 포함하세요. 모델은 다음 차례에 이 멀티모달 콘텐츠를 처리하여 더 많은 정보를 바탕으로 응답을 생성할 수 있습니다.

예를 들면 다음과 같습니다.

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

함수 응답에 인라인 안내 사용

함수 응답과 함께 플랫폼 안내를 후속 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,
            )
        ]),
    ],
)

불필요한 도구 호출 줄이기

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

1. 사고 수준 낮추기: 사고 수준이 높을수록 모델이 더 많은 도구를 사용하여 탐색하고 검증하므로 수준을 낮추면 도구 호출을 줄일 수 있습니다.

2. 시스템 안내 추가: 사고 수준을 조정한 후에도 과도한 사용이 지속되면 도구 사용을 제한하는 프롬프트를 고려하세요. 예를 들면 다음과 같습니다.

   You have a limited action budget of <n> tool calls. Use them efficiently.
   

3.5 Flash 또는 3.1 Pro에서 3.6 Flash로 마이그레이션

3.5 Flash 또는 3.1 Pro에서 3.6 Flash로 이전하려면 다음 단계를 따르세요.

1. 모델 ID 업데이트: API 호출에서 모델 문자열을 gemini-3.6-flash로 변경합니다.
2. 새로운 Gemini 3 제품군 API 규칙에 맞게 코드를 조정하세요. Gemini 3.6 Flash는 Gemini 3 제품군 전반에 걸쳐 설정된 매개변수 규칙과 API 규칙을 엄격하게 적용합니다.
   • 온도, Top-K, Top-P 삭제: 페이로드에서 이러한 맞춤 매개변수를 삭제합니다. 오류가 발생하지는 않지만 모델에서 완전히 무시합니다. 대신 thinking_level 파라미터 또는 json_schema 구조화된 출력을 사용하여 출력 결정성을 제어하세요.
   • 빈도 및 출현 빈도 페널티 삭제: API 호출에서 런타임 오류가 발생하지 않도록 빈도 또는 출현 빈도 페널티의 맞춤 구성을 삭제합니다.
   • 채팅 통합에서 모델 자동 완성 시도를 방지: 메시지 기록 배열을 검토하여 API 페이로드가 빈 사용자 턴이나 모델 턴으로 끝나지 않는지 확인합니다. 기록 배열의 마지막 객체가 'model' 역할 (GenerateContent API) 또는 'model_output' 유형 (Interactions API)인 경우 엄격한 유효성 검사 오류가 트리거되지 않도록 시퀀스를 재구성합니다.
   • thinking_level 사용: 지원 중단된 thinking_budget 매개변수의 인스턴스를 삭제하고 대신 thinking_level을 사용합니다.
   • 엄격한 함수 호출 규칙 적용: FunctionResponse는 이전 FunctionCall의 id, name, 실행 횟수와 엄격하게 일치해야 합니다. 인라인 명령어를 추가해야 하는 경우 함수 응답 텍스트 내에 두 개의 줄바꿈 (\n\n)으로 구분하여 직접 배치합니다.
3. 워크플로 교대근무 계정:
   • 애플리케이션이 다중 턴 대화형 루프를 사용하는 경우 모델의 새로운 단계 간결성으로 인해 조기 종료가 트리거되지 않도록 워크플로를 테스트하세요.
   • 프런트엔드 또는 기본 스크립팅 에이전트를 빌드하는 경우 모델이 사전 프로그래매틱 검사에 대해 새로운 편향을 보이므로 불필요한 탐색적 execute_code 호출이 있는지 모니터링하세요.

사전 도구 텍스트 요구사항 해결 방법

프롬프트에서 모델이 도구 호출을 하기 직전에 구조화된 텍스트 (XML, YAML, JSON 등) (예: <UPDATE>...</UPDATE>)를 출력해야 하는 경우 도구 호출이 Malformed_Function_Call 오류와 함께 실패할 수 있습니다. 다음 해결 방법 중 하나를 사용하여 이 문제를 해결할 수 있습니다.

• (권장) 모델이 원시 텍스트 대신 전용 update() 함수 호출 내에 사전 도구 메모를 넣도록 지시합니다. 자세한 구현 안내는 다음 섹션을 참고하세요.
• 구조화된 텍스트 대신 마크다운 헤더 (예: # UPDATE, ## PLAN)로 메모를 작성하도록 모델에 지시합니다.
• 모델이 도구 호출 전에 텍스트를 출력하도록 요구하지 마세요.

권장 솔루션: 전용 함수 호출로 작업 메모 래핑

원래 안내 대신 다음을 사용하세요.

Before calling a tool, in every response you MUST first output a single
`<UPDATE>` part as specified, don't skip this part or any of required sub-tags
within `<UPDATE>`.

업데이트된 요청 사항을 사용하세요.

Before calling any other tool, in every response you MUST first call `update`
with all required parameters (previous_step, plan, next_step, external).

고객 요청에서 이전 <UPDATE> XML 형식에 대한 모든 참조를 업데이트합니다. 그런 다음 업데이트 함수의 해당 함수 선언을 추가합니다.

{
  "name": "update",
  "description": "Update working notes (previous step analysis, plan, next step, external note).",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {
        "type": "STRING",
        "description": "Key findings and outcomes since the previous step."
      },
      "plan": {
        "type": "STRING",
        "description": "The current status of the plan."
      },
      "next_step": {
        "type": "STRING",
        "description": "Brief explanation of the immediate next action according to the plan."
      },
      "external": {
        "type": "STRING",
        "description": "A short, plain-language note shown to the User about what you are ABOUT TO DO next."
      }
    },
    "required": [
      "previous_step",
      "plan",
      "next_step",
      "external"
    ]
  }
}

모델은 동일한 단계에서 두 번 호출합니다. 구조화된 XML을 대체하는 update() 호출과 실행하려는 실제 함수 호출입니다.

추가 리소스

• Gemini 3.5 Flash 모델 페이지
• 소개 노트북