Spring AI로 Spring Boot에서 LLM 연동하는 방법

Spring AI로 Spring Boot에서 LLM 연동하는 방법

2026년 현재 Spring Boot 애플리케이션에 LLM을 연동하는 가장 표준적인 방법은 Spring AI를 사용하는 것입니다. 안정 버전은 1.1.x 라인이며, BOM과 스타터 의존성 하나만 추가하면 ChatClient API로 몇 줄 만에 OpenAI·Anthropic·Google 등 주요 모델을 호출할 수 있습니다. 2.0.0은 아직 마일스톤(M8) 단계이므로 프로덕션에는 1.1.x를 권장합니다.

이 글에서는 OpenAI를 예시로 의존성 설정부터 REST API로 LLM 응답을 반환하는 실습 코드까지 정리합니다.

Spring AI란

Spring AI는 Spring 생태계의 설계 원칙(이식성, 모듈화)을 AI 도메인에 적용한 애플리케이션 프레임워크입니다. 핵심은 ChatModel, EmbeddingModel 같은 공통 인터페이스입니다. 코드가 특정 벤더 API에 묶이지 않기 때문에, 설정만 바꾸면 OpenAI에서 Anthropic이나 Ollama(로컬 모델)로 갈아탈 수 있습니다. WebClient로 직접 JSON을 조립하던 방식과 비교하면 유지보수 부담이 크게 줄어듭니다.

의존성 설정

Spring Boot 3.4 이상 프로젝트 기준입니다. Gradle에 BOM과 OpenAI 스타터를 추가합니다.

ext {
    set('springAiVersion', "1.1.6")
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}

dependencyManagement {
    imports {
        mavenBom "org.springframework.ai:spring-ai-bom:${springAiVersion}"
    }
}

API 키는 application.yml에서 환경 변수로 주입합니다. 키를 소스에 하드코딩하면 저장소에 노출될 위험이 있으므로 반드시 환경 변수를 사용하세요.

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o-mini
          temperature: 0.7

ChatClient로 LLM 호출하기

ChatClient는 WebClient·RestClient와 유사한 플루언트 API입니다. 스타터가 ChatClient.Builder를 자동 구성해 주므로 주입받아 바로 사용하면 됩니다.

@RestController
@RequestMapping("/api/chat")
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder
                .defaultSystem("당신은 백엔드 개발을 돕는 어시스턴트입니다.")
                .build();
    }

    @GetMapping
    public String chat(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

http://localhost:8080/api/chat?message=JPA란 형태로 호출하면 LLM 응답이 문자열로 반환됩니다. 스트리밍이 필요하면 .call() 대신 .stream()을 사용해 Flux<String>으로 받을 수 있습니다.

응답을 DTO로 바로 매핑하는 구조화 출력(Structured Output)도 지원합니다.

record BookRecommendation(String title, String author, String reason) {}

BookRecommendation book = chatClient.prompt()
        .user("자바 개발자에게 추천할 책 한 권")
        .call()
        .entity(BookRecommendation.class);

실무 팁과 주의사항

타임아웃과 재시도를 반드시 설정하세요. LLM API는 일반 REST API보다 응답이 느리고 간헐적으로 실패합니다. Spring AI는 spring.ai.retry.* 프로퍼티로 재시도 정책을 제어할 수 있습니다.

버전 선택에 주의하세요. 2.0.0 마일스톤은 Jackson 3 전환, MCP 패키지 이동 등 브레이킹 체인지가 많아 실서비스 적용은 이릅니다. 1.1.x로 시작한 뒤 2.0 GA 이후 마이그레이션하는 편이 안전합니다.

비용 관리도 설계 대상입니다. model 옵션으로 경량 모델(gpt-4o-mini 등)을 기본으로 두고, 필요한 요청에만 상위 모델을 지정하는 방식이 일반적입니다. 실제 운영 중인 Kraft에서도 외부 API 연동부는 타임아웃·폴백을 먼저 설계해 두는 것이 장애 대응에 가장 효과적이었습니다.

마무리

Spring AI를 쓰면 LLM 연동이 "외부 API 연동" 수준의 익숙한 작업으로 내려옵니다. 인터페이스 기반 설계 덕분에 모델 교체 비용이 낮다는 점이 가장 큰 장점입니다. Spring AI 1.1.x는 Spring Boot 3.x를 전제로 하므로, 프로젝트의 부트 버전이 오래됐다면 Spring Boot 버전 선택 가이드를 먼저 확인해 보세요.

다음 글에서는 Spring AI의 RAG(검색 증강 생성) 구성과 벡터 스토어 연동을 다룰 예정입니다.