Gemini 3.7 Flash 개발자 가이드

Gemini 3.7 Flash는 개발자를 위한 지능적인 일상용 모델로, 소프트웨어 엔지니어링을 한 단계 발전시켜 빌드 환경을 크게 개선합니다. 이 모델은 복잡한 작업, 요청 사항 따르기, 도구 호출을 위한 더 나은 인텔리전스를 일상적인 워크플로에 제공합니다.

이 문서에서는 3.7 Flash의 새로운 기능, Gemini 모델 제품군에 어떻게 부합하는지, 3.7 Flash로 마이그레이션하는 방법을 다루고 3.7 Flash 사용을 위한 빠른 시작을 제공합니다.

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

Gemini 3.7 Flash는 Gemini 3 제품군의 주요 에이전트형 주력 모델로, 심층 추론 Pro 모델과 높은 처리량의 Gemini Flash-Lite 모델 간의 격차를 해소하는 동시에 높은 토큰 효율성과 다단계 멀티모달 처리를 제공합니다.

모델 사양 및 비교

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

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

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

Gemini 3.7 Flash의 새로운 기능

다음 표에서는 Gemini 3.7 Flash와 3.6 Flash의 표준 개발자 평가 벤치마크를 비교합니다.

평가 관련 업계 기준치	3.7 Flash	3.6 Flash
Terminal-bench 2.1	85.1%	73.0%
DeepSWE	63.7%	49.0%
Humanity's Last Exam (HLE)	45.7%	37.4%
LMArena WebDev	1592	1532

빠른 시작

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

필수 API 규칙 및 동작 규칙

중요: 3.7 Flash에서는 thinking_level="MINIMAL"를 사용할 수 없습니다. thinking_level를 MINIMAL로 명시적으로 설정하면 API 유효성 검사 오류가 반환됩니다. 유효한 구성은 LOW, MEDIUM (기본값), HIGH입니다.

Gemini 3.7 Flash는 다음 표준 Gemini 3 제품군 API 규칙을 엄격하게 적용합니다.

• 지원 중단된 샘플링 파라미터 (temperature, top_k, top_p): 이러한 파라미터는 백엔드에서 무시됩니다. 대신 thinking_level (LOW, MEDIUM, HIGH) 및 response_schema 또는 json_schema를 사용하여 결정론을 제어할 수 있습니다.
• 지원되지 않는 매개변수 (frequency_penalty, presence_penalty, candidate_count): frequency_penalty, presence_penalty 또는 candidate_count를 전달하면 활성 API 오류가 발생합니다. 기존 클라이언트 코드에서 삭제합니다.

• 엄격한 함수 호출 규칙: FunctionResponse 차례는 이전 FunctionCall의 id, name, 실행 횟수와 엄격하게 일치해야 합니다.

  • 멀티모달 애셋: 항상 응답 페이로드 내에 멀티모달 애셋을 배치합니다.
  • 형식 지정 및 도구 전 텍스트: \n\n를 사용하여 인라인 안내의 형식을 지정합니다. 도구 전 텍스트와 관련된 Malformed_Function_Call 오류가 발생하면 도구 호출 전에 선행 주석을 정리하세요.

  • 도구 호출 전에 중간 작업 메모 또는 상태 업데이트를 전달하려면 원시 XML 또는 텍스트를 내보내는 대신 전용 update() 함수 호출로 래핑합니다.

    {
      "name": "update",
      "description": "Update working notes before tool execution",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "previous_step": {"type": "STRING"},
          "plan": {"type": "STRING"},
          "next_step": {"type": "STRING"}
        },
        "required": ["previous_step", "plan", "next_step"]
      }
    }
    

• 채팅 시퀀스 검증:

  • 기록 페이로드는 "model" 역할 차례로 끝날 수 없습니다.
  • 사전 입력된 모델 턴은 지원되지 않으며 업그레이드할 때 삭제해야 합니다.
  • 대화 기록의 빈 차례는 자동으로 삭제되거나 검증 오류가 발생합니다.

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

3.5 Flash 또는 3.6 Flash에서 3.7 Flash로 마이그레이션하려면 다음 단계를 수행합니다.

1. 모델 ID 업데이트: API 호출의 모델 문자열을 gemini-3.7-flash로 변경합니다.
2. 사고 예산 파라미터 교체: 정수 thinking_budget 구성을 다음 값 중 하나로 설정된 문자열 enum thinking_level로 바꿉니다.
   • HIGH: 밀도 높은 시각적 QA, 순식간에 일어나는 움직임 감지(스포츠, 편집) 또는 60분 이상의 동영상에 대한 다단계 추론에 권장됩니다.
   • MEDIUM: 기본 사고 수준입니다. 이 수준은 일반적인 동영상 Q&A, 강의 요약, 클립 검색에 최적의 균형을 제공합니다.
   • LOW: 빠른 스크립트 중심 검색 또는 기본 메타데이터 추출과 같은 작업에 권장됩니다.
3. 지원 중단 및 지원되지 않는 매개변수 삭제:
   • temperature, top_p, top_k가 삭제됩니다.
   • candidate_count, frequency_penalty, presence_penalty가 삭제됩니다.
   • 대화 기록에서 사전 입력된 모델 턴을 삭제합니다.

개발자를 위한 요약 체크리스트

대상 모델 ID: gemini-3.7-flash

지원 중단된 thinking_budget 또는 temperature 필드 대신 thinking_level(기본값은 MEDIUM, 유효한 값은 LOW, MEDIUM, HIGH)를 사용합니다. MINIMAL은 이 모델에서 지원되지 않습니다.

지원되지 않는 매개변수 frequency_penalty, presence_penalty, candidate_count, temperature, top_p, top_k를 삭제합니다.

멀티턴 채팅 요청 기록에서 사전 입력된 모델 턴을 삭제합니다.

엄격한 FunctionResponse 일치 (id 또는 call_id 및 name)를 보장하고 \n\n를 사용하여 도구 전 안내의 형식을 지정합니다.

추가 리소스

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