제미나이 temperature 폐지 — 공식 문서 네 쪽이 갈렸고, 모델 50개 중 43개는 아직 그 값을 싣고 있어요

돌아가던 코드를 안 건드렸는데 문서가 먼저 바뀌는 일이 있어요. 제미나이 API의 temperature, top_p, top_k가 지금 그런 상태예요.

결론부터 적을게요. 폐지는 선언됐고, 요청은 아직 통과해요. 그리고 이 두 문장이 동시에 참이라는 사실을 한 쪽 문서만 봐서는 알 수 없어요. 같은 ai.google.dev 안에서 네 쪽이 서로 다른 말을 하고 있거든요.

그래서 문서를 네 쪽 다 받아 축자로 비교하고, API에는 모델 다섯 개에 일곱 가지 설정을 직접 쳐 봤어요. 모델 목록 50개 중 43개가 아직 그 세 파라미터의 기본값을 자기 메타데이터에 싣고 있었어요.

먼저 잰 범위부터 밝힐게요. 이 글의 숫자는 전부 Gemini Developer API의 v1beta를 기준으로, 2026년 8월 22일 오후 3시 30분에서 4시 5분 사이(한국 시각) 에 공식 문서 HTML과 API 응답을 직접 받아 센 값이에요. Vertex AI 쪽은 확인하지 않았어요.

어떤 조건에서 쟀는지 먼저 못박을게요

값이 조회 시점에 묶이는 종류의 측정이라 조건이 숫자보다 먼저예요.

한 가지 더 밝혀 둘게요. ?hl=en 없이 curl로 받으면 302가 무한히 돌아요. 이번에 curl: (47) Maximum (50) redirects followed로 두 번 죽었고, 주소 끝에 ?hl=en을 붙이니 200이 왔어요. 마크다운 원본 경로도 같은 이유로 curl로는 못 받아서 HTML 판을 받아 파싱했어요.

폐지를 선언한 자리는 릴리스 노트 한 줄이에요

출발점은 제미나이 API 릴리스 노트예요. 주소는 ai.google.dev/gemini-api/docs/changelog이고, 페이지 하단 표기는 Last updated 2026-08-13 UTC였어요.

2026년 7월 21일 항목에 이 문장이 있어요.

Deprecated parameters: The sampling parameters temperature, top_p and top_k are now deprecated. See the Latest Gemini Model for details.

샘플링 파라미터 세 개가 이제 폐지됐다는 뜻이에요. 같은 7월 21일 항목의 나머지 내용은 gemini-3.6-flash와 gemini-3.5-flash-lite의 정식 출시 발표였고요. 즉 모델 두 개가 정식으로 나온 날, 파라미터 세 개가 함께 폐지 목록에 올랐어요.

그런데 이 한 줄이 전부예요. 왜 폐지하는지, 대신 무엇을 쓰라는지, 언제부터 안 되는지는 이 자리에 없어요. 문장 끝에 붙은 링크를 따라가라고 적혀 있죠.

세 파라미터가 하던 일부터 짚고 갈게요

셋 다 "다음 낱말을 고를 때 얼마나 넓게 보느냐"를 정하는 값이에요. 공식 레퍼런스가 직접 적어 둔 설명을 그대로 옮길게요.

레퍼런스는 두 방식의 관계도 설명해요. 토큰을 확률 순으로 줄 세운 다음, topK는 개수로 자르고 topP는 누적 확률로 자른다는 거예요. 그래서 둘을 함께 쓰면 개수 제한과 확률 제한이 겹쳐 걸려요.

여기서 하나 짚을 게 있어요. 폐지 목록에 오른 건 이 셋뿐이에요. 같은 GenerationConfig 안에는 seed, presencePenalty, frequencyPenalty가 그대로 남아 있고, 전부 Optional 표시예요. 즉 "생성 조절 손잡이를 전부 걷어낸다"가 아니라 셋만 골라 내린 상태예요.

한 달 사이에 무슨 일이 있었는지 순서로 보면 이래요

릴리스 노트의 날짜 헤딩을 위에서부터 읽으면 흐름이 보여요.

폐지 선언이 붙은 7월 21일 이후로 정식 출시가 한 번 더 있었어요. 그러니까 폐지된 파라미터를 아직 싣고 있는 모델 중에는, 폐지 선언 뒤에 새로 나온 것도 있다는 뜻이에요.

그 링크가 가리킨 자리에 그 설명이 없었어요

링크의 실제 주소는 이랬어요.

/gemini-api/docs/latest-model#sampling-parameter-deprecation

# 뒤가 문서 안의 특정 자리를 가리키는 앵커예요. 그래서 대상 문서를 받아 그 앵커를 찾아봤는데 없었어요.

27개 가운데 코드 예제 탭과 페이지 골격용을 빼고 절 제목만 추리면 이래요. new-model, quickstart, whats-new-gemini-3-7-flash, choosing-the-right-model, understanding-reasoning-levels, updated-antigravity-agent, migration-checklist, migrate-to-gemini-3-7-flash, pricing, next-steps. 뺀 쪽까지 합쳐 27개를 전부 훑어도 샘플링이나 폐지라는 낱말이 들어간 자리는 하나도 없어요.

링크 자체는 열려요. 문서는 정상적으로 뜨고요. 다만 브라우저가 이동할 자리를 못 찾아 문서 맨 위에 그대로 머물러요. 그래서 링크를 눌러 들어간 사람은 "설명이 어디 있다는 거지"부터 헤매게 돼요.

설명은 그 문서 안에 실제로 있어요. 다만 #migration-checklist 쪽과 마이그레이션 표에 들어 있어요. 아래에서 그 문장을 볼게요.

문서 네 쪽이 서로 다른 말을 해요

같은 날 같은 사이트에서 받은 네 쪽이 이렇게 갈렸어요.

걷어내라고 적은 쪽

Latest Gemini model 가이드의 마이그레이션 표 위 문장이에요.

To upgrade from Gemini 3.5 Flash, Gemini 3 Flash (Preview), or Gemini 3.1 Pro, ensure you remove deprecated sampling parameters (temperature, top_p, top_k) and prefilled model turns. Gemini 3.6 Flash already no longer supported these parameters.

체크리스트 쪽은 더 직설적이에요.

Remove deprecated sampling parameters: Strip temperature, top_p, and top_k from generation configs.

여기서 문장이 두 갈래로 갈린다는 점을 짚고 갈게요. "걷어내라"는 권고고, "3.6 Flash는 이미 이 파라미터를 지원하지 않는다"는 사실 주장이에요. 권고는 따르면 그만이지만, 사실 주장은 확인할 수 있어요. 아래 실측이 이 문장과 맞물려요.

한 가지 더 있어요. 영어 원문의 no longer supported는 "거부한다" 로도 "받기는 하되 효과가 없다" 로도 읽혀요. 제가 잰 것은 거부 여부 하나예요. 이 구분은 글 끝까지 지킬게요.

그대로 쓰라고 가르치는 쪽

API 레퍼런스의 GenerationConfig 항목은 이렇게 적혀 있어요.

temperature number Optional. Controls the randomness of the output.

폐지 표시가 없어요. Optional이에요.

여기서 "그냥 표기를 안 하는 문서인가"를 의심해 볼 만하죠. 그래서 같은 페이지가 폐지를 표기할 줄 아는지 확인했어요. 같은 문서에서 Deprecated라는 낱말이 붙은 자리는 정확히 두 군데였고, 둘 다 다른 필드였어요.

VideoMetadata This item is deprecated! Deprecated: Use GenerateContentRequest.processing_options instead.

language_config Union type Deprecated: Use top-level language_codes instead.

어휘가 없어서 안 붙은 게 아니에요. 이 문서는 폐지를 표기하는 방법을 알고 있고, 실제로 두 곳에 붙였고, 샘플링 파라미터 세 개에는 안 붙였어요.

텍스트 생성 가이드는 한 걸음 더 나가요. 본문이 이렇게 적어요.

You can also override default generation parameters, such as temperature, using the generation_config parameter.

그리고 바로 아래 예제 세 종이 전부 generation_config에 temperature를 넣어요. REST 예제는 모델까지 최신판이에요.

{
  "model": "gemini-3.7-flash",
  "input": "Explain how AI works",
  "generation_config": { "temperature": 1.0 }
}

폐지 대상 파라미터를, 폐지 이후에 나온 모델에, 공식 가이드가 예제로 가르치고 있어요.

재미있는 비대칭도 하나 있어요. 이 가이드에서 top_p와 top_k는 등장 횟수가 0회예요. 세 개가 함께 폐지됐는데 문서에서는 두 개만 사라지고 temperature만 남았어요.

그래서 지금 보내면 어떻게 되나 직접 쳐 봤어요

문서가 갈리면 답은 응답에 있어요. 요청 본문을 고정하고 generationConfig만 바꿔 모델 다섯 개에 일곱 가지를 던졌어요. 프롬프트는 영어 명사 하나만 답하라는 짧은 문장이었고요.

정리하면 이래요. 살아 있는 네 모델 전부에서 세 파라미터가 통과했어요. 가이드가 "이미 지원하지 않는다"고 지목한 gemini-3.6-flash도 200이었고, 8월 13일에 정식 출시된 gemini-3.7-flash도 200이었어요.

한 번 실패한 걸 결론으로 삼을 뻔했어요

gemini-3.7-flash는 1차 실행에서 네 건 중 한 건이 503, 세 건이 읽기 타임아웃이었어요. 503 메시지는 이랬고요.

This model is currently experiencing high demand. Spikes in demand are usually temporary. Please try again later.

여기서 멈췄으면 "최신 모델만 거동이 다르다"고 적었을 거예요. 그런데 시간을 두고 다시 치니 네 건 전부 200이 왔어요. 시도 횟수는 각각 2회, 1회, 1회, 3회였어요. 문서가 갈릴 때는 실패 한 번도 결론으로 굳히면 안 돼요.

200이 "몰라서 통과"가 아니라는 증거를 먼저 놨어요

여기가 이 측정의 핵심이에요. 만약 이 API가 모르는 필드를 조용히 버린다면, 200은 아무것도 증명하지 않아요. 폐지돼 사라진 이름을 그냥 무시한 결과일 수도 있으니까요.

그래서 존재하지 않는 이름을 하나 지어서 같은 자리에 넣어 봤어요. 결과는 다섯 모델 전부 400이었고 메시지가 이랬어요.

Invalid JSON payload received. Unknown name "nonsenseParam" at 'generation_config': Cannot find field.

generation_config는 모르는 필드를 무시하지 않아요. 이름을 못 찾으면 요청 자체를 400으로 끊어요. 그러니 temperature, topP, topK가 200을 받았다는 건 그 이름이 아직 스키마에 살아 있다는 뜻이에요. 이름이 지워진 게 아니라 폐지 딱지가 붙은 상태인 거죠.

범위 검증도 아직 돌아요

이름만 남고 검사는 꺼졌을 수도 있으니 그것도 확인했어요. temperature에 9.9를 넣으니 400이 왔고 메시지가 이랬어요.

GenerateContentRequest.generation_config.temperature: temperature must be in the range [0.0, 2.0].

허용 범위가 0.0에서 2.0 사이라는 것까지 그대로 말해 줘요. 값을 받아 파싱하고 검사까지 하고 있어요.

레퍼런스가 "못 넣는다"고 적은 자리도 통과했어요

topK 설명에는 조건절이 하나 붙어 있어요.

Models running with nucleus sampling don't allow topK setting.

누적 확률 방식으로 도는 모델에는 topK를 설정할 수 없다는 뜻이에요. 같은 문서가 topP 쪽에도 비슷한 단서를 달아 뒀고요. topK 값이 비어 있는 모델은 top-k 표본을 쓰지 않으며 요청에 topK를 넣는 것도 허용하지 않는다고요.

그래서 어떤 모델이 여기 걸리는지 보려고 메타데이터를 확인했는데, 제가 친 네 모델은 전부 topK 값이 64로 채워져 있었어요. 비어 있는 모델이 아니었던 거죠. 그리고 실제 요청에서도 topK: 1이 네 모델 모두 200이었어요.

즉 이 조건절은 적용될 모델을 제가 이번에 만나지 못한 것이지 문서가 틀렸다는 뜻이 아니에요. 다만 실무에서는 이 차이가 중요해요. topK를 쓰던 코드를 다른 모델로 옮길 때, 그 모델의 메타데이터에 topK 값이 실려 있는지부터 보는 게 순서예요.

검증이 모델 확인보다 먼저였어요

측정 중에 나온 곁가지인데 알아 둘 만해요. gemini-2.5-pro는 지금 404예요.

This model models/gemini-2.5-pro is no longer available to new users. Please update your code to use models/gemini-3.1-pro-preview for the latest features and improvements.

그런데 없는 그 모델에 범위를 벗어난 temperature를 보내면 404가 아니라 400이 와요. 요청 파싱과 값 검증이 모델 존재 확인보다 앞선다는 뜻이에요. 그래서 400 하나만 보고 "모델은 살아 있나 보다"라고 읽으면 어긋나요. 모델이 살아 있는지는 설정 없이 한 번 던져 봐야 알 수 있어요. 모델 수명을 확인하는 방법은 제미나이 모델 지원 종료를 문서와 API로 대조한 기록에 따로 정리해 뒀어요.

모델 50개 중 43개가 아직 그 값을 싣고 있어요

응답 하나하나 말고, API가 스스로 광고하는 내용도 셌어요. 모델 목록을 페이지 끝까지 받으면 모델마다 기본 설정값이 함께 실려 오거든요.

50개 중 43개면 86%예요. 생성 호출을 지원하는 37개로 좁히면 36개, 그러니까 하나만 빼고 전부예요. 그 하나는 antigravity-preview-05-2026이었어요.

검산도 맞아요. 생성 호출을 지원하면서 temperature를 실은 36개에, 생성 호출을 지원하지 않으면서도 실은 7개를 더하면 43이에요.

값이 방치된 게 아니라 통일돼 있었어요

"남아 있긴 한데 옛날 값이 그냥 붙어 있는 것 아닌가" 싶어서 네 값을 묶어 조합을 세어 봤어요. 생성 호출을 지원하는 37개 기준이에요.

조합이 사실상 하나예요. 갈리는 건 maxTemperature가 2냐 1이냐 하나뿐이고, 나머지 세 값은 37개 중 36개가 똑같아요. 8월 13일에 나온 gemini-3.7-flash도, 가이드가 "이미 지원하지 않는다"고 지목한 gemini-3.6-flash도 전부 1, 2, 0.95, 64였어요.

기본값이 1이 아닌 모델은 전체 50개 중 딱 하나, aqa였어요. 값은 0.2고, 이 모델은 생성 호출이 아니라 generateAnswer만 지원해요. 생성 호출을 지원하지 않는데도 temperature를 실은 나머지 여섯은 전부 실시간 음성이나 번역 계열이었고요.

방치된 잔재라면 값이 제각각이어야 해요. 한 줄로 정렬돼 있다는 건 지금도 관리되고 있다는 뜻에 가까워요. 물론 이건 제 해석이고, 관측된 사실은 조합이 두 가지뿐이라는 것 하나예요.

그럼 무엇으로 조절하나요

세 손잡이를 내렸으면 대신 잡을 게 있어야죠. 같은 가이드가 지금 앞세우는 건 thinking_level 이에요. 축자로 옮길게요.

Gemini 3.7 Flash gives developers flexible control over latency and intelligence by adjusting the model's thinking level

세 단계로 갈려요.

예제도 generation_config에 문자열로 넣는 모양이에요.

{ "thinking_level": "medium" }

마이그레이션 체크리스트에는 thinking_budget을 이 문자열 값으로 바꾸라는 항목도 함께 있어요. 숫자로 예산을 주던 방식에서 단계 이름으로 옮겨 간 거죠.

한 가지 조심할 게 있어요. 문서는 thinking_level을 "샘플링 파라미터의 대체재"라고 말하지 않았어요. 지연과 지능을 조절하는 손잡이로 소개할 뿐이에요. 그러니 "temperature 대신 thinking_level을 쓰면 된다"고 옮기면 문서가 하지 않은 말을 얹는 셈이에요. 지금 확실한 건 공식 문서가 조절 수단으로 앞세우는 게 이것이라는 사실까지예요.

그래서 지금 지워야 하나요

제가 관측한 범위에서 판단하면 이래요.

새로 짜는 코드에는 넣지 마세요. 공식 마이그레이션 체크리스트가 최신 모델로 옮길 때 걷어내라고 직접 적어 뒀어요. 앞으로 나올 모델이 이 값을 무시하기 시작하면, 코드에 남은 숫자는 동작하지 않는데 동작한다고 믿게 만드는 함정이 돼요. 그게 지워진 것보다 나빠요.

돌아가는 코드를 오늘 급히 뜯을 이유는 이번 관측에서 찾지 못했어요. 요청이 거부되지 않았고, 범위 검증도 살아 있고, 모델 메타데이터도 값을 그대로 싣고 있어요. 모델 아이디를 바꾸는 작업이 생길 때 같이 정리하는 편이 안전해요. 모델을 옮기다 오류를 만나면 제미나이 AI 스튜디오 오류 유형별 대처 쪽을 참고하세요.

그리고 문서 한 쪽만 보고 판단하지 마세요. 이번 경우 릴리스 노트만 본 사람과 텍스트 생성 가이드만 본 사람은 정반대 결론에 도달해요. API 키를 막 발급받아 예제부터 따라 하는 분이라면 후자에 걸리기 쉬워요. 발급 절차부터 필요하면 구글 AI 스튜디오 API 키 발급 방법을 먼저 보시고요.

이 API에는 값을 잘라서 받아 준 전례가 있어요

같은 릴리스 노트를 아래로 한참 내리면 2024년 11월 자리에 이런 항목이 있어요.

Change to top_k parameter: The gemini-1.5-flash-002 model supports top_k values between 1 and 41 (exclusive). Values greater than 40 will be changed to 40.

40을 넘는 값을 넣으면 거부하지 않고 40으로 바꿔서 처리했다는 뜻이에요. 이 API가 파라미터를 다룰 때 "막는다"와 "조용히 조정한다" 사이를 오간 적이 있다는 기록이죠.

다만 이건 다른 파라미터의 옛 사례예요. 지금 세 파라미터가 그렇게 처리되고 있다는 근거로 쓰면 안 돼요. 오늘 확인된 건 값이 조정된다는 게 아니라 요청이 통과한다는 것 하나예요.

직접 확인하는 데 5초면 돼요

쓰시는 모델이 지금 어떤지는 짧은 요청 하나로 끝나요. 키만 자기 것으로 바꿔서 던져 보세요.

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: 자기키" \
  -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent" \
  -d '{"contents":[{"parts":[{"text":"hi"}]}],"generationConfig":{"temperature":0.5}}'

200이 오면 아직 통과하는 상태고, 400이 오면 메시지 본문을 읽어 보세요. 이때 없는 필드 이름을 하나 넣어 같이 던져 보는 게 중요해요. 그게 400으로 끊기는지를 봐야 200의 뜻이 확정되거든요.

확인하지 못한 것도 적어 둘게요

이 글이 말하지 않는 것들이에요.

첫째, 온도 값이 실제로 출력을 바꾸는지는 몰라요. temperature 0.0과 2.0으로 같은 프롬프트를 여섯 번씩 던져 결과 분포를 비교하려 했어요. 그런데 첫 여섯 번 중 다섯 번이 429로 막혔어요. 무료 등급 쿼터예요. 표본이 하나면 아무 결론도 못 내니까 실험을 접었어요. 200은 "받아들여졌다"까지만 말해요.

이 대목은 조금 더 풀어 둘게요. 수용 행렬을 돌릴 때 응답 본문도 함께 받았거든요. 답으로 온 낱말이 이랬어요.

이 표를 근거로 삼고 싶은 유혹이 있어요. 위 두 줄은 거의 같은 낱말이 나왔고 아래 줄은 제각각이니까, "3계열은 값이 안 먹고 2.5는 먹는다"고 읽고 싶어지죠.

그렇게 읽으면 안 돼요. 각 칸이 한 번씩만 친 결과예요. 온도를 2.0으로 올려도 우연히 같은 낱말이 나올 수 있고, 온도를 0.0으로 고정해도 모델이 완전히 결정적이라는 보장은 없어요. 차이를 말하려면 같은 설정으로 여러 번 쳐서 분포를 봐야 하는데, 그 실험이 429로 막힌 거예요. 한 번의 관측으로 경향을 주장하는 것이 이 글이 피하려는 바로 그 실수라서, 원자료만 놓고 결론은 비워 둘게요.

둘째, 제거 시한을 찾지 못했어요. 릴리스 노트에도 마이그레이션 가이드에도 "언제부터 안 된다"는 날짜가 없었어요. 모델 폐지 문서는 모델 단위 종료일만 다루고요. 없다고 단정하지는 않을게요. 제가 찾지 못했다는 뜻이에요.

셋째, Vertex AI 쪽은 안 봤어요. 전부 Gemini Developer API의 v1beta 기준이고, 다른 API 버전도 치지 않았어요.

넷째, 개인 키 하나로 쟀어요. 그 키가 속한 프로젝트의 사용 티어를 확인하지 못했으니 "어떤 키에서도 같다"로 일반화하지 않을게요.

정리하면

폐지 딱지가 붙었다고 그 자리가 바로 무너지지는 않아요. 다만 문서가 갈리기 시작한 시점부터는 문서를 근거로 삼는 게 위험해져요. 이럴 때 확실한 건 응답 하나뿐이에요. 쓰시는 모델에 짧은 요청 하나만 던져 보면 5초면 확인돼요.

확인한 자료: 구글 Gemini API 공식 문서 「Release notes」(페이지 표기 최종 갱신 2026-08-13 UTC), 「Latest Gemini model」(2026-08-13 UTC), 「Generating content」 API 레퍼런스(2026-08-17 UTC), 「Text generation」(2026-08-17 UTC). 네 쪽 모두 2026년 8월 22일 오후 4시 1분에서 4시 5분 사이(한국 시각)에 HTML 원본으로 직접 받아 문자열을 셌어요. 실측값은 같은 날 오후 3시 30분에서 3시 58분 사이에 generativelanguage.googleapis.com 의 v1beta 에 모델 목록 조회와 생성 호출을 직접 넣어 받은 응답이에요. gemini-3.7-flash 네 건은 첫 실행이 503과 타임아웃이라 오후 3시 54분에서 3시 57분 사이에 다시 쳐서 받은 값이고요.