소개와 모델 세팅

Spring AI는 LLM(거대 언어 모델) 같은 AI 모델을 스프링 애플리케이션에 자연스럽게 끼워 넣게 해 주는 프레임워크다. OpenAI·Anthropic·Google 등 제각각인 AI API를, 우리가 이미 아는 스프링 방식(빈 주입·자동설정)으로 통일해 다룬다. 분량이 많아 여덟 편으로 나누어, 하나의 실습 프로젝트를 키워 가며 다룬다.

#1. Spring AI란

LLM을 직접 쓰려면 각 회사의 REST API에 HTTP 요청을 만들고, JSON을 직렬화·역직렬화하고, 인증·재시도·스트리밍을 일일이 처리해야 한다. Spring AI는 이 반복 작업을 모델 추상화로 감싸, 핵심 코드만 남긴다.

flowchart LR
    App["우리 애플리케이션<br/>(@Service)"] --> SAI["Spring AI<br/>ChatClient / ChatModel"]
    SAI --> P1["OpenAI"]
    SAI --> P2["Anthropic"]
    SAI --> P3["Google · Ollama · ..."]

#2. 프로젝트 의존성

Spring Boot 프로젝트에 Spring AI BOM과 OpenAI 스타터를 추가한다. (Gradle 기준, 이 강의 실습 프로젝트의 build.gradle)

ext {
    set('springAiVersion', "1.1.7")   // Spring AI 버전
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-webflux'   // 스트리밍(SSE)용

    // OpenAI 모델(채팅·임베딩·이미지·음성)을 한 번에 제공하는 스타터
    implementation 'org.springframework.ai:spring-ai-starter-model-openai'

    // RAG에서 쓸 문서 리더와 RAG 어드바이저
    implementation 'org.springframework.ai:spring-ai-pdf-document-reader'
    implementation 'org.springframework.ai:spring-ai-advisors-vector-store'
}

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

#3. API 키와 모델 설정 {#3-config}

설정은 src/main/resources/application.yml에 둔다. API 키는 코드·설정 파일에 직접 박지 말고 환경변수로 주입하는 것이 원칙이다. 아래는 OPENAI_API_KEY 환경변수가 있으면 그 값을, 없으면 기본값을 쓰는 형태다.

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}          # 환경변수로 주입 (export OPENAI_API_KEY=sk-...)
      chat:
        options:
          model: ${OPENAI_MODEL:gpt-4o-mini}   # 기본 모델
          temperature: 0.7                      # 0에 가까울수록 일관, 1에 가까울수록 창의적
      embedding:
        options:
          model: text-embedding-3-small         # RAG에서 쓸 임베딩 모델

# 코드에서 참조할 모델 슬러그 모음 (모델 2개)
app:
  models:
    mini: gpt-4o-mini    # 빠르고 저렴 (기본)
    full: gpt-4o         # 더 강력 (비교용)

#모델을 2개 등록하는 이유

app.models에 모델 두 개를 등록해 두면, 코드에서 요청마다 모델을 바꿔 응답을 비교할 수 있다. 예를 들어 "빠르고 싼 모델"과 "느리지만 똑똑한 모델"의 답을 나란히 받아 품질·비용을 가늠한다. 실제 교체 방법은 다음 편에서 다룬다.

flowchart LR
    Q["같은 질문"] --> M1["gpt-4o-mini<br/>(빠름·저렴)"]
    Q --> M2["gpt-4o<br/>(강력)"]
    M1 --> R["응답 비교"]
    M2 --> R

spring:
  ai:
    openai:
      base-url: https://openrouter.ai/api   # 예: OpenRouter
      api-key: ${OPENROUTER_API_KEY}

#4. 동작 확인 {#4-smoke-test}

설정이 끝났으면 가장 간단한 채팅 한 줄로 연결을 확인한다. ChatClient.Builder를 주입받아 build()하고 호출하면 된다.

@RestController
public class PingController {

    private final ChatClient chatClient;

    public PingController(ChatClient.Builder builder) {
        this.chatClient = builder.build();   // 자동설정된 빌더로 ChatClient 생성
    }

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

# 애플리케이션을 띄운 뒤
curl "http://localhost:8080/ping?message=hello"
# -> Hello! How can I assist you today?

curl -G "http://localhost:8080/ping" --data-urlencode "message=스프링이 뭐야?"

이제 연결이 확인됐다. 다음 편에서 ChatClient와 ChatModel의 차이, 스트리밍, 그리고 등록한 모델 2개를 바꿔 쓰는 법을 본격적으로 다룬다.

➡️ 다음 편: 기본 채팅과 모델 비교