Gemini 모델 전달
Gemini 시리즈의 경우 두 가지 호출 방법, 즉 네이티브 API 호출과 OpenAI 호환 호출을 제공합니다.시작하기 전에
pip install google-genai 또는 pip install -U google-genai를 실행하여 네이티브 종속성을 설치하거나 업데이트해야 합니다.
1️⃣ 네이티브 전달의 경우 주로 내부 클라이언트 설정에 AiHubMix API 키와 요청 URL을 주입해야 합니다.⚡️ 참고: URL 형식은 기존의
base_url 사용법과 다릅니다. 아래 예를 참조하십시오:
v1 엔드포인트를 유지합니다.
- 네이티브 호출:
include_thoughts=True전달 - OpenAI 호환 방법:
reasoning_effort전달
Gemini 2.5 추론 모델 정보
- 전체 2.5 시리즈는 추론 모델로 구성됩니다.
- 2.5 Flash는 Claude Sonnet 3.7과 유사한 하이브리드 모델입니다. 최적의 제어를 위해
thinking_budget매개변수를 조정하여 추론 동작을 미세 조정할 수 있습니다. - 2.5 Pro는 순수 추론 모델입니다. 사고를 비활성화할 수 없으며
thinking_budget을 명시적으로 설정해서는 안 됩니다.
Gemini 2.5 Flash: 빠른 작업 지원
OpenAI 호환 호출 예제:미디어 이해
Aihubmix는 현재inline_data를 통해 최대 20MB의 멀티미디어 파일(이미지, 오디오 및 비디오) 업로드를 지원합니다.
20MB를 초과하는 파일의 경우 파일 API가 필요합니다. 이 기능은 아직 사용할 수 없습니다. 진행 상황 추적 및 upload_url 검색은 개발 중입니다.
코드 실행
코드 실행 기능을 사용하면 모델이 Python 코드를 생성 및 실행하고 최종 출력에 도달할 때까지 결과로부터 반복적으로 학습할 수 있습니다. 이 코드 실행 기능을 사용하여 코드 기반 추론의 이점을 활용하고 텍스트 출력을 생성하는 애플리케이션을 빌드할 수 있습니다. 예를 들어 방정식을 풀거나 텍스트를 처리하는 애플리케이션에서 코드 실행을 사용할 수 있습니다.Python
Interactions API
Interactions는 Gemini의 차세대 추론 인터페이스로, 구조화된Interaction 객체를 반환하며 텍스트 생성, 네이티브 이미지 생성(Nano Banana) 및 다단계 추론을 지원합니다. 현재 동기 모드(interactions.create())가 지원되며, 비동기 모드(Background Interactions)는 곧 제공될 예정입니다.
텍스트 생성
interactions.create()를 호출하여 추론을 시작하면, 반환된 Interaction 객체의 output_text 편의 속성을 사용할 수 있습니다.
네이티브 이미지 생성
response_format을 통해 출력 모달리티를 이미지로 설정하면, 반환된 Interaction 객체의 output_image 편의 속성을 사용할 수 있습니다.
스트리밍 출력
stream: true를 전달하여 SSE 스트리밍을 활성화합니다. 증분 텍스트는 event.delta.text를 통해 가져옵니다.
JavaScript
전체 SDK 가이드는 Gemini 네이티브 SDK 통합을 참조하세요.
컨텍스트 캐싱
Gemini의 네이티브 API는 기본적으로 암시적 컨텍스트 캐싱을 활성화하므로 설정이 필요하지 않습니다. 모든generate_content 요청에 대해 시스템은 자동으로 입력 콘텐츠를 캐시합니다. 후속 요청이 정확히 동일한 콘텐츠, 모델 및 매개변수를 사용하는 경우 시스템은 즉시 이전 결과를 반환하여 응답 시간을 크게 단축하고 잠재적으로 입력 토큰 비용을 절감합니다.
- 캐싱은 자동이며 수동 구성이 필요하지 않습니다.
- 캐시는 콘텐츠, 모델 및 모든 매개변수가 정확히 동일할 때만 적중됩니다. 어떤 차이라도 캐시 미스를 초래합니다.
- 캐시 TTL(Time-To-Live)은 개발자가 설정하거나 설정하지 않은 상태로 둘 수 있습니다(기본값 1시간). Google에서 적용하는 최소 또는 최대 TTL은 없습니다. 비용은 캐시된 토큰 수와 캐시 기간에 따라 다릅니다.
- Google은 TTL에 제한을 두지 않지만 전달 플랫폼으로서 제한된 TTL 범위만 지원합니다. 플랫폼의 한계를 넘어서는 요구 사항에 대해서는 문의해 주십시오.
참고
- 비용 절감 보장 없음: 캐시 토큰은 표준 입력 가격의 25%로 청구되므로 이론적으로 캐싱은 입력 토큰 비용을 최대 75%까지 절약할 수 있습니다. 그러나 Google의 공식 문서는 비용 절감을 보장하지 않습니다. 실제 효과는 캐시 적중률, 토큰 유형 및 저장 기간에 따라 다릅니다.
- 캐시 적중 조건: 캐시 효율성을 극대화하려면 입력 시작 부분에 반복 가능한 컨텍스트를 배치하고 끝 부분에 동적 콘텐츠(예: 사용자 입력)를 배치하십시오.
-
캐시 적중 감지 방법: 응답이 캐시에서 온 경우
response.usage_metadata에cache_tokens_details필드와cached_content_token_count가 포함됩니다. 이를 사용하여 캐시 사용량을 확인할 수 있습니다.
캐시 적중 시 예제 필드:
캐시가 적중되면핵심 결론: 암시적 캐싱은 자동이며 명확한 캐시 적중 피드백을 제공합니다. 개발자는 usage_metadata에서 캐시 상태를 확인할 수 있습니다. 비용 절감은 보장되지 않으며 실제 이점은 요청 구조와 캐시 적중률에 따라 다릅니다.response.usage_metadata에 다음이 포함됩니다:
함수 호출
openai 호환 방식을 사용하여 Gemini의 함수 호출을 호출하려면 요청 본문에tool_choice="auto"를 전달해야 합니다. 그렇지 않으면 오류가 발생합니다.
토큰 사용량 추적 간소화
-
Gemini는
usage_metadata를 사용하여 토큰 사용량을 추적합니다. 각 필드의 의미는 다음과 같습니다:prompt_token_count: 입력 토큰 수candidates_token_count: 출력 토큰 수thoughts_token_count: 추론 중에 사용된 토큰 (출력으로도 계산됨)total_token_count: 총 사용된 토큰 (입력 + 출력)
-
OpenAI 호환 형식을 사용하는 API의 경우 토큰 사용량은 다음 필드와 함께
.usage아래에서 추적됩니다:usage.completion_tokens: 입력 토큰 수usage.prompt_tokens: 출력 토큰 수 (추론 포함)usage.total_tokens: 총 토큰 사용량
코드에서 사용하는 방법은 다음과 같습니다:
마지막 업데이트: 2026-07-07