추론 깊이를 토큰이 아닌 레벨로 제어하기
Google의 최신 모델인 Gemini 3 Pro가 출시되면서 모델의 사고과정을 제어하는 방식이 근본적으로 변화했습니다.
기존 Gemini 2.5 계열까지는 추론에 사용할 토큰의 양을 숫자로 지정했으나, 이제는 추론의 깊이를 레벨로 선택할 수 있습니다.
이 포스팅에서는 Spring AI 1.1.x 및 2.0.0.M1 버전부터 정식 지원되는 이 기능을 어떻게 실무에 적용하는지 상세히 알아봅니다.
1. 추론
- Gemini 3 Pro부터 추론 제어 방식이
thinkingBudget에서thinkingLevel로 변경되었습니다. - 모델 전용성:
thinkingLevel은 Gemini 3 Pro 전용 기능입니다.
Gemini 2.5 계열에서는 사용할 수 없으며 반드시 기존의thinkingBudget을 사용해야 합니다. - 상호 배타적 옵션:
thinkingLevel과thinkingBudget은 동시에 설정할 수 없습니다. 병행 시 API 400 에러가 발생합니다. - 엔드포인트: Gemini 3 Pro Preview 모델 사용 시 반드시
global엔드포인트를 지정해야 합니다. - Spring AI 지원: Spring AI 1.1.x / 2.0.0.M1 버전부터 해당 옵션을 정식 라이브러리 레벨에서 지원합니다.
2. 왜 추론 레벨 제어가 중요한가?
기존 Gemini 2.5까지는 개발자가 모델에게 다음과 같이 명령해야 했습니다.
"이 문제를 해결하기 위해 최대 8192개의 토큰을 생각하는 데 사용해라."
하지만 이 방식에는 몇 가지 현실적인 문제가 있었습니다.
- 직관성 부족: 2000토큰의 생각과 5000토큰의 생각이 결과물의 품질에 어떤 차이를 주는지 예측하기 어렵습니다.
- 비용과 품질의 모호함: 서비스 운영자 입장에서 속도와 품질 사이의 트레이드오프를 설정하기가 매우 까다롭습니다.
- 모델 아키텍처 의존성: 모델 내부의 추론 구조가 개선되거나 변경될 경우, 동일한 토큰 수라도 추론의 밀도가 달라져 기준이 흔들리게 됩니다.
Google은 이를 해결하기 위해 Gemini 3 Pro부터 추론을 양이 아닌 질의 관점으로 접근하도록 설계를 변경했습니다.
3. ThinkingConfig 구조 상세 분석
Gemini의 추론 관련 옵션은 크게 3가지 파라미터로 구성됩니다.
| 옵션명 | 의미 | 데이터 타입 |
|---|---|---|
| thinkingLevel | 모델의 추론 깊이 설정 | Enum (LOW, HIGH, UNSPECIFIED) |
| thinkingBudget | 추론에 소비할 최대 토큰 수 | Integer |
| includeThoughts | 응답에 모델의 사고 과정 포함 여부 | Boolean |
핵심 규칙
thinkingLevel과thinkingBudget은 절대로 동시에 사용할 수 없습니다.includeThoughts는thinkingLevel혹은thinkingBudget중 활성화된 옵션과 함께 조합하여 사용할 수 있습니다.
4. ThinkingLevel 개념 정리
thinkingLevel은 모델이 문제 해결을 위해 얼마나 논리적인 단계를 깊게 밟을지를 결정합니다.
- LOW: 복잡한 추론 단계를 줄이고 빠르게 결론에 도달합니다. 단순 FAQ, 간단한 질의응답, 속도가 생명인 실시간 채팅 서비스에 적합합니다.
Gemini 3 Pro에서는 추론 기능을 아예 끌 수 없으므로, LOW가 실질적인 최소 설정값입니다. - HIGH: 가능한 모든 논리적 경로를 탐색하여 정교한 답변을 생성합니다. 데이터 분석, 소프트웨어 설계, 복잡한 비즈니스 로직 판별, 창의적 글쓰기에 적합합니다.
- THINKING_LEVEL_UNSPECIFIED: 모델의 기본값에 판단을 맡깁니다.
5. Spring AI에서의 구현 내용
Spring AI 프로젝트 통해 다음 기능들이 추가되었습니다.
- GoogleGenAiThinkingLevel: Java Enum 클래스가 추가되어 LOW, HIGH 값을 타입 안전하게 사용할 수 있습니다.
- GoogleGenAiChatOptions: 해당 클래스 내부에
thinkingLevel필드가 추가되었습니다. - 자동화된 요청 생성: 개발자가 옵션을 설정하면 Spring AI가 내부적으로 Gemini API의
ThinkingConfig구조에 맞춰 JSON 요청을 생성합니다. - 검증 로직:
thinkingLevel과thinkingBudget이 동시에 들어오지 않도록 방어 로직이 포함되었습니다.
6. 모델별 지원 여부 매트릭스
이 표는 설정 시 발생할 수 있는 시행착오를 줄여줍니다.
| 모델명 | thinkingLevel 지원 | thinkingBudget 지원 | 비고 |
|---|---|---|---|
| Gemini 3 Pro (Preview) | YES | NO | global 엔드포인트 필수, Thinking 비활성화 불가 |
| Gemini 2.5 Pro | NO | YES | Budget으로만 깊이 제어 가능 |
| Gemini 2.5 Flash | NO | YES | Budget 설정 필수 |
| Gemini 2.5 Flash-Lite | NO | YES | 기본값은 Thinking OFF 상태 |
| Gemini 2.0 Flash | NO | NO | Thinking 기능 자체를 지원하지 않음 |
7. 실서비스 적용을 위한 설정 방법
1) application.properties를 통한 전역 설정
가장 간단한 방법이지만, 모든 요청에 동일한 추론 레벨이 적용되므로 주의가 필요합니다.
# 모델 설정
spring.ai.google.genai.chat.options.model=gemini-3-pro-preview
# 추론 레벨 설정
spring.ai.google.genai.chat.options.thinking-level=HIGH
# 위치 설정
spring.ai.google.genai.location=global
2) 자바 코드를 통한 Bean 설정
프로젝트 내에서 ChatModel을 커스터마이징하여 주입할 때 사용합니다.
@Bean
public GoogleGenAiChatModel googleGenAiChatModel() {
return GoogleGenAiChatModel.builder()
.genAiClient(Client.builder()
.project("your-project-id")
.location("global") // 필수 설정
.vertexAI(true)
.build())
.defaultOptions(GoogleGenAiChatOptions.builder()
.model("gemini-3-pro-preview")
.thinkingLevel(GoogleGenAiThinkingLevel.HIGH)
.build())
.build();
}
8. 상황별 API 호출 예제
실무에서는 요청의 성격에 따라 Prompt 단위로 옵션을 다르게 가져가는 것이 효율적입니다.
시나리오 A: 단순 질의응답
속도가 중요하고 논리적 비약이 적은 질문에 사용합니다.
ChatResponse response = chatModel.call(
new Prompt(
"대한민국의 수도는 어디인가요?",
GoogleGenAiChatOptions.builder()
.thinkingLevel(GoogleGenAiThinkingLevel.LOW)
.build()
)
);
시나리오 B: 복잡한 분석 및 리포트
심도 있는 사고가 필요한 고난도 작업에 사용합니다.
ChatResponse response = chatModel.call(
new Prompt(
"최근 10년간의 양자 역학 발전에 대한 리포트를 작성하고, 향후 5년의 기술 트렌드를 예측해줘.",
GoogleGenAiChatOptions.builder()
.thinkingLevel(GoogleGenAiThinkingLevel.HIGH)
.includeThoughts(true) // 사고 과정도 함께 확인
.build()
)
);
9. 주의사항 및 방어 코드
에러 케이스: 혼합 사용 금지
다음과 같이 설정하면 API 서버에서 400 Bad Request 에러를 반환합니다.
// 실행 시 에러 발생
GoogleGenAiChatOptions.builder()
.model("gemini-3-pro-preview")
.thinkingLevel(GoogleGenAiThinkingLevel.HIGH)
.thinkingBudget(4096)
.build();
includeThoughts 사용 시점
includeThoughts를 true로 설정하면 모델이 실제로 무슨 고민을 했는지 확인할 수 있지만, 이는 전체 응답 토큰 양을 증가시킵니다.
- 프롬프트 엔지니어링 단계에서 모델의 사고 과정을 디버깅할 때
- 복잡한 툴 호출 시 모델의 판단 근거를 로그로 남겨야 할 때
위 두 경우를 제외하고는 false로 유지하는 것이 비용 최적화에 유리합니다.
10. 운영 전략 베스트 프랙티스
운영 환경에서는 모든 요청에 HIGH를 적용하는 것은 비용과 지연 시간 관점에서 위험합니다. 다음과 같은 전략적 분기를 추천합니다.
- 기본값은 LOW: 일반적인 대화나 단순 정보 전달은 LOW로 처리합니다.
- 인텐트 기반 전환: 사용자의 질문이 '분석', '설계', '코드 리뷰' 등의 키워드를 포함하거나 입력 데이터가 일정 길이 이상일 경우에만 HIGH를 할당합니다.
- 사용자 선택권 제공: UI상에서 '깊게 생각하기' 토글 버튼을 제공하여, 사용자가 필요할 때만 고사양 추론을 사용하도록 유도합니다.
결론
Gemini 3 Pro의 thinkingLevel 도입은 AI 모델을 사용하는 방식이 점차 정교해지고 있음을 보여줍니다.
개발자는 이제 토큰 개수라는 기술적 수치에 매몰되지 않고, 서비스의 목적에 맞는 '사고의 깊이'를 선택할 수 있게 되었습니다.
Spring AI를 활용하여 이 강력한 기능을 안전하고 효율적으로 도입하면 좋을것 같습니다.
