Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Gemini 3.6 Flash 개발자 가이드

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

이 문서에서는 3.6 Flash의 새로운 기능, Gemini 모델 제품군 내에서의 위치, 3.6 Flash로 마이그레이션하는 방법을 설명하고 3.6 Flash 사용을 위한 빠른 시작을 제공합니다.

Gemini 제품군에서 어떤 위치를 차지하나요?

Gemini 3.6 Flash는 Gemini 3 제품군의 주요 에이전트형 모델입니다. 심층 추론 Gemini Pro 모델과 높은 처리량의 Gemini Flash-Lite 모델 간의 격차를 해소합니다. Gemini 3.5 Flash와 비교해 3.6 Flash는 더 적은 토큰과 추론 차례를 사용하면서도 다단계 도구 조정, 풀 스택 코드 리팩터링, 시각적 추론에서 훨씬 더 높은 품질을 제공합니다. Flash 속도와 가격으로 Pro에 가까운 수준의 기능을 제공합니다.

모델 사양 및 비교

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

	Gemini 3.6 Flash	Gemini 3.5 Flash	Gemini 3.1 Pro
모델 ID	`gemini-3.6-flash`	`gemini-3.5-flash`	`gemini-3.1-pro-preview`
출시 단계	GA	GA	미리보기
입력 유형	텍스트, 이미지, 오디오, 동영상	텍스트, 이미지, 오디오, 동영상	텍스트, 이미지, 오디오, 동영상
출력 유형	텍스트	텍스트	텍스트
컨텍스트 윈도우	1,048,576	1,048,576	1,048,576
최대 출력 토큰 길이	65,536	65,536	65,536
지원되는 리전	전역, 멀티 리전	전 세계, 멀티 리전, 미주, 유럽, 아시아 태평양	전역
지원되는 사고 수준	`MINIMAL`, `LOW`, `MEDIUM`, `HIGH` (기본값: `MEDIUM`)	`MINIMAL`, `LOW`, `MEDIUM`, `HIGH` (기본값: `MEDIUM`)	`LOW`, `MEDIUM`, `HIGH` (기본값: `HIGH`)
주요 초점	고효율 에이전트형 워크플로, 다단계 조정, 풀 스택 코딩	균형 잡힌 작업, 도구 호출, 중간 추론	심층 추론, 복잡성이 높은 작업

지원되는 기능, 도구, 사용 옵션의 전체 목록은 3.6 Flash 모델 페이지를 참조하세요.

Gemini 3.6 Flash의 새로운 기능

3.6 Flash는 다단계 조정, 풀 스택 코드 리팩터링, 일반 추론에 최적화되어 있으며 이전 버전보다 토큰 효율성이 크게 향상되었습니다.

기능 및 성능 업데이트

다음은 이전 모델과 비교하여 3.6 Flash의 기능 및 성능 변경사항 목록입니다.

토큰 및 대화 차례 감소: 3.5 Flash보다 더 적은 토큰을 사용하고 더 적은 추론 단계와 대화 차례로 다단계 워크플로를 완료합니다.
코드 생성 개선: 애플리케이션 빌드, 프로토타입 제작, IDE 에이전트 환경 전반에서 컴파일 실패 및 수정률이 낮은 더 깔끔한 코드를 생성합니다.
작업 편향 감소: 요청하지 않은 작업공간 수정이나 조기 상태 변경 없이 읽기 전용 진단 작업을 해결합니다.
멀티모달 및 공간 추론: 차트 해석, 시각적 청사진 변환, 다중 요소 웹 레이아웃 생성에서 향상된 성능을 제공합니다.
컴퓨터 사용 지원: 에이전트 UI 자동화를 위한 기본 제공 도구로 지원됩니다.
UI 스타일 지정 환경설정: 기능 코드를 더 잘 생성하지만, 인간 평가자는 프런트엔드 프레젠테이션 및 시각적 레이아웃에 이전 모델을 선호한다고 언급했습니다. 이는 명시적인 설계 가이드라인을 제공하여 완화할 수 있습니다.

동작 및 API 매개변수 변경사항

다음은 이전 모델에서 3.6 Flash의 동작 및 API 파라미터 변경사항 목록입니다.

단계 간결성: 3.5 Flash보다 추론 단계가 적습니다. 이렇게 하면 코드 리팩터링 및 도구 워크플로의 지연 시간과 비용이 줄어들지만, 더 긴 반복 체인이 필요한 확장된 멀티턴 대화 후속 작업에서 조기 종료가 발생할 수 있습니다.
사전 프로그래매틱 검사: 상태를 변경하기 전에 문제를 검사하기 위해 진단 코드 스크립트(execute_code)를 실행하는 것을 3.5 Flash보다 더 선호합니다. 이렇게 하면 복잡한 백엔드 리팩터링의 진단 정확도가 향상되지만, 이전 버전에서 코드를 직접 생성하는 간단한 프런트엔드 웹 및 스크립팅 작업에서 추가 탐색 검사 단계를 실행해야 할 수도 있습니다.
기본 작업: 3.5 Flash에 도입된 중간 기본 작업 수준을 전달합니다.
샘플링 재정의 없음: temperature, top-k 또는 top-p 파라미터의 커스텀 값은 더 이상 지원되지 않습니다. 커스텀 값 설정은 API 노출 영역에서 무시됩니다. 대신 thinking_level 또는 구조화된 JSON 스키마를 사용하여 출력 결정론을 제어하세요.
빈도 및 존재 페널티 제한: 이러한 매개변수의 커스텀 값은 더 이상 지원되지 않습니다. 이제 이를 설정하면 활성 API 오류가 발생합니다.
마지막 입력 차례에 '모델' 역할이 있는 API 요청은 지원되지 않습니다.
대화 기록의 빈 차례는 삭제됩니다.
이제 잘못된 생각 서명으로 인해 오류가 발생합니다.
엄격한 함수 호출: FunctionResponse은 이전 FunctionCall의 id, name, 실행 횟수와 정확히 일치해야 합니다. 함수 응답 텍스트 내에 직접 인라인 안내를 추가하고, 두 개의 줄바꿈 (\n\n)으로 구분합니다.

빠른 시작

시작하기 전에 애플리케이션 기본 사용자 인증 정보 (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.6-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.6-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

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) 두 개로 구분합니다.
워크플로 변화 고려:
- 애플리케이션이 멀티턴 대화 루프를 사용하는 경우 워크플로를 테스트하여 모델의 새로운 단계 간결성이 조기 종료를 트리거하지 않는지 확인합니다.
- 프런트엔드 또는 기본 스크립팅 에이전트를 빌드하는 경우 모델의 새로운 편향으로 인해 사전 프로그래매틱 검사가 수행되어 불필요한 탐색적 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() 호출과 실행하려는 실제 함수 호출입니다.

Gemini 3.6 Flash 개발자 가이드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.