Google GenAI Chat

Google GenAI Chat (Gemini / Vertex AI)

구글의 Gemini 모델로 생성형 AI 애플리케이션을 만들 때, Spring AI는 Google GenAI API를 지원해요. 이 API는 Gemini Developer API와 Vertex AI 두 가지 경로로 Gemini 모델에 접근할 수 있어요. Gemini는 Google DeepMind가 만든 생성형 AI 모델 패밀리로, 이미지·비디오·텍스트 같은 여러 모달리티를 함께 처리할 수 있는 게 특징이에요. 예를 들어 쿠키가 담긴 사진을 보내면서 그 쿠키 레시피를 물어볼 수 있어요.

출처: 공식문서

이 구현은 두 가지 인증 모드를 제공해요.

• Gemini Developer API: 빠른 프로토타이핑과 개발을 위한 API 키 방식
• Vertex AI: 엔터프라이즈 기능을 갖춘 프로덕션 배포를 위한 Google Cloud 자격 증명 방식

사전 준비

다음 두 인증 방법 중 하나를 선택해요.

옵션 1: Gemini Developer API (API 키)

• Google AI Studio에서 API 키를 발급받아요.
• API 키를 환경 변수나 애플리케이션 속성으로 설정해요.

옵션 2: Vertex AI (Google Cloud)

• OS에 맞는 gcloud CLI를 설치해요.
• 다음 명령으로 인증해요. PROJECT_ID는 Google Cloud 프로젝트 ID, ACCOUNT는 Google Cloud 사용자명으로 바꿔요.

gcloud config set project <PROJECT_ID> &&
gcloud auth application-default login <ACCOUNT>

자동 설정 (Auto-configuration)

Spring AI의 자동 설정과 스타터 모듈의 아티팩트 이름이 크게 바뀌었어요. 자세한 내용은 업그레이드 노트를 확인해주세요.

Spring AI는 Google GenAI Chat 클라이언트를 위한 Spring Boot 자동 설정을 제공해요. Maven pom.xml이나 Gradle build.gradle에 다음 의존성을 추가하면 돼요.

• Maven
• Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-google-genai</artifactId>
</dependency>

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-google-genai'
}

채팅 속성 (Chat Properties)

채팅 자동 설정의 활성·비활성은 프리픽스 spring.ai.model.chat로 관리해요. 활성화하려면 spring.ai.model.chat=google-genai(기본값), 비활성화하려면 spring.ai.model.chat=none을 쓰면 돼요.

연결 속성

Google GenAI에 연결하기 위한 속성 프리픽스는 spring.ai.google.genai예요.

속성	설명	기본값
spring.ai.model.chat	채팅 모델 클라이언트 활성화	google-genai
spring.ai.google.genai.api-key	Gemini Developer API용 API 키. 설정하면 Vertex AI 대신 Gemini Developer API를 사용해요.	-
spring.ai.google.genai.project-id	Google Cloud Platform 프로젝트 ID (Vertex AI 모드에서 필요)	-
spring.ai.google.genai.location	Google Cloud 리전 (Vertex AI 모드에서 필요)	-
spring.ai.google.genai.credentials-uri	Google Cloud 자격 증명 URI. 설정하면 인증용 GoogleCredentials 인스턴스를 만드는 데 사용해요.	-

채팅 모델 속성

Google GenAI Chat의 채팅 모델 구현을 구성하는 속성 프리픽스는 spring.ai.google.genai.chat예요.

속성	설명	기본값
spring.ai.google.genai.chat.model	사용할 Google GenAI 채팅 모델. gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.5-pro, gemini-3.1-pro-preview, gemini-3.1-flash-lite, gemini-3.5-flash 등	gemini-2.5-flash
spring.ai.google.genai.chat.response-mime-type	생성된 후보 텍스트의 출력 MIME 유형	text/plain(기본): 텍스트 출력 또는 application/json: JSON 응답
spring.ai.google.genai.chat.google-search-retrieval	Google 검색 Grounding 기능 사용	true 또는 false, 기본 false
spring.ai.google.genai.chat.include-server-side-tool-invocations	true면 서버 사이드 도구 호출과 응답(예: Google 검색 호출)을 응답 메타데이터에 포함해요. Gemini Developer API(MLDev)에서만 지원되고 Vertex AI에서는 지원하지 않아요.	false
spring.ai.google.genai.chat.temperature	출력의 무작위성 제어. [0.0,1.0] 범위. 1.0에 가까울수록 다양해지고 0.0에 가까울수록 덜 놀라운 응답을 만들어요.	-
spring.ai.google.genai.chat.top-k	샘플링 시 고려할 최대 토큰 수. Top-k 샘플링은 상위 topK개의 가장 가능성 높은 토큰을 고려해요.	-
spring.ai.google.genai.chat.top-p	샘플링 시 고려할 최대 누적 토큰 확률. Nucleus 샘플링은 확률 합이 최소한 topP가 되는 가장 작은 토큰 집합을 고려해요.	-
spring.ai.google.genai.chat.candidate-count	반환할 생성 응답 메시지 수. [1, 8] 사이여야 하고 기본 1이에요.	1
spring.ai.google.genai.chat.max-output-tokens	생성할 최대 토큰 수	-
spring.ai.google.genai.chat.frequency-penalty	반복을 줄이기 위한 빈도 페널티	-
spring.ai.google.genai.chat.presence-penalty	반복을 줄이기 위한 존재 페널티	-
spring.ai.google.genai.chat.thinking-budget	사고 과정의 thinking budget	-
spring.ai.google.genai.chat.thinking-level	모델이 생성할 thinking 토큰 수준. LOW, HIGH, THINKING_LEVEL_UNSPECIFIED 중 유효	-
spring.ai.google.genai.chat.include-thoughts	함수 호출을 위한 thought 시그니처 활성화. Gemini 3 Pro에서 tool-call 루프 중 검증 오류를 피하려면 필수.	false
spring.ai.google.genai.chat.tool-callbacks	ChatModel에 등록할 Tool 콜백	-
spring.ai.google.genai.chat.safety-settings	Google GenAI 안전 설정에 정의된 대로 안전 필터를 제어하는 안전 설정 목록	-
spring.ai.google.genai.chat.cached-content-name	이 요청에 사용할 캐시된 콘텐츠 이름	-
spring.ai.google.genai.chat.use-cached-content	가능하면 캐시된 콘텐츠를 사용할지 여부	false
spring.ai.google.genai.chat.auto-cache-threshold	이 토큰 임계값을 초과하는 프롬프트를 자동 캐시. null로 설정하면 자동 캐싱 비활성화	-
spring.ai.google.genai.chat.auto-cache-ttl	자동 캐시된 콘텐츠의 TTL (ISO-8601 형식, 예: PT1H는 1시간)	PT1H
spring.ai.google.genai.chat.enable-cached-content	캐시된 콘텐츠 관리를 위한 GoogleGenAiCachedContentService 빈 활성화	true
spring.ai.google.genai.chat.service-tier	요청에 사용할 서비스 티어. STANDARD, PRIORITY, FLEX 중 유효	-
spring.ai.google.genai.chat.tool-choice.mode	도구 제공 시 모델이 함수를 선택하는 방식 제어. AUTO(모델 결정), ANY(항상 함수 호출), VALIDATED(함수 호출 또는 자연어), NONE(함수 호출 없음)	-
spring.ai.google.genai.chat.tool-choice.allowed-function-names	모델이 호출할 수 있는 함수 이름의 쉼표 구분 목록. tool-choice.mode가 ANY나 VALIDATED일 때만 적용	-

spring.ai.google.genai.chat 프리픽스가 붙은 모든 속성은 Prompt 호출에 요청별 runtime 옵션을 추가해 런타임에 덮어쓸 수 있어요.

런타임 옵션

시작 시 기본 옵션은 GoogleGenAiChatModel(client, options) 생성자나 spring.ai.google.genai.chat.* 속성으로 구성해요. 런타임에는 Prompt 호출에 요청별 옵션을 추가해 기본값을 덮어쓸 수 있어요. 예를 들어 특정 요청의 기본 temperature를 덮어쓰는 코드예요.

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        GoogleGenAiChatOptions.builder()
            .temperature(0.4)
        .build()
    ));

도구 호출 (Tool Calling)

GoogleGenAiChatModel은 도구 호출을 지원해요. 모델이 도구 실행을 요청할 수 있지만 직접 실행하지는 않고, Spring AI가 실행을 담당해요.

대부분의 애플리케이션에서는 자동 등록되는 ToolCallingAdvisor와 함께 ChatClient를 쓰면 돼요. 루프를 직접 제어해야 하는 저수준 제어가 필요하면 ChatModel Tool Calling을 참고해요. 구글의 내장 도구(검색, 지도, URL Context)와 클라이언트 사이드 함수 호출을 결합하는 방법은 아래 Server-Side Tool Invocations에서 다뤄요.

도구 선택 (Tool Choice)

GoogleGenAiChatOptions.ToolChoice는 도구가 제공될 때 모델이 함수를 선택하는 방식을 구성해요. Google GenAI의 FunctionCallingConfig에 매핑돼요.

모드	동작
AUTO	모델이 함수 호출 또는 자연어 응답을 스스로 결정 (기본 동작)
ANY	모델이 항상 함수 호출을 예측. allowedFunctionNames가 설정되면 그 함수들로 제한
VALIDATED	모델이 함수 호출 또는 자연어 응답을 할 수 있음. allowedFunctionNames가 설정되면 그 함수들로 제한
NONE	모델이 함수를 호출하지 않고 자연어 응답만 반환

allowedFunctionNames는 모드가 ANY 또는 VALIDATED일 때만 적용되고, AUTO와 NONE에서는 조용히 무시돼요.

프로그래밍 방식 설정

ChatResponse response = chatModel.call(
    new Prompt(
        "What is the weather in Paris?",
        GoogleGenAiChatOptions.builder()
            .toolChoice(new GoogleGenAiChatOptions.ToolChoice(
                GoogleGenAiChatOptions.ToolChoice.Mode.ANY,
                List.of("get_weather")))
            .build()
    ));

샘플 컨트롤러

이렇게 하면 클래스에 주입할 수 있는 GoogleGenAiChatModel 구현이 만들어져요. 텍스트 생성을 위한 간단한 @Controller 클래스 예시를 볼게요.

@RestController
public class ChatController {

    private final GoogleGenAiChatModel chatModel;

    @Autowired
    public ChatController(GoogleGenAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
	public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}

수동 설정

GoogleGenAiChatModel은 ChatModel을 구현하고, Google GenAI 서비스에 연결하기 위해 com.google.genai.Client를 사용해요.

Maven pom.xml에 spring-ai-google-genai 의존성을 추가해요.

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-google-genai</artifactId>
</dependency>

또는 Gradle build.gradle 파일에 추가해요.

dependencies {
    implementation 'org.springframework.ai:spring-ai-google-genai'
}

다음으로 GoogleGenAiChatModel을 만들어 텍스트 생성에 사용해요.

API 키 사용

Client genAiClient = Client.builder()
    .apiKey(System.getenv("GOOGLE_API_KEY"))
    .build();

var chatModel = new GoogleGenAiChatModel(genAiClient,
    GoogleGenAiChatOptions.builder()
        .model(ChatModel.GEMINI_2_0_FLASH)
        .temperature(0.4)
    .build());

ChatResponse response = this.chatModel.call(
    new Prompt("Generate the names of 5 famous pirates."));

Vertex AI 사용

Client genAiClient = Client.builder()
    .project(System.getenv("GOOGLE_CLOUD_PROJECT"))
    .location(System.getenv("GOOGLE_CLOUD_LOCATION"))
    .vertexAI(true)
    .build();

var chatModel = new GoogleGenAiChatModel(genAiClient,
    GoogleGenAiChatOptions.builder()
        .model(ChatModel.GEMINI_2_0_FLASH)
        .temperature(0.4)
    .build());

ChatResponse response = this.chatModel.call(
    new Prompt("Generate the names of 5 famous pirates."));

GoogleGenAiChatOptions는 채팅 요청에 대한 구성 정보를 제공하고, GoogleGenAiChatOptions.Builder는 플루언트 옵션 빌더예요.

Vertex AI Gemini에서 마이그레이션

이전에 사용하던 Vertex AI Gemini 구현(spring-ai-vertex-ai-gemini)은 제거됐어요. Google GenAI로 마이그레이션해야 해요. 핵심 차이점은 다음과 같아요.

1. SDK: Google GenAI는 com.google.cloud.vertexai.VertexAI 대신 새 com.google.genai.Client를 사용해요.
2. 인증: API 키와 Google Cloud 자격 증명(Vertex AI 모드)을 모두 지원해요.
3. 패키지 이름: 클래스가 org.springframework.ai.vertexai.gemini 대신 org.springframework.ai.google.genai에 있어요.
4. 속성 프리픽스: spring.ai.vertex.ai.gemini 대신 spring.ai.google.genai를 사용해요.

Google GenAI는 API 키로 빠른 프로토타이핑을, Google Cloud 자격 증명으로 Vertex AI를 통한 프로덕션 배포를 지원해요.

저수준 Java 클라이언트

Google GenAI 구현은 Gemini 모델에 접근하기 위한 현대적이고 간결한 API를 제공하는 새 Google GenAI Java SDK 위에 구축돼 있어요.

더 알아보기

• Google GenAI API 문서
• Spring AI 툴 호출 문서
• Spring AI 업그레이드 노트