Gemini 4 Neon 마이그레이션: 기본 사고 수준 상향, 400 오류와 65K 제한

AIHubMix14분 분량

Google은 Gemini 3.1 Pro의 업그레이드 대상으로 Gemini 4 Neon을 안내하며, Gemini 4 Argon을 사용하던 일반적인 코딩 작업과 Gemini 3.8 Flash를 사용하던 복잡한 코딩 또는 과학 작업에도 Neon을 권장합니다. 모델 문자열을 gemini-4-neon으로 바꾸는 건 간단합니다. 나머지 변경 사항은 네 가지로 나뉩니다.

  • 눈에 띄지 않는 변경: 기본 사고 수준이 이제 high입니다. Argon과 3.8 Flash의 기본값은 medium이었습니다. 수준을 지정하지 않으면 각 요청에서 medium일 때보다 더 많이 추론합니다. 3.8 Flash 사용자는 비용이 늘지만, Argon 사용자는 작업당 비용이 오히려 줄어듭니다(아래 참고).
  • 명시적인 변경: Neon은 기존 코드에서 여전히 보내는 다음 항목에 HTTP 400을 반환합니다. thinking_budget, 네이티브 MINIMAL 수준, 두 가지 페널티 매개변수, 후보를 두 개 이상 요청하는 설정, 도구 호출에 포함된 잘못된 사고 서명입니다.
  • 조용히 무시되는 변경: temperature, top_p, top_k는 무시되며, 출력 토큰 제한이 낮으면 모델이 아직 추론 중일 때 멈출 수 있습니다. 명시적 컨텍스트 캐싱과 미리 채워 둔 어시스턴트 턴은 지원되지 않지만, Google은 이런 경우 어떻게 실패하는지 밝히지 않았습니다.
  • AIHubMix에서: 요청당 출력 토큰은 65,536개로 계획하세요. Google의 1M 토큰 장문 디코딩은 AIHubMix의 OpenAI 호환 엔드포인트에서 사용할 수 없으며, 이 글에서는 네이티브 경로를 테스트하지 않았습니다.

Gemini 4 Carbon에서 넘어오는 경우는 더 간단합니다. Google은 요청 스키마가 바뀌지 않는다고 밝혔으며, 주요 차이는 기본 수준입니다. 이 전환에 대해서는 Neon과 Carbon 비교 글에서 다룹니다.

시작 모델에 따라 달라지는 점

변경 사항 3.1 Pro에서 전환 Argon에서 전환 3.8 Flash에서 전환
기본 사고 수준 이제 high medium에서 high로 medium에서 high로
xhigh 수준 새로 추가 새로 추가 새로 추가
토큰 제한 1M으로 통합 이미 통합됨 1M으로 통합
명시적 캐싱 제거됨 이미 제거됨 제거됨
가격, 입력 / 출력 $2 / $12에서 $3 / $15로 $2 / $10에서 $3 / $15로 $0.75 / $3.75에서 $3 / $15로

Google 공식 가격, 토큰 100만 개당 USD입니다. Gemini 3.1 Pro의 $2/$12 요금은 최대 200K 토큰 프롬프트에 적용되며(그보다 크면 $4/$18), Neon은 1M 윈도우 전체에 동일한 요금을 적용합니다. Argon의 $2/$10은 2026년 12월 1일에 $4/$20으로 바뀌는 출시 기념 가격입니다. 3.8 Flash의 $0.75/$3.75 요금은 2026년 12월 31일까지 적용됩니다. Google은 3.1 Pro와 Argon 모두 high까지 지원한다고 밝혔지만, 3.1 Pro의 기본값은 명시하지 않았습니다.

이 글의 나머지 내용은 별도 표시가 없는 한 Google Cloud의 Google Neon 개발자 가이드와 AI Studio의 마이그레이션 체크리스트를 바탕으로 합니다.

시작 모델에 관한 참고 사항: Google AI Studio의 업그레이드 표에서는 3.8 Flash 사용자가 Gemini 4 Hydrogen으로 전환하도록 안내합니다. 복잡한 코딩 및 과학 작업을 위해 3.8 Flash에서 Neon으로 전환하라고 안내하는 것은 Google Cloud 가이드입니다. Google은 3.1 Pro Preview, 3.8 Flash 또는 Gemini 4 모델의 지원 종료 날짜를 발표하지 않았습니다.

눈에 띄지 않는 변경: 기본값이 high로 바뀜

Google은 이를 분명히 밝힙니다. "기본 thinking_level은 HIGH입니다(gemini-4-argon 및 gemini-3.8-flash의 MEDIUM에서 변경됨). 심층 추론 작업에는 XHIGH를 지원합니다…" 해결 방법도 간단히 제시합니다. "워크로드가 gemini-4-argon 또는 gemini-3.8-flash의 기본값인 MEDIUM에 의존했다면, 동등한 추론 지연 시간을 유지하도록 thinking_level="MEDIUM"을 명시적으로 설정하세요."

Artificial Analysis가 Google API를 측정한 결과에서 추가 수준에 따른 비용을 살펴보겠습니다(2026-11-19, 13:27 UTC 재확인. 제3자 측정치이며 AA가 모델을 다시 실행할 때마다 바뀝니다).

Neon 설정 AA 지수 작업당 $ 작업당 분 첫 응답(초)
Medium 54.9 1.90 8.3 20.1
High(기본값) 59.6 3.74 14.8 40.6
Xhigh 61.4 6.44 21.5 56.5

Neon의 $3/$15 요금을 기준으로 한 AA의 Intelligence Index 작업당 평균입니다. "첫 응답"은 첫 응답 토큰까지 걸리는 시간입니다.

medium에서 high로 바꾸면 지수 점수는 4.8점 오르지만, 작업당 비용은 거의 두 배, 작업당 소요 시간은 1.8배, 첫 응답 토큰까지 기다리는 시간은 두 배가 됩니다. 이어서 xhigh로 높이면 비용이 72% 더 들고 점수는 1.8점 오릅니다. 여러 단계를 거치는 어려운 작업에는 합리적인 선택이지만, 채팅 응답에는 그렇지 않습니다.

같은 데이터에서 Argon 사용자에게 반가운 점도 있습니다. Neon Medium은 Argon의 기본값인 Medium보다 점수가 높습니다(54.9 대 47.6). 작업당 비용은 $4.31에서 $1.90으로, 소요 시간은 28.9분에서 8.3분으로 줄어듭니다. Argon 가격이 두 배로 오르기 전부터, Argon에서 Neon Medium으로 바꾸면 품질은 높아지고 작업당 비용은 낮아집니다. Neon의 기본값인 High도($3.74, 14.8분) AA의 작업 기준으로 Argon Medium보다 작업당 비용이 적습니다. 수준을 지정하지 않을 때 포기하게 되는 것은 더 저렴한 Medium 옵션입니다.

기본값이 높아지면 다음과 같은 영향도 있습니다.

  • 추론 토큰도 출력 제한에 포함됩니다. Google 설명: "HIGH(기본값) 및 XHIGH에서 생성된 추론 토큰은 max_output_tokens에 포함되며, 턴 사이에 사고 서명을 보존하면 멀티턴 컨텍스트에 누적됩니다."
  • 컨텍스트가 더 빨리 찹니다. 멀티턴 코딩 에이전트에서는 추론 토큰이 누적됩니다. Google은 "지나치게 낮은 컨텍스트 압축 임계값"을 피하라고 경고하며, 지연 시간에 민감한 도구 턴에는 medium을 권장합니다.

수준을 설정하는 방법은 프로토콜에 따라 다릅니다.

프로토콜 필드 Neon에서 사용할 수 있는 값
네이티브 Gemini thinkingConfig.thinkingLevel LOW부터 XHIGH까지
Chat Completions reasoning_effort low부터 xhigh까지
Responses reasoning.effort low부터 xhigh까지
Anthropic Messages output_config.effort low부터 xhigh까지

네이티브 GenerateContent의 값은 대문자입니다. 나머지 세 프로토콜의 값은 gemini-4-neon에 대한 AIHubMix 매개변수 스키마를 기준으로 하며, 모든 프로토콜에서 기본값은 high로 표시되어 있습니다.

Google의 OpenAI 호환성 계층은 reasoning_effort를 사고 수준에 매핑하며, minimal은 low에 통합됩니다. 또한 두 항목은 "기능이 중복되므로 동시에 사용할 수 없다"고 명시합니다. 둘 중 하나만 보내세요.

400 오류

이 항목은 모두 Google이 Neon에 대해 문서화한 내용입니다. AIHubMix의 자체 오류 안내에 따르면 400 오류는 매개변수 오류이며 "대부분 상위 공급자에서 그대로 전달됩니다". 이 글을 위해 실시간 테스트를 진행하지 않았으므로 게이트웨이를 거쳐 받는 정확한 오류 문구는 다를 수 있습니다.

thinking_budget 및 MINIMAL

표시되는 현상: Gemini 3 모델에서 작동하던 요청이 HTTP 400을 반환합니다.

이유: Neon은 이름이 지정된 네 가지 수준만 허용합니다. Google 모델 페이지에 따르면 "thinking_budget을 설정하거나 thinking_level="MINIMAL"로 설정하면 HTTP 400 유효성 검사 오류가 반환됩니다." Google의 코드 변경 예시도 이전 필드를 표시합니다. thinking_budget=16384, # Returns HTTP 400 instead of mapping silently.

해결 방법: thinking_budget을 삭제하세요. MINIMAL은 LOW로 바꾸세요. OpenAI 호환 경로에서는 Google이 reasoning_effort="minimal"을 low로 매핑하지만, 직접 low를 보내면 혼란의 여지가 없습니다.

frequency_penalty, presence_penalty 및 추가 후보

표시되는 현상: 페널티를 설정하거나 후보를 여러 개 요청하는 경우 HTTP 400이 반환됩니다.

이유: "frequency_penalty, presence_penalty를 전달하거나 candidate_count를 1보다 큰 값으로 설정하면(candidateCount는 1로 고정) HTTP 400 오류가 반환됩니다."

해결 방법: 두 페널티를 모두 삭제하세요. candidate_count는 1로 유지하거나 생략하세요. Chat Completions에서는 n도 1보다 큰 값으로 보내지 마세요. Google은 호환성 계층에서 이를 어떻게 처리하는지 밝히지 않았으며, AIHubMix 스키마에서는 보내지 말아야 할 필드로 표시합니다.

max_output_tokens가 1,048,576보다 큰 경우

표시되는 현상: HTTP 400이 반환됩니다.

이유: 입력과 출력이 하나의 1,048,576 토큰 윈도우를 공유하므로, 출력 예산을 이보다 크게 설정할 수 없습니다.

해결 방법: AIHubMix에서는 최대 65,536을 보내세요(출력 제한 섹션 참고). 이 상한은 Google 자체 API에서 장문 디코딩을 할 때만 중요합니다.

누락되거나 잘못 배치된 사고 서명

표시되는 현상: 도구 호출 턴의 두 번째 단계 또는 그 이후 단계에서 HTTP 400이 반환됩니다.

이유: Neon은 현재 턴의 함수 호출에 첨부된 사고 서명을 검증합니다. "활성 턴에서 첫 번째 functionCall 부분의 thought_signature를 생략하면 HTTP 400 오류가 반환됩니다. 형제 functionCall 부분에 서명을 중복해서 넣거나 턴을 서로 끼워 넣어도 HTTP 400 오류가 반환됩니다."

Google의 사고 서명 가이드에서는 Gemini 3 모델의 메시지 형식을 다음과 같이 보여 줍니다. "<Function Call> 함수 호출이 <index of contents array> 콘텐츠 블록에 있으며 thought_signature가 누락되었습니다." Neon 가이드는 400 오류가 발생한다고 설명하지만 오류 문구는 명시하지 않습니다.

해결 방법: 모델의 턴을 받은 그대로 되돌려 보내세요. 병렬 호출에서는 첫 번째 호출에만 서명이 포함됩니다. 모든 호출은 하나의 모델 턴에, 모든 결과는 하나의 사용자 턴에 같은 순서로 넣으세요. Google의 예시에서는 모델이 "FC1 + 서명, FC2"를 반환했을 때 다음 요청에 "FC1 + 서명, FC2, FR1, FR2"가 포함되어야 합니다. "FC1 + 서명, FR1, FC2, FR2"처럼 서로 끼워 넣으면 400 오류가 반환됩니다.

범위를 벗어난 샘플링 값

표시되는 현상: temperature 또는 top_p가 유효 범위를 벗어나면 HTTP 400이 반환됩니다.

이유: Google은 범위 내 값을 무시하지만, 값 자체는 여전히 검증합니다. "범위를 벗어난 값은 400 유효성 검사 오류를 반환합니다."

해결 방법: 샘플링 매개변수를 모두 삭제하세요(다음 섹션 참고).

요청 형식

AIHubMix를 통해 보내는 올바른 요청입니다. 빠른 시작 설정을 사용합니다.

curl -s https://aihubmix.com/v1/chat/completions \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-neon",
    "reasoning_effort": "medium",
    "max_completion_tokens": 65536,
    "messages": [{"role": "user", "content": "Reply with OK."}]
  }'

Google이 Neon에서 400 오류를 반환한다고 문서화한 요청입니다.

curl -s https://aihubmix.com/v1/chat/completions \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-neon",
    "frequency_penalty": 0.5,
    "messages": [{"role": "user", "content": "Reply with OK."}]
  }'

이전 thinkingBudget 필드를 사용한 요청을 네이티브 Gemini 엔드포인트에서 동일하게 확인하는 예입니다. 경로는 AIHubMix가 다른 Gemini 모델에 대해 문서화한 패턴을 따릅니다. Neon 자체 목록에는 Chat Completions 예시만 나와 있습니다.

curl -s "https://aihubmix.com/gemini/v1beta/models/gemini-4-neon:generateContent" \
  -H "x-goog-api-key: $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Reply with OK."}]}],
    "generationConfig": {"thinkingConfig": {"thinkingBudget": 16384}}
  }'

이는 요청 형식의 예시이며 실제 응답을 기록한 것이 아닙니다. 이 글을 위해 어느 요청도 실행하지 않았습니다.

대비해야 할 기타 변경 사항

샘플링 매개변수는 효과가 없습니다

Google은 Neon의 샘플링 설정을 temperature 1.0, topP 0.95, topK 64로 고정하고 사용자 지정 값은 무시합니다. 출력을 반복 가능하게 만들려고 설정한 temperature: 0은 아무 효과가 없으며, 이를 알려 주는 오류도 없습니다. Google은 "thinking_level로 추론 깊이를 제어하고 response_schema로 출력 형식을 제어하라"고 권장합니다. 고정 형식이 필요하면 구조화된 출력을 사용하세요.

명시적 캐싱은 지원되지 않습니다

cachedContents, caches.create, cached_content는 지원되지 않습니다. Google은 이러한 항목을 계속 전송하는 요청이 실패하는지 무시되는지 밝히지 않았으므로, 직접 확인하려 하기보다 제거하세요. Neon의 캐싱은 암묵적으로만 적용됩니다. 공유 프롬프트 접두부가 4,096토큰 이상이면 자동으로 적용됩니다(3.8 Flash는 6,144토큰이 필요했습니다). 캐시된 입력 비용은 토큰 100만 개당 $3.00 대신 $0.15입니다. 캐시를 적용하려면 시스템 지침, 도구 정의, 참조 문서처럼 프롬프트의 정적인 부분을 앞에 배치하세요. 명시적 캐시 코드는 제거하세요. Neon에는 이에 해당하는 기능이 없습니다.

출력 한도가 낮으면 사고가 잘립니다

이전 모델에 맞춰 조정한 앱은 max_tokens를 8,192 이하로 설정하는 경우가 많습니다. Neon에서는 사고와 답변이 이 한도를 공유하므로 한도가 낮으면 답변을 시작하기도 전에 응답이 끝날 수 있습니다. Google은 다음과 같이 안내합니다. "8,192와 같은 낮은 한도를 하드코딩한 설정을 제거하거나 max_output_tokens를 65,536으로 높이세요. 토큰을 적게 쓰려면 사고 수준을 낮추세요."

짧은 타임아웃

Google의 안내: "어려운 프롬프트는 처리에 몇 분이 걸릴 수 있습니다. 백그라운드 실행을 사용하거나 HTTP 클라이언트 타임아웃을 최소 15분으로 설정하세요." AA의 평균을 기준으로 Neon High는 첫 답변 토큰이 나오기까지 40.6초, Xhigh는 56.5초가 걸립니다. 일부 요청은 평균보다 훨씬 오래 걸릴 수 있습니다.

미리 채워진 어시스턴트 턴

Neon의 대화 기록 규칙: "기록 페이로드는 모델 역할의 턴으로 끝날 수 없습니다." "미리 채워진 모델 턴은 지원되지 않습니다." 응답 형식을 유도하려고 어시스턴트 답변의 시작 부분을 미리 넣는 코드는 Anthropic API에서 흔히 쓰이는 방식이지만, 이제 중단해야 합니다. Google은 이 항목을 채팅 검증 항목으로 나열했으나 어떤 응답이 반환되는지는 밝히지 않았습니다. AIHubMix의 스키마에 따르면 마지막 모델 턴은 오류를 반환합니다. 코드에서 프리필에 의존한다면 직접 테스트하세요.

텍스트로 작성된 도구 호출

시스템 프롬프트에서 선언된 도구 없이 도구 호출을 일반 텍스트로 JSON 형식으로 작성하라고 모델에 요청하면 Neon은 "MALFORMED_FUNCTION_CALL을 반환할 수 있다"고 Google은 안내합니다. 도구를 네이티브 방식으로 선언하거나 구조화된 출력을 사용하세요.

AIHubMix의 출력 한도: 65,536토큰

Google 자체 API에서 Neon의 단일 응답은 스트리밍 여부와 관계없이 출력 토큰 65,536개로 제한됩니다. 더 긴 답변에는 long decode를 사용합니다. Interactions API 또는 GenerateContent v1beta1을 통해 입력을 제외하고 최대 1,048,576토큰까지 64K 단위로 생성을 이어갑니다. 다음 버전부터 Google SDK는 이어쓰기 토큰을 자동으로 처리할 수 있습니다. Interactions API의 경우 Python google-genai 2.34.0 및 JavaScript @google/genai 2.32.0입니다.

Google은 또한 "이전 SDK 버전과 OpenAI 호환 계층에서는 이어쓰기 토큰을 사용해 긴 완료 응답을 가져올 수 없다"고 안내합니다.

AIHubMix의 gemini-4-neon 매개변수 스키마는 Chat Completions, Responses, Anthropic Messages, 네이티브 Gemini 등 제공하는 모든 프로토콜에서 출력을 65,536토큰으로 제한합니다. 스키마에는 네이티브 Gemini 프로토콜에서 사용할 수 있는 Google의 continuationToken 필드도 나와 있으며, AIHubMix는 Google 네이티브 SDK와 Interactions API를 일반적으로 문서화하고 있습니다. 이 경로에서 Neon의 long decode 기능은 이 게시물을 위해 테스트하지 않았습니다. 제대로 작동하는지 확인하기 전에는 사고를 포함해 응답 하나당 최대 65,536토큰을 기준으로 설계하세요. 더 많은 토큰이 필요하면 요청마다 파일 하나 또는 섹션 하나를 처리하는 식으로 직접 작업을 나누세요.

놓치기 쉬운 요금 규칙

사고도 출력에 포함됩니다. Neon의 출력 토큰 100만 개당 $15 요금에는 사고 토큰이 포함됩니다. high에서는 어려운 요청의 출력 대부분이 사고일 수 있습니다.

그라운딩은 비용이 두 번 청구됩니다. Google은 "그라운딩 사용 시 내부 도구 시스템 지침 및 함수 선언"을 과금 대상 토큰으로 계산하며, 검색 쿼리마다 별도 요금을 부과합니다. Google 자체 할당량은 Gemini 3 이상 모델이 공유하며, 월 5,000회 검색까지 무료이고 이후에는 1,000회당 $14입니다. AIHubMix는 요청별로 웹 검색 요금을 부과합니다. Neon 모델 페이지에서 요금을 확인할 수 있습니다.

캐시를 사용하려면 프롬프트 순서가 맞아야 합니다. 캐시 95% 할인은 4,096토큰 이상의 변경되지 않는 접두부에만 적용됩니다. 시스템 프롬프트 맨 앞에 타임스탬프나 사용자 이름을 넣으면 요청마다 캐시가 무효화됩니다.

long decode는 입력 요금을 다시 부과합니다(Google API만 해당). "각 이어쓰기 구간에서 프롬프트와 이전에 디코딩된 토큰을 다시 프리필하므로" 입력 토큰 수가 구간마다 늘어납니다. "나중 구간이 실패하거나 취소되더라도 완료된 구간은 구간이 끝날 때 과금됩니다." AIHubMix의 65,536토큰 한도에서는 이런 상황이 발생하지 않습니다.

저렴한 티어 요금은 Google 기준입니다. Google은 Neon Batch와 Flex를 $1.50/$7.50, Priority를 $5.40/$27에 제공합니다. AIHubMix 스키마는 Neon의 service_tier로 flex 또는 priority를 허용하지만 해당 티어의 요금은 공개하지 않으며 Batch는 목록에 없습니다. 일반 요금인 $3/$15를 기준으로 예산을 책정하세요.

비용을 줄이는 방법:

  • 호출 유형별로 reasoning_effort를 설정하세요. 대화형 작업과 도구 턴에는 medium, 계획에는 high, 직접 평가했을 때 효과가 입증된 경우에만 xhigh를 사용하세요.
  • 정적인 프롬프트 접두부를 맨 앞에 두고 4,096토큰보다 길게 유지하세요.
  • 웹 검색은 필요한 턴에서만 사용하세요.
  • 눈에 보이는 답변뿐 아니라 사고도 포함하는 completion_tokens 사용량을 확인하세요.

실제 권한이 있는 에이전트

Neon의 도구 호출 규칙은 엄격하며, 에이전트가 파일을 쓰거나 명령을 실행할 수 있는 경우 특히 중요합니다.

  • 호출과 결과를 일치시키세요. "각 FunctionResponse는 앞선 FunctionCall의 id, name, 순서와 일치해야 합니다."
  • 서명까지 포함해 전체 기록을 유지하세요. Google의 안내: "이전 모든 턴에서 각 thought_signature를 원래 Part에 포함된 그대로 전달하세요…" 이전 서명을 제거하거나 skip_thought_signature_validator 같은 플레이스홀더를 사용하면 "추론 컨텍스트가 사라지고 MALFORMED_FUNCTION_CALL이 발생할 수 있습니다."
  • Chat Completions에서는 어시스턴트 메시지를 수정 없이 반환하세요. 도구 호출을 포함해 각 어시스턴트 메시지를 API가 반환한 그대로 유지하세요. 자체 로그로 기록을 재구성하지 마세요. Google은 Gemini 3 모델의 OpenAI 호환 Chat Completions에서 사고 서명을 지원한다고 문서화했습니다. Neon에서도 클라이언트가 서명을 유지하는지 확인하세요.
  • 응답 없이 조용히 끝나는 경우를 주의하세요. 함수 호출 형식이 잘못되면 사용할 수 있는 답변 없이 턴이 끝납니다. 오픈소스 프록시에서는 이 상황이 OpenAI 스타일 클라이언트에 일반 stop으로 전달되거나 서버 오류로 나타날 수 있다고 보고했습니다. 2026년 11월에 등록된 GitHub 이슈로 LiteLLM pull request 52745와 Divyam issue 60이 있습니다. 에이전트가 도구 호출 없이 빈 턴을 받으면 작업 완료로 처리하지 말고 실패로 판단해 재시도하세요.

Google은 Neon이 이러한 루프에서 이전 모델보다 더 안정적으로 작동한다고 설명합니다. Neon은 "불필요한 파일 읽기를 줄이고, 컨텍스트 압축을 안정적으로 처리하며, 허위 주장과 작업 지름길을 최소화하고" "에이전트의 과도한 개입과 불충분한 서비스 제공을 줄인다"고 합니다. 이는 Google 자체 평가에 기반한 Google의 주장입니다. 위험을 줄여줄 수는 있지만, 쓰기 작업에 대한 권한 제한과 검토를 대신하지는 않습니다.

코딩 도구: Claude Code와 Codex

AIHubMix의 매개변수 스키마에는 gemini-4-neon의 프로토콜이 네 가지로 나와 있으며, 그중 코딩 에이전트가 사용하는 두 가지는 Claude Code용 Anthropic Messages와 Codex용 Responses API입니다. 설정 방법은 다른 AIHubMix 모델과 같습니다. 자세한 내용은 Claude Code 설정 게시물과 Codex config.toml 게시물을 참고하세요. Neon에서 달라지는 부분은 다음과 같습니다.

설정 Claude Code Codex
프로토콜 Anthropic Messages Responses API
모델 ID gemini-4-neon gemini-4-neon
추론 수준 값 low~xhigh low~xhigh
컨텍스트 윈도우 1,048,576 1,048,576
요청당 출력 65,536 65,536

추론 수준 값과 한도는 AIHubMix의 매개변수 스키마를 기준으로 합니다. 두 프로토콜의 기본 추론 수준은 high입니다.

Claude Code. ANTHROPIC_MODEL을 gemini-4-neon으로 설정하세요. API_TIMEOUT_MS를 높이세요. 기본값은 10분이며, Google은 어려운 프롬프트에 최소 15분을 권장합니다. 같은 엔드포인트를 사용하는 맞춤 요청에는 어시스턴트 프리필을 추가하지 마세요. Neon은 이를 지원하지 않습니다.

Codex. wire_api = "responses"와 AIHubMix base_url은 그대로 두고, model = "gemini-4-neon"으로 설정한 다음 Neon의 수준 중에서 model_reasoning_effort를 선택하세요. 먼저 medium으로 시작하세요. Codex는 짧은 도구 턴을 많이 실행하며, 이때 high는 대부분 대기 시간만 늘립니다.

예상되는 알려진 문제:

  • high 및 xhigh에서 첫 토큰이 나오기까지 오래 걸립니다.
  • 사고에 시간이 오래 걸리면 응답이 65,536토큰 한도에서 끝납니다.
  • 위에서 설명한 것처럼 도구 호출 실패로 빈 턴이 발생할 수 있습니다.
  • 지식 컷오프는 2026년 3월이므로, 그 이후에 나온 라이브러리 버전은 컨텍스트에 포함해야 합니다.

10~15분 스모크 테스트

  1. 실패하는 단위 테스트가 하나 있고 테스트 명령 실행 시간이 1분 이내인 작은 저장소를 선택하세요.
  2. 도구를 gemini-4-neon에 연결하고 추론 수준을 medium으로 설정한 다음 클라이언트 타임아웃을 최소 15분으로 설정하세요.
  3. 테스트를 통과시키는 데 필요한 최소한의 변경을 요청하세요. 그런 다음 테스트를 실행하고 diff를 확인하세요.
  4. 통과 기준: diff가 최소한이고 테스트가 15분 이내에 통과합니다. 실패한 경우 400 오류, 빈 턴, 타임아웃, 잘못된 수정 중 어떤 문제가 발생했는지 기록하세요. 각각에 대한 해결책은 위에 설명되어 있습니다.
  5. high로 반복 테스트하세요. medium에서 잘못 처리한 문제를 high가 해결하는 경우가 아니라면 더 낮은 수준을 유지하세요.

체크리스트

  • 모델 ID를 gemini-4-neon으로 설정합니다.
  • 호출 유형별로 사고 수준을 명시적으로 설정합니다. Argon 또는 3.8 Flash의 기본값에 의존했다면 medium으로 설정합니다.
  • thinking_budget은 사용하지 않습니다. MINIMAL은 LOW로 대체되었습니다.
  • 요청마다 reasoning_effort와 네이티브 사고 수준 중 하나만 사용합니다.
  • frequency_penalty와 presence_penalty는 사용하지 않습니다. candidate_count와 n은 1로 설정하거나 생략합니다.
  • temperature, top_p, top_k는 사용하지 않습니다. 형식이 중요할 때는 구조화된 출력을 사용합니다.
  • 명시적 캐시 코드를 제거하고 정적인 프롬프트 접두부를 맨 앞에 배치해 4,096토큰을 초과하도록 설정합니다.
  • AIHubMix의 출력 한도를 65,536 이하로 설정하고 이전 모델에서 사용한 낮은 한도는 모두 제거합니다.
  • 클라이언트 타임아웃을 15분 이상으로 설정합니다.
  • 대화 기록이 어시스턴트 턴으로 끝나지 않도록 하고 프리필을 사용하지 않습니다.
  • 어시스턴트 턴과 도구 호출은 받은 그대로 반환합니다. 병렬 호출과 결과는 순서에 맞게 묶습니다.
  • 도구 호출 없이 발생한 빈 턴은 실패로 처리하고 재시도합니다.
  • 예산에 사고 토큰과 웹 검색 요청을 포함합니다.
  • 코딩 도구를 medium과 high에서 스모크 테스트합니다.

FAQ

Gemini 4 Neon으로 전환하려면 요청 형식을 변경해야 하나요?
다른 Gemini 4 모델에서 전환하는 경우에는 아닙니다. Google에 따르면 스키마는 동일하므로 모델 ID를 변경하고 사고 수준을 확인하면 됩니다. Gemini 3.1 Pro 또는 3.8 Flash에서 전환한다면 thinking_budget, MINIMAL, 페널티 매개변수와 명시적 캐싱을 제거하세요.

3.8 Flash에서 전환한 뒤 요청 비용이 더 많이 드는 이유는 무엇인가요?
Neon의 가격은 3.8 Flash의 4배이며, 3.8 Flash의 기본값은 medium이었던 반면 Neon은 high를 기본값으로 사용합니다. Artificial Analysis의 측정 결과에 따르면 Neon High는 작업당 Neon Medium보다 비용이 약 2배 높습니다. 수준을 명시적으로 설정하세요. Argon에서 전환하는 경우에는 높은 수준에서도 AA 기준 작업당 비용이 낮아집니다.

Neon에서 thinking_budget을 사용하면 400 오류가 반환되는 이유는 무엇인가요?
Neon은 low, medium, high, xhigh라는 지정된 사고 수준만 허용합니다. Google은 thinking_budget과 MINIMAL을 다른 값으로 변환하지 않고 HTTP 400 오류를 반환합니다.

temperature는 여전히 작동하나요?
아니요. Neon은 temperature, top_p, top_k를 무시하며, 허용 범위를 벗어난 값을 사용하면 400 오류가 반환됩니다. 대신 사고 수준과 구조화된 출력을 사용하세요.

AIHubMix를 통해 Neon에서 65,536개가 넘는 토큰을 반환할 수 있나요?
AIHubMix 문서에는 Neon의 요청당 출력 한도가 사고 토큰을 포함해 65,536토큰으로 명시되어 있습니다. 약 1M 토큰까지 가능한 Google의 긴 디코딩은 Google 자체 API에서 작동합니다. AIHubMix에서는 OpenAI 호환 엔드포인트로 사용할 수 없으며, 네이티브 경로는 여기서 테스트하지 않았습니다.

Claude Code나 Codex에서 Gemini 4 Neon을 사용할 수 있나요?
네. AIHubMix에는 Claude Code가 사용하는 Anthropic Messages 프로토콜과 Codex가 사용하는 Responses API가 등록되어 있습니다. 모델을 gemini-4-neon으로 설정하고 시간 제한을 늘린 다음, 먼저 짧은 스모크 테스트를 실행하세요.

Gemini 3.1 Pro는 지원 중단되나요?
Google은 Gemini 3.1 Pro Preview, Gemini 3.8 Flash 또는 어떤 Gemini 4 모델에 대해서도 지원 중단 날짜를 발표하지 않았습니다. Google은 3.1 Pro의 업그레이드 모델로 Neon을 권장합니다.

계속 읽기: Gemini 4 Neon 시리즈

출처

여러 AI 제공업체를 하나의 게이트웨이로. 프로덕션 환경을 위해 설계했습니다.

AIHubMix 웹사이트 방문