대부분의 "백엔드에 LLM 추가하기" 튜토리얼은 제공업체가 필드를 변경하는 순간 쓸모없어지는 수동으로 만든 HTTP 클라이언트, JSON 매핑, 그리고 재시도 로직(retry logic)의 더미로 끝납니다. Spring AI는 다른 방식을 택합니다. 모델을 Spring이 이미 데이터 소스(datasource)나 메시지 브로커(message broker)를 다루는 방식과 동일하게 취급합니다. 즉, 속성(properties)으로 구성하고 필요한 곳에 주입(inject)하는 빈(bean)으로 다루는 것입니다. Google의 Gemini를 사용할 때 이것이 어떻게 적용되는지, 그리고 사람들이 반나절을 허비하게 만드는 두 가지 설정 함정에 대해 알아보겠습니다.

하나의 스타터, 두 가지 인증 방식

2026년 기준으로 여러분이 사용해야 할 모듈은 Google GenAI 스타터(starter)입니다. 이 모듈은 무료 Gemini Developer API(API 키만 필요)와 유료 Vertex AI 경로(GCP 자격 증명 필요)를 모두 지원합니다. 코드는 동일하지만 설정만 다릅니다.

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

버전을 수동으로 고정할 필요가 없도록 pom.xml에 Spring AI BOM을 함께 사용하세요. **무료 티어(free tier)**의 경우, aistudio.google.com/apikey에서 키를 가져오고(Google 계정만 필요, 카드 불필요) 키만 설정하면 됩니다:

spring:
  ai:
    google:
...

반면 Vertex AI를 사용하는 경우에는 API 키를 제외하고 프로젝트(project)와 위치(location)를 지정합니다. Spring AI가 gcloud 애플리케이션 기본 자격 증명(application-default credentials)을 자동으로 탐색하므로, 인증 코드를 전혀 작성할 필요가 없습니다:

spring:
  ai:
    google:
...

실제 호출은 지루할 정도입니다 — 이것이 핵심입니다

스타터는 ChatClient.Builder를 자동 구성합니다. 이를 주입(inject)하고 한 번 빌드하면, 호출 코드는 OpenAI나 Anthropic을 위해 작성하는 코드와 동일해 보입니다:

@Service
public class GeminiService {

...

나중에 제공업체를 교체한다는 것은 이 서비스가 아니라 의존성(dependency)과 설정 블록을 변경하는 것을 의미합니다. 이것이 바로 핵심 가치 제안입니다. 모델은 코드베이스 전체에 스레드(threaded)된 강력한 의존성이 아니라, 교체 가능한 세부 사항이 됩니다.

문자열 스크래핑 대신 구조화된 출력(Structured output)

백엔드에서 실제로 시간을 절약해 주는 부분은 모델의 답변을 Java 타입으로 직접 매핑하여, 산문 형태의 텍스트를 정규 표현식(regex)으로 처리할 필요가 없게 만드는 것입니다:

public record Summary(String headline, List<String> keyPoints) {}

public Summary summarize(String article) {
...

Spring AI는 스키마(schema)를 생성하고, Gemini가 이를 준수하도록 요청하며, 응답을 사용자의 record로 역직렬화(deserialization)합니다. 여기서부터 도구 호출(tool calling)과 RAG(검색 증강 생성)로 넘어가는 과정은 매우 간단합니다. 동일한 ChatClient를 사용하며, 몇 가지 빌더 메서드(builder methods)만 더 추가하면 됩니다.

버그처럼 보이지만 버그가 아닌 두 가지 함정

모델 지원 중단 (Model deprecation). gemini-2.0-flash는 지원이 중단되어 종료될 예정입니다. Gemini 1.x 식별자는 이미 404 오류를 반환합니다. gemini-2.5-flash를 사용하세요. limit: 0 할당량(quota) 오류는 보통 계정이 제한된 것이 아니라, 모델 자체의 무료 티어(free-tier) 용량이 소진되었음을 의미합니다.

인증 모드 혼선 (Auth-mode bleed). 실험 과정에서 남겨진 설정이라도 project-id나 location을 어디에든 설정하면, 클라이언트는 조용히 Vertex AI 모드로 전환됩니다. 이 경우 사용자의 무료 Developer API 키는 할당량 문제처럼 보이는 400 오류와 함께 거부됩니다. 무료 티어를 사용하려면 오직 API 키만 설정하고, 프로젝트(project)나 위치(location)에 대한 모든 흔적을 삭제하십시오.

이 두 가지 사례 모두 설정이 실제 원인임에도 불구하고, 자신의 키가 잘못되었다고 오해하여 어려움을 겪은 사용자들이 있었습니다.

마무리

Spring AI의 추상화가 제값을 하는 순간은 Gemini를 다른 모델로 교체할 때, 의존성(dependency)과 YAML 블록 외에는 아무것도 건드리지 않아도 되는 날입니다. 여기에 도달하기 위해서는 스타터(starter) 하나와 몇 가지 속성(properties), 그리고 project-id가 단순한 메타데이터가 아니라 모드 전환 스위치라는 점을 기억하는 것만 있으면 됩니다.

프로토타이핑을 위해 무료 Developer API를 선호하시나요, 아니면 운영(prod)과 개발(dev) 환경이 동일한 코드 경로를 공유하도록 Vertex AI로 바로 넘어가시나요? 여러분의 결정은 무엇이었나요?