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

모델 사양 및 비교

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

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

Gemini 3.6 Flash의 새로운 기능

3.6 Flash는 이전 모델보다 훨씬 더 나은 토큰 효율성으로 다단계 조정, 전체 스택 코드 리팩터링, 일반 추론에 최적화되어 있습니다.

기능 및 성능 업데이트

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

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

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

다음은 이전 모델의 3.6 Flash 동작 및 API 매개변수 변경사항 목록입니다.

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

빠른 시작

시작하기 전에 애플리케이션 기본 사용자 인증 정보 (ADC) 또는 API 키를 사용하여 Agent Platform에 인증해야 합니다. 자세한 내용은 Get started with 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.6-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.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로 이전하려면 다음 단계를 따르세요.

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 호출이 있는지 모니터링합니다.

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

프롬프트에서 모델이 도구 호출을 하기 직전에 구조화된 텍스트 (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 모델 페이지
• 초급 노트북