Gemini 3.5 Flash는 Gemini 3 제품군에 속하는 고속의 비용 효율적인 강력한 모델입니다. 성능이나 가치를 저해하지 않으면서 Pro에 준하는 에이전트 기능을 제공하도록 설계된 이 모델은 이제 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 간의 몇 가지 사양을 비교한 것입니다.
| Gemini 3.5 Flash | Gemini 3.1 Pro | Gemini 3.1 Flash-Lite | |
|---|---|---|---|
| 모델 ID | gemini-3.5-flash |
gemini-3.1-pro-preview |
gemini-3.1-flash-lite |
| 출시 단계 | GA | 미리보기 | GA |
| 입력 유형 | 텍스트, 이미지, 오디오, 동영상 | 텍스트, 이미지, 오디오, 동영상 | 텍스트, 이미지, 오디오, 동영상 |
| 출력 유형 | 텍스트 | 텍스트 | 텍스트 |
| 컨텍스트 윈도우 | 1,048,576 | 1,048,576 | 1,048,576 |
| 최대 출력 토큰 길이 | 65,536 | 65,536 | 65,536 |
| 지원되는 리전 | 전 세계, 멀티 리전, 미주, 유럽, 아시아 태평양 | 전역 | 전역, 멀티 리전 |
| 지원되는 사고 수준 |
MINIMAL, LOW, MEDIUM, HIGH(기본값: MEDIUM)
|
LOW, MEDIUM, HIGH(기본값: HIGH)
|
MINIMAL, LOW, MEDIUM, HIGH(기본값: MINIMAL)
|
| 주요 초점 | 균형 잡힌 작업, 도구 호출, 중간 추론 | 심층 추론, 복잡성이 높은 작업 | 비용과 지연 시간에 민감한 대용량 작업 |
지원되는 기능, 도구, 소비 옵션의 전체 목록은 3.5 Flash 모델 페이지를 참조하세요.
사용 사례 분류
에이전트형 워크플로에 권장되는 전략은 계층화된 접근 방식을 사용하여 품질, 속도, 비용을 최적화합니다.
- Gemini Pro: 초기 루트 계획, 복잡한 문제 해결, 어려운 코딩, 중요한 의사 결정과 같이 심층적인 추론이 필요한 복잡성이 높은 인지 작업에 사용합니다.
- Gemini Flash: 실행 작업, 도구 호출, 중간 추론 단계의 기본 '워크호스'로 사용되어 성능과 효율성의 최적의 균형을 제공합니다.
- Gemini Flash-Lite: 인텐트 라우팅, 데이터 추출, 태그 지정, 분류와 같이 속도와 비용이 가장 중요한 대용량, 짧은 지연 시간의 전처리 및 구조적 작업에 배포합니다.
Gemini 3.5 Flash의 새로운 기능
Gemini 3.5 Flash는 Gemini 모델 라인업에 다음과 같은 변경사항과 개선사항을 제공합니다.
- 지속적인 최첨단 성능: 대규모 에이전트형 및 코딩 작업에 최적화된 Google의 가장 지능적인 Gemini Flash 모델입니다.
- 에이전트 실행: 하위 에이전트 배포, 문제 해결, 대규모의 빠른 에이전트 루프
- 코딩 개선: 반복적인 코딩 주기, 빠른 탐색, 프로토타입 제작을 통해 대체 경로를 테스트하고 솔루션을 동적으로 탐색합니다.
- 장기: 다단계 워크플로 및 대규모 도구 사용
- 추론 과정 보존: 모델은 멀티턴 대화 전반에서 중간 추론을 자동으로 유지합니다. API를 변경할 필요가 없습니다.
- 새로운 기본 사고 수준: 기본 사고 수준이
HIGH에서MEDIUM로 변경되었습니다. LOW사고 개선: 이제 사고 수준이 낮아져 더 적은 단계가 필요한 코드 및 에이전트 작업이 크게 개선되어 지연 시간과 비용이 줄어들고 품질이 향상되었습니다.
자세한 내용은 주요 변경사항 섹션을 참고하세요.
빠른 시작
시작하기 전에 애플리케이션 기본 사용자 인증 정보 (ADC) 또는 API 키를 사용하여 Agent Platform에 인증해야 합니다. 자세한 내용은 Gemini Enterprise Agent Platform 시작하기를 참조하세요.
다음 코드 블록에서 PROJECT_ID를 프로젝트 ID로 바꿉니다.
설치
최신 google-genai SDK를 사용하고 있는지 확인합니다.
pip install --upgrade google-genai
기본 요청
Python
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)
REST
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에 도입된 다음 변경사항을 자세히 설명합니다.
새로운 기본 사고 수준
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 모델에서는 다음 샘플링 파라미터가 더 이상 권장되지 않습니다.
temperaturetop_ptop_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 Flash 사용에 관한 다음 권장사항을 설명합니다.
함수 호출에 엄격한 응답 일치 사용
응답이 일치하지 않으면 대부분의 경우 모델이 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,
)
]),
],
)
불필요한 도구 호출 줄이기
도구 호출이 과도하게 사용되는 경우 다음 두 가지 기법을 사용하면 이를 최소화할 수 있습니다.
- 사고 수준 낮추기: 사고 수준이 높을수록 모델이 더 많은 도구를 사용하여 탐색하고 검증하므로 수준을 낮추면 도구 호출을 줄일 수 있습니다.
시스템 안내 추가: 사고 수준을 조정한 후에도 과도한 사용이 지속되면 도구 사용을 제한하는 프롬프트를 고려하세요. 예를 들면 다음과 같습니다.
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로 마이그레이션하려면 다음 단계를 수행합니다.
- 모델 ID 업데이트: API 호출의 모델 문자열을
gemini-3.6-flash로 변경합니다. - 새로운 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) 두 개로 구분합니다.
- 온도, Top-K, Top-P 삭제: 페이로드에서 이러한 맞춤 매개변수를 삭제합니다. 오류가 발생하지는 않지만 모델에서 완전히 무시됩니다. 대신
- 워크플로 변화 고려:
- 애플리케이션이 멀티턴 대화 루프를 사용하는 경우 워크플로를 테스트하여 모델의 새로운 단계 간결성이 조기 종료를 트리거하지 않는지 확인합니다.
- 프런트엔드 또는 기본 스크립팅 에이전트를 빌드하는 경우 모델의 새로운 편향으로 인해 사전 프로그래매틱 검사가 수행되어 불필요한 탐색적
execute_code호출이 발생하는지 모니터링합니다.
도구 사용 전 텍스트 요구사항 해결 방법
프롬프트에서 도구 호출을 수행하기 직전에 모델이 구조화된 텍스트 (XLM, 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() 호출과 실행하려는 실제 함수 호출입니다.