B컷전문 | 개발과 인생의 이야기

Spring AI를 통해 OpenAI GPT API를 Spring Boot 애플리케이션에 연동하는 방법을 소개합니다. 프로젝트 설정, 프롬프트 구성, 결과 출력까지 실습 중심으로 설명합니다.

 

 

이전 글에서 Spring AI의 모듈 구조와 계층 설계를 살펴봤습니다. 이번 글에서는 그 구조를 실제로 적용해보는 시간을 갖겠습니다.

Spring Boot 애플리케이션에 OpenAI GPT 모델을 연동하고, 사용자의 입력을 받아 텍스트를 생성하는 과정을 실습 중심으로 정리했습니다.

 

---

 

1. 의존성 설정

 

프로젝트에 OpenAI Starter를 추가합니다. 현재 Spring AI는 Maven Central에 공개되어 있으며, 버전은 0.8.0 기준입니다.

 

 

Maven

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
  <version>0.8.0</version>
</dependency>

 

Gradle

implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter:0.8.0'

버전은 사용 시점 기준 최신으로 업데이트하는 것이 좋습니다.

 

---

 

2. application.yml 설정

 

OpenAI API 연동을 위해 기본적인 환경 설정을 구성합니다.

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-3.5-turbo
          temperature: 0.7
          max-tokens: 300

환경 변수로 API 키를 전달하면 운영 환경에서도 유연하게 대응할 수 있습니다.

 

---

 

3. ChatClient를 이용한 텍스트 생성

 

Spring AI는 LLM 호출을 위한 추상 인터페이스로 ChatClient를 제공합니다. 의존성 주입만으로 간단하게 사용이 가능합니다.

@RestController
@RequestMapping("/ai")
public class AiController {

    private final ChatClient chatClient;

    public AiController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping("/ask")
    public String ask(@RequestParam String prompt) {
        return chatClient.call(prompt).getResult().getOutput().getContent();
    }
}

브라우저에서 /ai/ask?prompt=봄날의 시를 써줘를 호출하면 GPT가 생성한 응답을 바로 받을 수 있습니다.

 

---

 

4. PromptTemplate 활용

 

정형화된 프롬프트는 PromptTemplate을 사용하여 가독성과 재사용성을 높일 수 있습니다.

@GetMapping("/email")
public String generateEmail(@RequestParam String product) {
    PromptTemplate template = new PromptTemplate("우리 제품 {product}에 대한 마케팅 이메일을 작성해줘.");
    template.add("product", product);
    return chatClient.call(template.create()).getResult().getOutput().getContent();
}

템플릿 기반 프롬프트 구성은 특히 마케팅 문구, 고객 대응, 문서 요약 등에 유용합니다.

 

---

 

5. 예외 처리 고려 사항

 

실제 서비스에서는 다음과 같은 상황에 대비해야 합니다.

 

• API 키 누락 또는 잘못된 인증
• 호출 제한 초과 (rate limit)
• OpenAI 서버 지연 또는 오류
• 비정상 응답 처리

 

Spring AI는 예외 발생 시 AiClientException, RetryableException 등으로 예외를 포장합니다. Spring의 기본 예외 처리 방식을 활용하면 에러 핸들링을 일관성 있게 구성할 수 있습니다.

@ExceptionHandler(Exception.class)
public ResponseEntity<String> handleError(Exception e) {
    return ResponseEntity.status(500).body("AI 호출 중 오류가 발생했습니다.");
}

 

---

 

핵심 정리

항목내용

연동 방식	Spring Boot Starter 기반 설정
주요 클래스	ChatClient, PromptTemplate
설정 파일	application.yml 내 OpenAI 관련 설정
호출 구조	REST 컨트롤러 또는 서비스 내부에서 chatClient.call(prompt) 사용
장점	최소한의 코드로 GPT 연동, Spring 방식에 맞는 구성과 확장성 확보