Spring AI 완벽 가이드 환경 설정부터 첫 실행까지

인공지능을 Spring 애플리케이션에 통합하는 새로운 프레임워크 Spring AI를 소개합니다. Java 개발자를 위한 친절한 환경 설정 가이드부터 첫 번째 AI 애플리케이션 실행까지, 점프 투 자바 스타일로 술술 읽히는 입문서입니다.

1. Spring AI란 무엇인가

2024년 어느 날, 김개발 씨는 회사에서 흥미로운 프로젝트를 맡게 되었습니다. "우리 서비스에 ChatGPT를 연동해보세요." 팀장님의 말씀에 김개발 씨는 막막했습니다.

Python으로는 AI 연동이 쉽다는데, Spring으로는 어떻게 해야 할까요?

Spring AI는 Spring 생태계에서 인공지능 기능을 쉽게 사용할 수 있도록 만든 공식 프레임워크입니다. 마치 Spring Data JPA가 데이터베이스 접근을 쉽게 만들어주듯이, Spring AI는 OpenAI, Azure OpenAI 같은 AI 서비스를 Spring 방식으로 연동할 수 있게 해줍니다.

Java 개발자에게 익숙한 Spring의 철학과 패턴을 그대로 사용하면서 AI 기능을 활용할 수 있습니다.

다음 코드를 살펴봅시다.

// Spring AI의 기본 개념을 보여주는 간단한 예제
@RestController
public class AiController {

    private final ChatClient chatClient;

    // Spring AI의 ChatClient를 주입받습니다
    public AiController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping("/ai/chat")
    public String chat(@RequestParam String message) {
        // 마치 RestTemplate처럼 간단하게 AI와 대화합니다
        return chatClient.prompt()
            .user(message)
            .call()
            .content();
    }
}

김개발 씨는 입사 1년 차 백엔드 개발자입니다. Spring Boot로 REST API를 만드는 일에는 이제 제법 익숙해졌습니다.

그런데 요즘 회사에서 자꾸 AI 프로젝트 이야기가 나옵니다. 회의 시간에 팀장님이 말씀하셨습니다.

"우리 고객 상담 시스템에 ChatGPT를 붙여봅시다. 김개발 씨가 한번 알아보세요." 김개발 씨는 당황했습니다.

Python이라면 LangChain 같은 라이브러리가 있다는데, Spring에서는 어떻게 해야 할까요? 그렇다면 Spring AI란 정확히 무엇일까요?

쉽게 비유하자면, Spring AI는 마치 Spring Data JPA와 같은 역할을 합니다. Spring Data JPA가 복잡한 데이터베이스 작업을 Spring 방식으로 단순화해주듯이, Spring AI는 복잡한 AI 모델 연동을 Spring 방식으로 단순하게 만들어줍니다.

직접 OpenAI API를 호출하고 JSON을 파싱하는 대신, Spring의 의존성 주입과 자동 설정 기능을 활용할 수 있습니다. Spring AI가 없던 시절에는 어땠을까요?

개발자들은 OpenAI API를 호출하기 위해 RestTemplate이나 WebClient를 직접 설정해야 했습니다. 요청 본문을 JSON으로 만들고, 응답을 파싱하고, 예외 처리를 하고, API 키를 관리하는 모든 과정을 직접 구현했습니다.

더 큰 문제는 AI 모델마다 API 형식이 달라서 OpenAI에서 Azure OpenAI로 변경하려면 코드를 대폭 수정해야 했다는 점입니다. 바로 이런 문제를 해결하기 위해 Spring AI가 등장했습니다.

Spring AI를 사용하면 통일된 인터페이스로 다양한 AI 모델을 사용할 수 있습니다. 또한 Spring Boot의 자동 설정 기능으로 복잡한 초기 설정을 최소화할 수 있습니다.

무엇보다 Spring의 철학을 그대로 따르기 때문에 기존 Spring 개발자라면 익숙하게 사용할 수 있다는 큰 이점이 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다.

먼저 생성자에서 ChatClient.Builder를 주입받는 부분을 보면 전형적인 Spring 방식임을 알 수 있습니다. 이 부분이 핵심입니다.

Spring AI가 자동으로 설정한 Builder를 주입해주기 때문에 개발자는 별도 설정 없이 바로 사용할 수 있습니다. 다음으로 prompt() 메서드에서는 AI에게 보낼 메시지를 구성합니다.

마지막으로 call().content()를 통해 AI의 응답을 문자열로 받아옵니다. 실제 현업에서는 어떻게 활용할까요?

예를 들어 온라인 쇼핑몰의 고객 상담 서비스를 개발한다고 가정해봅시다. 고객이 "배송은 언제 되나요?"라고 물으면 주문 정보를 조회하고, AI에게 상황을 설명하고, 자연스러운 답변을 생성하는 시나리오에서 Spring AI를 활용하면 기존 Spring 코드와 매끄럽게 통합할 수 있습니다.

네이버, 카카오 같은 많은 기업에서 이런 패턴을 적극적으로 도입하고 있습니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 Spring AI를 단순한 HTTP 클라이언트로만 생각하는 것입니다. 이렇게 하면 Spring AI가 제공하는 프롬프트 템플릿, 출력 파싱, 벡터 스토어 같은 강력한 기능을 놓칠 수 있습니다.

따라서 공식 문서를 꼼꼼히 읽어보고 Spring AI의 전체 기능을 이해한 후 사용해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다.

선배 개발자 박시니어 씨가 Spring AI를 소개해주었습니다. "Python 부럽지 않죠?

우리도 Spring 방식으로 AI를 쓸 수 있어요." Spring AI를 제대로 이해하면 기존 Spring 지식을 활용해 빠르게 AI 기능을 개발할 수 있습니다. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - Spring AI는 2023년 공식 릴리스된 비교적 새로운 프로젝트입니다

OpenAI뿐만 아니라 Azure OpenAI, HuggingFace, Ollama 등 다양한 모델을 지원합니다

2. Spring AI의 주요 특징과 장점

Spring AI 문서를 읽던 김개발 씨는 궁금해졌습니다. "그냥 RestTemplate로 OpenAI API 호출하면 안 되나?

굳이 새로운 라이브러리를 배워야 할까?" 마침 옆을 지나던 박시니어 씨가 웃으며 말했습니다. "그렇게 생각했다가는 나중에 후회할걸요?"

Spring AI는 단순한 API 래퍼가 아닙니다. 통일된 추상화 계층으로 여러 AI 모델을 일관되게 사용하고, 프롬프트 템플릿으로 동적인 메시지를 생성하며, 구조화된 출력으로 AI 응답을 자바 객체로 자동 변환합니다.

또한 벡터 스토어 통합으로 RAG 패턴을 쉽게 구현할 수 있어, AI 애플리케이션 개발의 모든 복잡성을 Spring 방식으로 해결해줍니다.

다음 코드를 살펴봅시다.

@Service
public class ProductRecommendationService {

    private final ChatClient chatClient;

    public ProductRecommendationService(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    // AI 응답을 자바 객체로 자동 변환합니다
    public ProductList recommendProducts(String userPreference) {
        return chatClient.prompt()
            .user(u -> u.text("사용자 취향: {preference}에 맞는 상품 5개 추천")
                .param("preference", userPreference))
            .call()
            .entity(ProductList.class);  // JSON을 자바 객체로 자동 변환
    }
}

박시니어 씨가 김개발 씨 옆에 앉았습니다. "제가 지난달에 직접 OpenAI API를 호출하는 코드를 짰었어요.

한 100줄쯤 됐는데, Spring AI로 다시 짜니까 20줄로 줄어들더라고요." 김개발 씨는 반신반의했습니다. 정말 그렇게 큰 차이가 있을까요?

박시니어 씨는 노트북을 열어 직접 보여주기 시작했습니다. 그렇다면 Spring AI의 주요 특징은 정확히 무엇일까요?

첫 번째 특징은 포터블 API 추상화입니다. 쉽게 비유하자면, JDBC가 데이터베이스마다 다른 드라이버를 통일된 인터페이스로 제공하듯이, Spring AI는 OpenAI, Azure OpenAI, Anthropic Claude, Google Vertex AI 등을 동일한 인터페이스로 사용할 수 있게 해줍니다.

설정 파일의 한 줄만 바꾸면 다른 AI 모델로 전환할 수 있습니다. 두 번째 특징은 프롬프트 템플릿입니다.

마치 Thymeleaf나 JSP가 HTML 템플릿을 제공하듯이, Spring AI는 프롬프트 템플릿을 제공합니다. 변수를 사용해 동적으로 프롬프트를 생성할 수 있어, 같은 패턴의 질문을 반복할 때 코드 중복을 줄일 수 있습니다.

직접 API를 호출하던 시절에는 어땠을까요? 개발자들은 매번 JSON 문자열을 직접 조합해야 했습니다.

사용자 입력을 프롬프트에 삽입할 때 이스케이프 처리를 잊어서 JSON 파싱 에러가 나기도 했습니다. 더 큰 문제는 AI 모델의 응답이 항상 JSON 문자열이기 때문에 이를 자바 객체로 변환하는 코드를 매번 작성해야 했다는 점입니다.

Jackson 라이브러리로 파싱하고, 예외 처리하고, null 체크하는 보일러플레이트 코드가 끝없이 반복되었습니다. 바로 이런 문제를 해결하기 위해 Spring AI의 고급 기능들이 등장했습니다.

Spring AI를 사용하면 구조화된 출력이 가능해집니다. entity() 메서드에 자바 클래스를 지정하면 AI 응답을 자동으로 객체로 변환해줍니다.

또한 함수 호출도 지원해서 AI가 필요할 때 자바 메서드를 호출하도록 설정할 수 있습니다. 무엇보다 벡터 스토어 통합으로 RAG 패턴을 손쉽게 구현할 수 있다는 큰 이점이 있습니다.

위의 코드를 한 줄씩 살펴보겠습니다. 먼저 user() 메서드 안에서 text()와 param()을 사용하는 부분을 보면 전형적인 템플릿 패턴임을 알 수 있습니다.

중괄호 안의 preference는 플레이스홀더이고, param()으로 실제 값을 바인딩합니다. 다음으로 entity(ProductList.class) 부분에서는 AI의 JSON 응답을 자동으로 ProductList 객체로 변환합니다.

Jackson을 사용한 수동 파싱이 필요 없습니다. 실제 현업에서는 어떻게 활용할까요?

예를 들어 이커머스 추천 시스템을 개발한다고 가정해봅시다. 사용자의 검색 이력, 구매 이력, 관심사를 분석해서 맞춤 상품을 추천하는 시나리오에서 Spring AI의 프롬프트 템플릿을 활용하면 다양한 상황에 맞는 프롬프트를 재사용 가능한 형태로 관리할 수 있습니다.

쿠팡, 무신사 같은 기업에서 이런 패턴을 실제로 활용하고 있습니다. 또한 RAG 패턴을 구현할 때 Spring AI의 진가가 드러납니다.

RAG는 Retrieval-Augmented Generation의 약자로, 벡터 데이터베이스에서 관련 문서를 검색한 후 그 내용을 프롬프트에 포함시켜 더 정확한 답변을 생성하는 기법입니다. Spring AI는 Redis, Pinecone, Chroma 같은 벡터 스토어를 기본 지원하므로 복잡한 RAG 파이프라인을 Spring 방식으로 구성할 수 있습니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 모든 응답을 entity()로 변환하려고 시도하는 것입니다.

이렇게 하면 AI가 원하는 형식으로 응답하지 않았을 때 파싱 에러가 발생할 수 있습니다. 따라서 단순한 텍스트 응답이 필요한 경우에는 content()를 사용하고, 구조화된 데이터가 필요한 경우에만 entity()를 사용하는 것이 올바른 방법입니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 코드를 본 김개발 씨는 감탄했습니다.

"와, 이렇게 간단하게 되는구나!" Spring AI의 특징을 제대로 이해하면 AI 통합 코드를 훨씬 깔끔하게 작성할 수 있습니다. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - entity()로 변환할 클래스는 record나 일반 POJO 모두 사용 가능합니다

프롬프트 템플릿은 외부 파일로 관리하면 유지보수가 편리합니다

3. 개발 환경 설정

"그럼 저도 한번 해볼까요?" 김개발 씨는 신이 나서 자신의 노트북을 열었습니다. 그런데 막상 시작하려니 막막했습니다.

"Java 버전은 얼마가 필요하죠? Spring Boot는요?" 박시니어 씨가 친절하게 설명해주기 시작했습니다.

Spring AI를 사용하려면 Java 17 이상과 Spring Boot 3.0 이상이 필수입니다. Spring Boot 3는 Java 17을 최소 요구사항으로 하기 때문에 이전 버전을 사용 중이라면 먼저 업그레이드해야 합니다.

또한 빌드 도구로는 Maven 3.6+ 또는 **Gradle 7.5+**를 권장하며, IDE는 IntelliJ IDEA나 Eclipse 최신 버전을 사용하면 개발 경험이 더 좋습니다.

다음 코드를 살펴봅시다.

// Java 버전 확인
// 터미널에서 실행
java -version
// 출력 예시: openjdk version "17.0.9" 2023-10-17

// build.gradle (Gradle 사용 시)
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.1'
    id 'io.spring.dependency-management' version '1.1.4'
}

java {
    sourceCompatibility = '17'
    targetCompatibility = '17'
}

김개발 씨는 현재 회사 프로젝트에서 Java 11을 사용하고 있습니다. Spring Boot 버전은 2.7입니다.

그런데 Spring AI를 쓰려면 업그레이드가 필요하다니, 걱정이 앞섭니다. 박시니어 씨가 안심시켰습니다.

"개인 프로젝트로 먼저 연습해보세요. 회사 프로젝트는 나중에 차근차근 업그레이드하면 됩니다." 그렇다면 정확히 어떤 환경이 필요한 걸까요?

쉽게 비유하자면, Spring AI는 최신 자동차입니다. 최신 자동차를 운전하려면 최신 면허증과 도로가 필요하듯이, Spring AI를 실행하려면 Java 17이라는 최신 런타임과 Spring Boot 3라는 최신 프레임워크가 필요합니다.

이전 버전에서는 작동하지 않습니다. 왜 Java 17이 필수일까요?

Spring Boot 3는 Jakarta EE 9를 기반으로 재작성되었습니다. 기존 javax 패키지가 jakarta로 변경되면서 많은 내부 구조가 바뀌었습니다.

Java 17은 이런 변화를 지원하는 첫 번째 LTS 버전입니다. 또한 Java 17에는 레코드, sealed 클래스, 패턴 매칭 같은 유용한 기능이 추가되어 Spring AI 코드를 더 간결하게 작성할 수 있습니다.

예전 Java 8이나 11 환경에서는 어땠을까요? 물론 Java 8이나 11도 훌륭한 버전입니다.

많은 레거시 프로젝트가 아직도 이 버전을 사용하고 있습니다. 하지만 Spring AI는 최신 기능을 적극 활용하기 때문에 이전 버전을 지원하지 않습니다.

억지로 다운그레이드하려고 시도하면 컴파일 에러와 런타임 에러의 늪에 빠지게 됩니다. 바로 이런 이유로 개발 환경 준비가 중요합니다.

먼저 Java 17을 설치해야 합니다. Oracle JDK, OpenJDK, Amazon Corretto, Azul Zulu 등 다양한 배포판 중 하나를 선택하면 됩니다.

요즘은 무료인 OpenJDK를 많이 사용합니다. 다음으로 빌드 도구를 설정해야 합니다.

Maven을 사용한다면 pom.xml에서 java.version을 17로 설정하고, Gradle을 사용한다면 build.gradle에서 sourceCompatibility를 17로 설정합니다. 위의 코드를 단계별로 살펴보겠습니다.

먼저 터미널에서 java -version을 실행해보면 현재 설치된 Java 버전을 확인할 수 있습니다. 만약 17 미만이라면 새로 설치해야 합니다.

다음으로 build.gradle의 plugins 블록을 보면 Spring Boot 3.2.1 버전을 사용하는 것을 알 수 있습니다. 마지막으로 java 블록에서 sourceCompatibility와 targetCompatibility를 17로 설정하면 Java 17 문법을 사용할 수 있습니다.

실제 현업에서는 어떻게 준비할까요? 예를 들어 신규 프로젝트를 시작하는 팀이라면 처음부터 Java 17과 Spring Boot 3로 시작하는 것이 좋습니다.

반면 레거시 프로젝트를 유지보수하는 팀이라면 별도 브랜치나 새 저장소를 만들어 실험적으로 Spring AI를 도입해볼 수 있습니다. 많은 스타트업에서 이런 방식으로 점진적으로 기술 스택을 업그레이드하고 있습니다.

IDE 설정도 중요합니다. IntelliJ IDEA를 사용한다면 Settings에서 Project SDK를 Java 17로 설정해야 합니다.

Eclipse를 사용한다면 Installed JREs에 Java 17을 추가하고 프로젝트 속성에서 선택해야 합니다. VSCode를 사용한다면 Extension Pack for Java를 설치하고 java.configuration.runtimes에서 Java 17 경로를 지정해야 합니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 시스템에 여러 Java 버전이 설치되어 있을 때 JAVA_HOME 환경 변수를 제대로 설정하지 않는 것입니다.

IDE에서는 Java 17을 사용하는데 터미널에서는 Java 8이 실행되는 경우가 있습니다. 따라서 환경 변수를 정확히 설정하고 터미널을 재시작해야 합니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 도움으로 김개발 씨는 Java 17과 Spring Boot 3 환경을 무사히 준비했습니다.

"생각보다 어렵지 않네요!" 환경 설정을 제대로 하면 나중에 발생할 수 있는 버전 충돌 문제를 예방할 수 있습니다. 여러분도 오늘 배운 내용을 바탕으로 개발 환경을 정비해 보세요.

실전 팁

💡 - SDKMAN을 사용하면 여러 Java 버전을 쉽게 관리할 수 있습니다

Spring Initializr에서 프로젝트를 생성하면 자동으로 최신 버전이 설정됩니다

4. 프로젝트 초기 설정

환경 준비가 끝난 김개발 씨는 본격적으로 프로젝트를 만들기로 했습니다. "Spring Boot 프로젝트 생성은 익숙한데, Spring AI는 뭘 추가해야 하죠?" 박시니어 씨가 Spring Initializr 사이트를 열어 보여주기 시작했습니다.

Spring AI 프로젝트는 Spring Initializr를 통해 쉽게 생성할 수 있습니다. 기본적인 Spring Boot 프로젝트 구조에 Spring AI 의존성을 추가하는 방식입니다.

Group, Artifact, Package name을 설정하고, Spring Web과 OpenAI 의존성을 선택하면 기본 프로젝트가 생성됩니다. 생성된 프로젝트는 표준 Maven이나 Gradle 구조를 따르므로 기존 Spring 개발자에게 익숙한 형태입니다.

다음 코드를 살펴봅시다.

// pom.xml (Maven 사용 시)
<dependencies>
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring AI OpenAI -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

김개발 씨는 그동안 수십 개의 Spring Boot 프로젝트를 만들어왔습니다. Spring Initializr는 이제 눈 감고도 사용할 수 있을 정도입니다.

하지만 Spring AI는 처음이라 조금 긴장됩니다. 박시니어 씨가 브라우저에서 start.spring.io를 열었습니다.

"자, 같이 해볼까요?" 그렇다면 Spring AI 프로젝트는 어떻게 생성할까요? 쉽게 비유하자면, Spring Initializr는 마치 레고 블록 세트를 고르는 것과 같습니다.

기본 블록인 Spring Boot에 원하는 기능 블록들을 추가로 선택하면 됩니다. Spring AI도 그런 블록 중 하나입니다.

Web 블록을 선택하면 REST API를 만들 수 있고, OpenAI 블록을 선택하면 AI 기능을 사용할 수 있습니다. Spring Initializr에서는 어떤 옵션을 선택해야 할까요?

먼저 Project는 Maven이나 Gradle 중 하나를 선택합니다. 회사 표준을 따르거나 개인 선호에 따라 정하면 됩니다.

다음으로 Language는 Java를 선택합니다. Kotlin이나 Groovy도 가능하지만 이 가이드에서는 Java를 기준으로 설명합니다.

Spring Boot 버전은 3.2.x 이상을 선택해야 합니다. Dependencies 섹션이 가장 중요합니다.

검색창에 "web"을 입력하면 Spring Web이 나타납니다. 이것을 선택하면 REST API를 만들 수 있습니다.

다음으로 "openai"를 검색하면 OpenAI가 나타납니다. 이것이 바로 Spring AI의 OpenAI 통합 모듈입니다.

이 두 가지를 선택한 후 Generate 버튼을 누르면 ZIP 파일이 다운로드됩니다. 다운로드한 ZIP 파일을 어떻게 사용할까요?

압축을 풀면 표준적인 Spring Boot 프로젝트 구조가 나타납니다. src/main/java에는 메인 애플리케이션 클래스가 있고, src/main/resources에는 application.properties 파일이 있습니다.

pom.xml이나 build.gradle 파일을 열어보면 앞서 선택한 의존성들이 자동으로 추가되어 있습니다. 위의 코드를 살펴보겠습니다.

spring-boot-starter-web은 우리가 잘 아는 의존성입니다. 내장 톰캣과 Spring MVC가 포함되어 있어 REST API를 만들 수 있습니다.

중요한 것은 spring-ai-openai-spring-boot-starter입니다. 이 스타터가 OpenAI API를 호출하는 모든 기능을 제공합니다.

자동 설정 덕분에 별도 Bean 등록 없이 바로 ChatClient를 주입받아 사용할 수 있습니다. 실제 현업에서는 어떻게 프로젝트를 구성할까요?

대부분의 회사는 사내 표준 프로젝트 템플릿을 가지고 있습니다. 로깅, 보안, 공통 예외 처리 같은 기본 설정이 미리 되어 있는 템플릿입니다.

이런 경우에는 템플릿을 복사한 후 pom.xml이나 build.gradle에 Spring AI 의존성만 추가하면 됩니다. 새로운 프로젝트라면 Spring Initializr로 시작하는 것이 더 편리합니다.

프로젝트 구조는 어떻게 잡을까요? 일반적으로 controller, service, repository 패키지로 나누는 레이어드 아키텍처를 사용합니다.

AI 기능은 service 계층에 위치시키는 것이 자연스럽습니다. 예를 들어 AiService 클래스를 만들어 ChatClient를 주입받고, 비즈니스 로직에서 필요할 때 AI 기능을 호출하는 식입니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 Spring AI 의존성을 추가할 때 버전을 명시적으로 지정하는 것입니다.

Spring Boot의 의존성 관리 기능을 사용하면 자동으로 호환되는 버전이 선택되므로 수동으로 버전을 지정할 필요가 없습니다. 오히려 잘못된 버전을 지정하면 충돌이 발생할 수 있습니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 김개발 씨는 박시니어 씨의 안내에 따라 프로젝트를 성공적으로 생성했습니다.

IntelliJ IDEA로 열어보니 익숙한 구조가 반겼습니다. "이제 코드를 짜면 되는 거죠?" 프로젝트 초기 설정을 제대로 하면 나중에 의존성 문제로 고생할 일이 없습니다.

여러분도 오늘 배운 내용을 바탕으로 첫 Spring AI 프로젝트를 만들어 보세요.

실전 팁

💡 - Spring Initializr CLI를 사용하면 터미널에서도 프로젝트를 생성할 수 있습니다

Lombok, DevTools 같은 개발 편의 도구도 함께 추가하면 좋습니다

5. 의존성 구성 및 API 키 설정

프로젝트를 열어본 김개발 씨는 또 하나의 의문이 생겼습니다. "OpenAI API 키는 어디에 넣어야 하죠?

혹시 코드에 하드코딩하면 안 되겠죠?" 박시니어 씨가 고개를 끄덕였습니다. "당연하죠.

application.properties에 설정하는 겁니다."

Spring AI는 application.properties 또는 application.yml 파일에서 API 키와 모델 설정을 관리합니다. OpenAI API 키는 spring.ai.openai.api-key 속성으로 설정하고, 사용할 모델은 spring.ai.openai.chat.options.model로 지정합니다.

민감한 정보인 API 키는 환경 변수나 외부 설정 파일로 관리해야 하며, 절대 코드에 하드코딩하거나 Git에 커밋하면 안 됩니다.

다음 코드를 살펴봅시다.

# src/main/resources/application.properties

# OpenAI API 키 설정 (환경 변수 사용 권장)
spring.ai.openai.api-key=${OPENAI_API_KEY}

# 사용할 모델 지정 (기본값: gpt-3.5-turbo)
spring.ai.openai.chat.options.model=gpt-4

# 응답 온도 설정 (0.0 ~ 2.0, 낮을수록 일관적)
spring.ai.openai.chat.options.temperature=0.7

# 최대 토큰 수 제한
spring.ai.openai.chat.options.max-tokens=1000

# 애플리케이션 기본 설정
server.port=8080

김개발 씨는 예전에 AWS Access Key를 실수로 GitHub에 올렸다가 큰일 날 뻔한 적이 있습니다. 다행히 박시니어 씨가 발견해서 즉시 삭제했지만, 그날의 식은땀을 아직도 기억합니다.

박시니어 씨가 조언했습니다. "API 키는 돈이에요.

절대 코드에 넣으면 안 됩니다." 그렇다면 API 키는 어떻게 관리해야 할까요? 쉽게 비유하자면, API 키는 은행 비밀번호와 같습니다.

비밀번호를 수첩에 적어두지 않듯이, API 키도 코드에 직접 적으면 안 됩니다. Spring Boot는 이런 문제를 해결하기 위해 외부 설정 기능을 제공합니다.

application.properties에 플레이스홀더를 사용하고, 실제 값은 환경 변수나 외부 파일로 주입하는 방식입니다. OpenAI API 키는 어디서 받을 수 있을까요?

OpenAI 웹사이트에 가입한 후 API Keys 페이지에서 새로운 키를 생성할 수 있습니다. 생성된 키는 "sk-"로 시작하는 긴 문자열입니다.

이 키는 한 번만 표시되므로 안전한 곳에 복사해두어야 합니다. 키를 분실하면 재발급받아야 하고, 노출되면 즉시 폐기하고 새로 만들어야 합니다.

API 키를 받았다면 어떻게 설정할까요? 가장 안전한 방법은 운영체제 환경 변수로 설정하는 것입니다.

Windows에서는 시스템 환경 변수 설정에서 OPENAI_API_KEY를 추가하고, macOS나 Linux에서는 ~/.bashrc나 ~/.zshrc 파일에 export OPENAI_API_KEY=your-key-here를 추가합니다. 그러면 application.properties의 ${OPENAI_API_KEY}가 자동으로 치환됩니다.

개발 환경에서는 어떻게 관리할까요? IntelliJ IDEA를 사용한다면 Run Configuration에서 Environment Variables를 설정할 수 있습니다.

또는 src/main/resources에 application-local.properties 파일을 만들어 로컬 전용 설정을 넣고, 이 파일은 .gitignore에 추가하는 방법도 있습니다. Spring Profile 기능을 활용하면 개발, 테스트, 운영 환경별로 다른 설정을 사용할 수 있습니다.

위의 코드를 하나씩 살펴보겠습니다. spring.ai.openai.api-key 속성은 OpenAI API 인증에 사용됩니다.

${OPENAI_API_KEY} 문법은 환경 변수에서 값을 읽어옵니다. 다음으로 spring.ai.openai.chat.options.model은 사용할 AI 모델을 지정합니다.

gpt-4는 더 똑똑하지만 비용이 높고, gpt-3.5-turbo는 빠르고 저렴합니다. temperature는 응답의 창의성을 조절하는 값으로, 0에 가까우면 일관적이고 2에 가까우면 창의적입니다.

실제 현업에서는 어떻게 관리할까요? 많은 회사에서 AWS Secrets Manager, HashiCorp Vault 같은 비밀 관리 도구를 사용합니다.

Spring Cloud Config를 사용하면 중앙 설정 서버에서 API 키를 관리할 수도 있습니다. 쿠버네티스 환경이라면 Secret 리소스를 활용합니다.

중요한 것은 API 키가 절대 소스 코드 저장소에 들어가지 않도록 하는 것입니다. 모델 선택은 어떻게 해야 할까요?

간단한 질의응답에는 gpt-3.5-turbo로 충분합니다. 복잡한 추론이나 긴 맥락 이해가 필요하면 gpt-4를 사용합니다.

최신 모델인 gpt-4-turbo는 속도와 성능의 균형이 좋습니다. 비용을 고려해서 개발 환경에서는 저렴한 모델을 사용하고, 운영 환경에서만 고급 모델을 사용하는 전략도 있습니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 application.properties에 API 키를 직접 적어두고 Git에 커밋하는 것입니다.

한번 커밋된 정보는 Git 히스토리에 영원히 남기 때문에, 나중에 파일을 삭제해도 과거 커밋에서 여전히 확인할 수 있습니다. 따라서 처음부터 환경 변수나 외부 파일을 사용하는 습관을 들여야 합니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 김개발 씨는 박시니어 씨의 조언대로 환경 변수로 API 키를 설정했습니다.

"이제 안전하게 개발할 수 있겠네요!" API 키 관리를 제대로 하면 보안 사고를 예방하고 비용도 통제할 수 있습니다. 여러분도 오늘 배운 내용을 바탕으로 안전한 설정 방법을 익혀 보세요.

실전 팁

💡 - OpenAI API 사용량은 Usage 페이지에서 실시간으로 확인할 수 있습니다

API 키에 사용 한도를 설정해두면 예상치 못한 비용을 방지할 수 있습니다

6. 첫 번째 Spring AI 애플리케이션 실행

드디어 모든 준비가 끝났습니다. 김개발 씨는 떨리는 마음으로 첫 번째 AI 컨트롤러를 작성하기 시작했습니다.

"정말 이렇게 간단하게 ChatGPT와 연동이 될까요?" 박시니어 씨가 웃으며 대답했습니다. "직접 실행해보면 알 수 있어요."

첫 번째 Spring AI 애플리케이션은 간단한 REST API 엔드포인트를 만들어 AI와 대화하는 것부터 시작합니다. @RestController로 컨트롤러를 만들고, ChatClient를 주입받아 사용자 메시지를 AI에게 전달하고 응답을 받습니다.

애플리케이션을 실행한 후 브라우저나 Postman으로 API를 호출하면 실시간으로 AI 응답을 확인할 수 있습니다. 단 몇 줄의 코드로 강력한 AI 기능을 구현할 수 있습니다.

다음 코드를 살펴봅시다.

package com.example.springai;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AiController {

    private final ChatClient chatClient;

    // ChatClient를 의존성 주입받습니다
    public AiController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    // /ai/chat?message=안녕하세요 형식으로 호출합니다
    @GetMapping("/ai/chat")
    public String chat(@RequestParam String message) {
        // AI에게 메시지를 보내고 응답을 받습니다
        return chatClient.prompt()
            .user(message)
            .call()
            .content();
    }
}

김개발 씨는 손을 떨며 키보드를 두드리기 시작했습니다. 코드는 생각보다 짧습니다.

일반적인 Spring MVC 컨트롤러와 거의 같습니다. 정말 이것만으로 ChatGPT와 연동이 될까요?

박시니어 씨가 옆에서 지켜봅니다. "자, 이제 실행해보세요." 그렇다면 이 코드는 어떻게 동작하는 걸까요?

쉽게 비유하자면, ChatClient는 마치 RestTemplate과 같은 역할을 합니다. RestTemplate이 외부 REST API를 호출하듯이, ChatClient는 OpenAI API를 호출합니다.

차이점은 RestTemplate은 개발자가 직접 URL, 헤더, 바디를 구성해야 하지만, ChatClient는 Spring AI가 모든 것을 자동으로 처리해준다는 점입니다. 컨트롤러 코드를 자세히 살펴볼까요?

@RestController 어노테이션은 우리가 잘 아는 것입니다. 이 클래스가 REST API를 제공한다는 표시입니다.

생성자에서 ChatClient.Builder를 주입받는 부분이 핵심입니다. Spring AI가 자동 설정으로 이 Builder를 Bean으로 등록해주기 때문에 별도 설정 없이 바로 사용할 수 있습니다.

chat() 메서드는 어떻게 작동할까요? @GetMapping 어노테이션으로 /ai/chat 경로를 매핑합니다.

@RequestParam으로 사용자가 보낸 메시지를 받습니다. 그리고 chatClient.prompt().user(message).call().content() 체인을 통해 AI 응답을 받습니다.

이 한 줄이 내부적으로는 HTTP 요청 생성, JSON 직렬화, OpenAI API 호출, 응답 파싱, 에러 처리를 모두 수행합니다. 이제 애플리케이션을 실행해봅시다.

IDE에서 메인 클래스의 main() 메서드를 실행하거나, 터미널에서 mvn spring-boot:run 또는 gradle bootRun을 실행합니다. 콘솔에 "Started Application in X seconds"라는 메시지가 나타나면 성공입니다.

기본적으로 8080 포트에서 실행됩니다. 어떻게 테스트할 수 있을까요?

가장 간단한 방법은 브라우저를 여는 것입니다. 주소창에 http://localhost:8080/ai/chat?message=안녕하세요를 입력하고 엔터를 누르면 AI의 응답이 화면에 나타납니다.

"안녕하세요! 무엇을 도와드릴까요?" 같은 답변을 볼 수 있습니다.

이것이 바로 ChatGPT와의 첫 대화입니다. 더 전문적으로 테스트하려면 어떻게 할까요?

Postman이나 IntelliJ IDEA의 HTTP Client를 사용할 수 있습니다. curl 명령어로도 가능합니다.

예를 들어 터미널에서 curl "http://localhost:8080/ai/chat?message=Spring AI란 무엇인가요?"를 실행하면 AI가 Spring AI에 대해 설명해줍니다. 실시간으로 응답이 생성되는 것을 확인할 수 있습니다.

실제 현업에서는 어떻게 확장할까요? 이 기본 예제를 출발점으로 다양한 기능을 추가할 수 있습니다.

예를 들어 대화 히스토리를 저장하려면 세션이나 데이터베이스를 활용합니다. 스트리밍 응답을 구현하려면 Server-Sent Events를 사용합니다.

사용자별로 다른 프롬프트를 적용하려면 프롬프트 템플릿을 활용합니다. 많은 기업에서 이런 기본 패턴을 확장해 고객 상담, 콘텐츠 생성, 코드 리뷰 자동화 등 다양한 서비스를 만들고 있습니다.

응답 시간은 어느 정도일까요? OpenAI API는 인터넷을 통해 호출되므로 보통 1-3초 정도 걸립니다.

네트워크 상태와 OpenAI 서버 부하에 따라 달라질 수 있습니다. 긴 응답일수록 시간이 더 걸립니다.

프로덕션 환경에서는 타임아웃 설정과 재시도 로직을 추가하는 것이 좋습니다. 비용은 얼마나 들까요?

OpenAI API는 사용한 만큼 과금됩니다. 토큰 단위로 계산되는데, 대략 1,000개의 영어 단어가 1,300개 정도의 토큰입니다.

gpt-3.5-turbo는 매우 저렴해서 테스트 용도로는 큰 부담이 없습니다. gpt-4는 더 비싸므로 필요한 경우에만 사용하는 것이 좋습니다.

OpenAI 대시보드에서 실시간으로 사용량을 모니터링할 수 있습니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 API 호출 실패 시 예외 처리를 하지 않는 것입니다. 네트워크 오류, API 키 문제, 할당량 초과 등 다양한 이유로 호출이 실패할 수 있습니다.

따라서 try-catch 블록이나 @ControllerAdvice를 사용해 적절한 에러 응답을 반환해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다.

김개발 씨는 브라우저에서 AI 응답을 보고 감탄했습니다. "와, 정말 되네요!

생각보다 훨씬 간단한데요?" 첫 번째 애플리케이션을 성공적으로 실행하면 Spring AI의 가능성을 직접 확인할 수 있습니다. 여러분도 오늘 배운 내용을 바탕으로 첫 AI 통합 애플리케이션을 만들어 보세요.

실전 팁

💡 - 응답이 느리면 temperature를 낮춰보세요. 더 빠르게 응답합니다

로그 레벨을 DEBUG로 설정하면 실제 API 요청/응답을 확인할 수 있습니다

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!

#Spring#SpringAI#OpenAI#ChatGPT#Backend#Spring,AI,Backend

Spring AI 완벽 가이드 환경 설정부터 첫 실행까지

# Spring AI 완벽 가이드 환경 설정부터 첫 실행까지 인공지능을 Spring 애플리케이션에 통합하는 새로운 프레임워크 Spring AI를 소개합니다. Java 개발자를 위한 친절한 환경 설정 가이드부터 첫 번째 AI 애플리케이션 실행까지, 점프 투 자바 스타일로 술술 읽히는 입문서입니다. --- ## 목차 1. [Spring AI란 무엇인가](#spring-ai란-무엇인가) 2. [Spring AI의 주요 특징과 장점](#spring-ai의-주요-특징과-장점) 3. [개발 환경 설정](#개발-환경-설정) 4. [프로젝트 초기 설정](#프로젝트-초기-설정) 5. [의존성 구성 및 API 키 설정](#의존성-구성-및-api-키-설정) 6. [첫 번째 Spring AI 애플리케이션 실행](#첫-번째-spring-ai-애플리케이션-실행) --- ## 1. Spring AI란 무엇인가 2024년 어느 날, 김개발 씨는 회사에서 흥미로운 프로젝트를 맡게 되었습니다. "우리 서비스에 ChatGPT를 연동해보세요." 팀장님의 말씀에 김개발 씨는 막막했습니다. Python으로는 AI 연동이 쉽다는데, Spring으로는 어떻게 해야 할까요? **Spring AI**는 Spring 생태계에서 인공지능 기능을 쉽게 사용할 수 있도록 만든 공식 프레임워크입니다. 마치 Spring Data JPA가 데이터베이스 접근을 쉽게 만들어주듯이, Spring AI는 OpenAI, Azure OpenAI 같은 AI 서비스를 Spring 방식으로 연동할 수 있게 해줍니다. Java 개발자에게 익숙한 Spring의 철학과 패턴을 그대로 사용하면서 AI 기능을 활용할 수 있습니다. 다음 코드를 살펴봅시다. ```java // Spring AI의 기본 개념을 보여주는 간단한 예제 @RestController public class AiController { private final ChatClient chatClient; // Spring AI의 ChatClient를 주입받습니다 public AiController(ChatClient.Builder builder) { this.chatClient = builder.build(); } @GetMapping("/ai/chat") public String chat(@RequestParam String message) { // 마치 RestTemplate처럼 간단하게 AI와 대화합니다 return chatClient.prompt() .user(message) .call() .content(); } } ``` 김개발 씨는 입사 1년 차 백엔드 개발자입니다. Spring Boot로 REST API를 만드는 일에는 이제 제법 익숙해졌습니다. 그런데 요즘 회사에서 자꾸 AI 프로젝트 이야기가 나옵니다. 회의 시간에 팀장님이 말씀하셨습니다. "우리 고객 상담 시스템에 ChatGPT를 붙여봅시다. 김개발 씨가 한번 알아보세요." 김개발 씨는 당황했습니다. Python이라면 LangChain 같은 라이브러리가 있다는데, Spring에서는 어떻게 해야 할까요? 그렇다면 Spring AI란 정확히 무엇일까요? 쉽게 비유하자면, Spring AI는 마치 Spring Data JPA와 같은 역할을 합니다. Spring Data JPA가 복잡한 데이터베이스 작업을 Spring 방식으로 단순화해주듯이, Spring AI는 복잡한 AI 모델 연동을 Spring 방식으로 단순하게 만들어줍니다. 직접 OpenAI API를 호출하고 JSON을 파싱하는 대신, Spring의 의존성 주입과 자동 설정 기능을 활용할 수 있습니다. Spring AI가 없던 시절에는 어땠을까요? 개발자들은 OpenAI API를 호출하기 위해 RestTemplate이나 WebClient를 직접 설정해야 했습니다. 요청 본문을 JSON으로 만들고, 응답을 파싱하고, 예외 처리를 하고, API 키를 관리하는 모든 과정을 직접 구현했습니다. 더 큰 문제는 AI 모델마다 API 형식이 달라서 OpenAI에서 Azure OpenAI로 변경하려면 코드를 대폭 수정해야 했다는 점입니다. 바로 이런 문제를 해결하기 위해 Spring AI가 등장했습니다. Spring AI를 사용하면 **통일된 인터페이스**로 다양한 AI 모델을 사용할 수 있습니다. 또한 **Spring Boot의 자동 설정** 기능으로 복잡한 초기 설정을 최소화할 수 있습니다. 무엇보다 **Spring의 철학을 그대로 따르기 때문에** 기존 Spring 개발자라면 익숙하게 사용할 수 있다는 큰 이점이 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다. 먼저 생성자에서 ChatClient.Builder를 주입받는 부분을 보면 전형적인 Spring 방식임을 알 수 있습니다. 이 부분이 핵심입니다. Spring AI가 자동으로 설정한 Builder를 주입해주기 때문에 개발자는 별도 설정 없이 바로 사용할 수 있습니다. 다음으로 prompt() 메서드에서는 AI에게 보낼 메시지를 구성합니다. 마지막으로 call().content()를 통해 AI의 응답을 문자열로 받아옵니다. 실제 현업에서는 어떻게 활용할까요? 예를 들어 온라인 쇼핑몰의 고객 상담 서비스를 개발한다고 가정해봅시다. 고객이 "배송은 언제 되나요?"라고 물으면 주문 정보를 조회하고, AI에게 상황을 설명하고, 자연스러운 답변을 생성하는 시나리오에서 Spring AI를 활용하면 기존 Spring 코드와 매끄럽게 통합할 수 있습니다. 네이버, 카카오 같은 많은 기업에서 이런 패턴을 적극적으로 도입하고 있습니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 Spring AI를 단순한 HTTP 클라이언트로만 생각하는 것입니다. 이렇게 하면 Spring AI가 제공하는 프롬프트 템플릿, 출력 파싱, 벡터 스토어 같은 강력한 기능을 놓칠 수 있습니다. 따라서 공식 문서를 꼼꼼히 읽어보고 Spring AI의 전체 기능을 이해한 후 사용해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 선배 개발자 박시니어 씨가 Spring AI를 소개해주었습니다. "Python 부럽지 않죠? 우리도 Spring 방식으로 AI를 쓸 수 있어요." Spring AI를 제대로 이해하면 기존 Spring 지식을 활용해 빠르게 AI 기능을 개발할 수 있습니다. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요. **실전 팁** 💡 - Spring AI는 2023년 공식 릴리스된 비교적 새로운 프로젝트입니다 - OpenAI뿐만 아니라 Azure OpenAI, HuggingFace, Ollama 등 다양한 모델을 지원합니다 --- ## 2. Spring AI의 주요 특징과 장점 Spring AI 문서를 읽던 김개발 씨는 궁금해졌습니다. "그냥 RestTemplate로 OpenAI API 호출하면 안 되나? 굳이 새로운 라이브러리를 배워야 할까?" 마침 옆을 지나던 박시니어 씨가 웃으며 말했습니다. "그렇게 생각했다가는 나중에 후회할걸요?" Spring AI는 단순한 API 래퍼가 아닙니다. **통일된 추상화 계층**으로 여러 AI 모델을 일관되게 사용하고, **프롬프트 템플릿**으로 동적인 메시지를 생성하며, **구조화된 출력**으로 AI 응답을 자바 객체로 자동 변환합니다. 또한 **벡터 스토어 통합**으로 RAG 패턴을 쉽게 구현할 수 있어, AI 애플리케이션 개발의 모든 복잡성을 Spring 방식으로 해결해줍니다. 다음 코드를 살펴봅시다. ```java @Service public class ProductRecommendationService { private final ChatClient chatClient; public ProductRecommendationService(ChatClient.Builder builder) { this.chatClient = builder.build(); } // AI 응답을 자바 객체로 자동 변환합니다 public ProductList recommendProducts(String userPreference) { return chatClient.prompt() .user(u -> u.text("사용자 취향: {preference}에 맞는 상품 5개 추천") .param("preference", userPreference)) .call() .entity(ProductList.class); // JSON을 자바 객체로 자동 변환 } } ``` 박시니어 씨가 김개발 씨 옆에 앉았습니다. "제가 지난달에 직접 OpenAI API를 호출하는 코드를 짰었어요. 한 100줄쯤 됐는데, Spring AI로 다시 짜니까 20줄로 줄어들더라고요." 김개발 씨는 반신반의했습니다. 정말 그렇게 큰 차이가 있을까요? 박시니어 씨는 노트북을 열어 직접 보여주기 시작했습니다. 그렇다면 Spring AI의 주요 특징은 정확히 무엇일까요? 첫 번째 특징은 **포터블 API 추상화**입니다. 쉽게 비유하자면, JDBC가 데이터베이스마다 다른 드라이버를 통일된 인터페이스로 제공하듯이, Spring AI는 OpenAI, Azure OpenAI, Anthropic Claude, Google Vertex AI 등을 동일한 인터페이스로 사용할 수 있게 해줍니다. 설정 파일의 한 줄만 바꾸면 다른 AI 모델로 전환할 수 있습니다. 두 번째 특징은 **프롬프트 템플릿**입니다. 마치 Thymeleaf나 JSP가 HTML 템플릿을 제공하듯이, Spring AI는 프롬프트 템플릿을 제공합니다. 변수를 사용해 동적으로 프롬프트를 생성할 수 있어, 같은 패턴의 질문을 반복할 때 코드 중복을 줄일 수 있습니다. 직접 API를 호출하던 시절에는 어땠을까요? 개발자들은 매번 JSON 문자열을 직접 조합해야 했습니다. 사용자 입력을 프롬프트에 삽입할 때 이스케이프 처리를 잊어서 JSON 파싱 에러가 나기도 했습니다. 더 큰 문제는 AI 모델의 응답이 항상 JSON 문자열이기 때문에 이를 자바 객체로 변환하는 코드를 매번 작성해야 했다는 점입니다. Jackson 라이브러리로 파싱하고, 예외 처리하고, null 체크하는 보일러플레이트 코드가 끝없이 반복되었습니다. 바로 이런 문제를 해결하기 위해 Spring AI의 고급 기능들이 등장했습니다. Spring AI를 사용하면 **구조화된 출력**이 가능해집니다. entity() 메서드에 자바 클래스를 지정하면 AI 응답을 자동으로 객체로 변환해줍니다. 또한 **함수 호출**도 지원해서 AI가 필요할 때 자바 메서드를 호출하도록 설정할 수 있습니다. 무엇보다 **벡터 스토어 통합**으로 RAG 패턴을 손쉽게 구현할 수 있다는 큰 이점이 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다. 먼저 user() 메서드 안에서 text()와 param()을 사용하는 부분을 보면 전형적인 템플릿 패턴임을 알 수 있습니다. 중괄호 안의 preference는 플레이스홀더이고, param()으로 실제 값을 바인딩합니다. 다음으로 entity(ProductList.class) 부분에서는 AI의 JSON 응답을 자동으로 ProductList 객체로 변환합니다. Jackson을 사용한 수동 파싱이 필요 없습니다. 실제 현업에서는 어떻게 활용할까요? 예를 들어 이커머스 추천 시스템을 개발한다고 가정해봅시다. 사용자의 검색 이력, 구매 이력, 관심사를 분석해서 맞춤 상품을 추천하는 시나리오에서 Spring AI의 프롬프트 템플릿을 활용하면 다양한 상황에 맞는 프롬프트를 재사용 가능한 형태로 관리할 수 있습니다. 쿠팡, 무신사 같은 기업에서 이런 패턴을 실제로 활용하고 있습니다. 또한 **RAG 패턴**을 구현할 때 Spring AI의 진가가 드러납니다. RAG는 Retrieval-Augmented Generation의 약자로, 벡터 데이터베이스에서 관련 문서를 검색한 후 그 내용을 프롬프트에 포함시켜 더 정확한 답변을 생성하는 기법입니다. Spring AI는 Redis, Pinecone, Chroma 같은 벡터 스토어를 기본 지원하므로 복잡한 RAG 파이프라인을 Spring 방식으로 구성할 수 있습니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 모든 응답을 entity()로 변환하려고 시도하는 것입니다. 이렇게 하면 AI가 원하는 형식으로 응답하지 않았을 때 파싱 에러가 발생할 수 있습니다. 따라서 단순한 텍스트 응답이 필요한 경우에는 content()를 사용하고, 구조화된 데이터가 필요한 경우에만 entity()를 사용하는 것이 올바른 방법입니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 코드를 본 김개발 씨는 감탄했습니다. "와, 이렇게 간단하게 되는구나!" Spring AI의 특징을 제대로 이해하면 AI 통합 코드를 훨씬 깔끔하게 작성할 수 있습니다. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요. **실전 팁** 💡 - entity()로 변환할 클래스는 record나 일반 POJO 모두 사용 가능합니다 - 프롬프트 템플릿은 외부 파일로 관리하면 유지보수가 편리합니다 --- ## 3. 개발 환경 설정 "그럼 저도 한번 해볼까요?" 김개발 씨는 신이 나서 자신의 노트북을 열었습니다. 그런데 막상 시작하려니 막막했습니다. "Java 버전은 얼마가 필요하죠? Spring Boot는요?" 박시니어 씨가 친절하게 설명해주기 시작했습니다. Spring AI를 사용하려면 **Java 17 이상**과 **Spring Boot 3.0 이상**이 필수입니다. Spring Boot 3는 Java 17을 최소 요구사항으로 하기 때문에 이전 버전을 사용 중이라면 먼저 업그레이드해야 합니다. 또한 빌드 도구로는 **Maven 3.6+** 또는 **Gradle 7.5+**를 권장하며, IDE는 IntelliJ IDEA나 Eclipse 최신 버전을 사용하면 개발 경험이 더 좋습니다. 다음 코드를 살펴봅시다. ```java // Java 버전 확인 // 터미널에서 실행 java -version // 출력 예시: openjdk version "17.0.9" 2023-10-17 // build.gradle (Gradle 사용 시) plugins { id 'java' id 'org.springframework.boot' version '3.2.1' id 'io.spring.dependency-management' version '1.1.4' } java { sourceCompatibility = '17' targetCompatibility = '17' } ``` 김개발 씨는 현재 회사 프로젝트에서 Java 11을 사용하고 있습니다. Spring Boot 버전은 2.7입니다. 그런데 Spring AI를 쓰려면 업그레이드가 필요하다니, 걱정이 앞섭니다. 박시니어 씨가 안심시켰습니다. "개인 프로젝트로 먼저 연습해보세요. 회사 프로젝트는 나중에 차근차근 업그레이드하면 됩니다." 그렇다면 정확히 어떤 환경이 필요한 걸까요? 쉽게 비유하자면, Spring AI는 최신 자동차입니다. 최신 자동차를 운전하려면 최신 면허증과 도로가 필요하듯이, Spring AI를 실행하려면 Java 17이라는 최신 런타임과 Spring Boot 3라는 최신 프레임워크가 필요합니다. 이전 버전에서는 작동하지 않습니다. 왜 Java 17이 필수일까요? Spring Boot 3는 Jakarta EE 9를 기반으로 재작성되었습니다. 기존 javax 패키지가 jakarta로 변경되면서 많은 내부 구조가 바뀌었습니다. Java 17은 이런 변화를 지원하는 첫 번째 LTS 버전입니다. 또한 Java 17에는 레코드, sealed 클래스, 패턴 매칭 같은 유용한 기능이 추가되어 Spring AI 코드를 더 간결하게 작성할 수 있습니다. 예전 Java 8이나 11 환경에서는 어땠을까요? 물론 Java 8이나 11도 훌륭한 버전입니다. 많은 레거시 프로젝트가 아직도 이 버전을 사용하고 있습니다. 하지만 Spring AI는 최신 기능을 적극 활용하기 때문에 이전 버전을 지원하지 않습니다. 억지로 다운그레이드하려고 시도하면 컴파일 에러와 런타임 에러의 늪에 빠지게 됩니다. 바로 이런 이유로 개발 환경 준비가 중요합니다. 먼저 **Java 17을 설치**해야 합니다. Oracle JDK, OpenJDK, Amazon Corretto, Azul Zulu 등 다양한 배포판 중 하나를 선택하면 됩니다. 요즘은 무료인 OpenJDK를 많이 사용합니다. 다음으로 **빌드 도구를 설정**해야 합니다. Maven을 사용한다면 pom.xml에서 java.version을 17로 설정하고, Gradle을 사용한다면 build.gradle에서 sourceCompatibility를 17로 설정합니다. 위의 코드를 단계별로 살펴보겠습니다. 먼저 터미널에서 java -version을 실행해보면 현재 설치된 Java 버전을 확인할 수 있습니다. 만약 17 미만이라면 새로 설치해야 합니다. 다음으로 build.gradle의 plugins 블록을 보면 Spring Boot 3.2.1 버전을 사용하는 것을 알 수 있습니다. 마지막으로 java 블록에서 sourceCompatibility와 targetCompatibility를 17로 설정하면 Java 17 문법을 사용할 수 있습니다. 실제 현업에서는 어떻게 준비할까요? 예를 들어 신규 프로젝트를 시작하는 팀이라면 처음부터 Java 17과 Spring Boot 3로 시작하는 것이 좋습니다. 반면 레거시 프로젝트를 유지보수하는 팀이라면 별도 브랜치나 새 저장소를 만들어 실험적으로 Spring AI를 도입해볼 수 있습니다. 많은 스타트업에서 이런 방식으로 점진적으로 기술 스택을 업그레이드하고 있습니다. IDE 설정도 중요합니다. IntelliJ IDEA를 사용한다면 Settings에서 Project SDK를 Java 17로 설정해야 합니다. Eclipse를 사용한다면 Installed JREs에 Java 17을 추가하고 프로젝트 속성에서 선택해야 합니다. VSCode를 사용한다면 Extension Pack for Java를 설치하고 java.configuration.runtimes에서 Java 17 경로를 지정해야 합니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 시스템에 여러 Java 버전이 설치되어 있을 때 JAVA_HOME 환경 변수를 제대로 설정하지 않는 것입니다. IDE에서는 Java 17을 사용하는데 터미널에서는 Java 8이 실행되는 경우가 있습니다. 따라서 환경 변수를 정확히 설정하고 터미널을 재시작해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 도움으로 김개발 씨는 Java 17과 Spring Boot 3 환경을 무사히 준비했습니다. "생각보다 어렵지 않네요!" 환경 설정을 제대로 하면 나중에 발생할 수 있는 버전 충돌 문제를 예방할 수 있습니다. 여러분도 오늘 배운 내용을 바탕으로 개발 환경을 정비해 보세요. **실전 팁** 💡 - SDKMAN을 사용하면 여러 Java 버전을 쉽게 관리할 수 있습니다 - Spring Initializr에서 프로젝트를 생성하면 자동으로 최신 버전이 설정됩니다 --- ## 4. 프로젝트 초기 설정 환경 준비가 끝난 김개발 씨는 본격적으로 프로젝트를 만들기로 했습니다. "Spring Boot 프로젝트 생성은 익숙한데, Spring AI는 뭘 추가해야 하죠?" 박시니어 씨가 Spring Initializr 사이트를 열어 보여주기 시작했습니다. Spring AI 프로젝트는 **Spring Initializr**를 통해 쉽게 생성할 수 있습니다. 기본적인 Spring Boot 프로젝트 구조에 Spring AI 의존성을 추가하는 방식입니다. Group, Artifact, Package name을 설정하고, **Spring Web**과 **OpenAI** 의존성을 선택하면 기본 프로젝트가 생성됩니다. 생성된 프로젝트는 표준 Maven이나 Gradle 구조를 따르므로 기존 Spring 개발자에게 익숙한 형태입니다. 다음 코드를 살펴봅시다. ```java // pom.xml (Maven 사용 시) org.springframework.boot spring-boot-starter-web org.springframework.ai spring-ai-openai-spring-boot-starter ``` 김개발 씨는 그동안 수십 개의 Spring Boot 프로젝트를 만들어왔습니다. Spring Initializr는 이제 눈 감고도 사용할 수 있을 정도입니다. 하지만 Spring AI는 처음이라 조금 긴장됩니다. 박시니어 씨가 브라우저에서 start.spring.io를 열었습니다. "자, 같이 해볼까요?" 그렇다면 Spring AI 프로젝트는 어떻게 생성할까요? 쉽게 비유하자면, Spring Initializr는 마치 레고 블록 세트를 고르는 것과 같습니다. 기본 블록인 Spring Boot에 원하는 기능 블록들을 추가로 선택하면 됩니다. Spring AI도 그런 블록 중 하나입니다. Web 블록을 선택하면 REST API를 만들 수 있고, OpenAI 블록을 선택하면 AI 기능을 사용할 수 있습니다. Spring Initializr에서는 어떤 옵션을 선택해야 할까요? 먼저 **Project**는 Maven이나 Gradle 중 하나를 선택합니다. 회사 표준을 따르거나 개인 선호에 따라 정하면 됩니다. 다음으로 **Language**는 Java를 선택합니다. Kotlin이나 Groovy도 가능하지만 이 가이드에서는 Java를 기준으로 설명합니다. **Spring Boot** 버전은 3.2.x 이상을 선택해야 합니다. Dependencies 섹션이 가장 중요합니다. 검색창에 "web"을 입력하면 **Spring Web**이 나타납니다. 이것을 선택하면 REST API를 만들 수 있습니다. 다음으로 "openai"를 검색하면 **OpenAI**가 나타납니다. 이것이 바로 Spring AI의 OpenAI 통합 모듈입니다. 이 두 가지를 선택한 후 Generate 버튼을 누르면 ZIP 파일이 다운로드됩니다. 다운로드한 ZIP 파일을 어떻게 사용할까요? 압축을 풀면 표준적인 Spring Boot 프로젝트 구조가 나타납니다. src/main/java에는 메인 애플리케이션 클래스가 있고, src/main/resources에는 application.properties 파일이 있습니다. pom.xml이나 build.gradle 파일을 열어보면 앞서 선택한 의존성들이 자동으로 추가되어 있습니다. 위의 코드를 살펴보겠습니다. spring-boot-starter-web은 우리가 잘 아는 의존성입니다. 내장 톰캣과 Spring MVC가 포함되어 있어 REST API를 만들 수 있습니다. 중요한 것은 spring-ai-openai-spring-boot-starter입니다. 이 스타터가 OpenAI API를 호출하는 모든 기능을 제공합니다. 자동 설정 덕분에 별도 Bean 등록 없이 바로 ChatClient를 주입받아 사용할 수 있습니다. 실제 현업에서는 어떻게 프로젝트를 구성할까요? 대부분의 회사는 사내 표준 프로젝트 템플릿을 가지고 있습니다. 로깅, 보안, 공통 예외 처리 같은 기본 설정이 미리 되어 있는 템플릿입니다. 이런 경우에는 템플릿을 복사한 후 pom.xml이나 build.gradle에 Spring AI 의존성만 추가하면 됩니다. 새로운 프로젝트라면 Spring Initializr로 시작하는 것이 더 편리합니다. 프로젝트 구조는 어떻게 잡을까요? 일반적으로 controller, service, repository 패키지로 나누는 레이어드 아키텍처를 사용합니다. AI 기능은 service 계층에 위치시키는 것이 자연스럽습니다. 예를 들어 AiService 클래스를 만들어 ChatClient를 주입받고, 비즈니스 로직에서 필요할 때 AI 기능을 호출하는 식입니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 Spring AI 의존성을 추가할 때 버전을 명시적으로 지정하는 것입니다. Spring Boot의 의존성 관리 기능을 사용하면 자동으로 호환되는 버전이 선택되므로 수동으로 버전을 지정할 필요가 없습니다. 오히려 잘못된 버전을 지정하면 충돌이 발생할 수 있습니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 김개발 씨는 박시니어 씨의 안내에 따라 프로젝트를 성공적으로 생성했습니다. IntelliJ IDEA로 열어보니 익숙한 구조가 반겼습니다. "이제 코드를 짜면 되는 거죠?" 프로젝트 초기 설정을 제대로 하면 나중에 의존성 문제로 고생할 일이 없습니다. 여러분도 오늘 배운 내용을 바탕으로 첫 Spring AI 프로젝트를 만들어 보세요. **실전 팁** 💡 - Spring Initializr CLI를 사용하면 터미널에서도 프로젝트를 생성할 수 있습니다 - Lombok, DevTools 같은 개발 편의 도구도 함께 추가하면 좋습니다 --- ## 5. 의존성 구성 및 API 키 설정 프로젝트를 열어본 김개발 씨는 또 하나의 의문이 생겼습니다. "OpenAI API 키는 어디에 넣어야 하죠? 혹시 코드에 하드코딩하면 안 되겠죠?" 박시니어 씨가 고개를 끄덕였습니다. "당연하죠. application.properties에 설정하는 겁니다." Spring AI는 **application.properties** 또는 **application.yml** 파일에서 API 키와 모델 설정을 관리합니다. OpenAI API 키는 `spring.ai.openai.api-key` 속성으로 설정하고, 사용할 모델은 `spring.ai.openai.chat.options.model`로 지정합니다. 민감한 정보인 API 키는 환경 변수나 **외부 설정 파일**로 관리해야 하며, 절대 코드에 하드코딩하거나 Git에 커밋하면 안 됩니다. 다음 코드를 살펴봅시다. ```java # src/main/resources/application.properties # OpenAI API 키 설정 (환경 변수 사용 권장) spring.ai.openai.api-key=${OPENAI_API_KEY} # 사용할 모델 지정 (기본값: gpt-3.5-turbo) spring.ai.openai.chat.options.model=gpt-4 # 응답 온도 설정 (0.0 ~ 2.0, 낮을수록 일관적) spring.ai.openai.chat.options.temperature=0.7 # 최대 토큰 수 제한 spring.ai.openai.chat.options.max-tokens=1000 # 애플리케이션 기본 설정 server.port=8080 ``` 김개발 씨는 예전에 AWS Access Key를 실수로 GitHub에 올렸다가 큰일 날 뻔한 적이 있습니다. 다행히 박시니어 씨가 발견해서 즉시 삭제했지만, 그날의 식은땀을 아직도 기억합니다. 박시니어 씨가 조언했습니다. "API 키는 돈이에요. 절대 코드에 넣으면 안 됩니다." 그렇다면 API 키는 어떻게 관리해야 할까요? 쉽게 비유하자면, API 키는 은행 비밀번호와 같습니다. 비밀번호를 수첩에 적어두지 않듯이, API 키도 코드에 직접 적으면 안 됩니다. Spring Boot는 이런 문제를 해결하기 위해 외부 설정 기능을 제공합니다. application.properties에 플레이스홀더를 사용하고, 실제 값은 환경 변수나 외부 파일로 주입하는 방식입니다. OpenAI API 키는 어디서 받을 수 있을까요? OpenAI 웹사이트에 가입한 후 API Keys 페이지에서 새로운 키를 생성할 수 있습니다. 생성된 키는 "sk-"로 시작하는 긴 문자열입니다. 이 키는 한 번만 표시되므로 안전한 곳에 복사해두어야 합니다. 키를 분실하면 재발급받아야 하고, 노출되면 즉시 폐기하고 새로 만들어야 합니다. API 키를 받았다면 어떻게 설정할까요? 가장 안전한 방법은 **운영체제 환경 변수**로 설정하는 것입니다. Windows에서는 시스템 환경 변수 설정에서 OPENAI_API_KEY를 추가하고, macOS나 Linux에서는 ~/.bashrc나 ~/.zshrc 파일에 export OPENAI_API_KEY=your-key-here를 추가합니다. 그러면 application.properties의 ${OPENAI_API_KEY}가 자동으로 치환됩니다. 개발 환경에서는 어떻게 관리할까요? IntelliJ IDEA를 사용한다면 Run Configuration에서 Environment Variables를 설정할 수 있습니다. 또는 src/main/resources에 application-local.properties 파일을 만들어 로컬 전용 설정을 넣고, 이 파일은 .gitignore에 추가하는 방법도 있습니다. Spring Profile 기능을 활용하면 개발, 테스트, 운영 환경별로 다른 설정을 사용할 수 있습니다. 위의 코드를 하나씩 살펴보겠습니다. spring.ai.openai.api-key 속성은 OpenAI API 인증에 사용됩니다. ${OPENAI_API_KEY} 문법은 환경 변수에서 값을 읽어옵니다. 다음으로 spring.ai.openai.chat.options.model은 사용할 AI 모델을 지정합니다. gpt-4는 더 똑똑하지만 비용이 높고, gpt-3.5-turbo는 빠르고 저렴합니다. temperature는 응답의 창의성을 조절하는 값으로, 0에 가까우면 일관적이고 2에 가까우면 창의적입니다. 실제 현업에서는 어떻게 관리할까요? 많은 회사에서 AWS Secrets Manager, HashiCorp Vault 같은 비밀 관리 도구를 사용합니다. Spring Cloud Config를 사용하면 중앙 설정 서버에서 API 키를 관리할 수도 있습니다. 쿠버네티스 환경이라면 Secret 리소스를 활용합니다. 중요한 것은 API 키가 절대 소스 코드 저장소에 들어가지 않도록 하는 것입니다. 모델 선택은 어떻게 해야 할까요? 간단한 질의응답에는 gpt-3.5-turbo로 충분합니다. 복잡한 추론이나 긴 맥락 이해가 필요하면 gpt-4를 사용합니다. 최신 모델인 gpt-4-turbo는 속도와 성능의 균형이 좋습니다. 비용을 고려해서 개발 환경에서는 저렴한 모델을 사용하고, 운영 환경에서만 고급 모델을 사용하는 전략도 있습니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 application.properties에 API 키를 직접 적어두고 Git에 커밋하는 것입니다. 한번 커밋된 정보는 Git 히스토리에 영원히 남기 때문에, 나중에 파일을 삭제해도 과거 커밋에서 여전히 확인할 수 있습니다. 따라서 처음부터 환경 변수나 외부 파일을 사용하는 습관을 들여야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 김개발 씨는 박시니어 씨의 조언대로 환경 변수로 API 키를 설정했습니다. "이제 안전하게 개발할 수 있겠네요!" API 키 관리를 제대로 하면 보안 사고를 예방하고 비용도 통제할 수 있습니다. 여러분도 오늘 배운 내용을 바탕으로 안전한 설정 방법을 익혀 보세요. **실전 팁** 💡 - OpenAI API 사용량은 Usage 페이지에서 실시간으로 확인할 수 있습니다 - API 키에 사용 한도를 설정해두면 예상치 못한 비용을 방지할 수 있습니다 --- ## 6. 첫 번째 Spring AI 애플리케이션 실행 드디어 모든 준비가 끝났습니다. 김개발 씨는 떨리는 마음으로 첫 번째 AI 컨트롤러를 작성하기 시작했습니다. "정말 이렇게 간단하게 ChatGPT와 연동이 될까요?" 박시니어 씨가 웃으며 대답했습니다. "직접 실행해보면 알 수 있어요." 첫 번째 Spring AI 애플리케이션은 간단한 **REST API 엔드포인트**를 만들어 AI와 대화하는 것부터 시작합니다. **@RestController**로 컨트롤러를 만들고, **ChatClient**를 주입받아 사용자 메시지를 AI에게 전달하고 응답을 받습니다. 애플리케이션을 실행한 후 브라우저나 Postman으로 API를 호출하면 실시간으로 AI 응답을 확인할 수 있습니다. 단 몇 줄의 코드로 강력한 AI 기능을 구현할 수 있습니다. 다음 코드를 살펴봅시다. ```java package com.example.springai; import org.springframework.ai.chat.client.ChatClient; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; @RestController public class AiController { private final ChatClient chatClient; // ChatClient를 의존성 주입받습니다 public AiController(ChatClient.Builder builder) { this.chatClient = builder.build(); } // /ai/chat?message=안녕하세요 형식으로 호출합니다 @GetMapping("/ai/chat") public String chat(@RequestParam String message) { // AI에게 메시지를 보내고 응답을 받습니다 return chatClient.prompt() .user(message) .call() .content(); } } ``` 김개발 씨는 손을 떨며 키보드를 두드리기 시작했습니다. 코드는 생각보다 짧습니다. 일반적인 Spring MVC 컨트롤러와 거의 같습니다. 정말 이것만으로 ChatGPT와 연동이 될까요? 박시니어 씨가 옆에서 지켜봅니다. "자, 이제 실행해보세요." 그렇다면 이 코드는 어떻게 동작하는 걸까요? 쉽게 비유하자면, ChatClient는 마치 RestTemplate과 같은 역할을 합니다. RestTemplate이 외부 REST API를 호출하듯이, ChatClient는 OpenAI API를 호출합니다. 차이점은 RestTemplate은 개발자가 직접 URL, 헤더, 바디를 구성해야 하지만, ChatClient는 Spring AI가 모든 것을 자동으로 처리해준다는 점입니다. 컨트롤러 코드를 자세히 살펴볼까요? @RestController 어노테이션은 우리가 잘 아는 것입니다. 이 클래스가 REST API를 제공한다는 표시입니다. 생성자에서 ChatClient.Builder를 주입받는 부분이 핵심입니다. Spring AI가 자동 설정으로 이 Builder를 Bean으로 등록해주기 때문에 별도 설정 없이 바로 사용할 수 있습니다. chat() 메서드는 어떻게 작동할까요? @GetMapping 어노테이션으로 /ai/chat 경로를 매핑합니다. @RequestParam으로 사용자가 보낸 메시지를 받습니다. 그리고 chatClient.prompt().user(message).call().content() 체인을 통해 AI 응답을 받습니다. 이 한 줄이 내부적으로는 HTTP 요청 생성, JSON 직렬화, OpenAI API 호출, 응답 파싱, 에러 처리를 모두 수행합니다. 이제 애플리케이션을 실행해봅시다. IDE에서 메인 클래스의 main() 메서드를 실행하거나, 터미널에서 mvn spring-boot:run 또는 gradle bootRun을 실행합니다. 콘솔에 "Started Application in X seconds"라는 메시지가 나타나면 성공입니다. 기본적으로 8080 포트에서 실행됩니다. 어떻게 테스트할 수 있을까요? 가장 간단한 방법은 브라우저를 여는 것입니다. 주소창에 http://localhost:8080/ai/chat?message=안녕하세요를 입력하고 엔터를 누르면 AI의 응답이 화면에 나타납니다. "안녕하세요! 무엇을 도와드릴까요?" 같은 답변을 볼 수 있습니다. 이것이 바로 ChatGPT와의 첫 대화입니다. 더 전문적으로 테스트하려면 어떻게 할까요? Postman이나 IntelliJ IDEA의 HTTP Client를 사용할 수 있습니다. curl 명령어로도 가능합니다. 예를 들어 터미널에서 `curl "http://localhost:8080/ai/chat?message=Spring AI란 무엇인가요?"`를 실행하면 AI가 Spring AI에 대해 설명해줍니다. 실시간으로 응답이 생성되는 것을 확인할 수 있습니다. 실제 현업에서는 어떻게 확장할까요? 이 기본 예제를 출발점으로 다양한 기능을 추가할 수 있습니다. 예를 들어 대화 히스토리를 저장하려면 세션이나 데이터베이스를 활용합니다. 스트리밍 응답을 구현하려면 Server-Sent Events를 사용합니다. 사용자별로 다른 프롬프트를 적용하려면 프롬프트 템플릿을 활용합니다. 많은 기업에서 이런 기본 패턴을 확장해 고객 상담, 콘텐츠 생성, 코드 리뷰 자동화 등 다양한 서비스를 만들고 있습니다. 응답 시간은 어느 정도일까요? OpenAI API는 인터넷을 통해 호출되므로 보통 1-3초 정도 걸립니다. 네트워크 상태와 OpenAI 서버 부하에 따라 달라질 수 있습니다. 긴 응답일수록 시간이 더 걸립니다. 프로덕션 환경에서는 타임아웃 설정과 재시도 로직을 추가하는 것이 좋습니다. 비용은 얼마나 들까요? OpenAI API는 사용한 만큼 과금됩니다. 토큰 단위로 계산되는데, 대략 1,000개의 영어 단어가 1,300개 정도의 토큰입니다. gpt-3.5-turbo는 매우 저렴해서 테스트 용도로는 큰 부담이 없습니다. gpt-4는 더 비싸므로 필요한 경우에만 사용하는 것이 좋습니다. OpenAI 대시보드에서 실시간으로 사용량을 모니터링할 수 있습니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 API 호출 실패 시 예외 처리를 하지 않는 것입니다. 네트워크 오류, API 키 문제, 할당량 초과 등 다양한 이유로 호출이 실패할 수 있습니다. 따라서 try-catch 블록이나 @ControllerAdvice를 사용해 적절한 에러 응답을 반환해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 김개발 씨는 브라우저에서 AI 응답을 보고 감탄했습니다. "와, 정말 되네요! 생각보다 훨씬 간단한데요?" 첫 번째 애플리케이션을 성공적으로 실행하면 Spring AI의 가능성을 직접 확인할 수 있습니다. 여러분도 오늘 배운 내용을 바탕으로 첫 AI 통합 애플리케이션을 만들어 보세요. **실전 팁** 💡 - 응답이 느리면 temperature를 낮춰보세요. 더 빠르게 응답합니다 - 로그 레벨을 DEBUG로 설정하면 실제 API 요청/응답을 확인할 수 있습니다 --- 이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!

카테고리: Spring,AI,Backend

언어: Java

태그: Spring, SpringAI, OpenAI, ChatGPT, Backend, Spring,AI,Backend

작성자: AI Generated

프리미엄 콘텐츠 - 3개월 무료 체험 가능

CodeDeck

Spring AI 완벽 가이드 환경 설정부터 첫 실행까지

목차

1. Spring AI란 무엇인가

2. Spring AI의 주요 특징과 장점

3. 개발 환경 설정

4. 프로젝트 초기 설정

5. 의존성 구성 및 API 키 설정

6. 첫 번째 Spring AI 애플리케이션 실행

이 카드뉴스가 포함된 코스

Spring AI 완전 정복 - 실전 AI 애플리케이션 개발

댓글 (0)

함께 보면 좋은 카드 뉴스

Voice Design 마스터하기

MCP 어노테이션 기반 개발 완벽 가이드

MCP 클라이언트 구현 완벽 가이드

MCP 서버 구현 WebFlux 완벽 가이드

MCP 서버 구현 WebMVC 완벽 가이드