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 간의 일부 사양을 비교한 것입니다.

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

Gemini 3.8 Flash의 새로운 기능

다음 표는 Gemini 3.8 Flash와 3.7 Flash 간의 표준 개발자 평가 벤치마크를 비교한 것입니다.

빠른 시작

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

필수 API 규칙 및 동작 규칙

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: 기본 사고 수준입니다. 이 수준은 일반 동영상 질의 응답, 강의 요약, 클립 검색에 최적의 균형을 제공합니다.
   • LOW: 빠른 트랜스크립트 중심 검색 또는 기본 메타데이터 추출과 같은 작업에 권장됩니다.
3. 지원 중단된 매개변수 및 지원되지 않는 매개변수 삭제:
   • temperature, top_p, top_k를 삭제합니다.
   • candidate_count, frequency_penalty, presence_penalty를 삭제합니다.
   • 대화 기록에서 미리 채워진 모델 턴을 삭제합니다.

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

추가 리소스

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