Gemini 3.5 Flash의 새로운 기능
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 출시: 확장된 프로덕션 사용을 위한 안정 모델입니다.
올바른 Flash 모델 선택
Gemini 3.5 Flash는 Google의 가장 지능적이고 강력한 Flash 모델입니다. 하지만 사용 사례에 따라 비용 및 지연 시간 요구사항이 다를 수 있습니다.
- Gemini 3.1 Flash-Lite: 3.5 Flash의 고급 추론 깊이가 필요하지 않은 저비용, 대량 작업에는 Gemini 3.1 Flash-Lite를 사용하는 것이 좋습니다. 효율성에 최적화된 안정적인 장기 모델입니다. 자세한 내용은 Flash-Lite 개발자 가이드를 참고하세요.
- Gemini 3 Flash 프리뷰: GA 안정성과 향상된 추론을 위해 3.5 Flash로 마이그레이션하는 것이 좋지만, 프리뷰 모델로 계속 테스트하려는 개발자는 Gemini 3 Flash (프리뷰)를 계속 사용할 수 있습니다.
동작 변경사항
새 기본 노력 수준: 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"
}
}
}'
다음 표에는 모델별로 지원되는 사고 수준이 나와 있습니다.
| 사고 수준 | Gemini 3.5 Flash | Gemini 3.1 Pro | Gemini 3.1 Flash-Lite | Gemini 3 Flash | 설명 |
|---|---|---|---|---|---|
minimal |
지원됨 | 지원되지 않음 | 지원됨 (기본값) | 지원됨 | 대부분의 질문에 대해 '생각하지 않음' 설정과 일치합니다. minimal는 사고가 사용 중지되었음을 보장하지 않으며, 모델이 복잡한 작업에 대해 매우 최소한의 추론을 할 수 있습니다. |
low |
지원됨 | 지원됨 | 지원됨 | 지원됨 | 지연 시간과 비용을 최소화합니다. |
medium |
지원됨 (기본값) | 지원됨 | 지원됨 | 지원됨 | 대부분의 작업에 균형 잡힌 사고를 제공합니다. |
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 프리뷰보다 가격이 비쌉니다. 비용에 매우 민감한 사용 사례의 경우 Gemini 3.1 Flash-Lite로 이전하는 것이 좋습니다. 자세한 내용은 가격 책정 페이지를 참고하세요.
- 구성에서
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 컨텍스트, 코드 실행, 함수 호출)와 결합합니다.
- 멀티모달 함수 응답: 함수 호출 결과에 이미지, 오디오, 기타 미디어를 반환합니다.
- 이미지를 사용한 코드 실행: 이미지를 처리하고 생성하는 코드를 실행합니다.
- 결합된 도구 사용: 동일한 요청에서 기본 제공 도구와 맞춤 함수 호출을 사용합니다.
- 미디어 해상도:
이미지, 동영상, PDF 입력의 토큰 할당을 세부적으로 제어합니다.
Gemini 3 모델은 혼합 충실도 프롬프트에 콘텐츠 항목별 해상도 설정 (
low,medium,high,ultra_high)을 지원합니다. - 사고 서명: 모델의 내부 추론을 암호화한 표현입니다. 다중 턴 함수 호출에 필요합니다. 공식 SDK에서 자동으로 관리합니다.
프롬프트 권장사항
Gemini 3.x 모델은 추론 모델이므로 프롬프트 작성 방식에도 변화가 필요합니다.
- 정확한 지시: 간결하게 작성하세요. Gemini 3.x는 직접적이고 명확한 지시에 가장 잘 반응합니다. 이전 모델을 위해 설계된 장황하거나 복잡한 프롬프트 엔지니어링 기법은 모델이 과분석을 유발할 수 있습니다.
- 출력 장황도: 기본적으로 Gemini 3.x는 덜 장황하며, 직접적이고 효율적인 답변을 선호합니다. 사용 사례에 대화형 어조가 필요한 경우 프롬프트에서 모델을 명시적으로 유도합니다 (예: "친근하고 말이 많은 조수처럼 설명해 줘").
- 컨텍스트 관리: 전체 책, 코드베이스, 긴 동영상과 같은 대규모 데이터 세트로 작업할 때는 데이터 컨텍스트 뒤에 프롬프트 끝에 구체적인 지침이나 질문을 배치하세요. '앞의 정보를 바탕으로...'와 같은 문구로 질문을 시작하여 모델의 추론을 고정하세요.
프롬프트 엔지니어링 가이드에서 프롬프트 설계 전략에 대해 자세히 알아보세요.
제한사항
- Gemini 3.x에서는 이미지 분할이 지원되지 않습니다. 분할 워크로드의 경우 사고를 사용 중지한 상태의 Gemini 2.5 Flash 또는 Gemini Robotics-ER 1.6을 계속 사용하세요.
FAQ
Gemini 3.5 Flash의 지식 단절 시점은 언제인가요? Gemini 3.5 Flash의 지식 단절 시점은 2025년 1월입니다. 최신 정보를 확인하려면 그라운딩 검색 도구를 사용하세요.
컨텍스트 윈도우 한도는 어떻게 되나요? Gemini 3.5 Flash는 최대 100만 개의 토큰 입력 컨텍스트 윈도우와 최대 65,000개의 출력 토큰을 지원합니다.
이전
thinking_budget코드가 계속 작동하나요? 예, 이전 버전과의 호환성을 위해thinking_budget가 계속 지원되지만 더 예측 가능한 성능을 위해thinking_level로 이전하는 것이 좋습니다. 동일한 요청에서 두 가지를 모두 사용하지 마세요.Gemini 3.5 Flash는 Batch API를 지원하나요? 예. 자세한 내용은 Batch API 가이드를 참고하세요.
컨텍스트 캐싱이 지원되나요? 예, 컨텍스트 캐싱이 지원됩니다.
어떤 도구가 지원되나요? Gemini 3.5 Flash는 Google 검색, Google 지도 기반 그라운딩, 파일 검색, 코드 실행, URL 컨텍스트, 결합된 도구 사용을 비롯한 표준 함수 호출을 지원합니다. Computer Use는 Gemini 3.5 Flash에서 지원되지 않습니다.
다음 단계
- 프롬프트 엔지니어링 가이드에서 프롬프트 설계 전략에 대해 자세히 알아보세요.
- Gemini 3 Cookbook 시작하기
- Gemini API 최적화 및 추론 알아보기