Gemini 3.8 Flash에서 Hydrogen으로 전환하며 문맥과 도구 기록 유지하기

Gemini 3.8 Flash에서 Hydrogen으로 이전할 때 추론 설정, 캐시 내용 복원, 도구 기록 보존, 회귀 검사와 롤백을 점검하는 방법입니다.

연결을 유지하며 경로를 바꾸는 모습을 표현한 주황색 전환 부품이 있는 평면 철도 분기기.

Gemini 3.8 Flash에서 Gemini 4 Hydrogen으로 이전하려면 API 규약과 애플리케이션 문맥을 보존하고, 모델 ID를 바꾸고, 추론 수준을 명시한 뒤 작업 단위 검증을 다시 수행하고 나서 운영 트래픽을 전환해야 합니다. 모델 이름만 바꿔서는 지원되지 않는 캐시 참조 뒤의 문서를 복원할 수 없고, 서버에 저장된 대화를 다른 모델에서 이어 갈 수 있다는 것도 입증되지 않습니다.

이 글은 이미 작동 중인 애플리케이션을 다룹니다. 첫 키 발급과 요청은 Hydrogen API 설정 가이드를 참고하세요. 여기서는 이전 전후의 작은 요청을 만들고, 기록 보존을 확인하며, 실제 이전의 합격 조건과 롤백을 정합니다. 문맥을 유지한다는 것은 필요한 검사와 복원을 수행한다는 뜻이며 두 모델이 같은 답을 낸다는 보장은 아닙니다.

문서 확인일은 2026년 11월 14일입니다. 링크한 Google 문서는 영문입니다. 다운로드 키트는 오프라인 요청 감사 테스트 21개와 모의 HTTP 전송을 이용한 실제 google-genai==3.3.0 직렬화 검사를 통과했습니다. 모델 호출, 실제 모델 간 대화 연속성 검증, 품질 측정, 청구서 비교는 하지 않았습니다. 아래 회귀 기준은 앱에서 실행할 검증안이며 측정된 벤치마크가 아닙니다.

실제로 바뀌는 설정 구분하기

Hydrogen 이전 안내와 Gemini 3.8 출시 문서를 함께 읽어야 합니다. 새 체크리스트에 반복된 제약을 새로 생긴 호환성 문제로 오해하지 않기 위해서입니다.

항목기존 Gemini 3.8 Flash 동작Hydrogen 이전 시 결정
Google 모델 IDgemini-3.8-flashgemini-4-hydrogen으로 변경하고 대상 계정 접근 권한을 별도로 확인
기본 추론 수준medium기본값이 high로 변경되므로 비교에서는 명시적으로 지정
추론 선택지low, medium, highxhigh 추가. minimal은 이미 3.8에서도 미지원
문맥 예산입력과 출력 한도가 별도입력·추론·출력이 1,048,576토큰 창을 공유
명시적 문맥 캐시기존 요청의 캐시 리소스 의존 여부 확인Hydrogen은 명시적 캐시 미지원. 참조 삭제 전에 내용 복원
샘플링 설정3.8 이전 안내에서 이미 사용 중단 예정으로 설명범위 안의 사용자 지정 값은 무시하지만 범위 밖 값은 400 검증 오류 가능
긴 출력앱이 한 번의 응답을 전제로 할 수 있음동기 응답 한 번의 65,536토큰 한도를 넘으면 백그라운드 실행이나 클라이언트 이어받기 설계 필요

Hydrogen의 medium은 설정 변수 하나를 통제할 뿐입니다. 내부 추론량, 지연, 답변 품질이 같음을 뜻하지 않습니다. 최대 출력이 커져도 입력이 창을 거의 채우면 그만큼의 출력 공간이 남는 것은 아닙니다. 추론과 답변을 포함한 공유 예산을 계산하고 앱 자체의 출력·지출 상한을 유지하세요.

문맥, 추론, 캐시, 샘플링 설명이 있는 Google 영문 Gemini 3.8 Flash 이전 체크리스트.

Google 영문 이전 문서의 실제 화면입니다. 출처의 안내를 기록한 것이며 API 이전 성공이나 Ofox 성능 측정 결과가 아닙니다.

출력 방식은 Google의 긴 출력 문서를 확인하세요. 한 단계의 제한은 제어 로직이 다룰 경계이며, 더 큰 출력 한도 지정이 모두 잘못되었다는 근거는 아닙니다.

원래 설정을 고정하고 같은 프로토콜 유지하기

모델을 바꾸기 전에 원래 설정의 버전과 재현 가능한 작은 작업 묶음을 저장하세요. 모델, 엔드포인트, SDK 버전, 시스템 지시, 입력 조립 방식, 도구, 응답 스키마, 출력 한도, 저장 설정, 재시도 정책, 공급자 라우팅 필드를 기록합니다. 원본 문서와 보관이 허용된 사용자 입력은 평소의 보호된 저장소에 두세요. 공개 디버그 로그는 이전 기록 보관소가 아닙니다.

세 가지 요청 형태를 구분해야 합니다.

기존 호출 방식유지할 규약그대로 섞으면 안 되는 것
Google Interactionsinput, generation_config, 상호작용 단계와 IDGenerateContent의 contents 요청 구조
Google GenerateContentcontents, 콘텐츠 part, 도구 선언, SDK 설정이 프로토콜의 기록 대신 쓰는 Interactions의 previous_interaction_id
Ofox OpenAI 호환 호출문서화된 messages, 모델 라우팅, 응답 규약Google 네이티브 Interactions 요청 원문

다음 완성 예제는 Google Interactions를 사용합니다. 키트의 별도 직렬화 테스트는 모델 part와 도구 응답을 검사하기 위해 GenerateContent를 사용합니다. 서로 독립된 검사이며 하나를 실행한다고 다른 프로토콜이 변환되지는 않습니다.

Ofox 앱은 현재 쓰는 Gemini Generate Content 또는 OpenAI 호환 Chat Completions 경로부터 확인하고, 해당 Ofox 키 및 인증 안내를 따르세요. Google 키와 Ofox 키는 바꿔 쓸 수 없습니다. Ofox의 Gemini 네이티브 경로 문서가 Google Interactions의 모든 기능이나 모델별 캐시 지원을 입증하는 것은 아닙니다.

완성형 도구 클라이언트 이전도 앱 이전과 구분하세요. Cline이나 OpenCode가 요청을 만든다면 Hydrogen 코딩 도구 설정 가이드에 따라 설정하고 실제 전송 내용을 검사합니다. 이 글의 JSON을 그대로 보낼 것이라고 가정하면 안 됩니다.

작고 명확한 이전 전후 요청 만들기

다른 모델에게 채점시키지 않아도 정답을 알 수 있는 작업을 선택합니다. 원본 예제에는 두 레코드 상태가 있고 차단된 것은 B뿐입니다. 다음 완성 객체를 source-request.json으로 저장하세요.

{
  "model": "gemini-3.8-flash",
  "input": "Records: A=ready; B=blocked. Return the blocked record IDs only.",
  "generation_config": {
    "max_output_tokens": 8192
  },
  "response_format": {
    "type": "text",
    "mime_type": "application/json",
    "schema": {
      "type": "object",
      "properties": {
        "blocked_ids": {"type": "array", "items": {"type": "string"}}
      },
      "required": ["blocked_ids"],
      "additionalProperties": false
    }
  }
}

입력, 스키마, 출력 한도는 보존하면서 모델을 바꾸고 추론 수준을 명시해 hydrogen-request.json을 만듭니다.

import json
from pathlib import Path

source = json.loads(Path("source-request.json").read_text())
target = json.loads(json.dumps(source))
target["model"] = "gemini-4-hydrogen"
target["generation_config"]["thinking_level"] = "medium"
Path("hydrogen-request.json").write_text(json.dumps(target, indent=2))

키트에는 완성된 JSON 두 개가 모두 들어 있습니다. 8,192토큰은 이 통제된 예제의 설정이며 운영 환경의 보편적인 권장값이 아닙니다. 최종 JSON이 짧아도 추론이 예산을 소진하면 실패할 수 있습니다. 완료와 잘림 여부를 확인하고 실패를 숨기려고 운영 한도를 자동으로 최대로 높이지 마세요.

응답 형식은 Google의 현재 구조화 출력 규약을 따릅니다. 텍스트 출력에 application/json MIME 유형과 스키마를 지정합니다. 스키마는 형태를 제한할 뿐 올바른 레코드를 골랐다는 증거는 아닙니다.

평소의 비밀 관리 방식으로 Google 프로젝트 키를 GEMINI_API_KEY에 설정한 후 필요하다면 아래 실제 요청을 실행할 수 있습니다. Google에 접속하므로 프로젝트 할당량이나 유료 사용량을 소모할 수 있습니다. 이 글에서는 실행하지 않았습니다.

curl --fail-with-body --max-time 180 \
  'https://generativelanguage.googleapis.com/v1beta/interactions' \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @hydrogen-request.json \
  --output hydrogen-response.json

원본 기준값은 같은 명령에서 source-request.json을 사용하고 출력 파일 이름을 달리해 얻습니다. 계정, 입력, 스키마, 실행 조건을 맞추세요. 먼저 상호작용 상태와 오류 또는 미완료 결과를 확인합니다. 완료되었고 필요한 출력이 있는 응답만 앱 파서로 전달해야 합니다. JSON 텍스트를 파싱한 뒤 이 예제에서는 정확히 {"blocked_ids":["B"]}인지 검사하고 다른 키나 ID를 허용하지 않습니다. HTTP 200, 유효한 JSON, 올바른 작업 답변은 별개의 검사입니다.

시간 초과 시 이미 받은 요청·상호작용 ID를 보관하고 서비스 상태를 확인한 다음 재시도를 결정하세요. 클라이언트 시간 초과만으로 서버가 작업을 멈췄다고 판단할 수 없습니다.

오프라인 키트 실행과 검증 범위 이해하기

Hydrogen 이전 키트를 내려받아 압축을 풀고 hydrogen-migration-kit 디렉터리로 이동하세요. 전체 도구에는 Python 3.11 이상을 사용합니다. 코드 주석과 README는 영문입니다. 요청 감사기 자체는 표준 라이브러리만 필요합니다.

python -m unittest test_audit.py -v
python migration_audit.py source-request.json
python migration_audit.py hydrogen-request.json

예상 단위 테스트 결과는 21개 통과입니다. 감사기는 요청 파일을 다시 쓰지 않고, 변경 없는 사본과 차단 항목·검토 항목을 반환합니다. 종료 코드 2는 차단 항목 발견, 0은 제한된 감사 범위에서 차단 항목이 없다는 뜻이지 배포 승인이라는 뜻이 아닙니다. 대상 예제도 앱 평가와 의도적으로 낮춘 출력 예산 검토가 필요합니다.

대상은 완전한 Interactions 최초 요청입니다. 다른 프로토콜 구조, 누락 입력, 명시적 캐시 의존, 잘못된 추론 수준, 잘못된 출력 한도, 저장·백그라운드 설정 충돌을 검사하며 기본값에 숨은 변경도 표시합니다. 캐시 문서를 복원하거나 서버 기록을 읽거나 계정 권한을 확인하거나 API의 모든 필드를 검증하지는 못합니다.

출력에는 요청 전체 사본이 포함됩니다. 먼저 제공된 비민감 예제를 사용하고 기밀 프롬프트를 공유 터미널 로그에 남기지 마세요. API 키는 요청 JSON에 넣지 않습니다.

별도 SDK 직렬화 검사에는 격리 환경을 만듭니다.

python -m venv .venv
source .venv/bin/activate
python -m pip install 'google-genai==3.3.0' httpx
python sdk_wire_check.py

Windows PowerShell에서는 .venv\Scripts\Activate.ps1로 활성화합니다. 패키지 설치는 의존성을 다운로드하지만 검사 자체는 명시적인 가상 키와 httpx.MockTransport를 씁니다. 환경 변수 자격 증명을 읽거나 모델 요청을 보내지 않습니다.

스크립트는 설치된 SDK로 두 GenerateContent 요청을 직렬화합니다. 같은 3개 대화 턴, 도구 선언, 두 도구 응답이 유지되는지 단언합니다. 모델 턴에는 두 병렬 함수 호출이 있고 합성 서명은 원래 첫 part에만 남으며 두 번째로 복사되지 않습니다. 대상 요청은 Hydrogen과 명시적 MEDIUM을 지정합니다. 캡처된 본문은 스크립트 옆 sdk-wire-requests.json에서 확인할 수 있습니다.

이는 로컬 직렬화에 대한 증거입니다. 합성 응답과 서명으로 서버 수락, 모델 간 대화 이어받기, 도구 실행기 동작을 증명할 수 없습니다. 실제 평가 전에 기록 유실을 발견하는 데 유용하지만 실제 평가를 대신하지는 못합니다.

캐시 내용을 복원하고 대화 상태 보존하기

명시적 캐시 ID는 참조이지 문서 자체가 아닙니다. cached_content나 cachedContent를 지우면 요청은 단순해 보이지만 앱이 의존하던 자료가 사라질 수 있습니다. Google의 캐시 문서는 암시적 재사용과 명시적 리소스 관리를 구분합니다. 암시적 캐시가 누락된 입력을 복원해 주지는 않습니다.

캐시에 의존하는 작업마다 다음을 수행하세요.

  1. 캐시를 만들 때 호출자가 사용한 원본 시스템 지시, 문서, 미디어 참조, 도구 선언을 찾습니다. 찾지 못하면 그 사례의 이전을 중단하고 빈 대체물을 동등하게 취급하지 않습니다.
  2. 버전과 순서를 기록하고 외부 파일 참조가 대상 계정과 요청 경로에서도 접근 가능한지 확인합니다.
  3. 현재 프로토콜에 맞는 필드로 완전한 요청을 재구성합니다. 시스템과 사용자 구분, 도구를 유지하고 캐시 ID를 지우려고 전부 사용자 메시지 하나로 합치지 않습니다.
  4. 복원한 문맥을 Hydrogen 공유 예산에 맞춰 다시 계산하고 추론과 답변 공간을 남깁니다. 필요하면 작업을 분할합니다.
  5. 복원 자료에 있는 알려진 사실이 있어야 답할 수 있는 질문을 내고 정확한 답을 확인한 뒤 기존 캐시 의존 경로를 제거합니다.

대화 상태는 별도 판단이 필요합니다. Interactions는 previous_interaction_id로 저장된 이전 상호작용을 참조합니다. 현재 요청에 store=false를 주는 것만으로 과거 저장 상태 읽기가 막히지는 않지만, 현재 결과는 저장되지 않아 다음 이어받기에 쓸 수 없습니다. 백그라운드 실행과 store=false는 함께 쓸 수 없습니다. 이전 ID가 있다는 이유만으로 모델 간 연속성을 가정하지 말고, 해당 계정·모델 조합을 시험하거나 문맥을 명시적으로 재구성한 새 대화로 소규모 시험을 시작하세요.

무상태 이어받기에서는 API가 요구하는 추론 관련 단계와 내장 도구 서명을 포함해 전체 순서를 보존합니다. GenerateContent는 모델 콘텐츠 전체와 part 순서를 유지하고 대응하는 도구 응답을 뒤에 붙입니다. 화면에 보이는 텍스트 대화만으로는 충분한 기록 저장소가 되지 않습니다.

추론 서명 누락 오류는 Gemini 도구 호출 서명 문제 해결과 공식 서명 규칙을 참고하세요. 서명을 원래 part에 두고 같은 서명을 병렬 함수 호출에 복사하거나 대체 서명을 만들지 않습니다. 키트의 합성 서명은 오프라인 직렬화 오류 확인용일 뿐입니다.

도구·출력·공유 예산 함께 점검하기

텍스트를 모두 유지해도 앱 동작이 보존되지 않을 수 있습니다. 함수 이름, 인수 스키마, 권한, 호출과 결과의 연결, 결과 순서를 일치시키세요. Google의 함수 호출 가이드는 프로토콜을 설명하지만 어떤 작업을 허용하고 실제로 성공했는지는 실행기가 판단해야 합니다.

쓰기 도구 전에 읽기 전용 예제를 사용합니다. 예를 들어 lookup_record가 A는 ready, B는 blocked로 반환하게 하고 최종 구조화 답변이 B를 선택하도록 합니다. 비밀을 제외한 호출 ID, 인수, 결과를 기록합니다. 두 호출이 발생하면 각각의 결과를 반환하고 연결 관계를 잃는 자유 형식 요약 하나로 합치지 마세요.

모델 출력은 앱이 검증할 후보 데이터입니다. 레코드 예제는 스키마를 검사한 다음 실제 레코드와 답을 대조합니다. 쓰기는 대상의 실제 상태를 확인합니다. 모델의 “저장 성공” 문구가 쓰기 증거는 아닙니다. 함수 대신 UI를 조작한다면 Computer Use 설정 가이드가 관찰·승인·실행·검증 루프를 설명합니다.

예산 실패는 작업 실패처럼 보일 수 있습니다. 입력·출력 사용량, 가능한 경우 추론 사용량, 완료 상태, 잘림 지표를 수집하세요. 누락된 사용량은 0이 아니라 알 수 없음입니다. 공급자 출력 합계에 추론이 포함되면 다시 더하지 않습니다. 비용 계산 전에 문서의 단위를 확인하세요.

긴 답변에는 이어받기 제어기나 백그라운드 경로와 중단 조건을 명시합니다. 재개 ID를 보존하고 완료된 부수 효과를 반복하지 않으며 여러 단계 전체의 작업량을 제한합니다. 제어기를 바꾸지 않고 단일 요청 한도만 높여서는 신뢰할 수 있는 장기 작업을 만들 수 없습니다.

독립된 합격 기준을 가진 회귀 집합 만들기

비밀 정보를 제거하고 사용 권한을 갖춘 실제 앱 사례부터 시작하세요. 성공 사례와 알려진 실패 경계를 모두 포함합니다. 다음 표는 재현 가능한 소규모 설계이며 측정된 모델 결과를 담고 있지 않습니다.

사례구체적 예제합격 조건
기본 추출A=ready; B=blocked완료 응답을 파싱하면 차단 ID는 B뿐
캐시 복원문서에 release_owner=team_amber가 있으나 질문에는 없음전체 문서를 복원한 뒤 team_amber 반환
기록 연속성첫 턴에 A를 team_amber에 할당하고 다음 턴에 담당자 질문선택한 상태 관리 방식으로 정확한 담당자 반환
병렬 도구A와 B에 대한 두 lookup_record대응 관계 유지, 중복 실행 없음, 최종 답이 예제와 일치
의도적 잘림큰 예제에 일부러 부족한 출력 한도 적용미완료를 감지하고 합격 처리하지 않음
무효 설정범위 밖 샘플링 값 또는 저장/백그라운드 충돌무조건 반복하지 않고 올바른 오류 처리 경로로 전달
쓰기 작업 롤백작업 ID는 있으나 클라이언트 응답 불확실재실행 전에 운영자나 실행기가 대상 상태 확인

매 실행마다 설정 버전, 모델 ID, 프롬프트·예제 hash, SDK 버전, 계정·라우팅 환경, 시작·종료 시간, 완료 상태, 검증 결과, 얻을 수 있는 사용량을 저장합니다. 민감한 원본 응답은 기존 보관 정책에 따라 저장합니다. 같은 조건을 비교하고 프롬프트·스키마·실행기를 함께 바꿨다면 개선을 모델만의 효과로 설명하지 마세요.

돈이나 할당량을 쓰는 평가 전에 합격 기준을 정합니다. 스키마 유효성과 부수 효과의 안전성에는 엄격한 기준을 적용할 수 있습니다. 작업 정확도, 지연, 비용은 앱에 맞는 임계값과 의미 있는 표본이 필요합니다. 이 글은 보편적 백분율을 제시하거나 7개 예제로 운영 신뢰성을 증명했다고 주장하지 않습니다. 특히 그럴듯하지만 정해진 규칙에 따른 검사를 통과하지 못한 답을 하나씩 조사하세요.

단계적으로 전환하고 사용 가능한 롤백 남기기

먼저 제한된 수의 새 읽기 전용 작업을 Hydrogen 설정으로 보냅니다. 원본과 대상 설정을 각각 선택 가능하게 두고 같은 승인된 예제 버전을 사용하세요. 확대 전에 실패와 미완료 응답을 검토합니다. 쓰기 작업은 실행기, 중복 제거, 대상 상태 검사를 통과한 뒤 추가합니다.

형식 오류는 요청을 고치고 같은 입력을 반복하지 않습니다. 모델 접근이 안 되면 정확한 계정·경로·ID를 확인합니다. 일시적 실패는 백오프를 넣은 제한된 재시도를 사용하고 식별자를 보관합니다. Ofox 호출자는 오류와 재시도 문서를 따르세요. Gemini 4 API 오류 진단 글도 권한·형식·속도 제한 분리에 도움이 되지만 모델 예시는 Argon이므로 Hydrogen ID로 그대로 복사하면 안 됩니다.

롤백은 전환 가능한 새 작업에 원래 설정을 복원하는 것이지 진행 중인 모든 상호작용을 무작정 재실행하는 것이 아닙니다. 새 부수 효과를 멈추고 불확실한 작업을 찾고 대상 상태를 검사한 뒤 재개·보상 처리·재시작을 결정하세요. 이전 경로는 권한과 모델 가용성이 유효할 때만 사용할 수 있습니다. 저장한 설정으로 공급자의 모델 종료나 접근 권한 상실을 우회할 수는 없습니다.

실제 경로에서 문맥 복원, 도구 상태 보존, 정확한 출력 검증, 제한된 실행, 롤백 연습을 증명할 수 있을 때 이전 준비가 된 것입니다. 버전별 증거를 보존해 나중의 프롬프트·SDK·공급자 변경과 이번 모델 이전을 구분하세요.