본문으로 건너뛰기
6분 읽기

Gemini 3.6 Flash 마이그레이션: API 변경, Copilot, AI Gateway

deprecated sampling 옵션, prefilled turn, thinking 설정, Copilot 정책, AI Gateway ID를 수정하며 Gemini 3.6 Flash 또는 3.5 Flash-Lite로 옮기는 방법을 설명합니다.

Gemini 모델 문자열 교체는 이번 업그레이드에서 가장 작은 부분입니다. 요청 계약을 바꾸는 것이 마이그레이션입니다. deprecated sampling 옵션과 미리 채운 model turn을 제거하고, thinking과 function response 필드를 검토한 다음 같은 작업으로 Gemini 3.6 Flash와 Gemini 3.5 Flash-Lite를 비교해야 합니다.

Google은 2026년 7월 21일 두 모델을 정식 출시했습니다. GitHub와 Vercel도 각자 호스팅 경로를 추가했지만, 제품별 정책 이름, 식별자, 배포 시점, 청구 방식은 서로 다릅니다. 이 글은 GitHub가 7월 31일 Copilot의 Gemini 3 Flash와 Gemini 2.5 Pro 폐기를 완료한 이후인 8월 5일 공식 문서를 기준으로 합니다.

두 개의 안정 계층 중 선택하기

모델Google 모델 ID기본 thinking입력 / 100만출력 / 100만평가 출발점
Gemini 3.6 Flashgemini-3.6-flashmedium$1.50$7.50코딩, 멀티모달 분석, 여러 단계의 에이전트 작업
Gemini 3.5 Flash-Litegemini-3.5-flash-liteminimal$0.30$2.50대량 추출·분류와 범위가 좁은 subagent 작업

두 모델 페이지는 모두 입력 한도 1,048,576토큰과 출력 한도 65,536토큰을 표시합니다. 두 페이지 모두 Computer Use를 **Supported (Preview)**로 표시합니다. 이는 Flash-Lite가 Computer Use를 지원하지 않는다고 썼던 이 글의 이전 내용을 바로잡은 것입니다.

“지원”은 “무인 워크플로에서 안전”과 같지 않습니다. Preview 도구에는 여전히 권한 경계, 행동 검증, rollback 경로가 필요합니다. 기능 가능 여부는 모델 페이지를, 신뢰성은 자체 테스트를 기준으로 판단하세요.

최소 Interactions API 호출부터 증명하기

Google의 현재 latest-model 가이드는 최신 모델의 권장 경로로 Interactions API를 제시합니다. 요청 형태 오류를 쉽게 분리할 수 있도록 도구 없이 시작하세요.

npm install @google/genai
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.6-flash",
  input: `이 TypeScript 변경을 검토하세요.
수정하기 전에 위험한 파일과 실행할 테스트를 나열하세요.`,
});

console.log(interaction.outputText);

이 예시는 Google의 현재 JavaScript quickstart와 대조했지만 Gemini API 자격 증명으로 실행하지는 않았습니다.

기능은 텍스트, 구조화 출력, 함수 호출, 상태 이어가기, 내장 도구 순서로 하나씩 추가합니다. 단계별 호출 흐름을 만들면 실패 원인이 모델, 요청 형태, 도구 계약, 상태 관리 중 어디에 있는지 구분하기 쉽습니다.

deprecated sampling 옵션 제거하기

Gemini 3.6 Flash와 3.5 Flash-Lite부터 temperature, top_p, top_k는 deprecated입니다. Google은 현재 이 값을 무시하며, 이후 모델 세대에서는 보내는 경우 HTTP 400을 반환할 것이라고 설명합니다.

기존 값을 조정하지 말고 Gemini adapter에서 제거하세요.

// Gemini 3.6과 3.5 Flash-Lite 호출에서 이 기존 설정을 제거합니다.
const legacyGenerationConfig = {
  temperature: 0.7,
  topP: 0.9,
  topK: 40,
};

이 차이는 장애 진단에서 중요합니다. sampling 필드는 현재 조용히 무시될 수 있지만, 다른 요청 계약 위반은 즉시 실패할 수 있습니다. HTTP 200 응답만으로 모든 옵션이 여전히 효과가 있다고 판단해서는 안 됩니다.

일관된 응답 형태에는 system instruction과 structured output을 사용합니다. sampling 설정에 결정성을 기대하지 말고 스키마나 도메인 검증기로 결과를 강제하세요.

prefilled model turn 제거하기

현재 모델은 마지막 비어 있지 않은 turn의 역할이 model인 요청을 거절합니다. 다음 기존 prefill 패턴은 HTTP 400을 반환합니다.

{
  "contents": [
    { "role": "user", "parts": [{ "text": "Translate Hello world to Korean." }] },
    { "role": "model", "parts": [{ "text": "Translation:" }] }
  ]
}

prefill을 instruction이나 structured output 계약으로 바꾸세요. Interactions API에서는 가짜 마지막 model turn을 수동으로 붙이는 대신 previous_interaction_id로 서버 측 대화를 이어갑니다.

이 필드 이름을 모든 SDK에 기계적으로 적용하지 마세요. 프로덕션 코드를 수정하기 전에 REST의 snake_case 필드인지 SDK 전용 property인지 확인해야 합니다.

나머지 Gemini 3.x 계약 감사하기

Google의 마이그레이션 체크리스트에는 sampling과 prefill 외의 항목도 있습니다.

  1. 모델 ID를 gemini-3.6-flash 또는 gemini-3.5-flash-lite로 변경합니다.
  2. thinking_budget을 thinking_level로 바꾸고 복잡한 작업은 medium이나 high를 평가합니다.
  3. Gemini 3.x 요청에서 지원하지 않는 candidate_count를 제거합니다.
  4. API가 반환한 thought signature를 도구 turn 사이에서 보존합니다.
  5. generateContent에서는 모든 FunctionResponse에 call_id와 name을 포함합니다.
  6. Interactions API 대화는 previous_interaction_id를 이용한 서버 측 상태를 우선합니다.
  7. 같은 합격 평가셋에서 도구 호출, turn, 토큰, 지연, 원하지 않은 수정을 측정합니다.

마지막 항목은 문서화된 계약을 바탕으로 한 편집상의 엔지니어링 권고입니다. Google은 자체 평가에서 3.6 Flash가 turn과 원하지 않은 수정을 줄였다고 설명하지만, 제공사 결과가 실제 저장소나 도구 하네스에서 같은 개선을 보장하지는 않습니다.

Copilot 폐기 간극 닫기

GitHub는 7월 21일 Copilot Pro, Pro+, Max, Business, Enterprise 사용자와 지원 클라이언트를 대상으로 Gemini 3.6 Flash의 점진적 배포를 발표했습니다. Business와 Enterprise 관리자는 사용자가 선택하기 전에 Gemini 3.6 Flash Preview라는 이름의 정책을 활성화해야 합니다.

Google API 모델은 안정 GA여도 GitHub의 호스팅 제품 정책에는 Preview 이름이 남을 수 있습니다. 두 표면을 별도로 관리해야 합니다.

GitHub는 7월 31일 모든 Copilot 경험에서 Gemini 3 Flash와 Gemini 2.5 Pro를 폐기했습니다. Gemini 3 Flash의 문서화된 대안은 Gemini 3.6 Flash입니다. 현재 마이그레이션에서는 예전의 미래형 알림을 반복하지 말고 완료 여부를 확인해야 합니다.

  1. 팀 지침과 자동화에서 폐기된 모델 이름을 검색합니다.
  2. 조직 또는 엔터프라이즈 모델 정책이 3.6 Flash를 허용하는지 확인합니다.
  3. 팀이 실제로 쓰는 클라이언트와 계정에 모델이 보이는지 확인합니다.
  4. 교체 모델에서 같은 읽기, 수정, agent 작업을 실행합니다.
  5. 출력 합격 여부, 도구 동작, 지연, usage-based 비용을 기록합니다.

관리자가 Copilot 정책을 바꿔도 애플리케이션의 Gemini API 모델 ID는 자동으로 바뀌지 않습니다.

정확한 Vercel AI Gateway ID 비교하기

Vercel AI Gateway는 두 경로를 google/gemini-3.6-flash와 google/gemini-3.5-flash-lite로 제공합니다. 간단한 AI SDK 비교에서는 프롬프트를 고정할 수 있습니다.

import { streamText } from "ai";

const models = [
  "google/gemini-3.6-flash",
  "google/gemini-3.5-flash-lite",
] as const;

for (const model of models) {
  const result = streamText({
    model,
    prompt: "배포 실패 원인을 찾고 검증 명령 하나를 제안하세요.",
  });

  for await (const textPart of result.textStream) {
    process.stdout.write(textPart);
  }
}

이 구문은 Vercel의 출시 예시와 대조했지만 Gateway 자격 증명으로 실행하지는 않았습니다. Gateway는 전송과 관측을 표준화하지만 제공사의 요청 제한을 없애거나 두 모델을 행동상 동일하게 만들지는 않습니다.

AI SDK agent의 승인, 복구, timeout 설계는 AI SDK 7 프로덕션 에이전트 가이드를 참고하세요.

합격 결과를 기준으로 배포하기

요청 호환성과 모델 품질을 분리하는 순서를 사용합니다.

  1. sampling 옵션, thinking_budget, candidate_count, 마지막 model-role turn을 검색합니다.
  2. 모델 ID를 바꾸기 전에 지원하지 않는 필드를 제거합니다.
  3. 최소 텍스트 요청과 오류 처리를 증명합니다.
  4. 구조화 출력과 함수 호출을 계약 테스트와 함께 추가합니다.
  5. 사용 권한이 확인된 대표 사례 20~50개를 두 모델 계층에서 실행합니다.
  6. 합격 결과, 도구 호출 수, 총 토큰, 지연, 재시도, 원하지 않은 파일 수정을 비교합니다.
  7. 쓰기나 UI 자동화를 허용하기 전에 읽기 전용 작업을 shadow 평가합니다.
  8. 명시적인 오류, 비용, 지연 rollback 임계값과 함께 작은 트래픽 비율부터 전환합니다.

여러 단계 추론, 코드 작업, 멀티모달 해석에서 측정된 이점이 있을 때 3.6 Flash를 사용합니다. 빈도가 높고 범위가 좁으며 외부 검증이 가능한 작업에는 Flash-Lite를 사용합니다. Flash-Lite의 thinking level은 추가 작업이 합격 결과를 개선해 지연과 비용을 상쇄한다는 평가가 있을 때만 올리세요.

권고

모델을 비교하기 전에 요청 계약을 고치세요. deprecated sampling 필드와 prefilled turn을 제거하고 나머지 Gemini 3.x 필드를 갱신한 뒤 가장 작은 호출을 증명합니다. 그 다음 같은 검증기를 적용하며 3.6 Flash를 복잡한 작업 후보, 3.5 Flash-Lite를 대량 작업 후보로 평가하세요.

마지막으로 Google API 코드, GitHub Copilot 정책, Vercel AI Gateway 설정을 서로 다른 세 개의 제어로 마이그레이션해야 합니다. 비슷한 이름이 하나의 배포를 뜻하지는 않습니다.

주요 출처