Gemini 3.8 Flash 개발자 가이드

Gemini 3.8 Flash는 Google의 가장 지능적인 주력 모델로, 소프트웨어 엔지니어링, 에이전트형 작업, 전문 분야의 중요한 다단계 추론 전반에서 3.7 Flash보다 크게 개선되었습니다. 3.8 Flash는 3.7 Flash에 비해 크게 향상되어 고비용 프런티어 모델의 성능에 근접하는 경우가 많습니다.

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

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

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

3.7 Flash와 비교했을 때 3.8 Flash는 토큰 소비가 더 많지만 정확성이 더 높고 성능이 더 안정적입니다. 하지만 3.8 Flash는 사고 수준을 통해 노력 제어 기능을 제공하므로 이러한 소비를 조절할 수 있습니다. 중간 사고 수준에서는 토큰 소비를 줄이면서 복잡한 에이전트 작업을 해결할 수 있습니다. 지연 시간에 민감한 작업에 낮은 사고 수준을 사용하여 컴퓨팅 오버헤드를 완전히 방지할 수도 있습니다. 컴퓨팅 효율성을 최적화하려면 3.7 Flash를 사용하는 것이 좋습니다.

모델 사양 및 비교

다음 표는 3.8 Flash, 3.7 Flash, 3.1 Pro 간의 몇 가지 사양을 비교한 것입니다.

	Gemini 3.8 Flash	Gemini 3.7 Flash	Gemini 3.1 Pro
모델 ID	gemini-3.8-flash	gemini-3.7-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)	LOW, MEDIUM, HIGH (기본값: MEDIUM)	LOW, MEDIUM, HIGH (기본값: HIGH)
주요 초점	에이전트형 워크플로, 코딩, 대화형 동영상 이해	일반 에이전트형 워크플로, 다단계 조정, 코딩	심층 추론, 복잡성이 높은 작업

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

Gemini 3.8 Flash의 새로운 기능

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

평가 관련 업계 기준치	3.8 Flash	3.7 Flash
Terminal-bench 2.1	90.8%	81.6%
SWE-Bench Pro	61.6%	60.4%
SWE-Atlas	51.9%	48.0%
τ³-bench Banking	38.1%	30.9%
CharXiv (멀티모달)	86.2%	84.5%
GDP.pdf	35.0%	34.0%
Humanity's Last Exam (HLE)	45.4%	45.7%

빠른 시작

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

필수 API 규칙 및 동작 규칙

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

Gemini 3.8 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.7 Flash 또는 3.6 Flash에서 3.8 Flash로

3.7 Flash 또는 3.6 Flash에서 3.8 Flash로 마이그레이션하려면 다음 단계를 따르세요.

1. 모델 ID 업데이트: API 호출의 모델 문자열을 gemini-3.8-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.8-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.8 Flash 모델 페이지
• 소개 노트북