Spring AI로 OpenAI Java SDK 사용하기
1. 개요
이 글에서는 Spring AI 2.0이 공식 OpenAI Java SDK를 표준 OpenAI 통합에 포함한 방식과, 이를 통해 ChatClient로 모델을 호출하는 방법을 다룹니다. 예제로는 지원 요청을 한 문장으로 요약하는 서비스 구현, Gemini를 대안 제공자로 사용하는 방법과 기존 별도 SDK 모듈에서의 마이그레이션 절차를 정리합니다.
2. Spring AI가 OpenAI Java SDK를 사용하는 방법
Spring AI는 언어 모델을 다루기 위한 공통 API를 제공합니다. 이번 통합에서 ChatClient는 OpenAiChatModel에 위임하여 Spring의 메시지와 옵션을 공식 SDK가 처리할 수 있는 요청으로 변환합니다.
애플리케이션은 Spring AI의 추상화에 의존하고, 실제 API 호출은 SDK가 담당합니다. Spring Boot의 자동 구성(auto-configuration)은 모델과 ChatClient.Builder를 제공하므로, 이전처럼 직접 SDK 요청을 조립할 필요가 줄어듭니다.
Spring AI 2.0에서는 과거의 별도 모듈인 spring-ai-openai-sdk를 제거하고, 내부적으로 공식 SDK를 사용합니다. (Spring AI 2.0.2에서는 Chat Completions API를 사용하며 OpenAI의 Responses API는 지원하지 않습니다.)
3. 통합 설정
예제는 Java 21, Spring Boot 4.1.2, Spring AI 2.0.2를 사용합니다.
3.1. Maven 의존성
프로젝트에 OpenAI starter를 추가합니다:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
<version>2.0.2</version>
</dependency>
Maven Repository에서 최신 버전을 확인할 수 있습니다. 2.0.2는 전이적(transitive)으로 openai-java-core 4.80.0을 포함하므로 별도의 SDK 의존성을 추가할 필요가 없습니다.
3.2. 자격 증명 및 모델 설정
OpenAI API 키와 사용 가능한 API 크레딧이 필요하며, 키는 환경변수 OPENAIAPIKEY로 제공합니다.
application.yml에서 엔드포인트와 응답 크기 제한을 다음과 같이 설정합니다:
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
base-url: https://api.openai.com/v1
timeout: 30s
max-retries: 0
chat:
model: ${OPENAI_MODEL:gpt-6-luna}
reasoning-effort: none
max-completion-tokens: 256
base URL에 /v1이 포함되어야 하며, SDK는 요청 시 자동으로 /chat/completions를 덧붙입니다.
reasoning-effort: none은 추론(reasoning)을 비활성화하고, max-completion-tokens로 생성 토큰 수를 제한합니다. 또한 요청 타임아웃과 자동 재시도 비활성화를 설정해 예제의 API 호출을 예측 가능하게 만듭니다.
4. ChatClient를 통해 OpenAI 호환 모델 호출하기
지원 요청을 받아 문제와 요청된 조치를 포함한 한 문장 요약을 생성해보겠습니다.
4.1. Summary 서비스 생성
자동 구성된 빌더를 서비스에 주입합니다:
@Service
public class SupportSummaryService {
private final ChatClient chatClient;
public SupportSummaryService(ChatClient.Builder builder) {
this.chatClient = builder.defaultSystem(
"Summarize the support request in one sentence. "
+ "Include the problem and the requested action. "
+ "Do not invent details.")
.build();
}
public String summarize(String request) {
return chatClient.prompt()
.user(request)
.call()
.content();
}
}
defaultSystem()은 요약 지침을 설정합니다. summarize() 호출은 사용자 메시지를 추가하고 모델을 동기적으로 호출하여 텍스트 결과를 반환합니다.
ChatClient는 스트리밍, 구조화된 출력 등 더 많은 기능도 지원하지만, 여기서는 SDK 통합에 집중하기 위해 단순 문자열 결과만 사용합니다.
4.2. OpenAI 호출 검증
SupportSummaryService를 주입해 중복 청구 관련 요청으로 동작을 확인합니다:
String summary = summaryService.summarize(
"I was charged twice for my subscription. Please refund the duplicate charge.");
assertThat(summary).isNotBlank();
logger.info("OpenAI support summary: {}", summary);
API 키를 설정한 뒤 레포지토리의 라이브 테스트를 실행합니다:
$ export OPENAI_API_KEY='our-openai-api-key'
mvn test -Dtest=OpenAiSupportSummaryLiveTest
라이브 테스트들은 @EnabledIfEnvironmentVariable로 활성화되므로 API 키가 없으면 Maven이 테스트를 건너뜁니다.
라이브 실행에서 OpenAI가 반환한 예시:
I was charged twice for my subscription and request a refund for the duplicate charge.
생성된 문장은 달라질 수 있으므로 정확한 문장보다 비어있지 않은지(nonblank)를 확인하는 것이 좋습니다.
4.3. Gemini를 대안으로 사용하기
유료 OpenAI 접근 권한이 없는 대안으로 Gemini를 사용할 수 있습니다. Gemini 3.5 Flash-Lite는 무료 또는 별도 요금제 하에서 사용할 수 있는 모델이며, 가용성 및 할당량(quota)이 적용됩니다.
application-gemini.yml에서 provider 설정을 오버라이드합니다:
spring:
ai:
openai:
api-key: ${GEMINI_API_KEY}
base-url: https://generativelanguage.googleapis.com/v1beta/openai/
timeout: 120s
chat:
model: ${GEMINI_MODEL:gemini-3.5-flash-lite}
reasoning-effort: low
max-completion-tokens: 1024
서비스와 SDK 코드는 동일하지만 모델별 옵션은 신경 써야 합니다. Gemini 3 계열은 reasoning-effort를 none으로 끌 수 없으므로 none 대신 low로 설정하고 더 많은 토큰을 허용해야 합니다.
요청당 최대 120초를 허용합니다. 라이브 테스트의 180초 제한은 JUnit이 먼저 요청을 중단하지 않도록 합니다.
Gemini 테스트는 해당 프로파일을 활성화하므로 키와 테스트 이름만 준비하면 됩니다:
$ export GEMINI_API_KEY='our-gemini-api-key'
mvn test -Dtest=GeminiSupportSummaryLiveTest
Gemini 3.5 Flash-Lite 실행에서의 반환 예시:
The user was charged twice for their subscription and is requesting a refund for the duplicate charge.
5. 별도 SDK 모듈에서의 마이그레이션
이 절차는 이전의 spring-ai-openai-sdk 통합을 사용하던 애플리케이션에 해당합니다. Spring AI 2.0에서 해당 모듈이 제거되었습니다.
표준 OpenAI 모듈을 이미 사용하는 애플리케이션은 기존 설정 속성 대부분을 유지할 수 있으며, chat.options.*는 deprecated alias로 남아 있습니다. 하지만 OpenAiChatModel을 수동으로 생성하던 코드는 수정이 필요합니다.
2.0.2에서는 OpenAiApi가 제거되었고, 모델 빌더가 더 이상 openAiApi(), defaultOptions(), retryTemplate()를 제공하지 않습니다. 대신 SDK의 OpenAIClient를 openAiClient()로 전달하고 모델 설정은 options()로 제공합니다.
5.1. 스타터와 프로퍼티 업데이트
Spring AI 1.1.x에서 2.0.2로 이동할 때는 Spring Boot 4 호환성도 필요합니다. spring-ai-starter-model-openai-sdk를 이전하고 3.1절에 나온 starter로 교체하세요.
예전 SDK starter 설정 예:
spring.ai.openai-sdk.api-key=${OPENAI_API_KEY}
spring.ai.openai-sdk.base-url=https://api.openai.com/v1
spring.ai.openai-sdk.chat.options.model=gpt-6-luna
Spring AI 2.0.2의 동등한 설정:
spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.base-url=https://api.openai.com/v1
spring.ai.openai.chat.model=gpt-6-luna
프리픽스가 spring.ai.openai-sdk에서 spring.ai.openai로 바뀌며, chat.options.model 대신 평탄한 chat.model을 사용합니다. 기존의 chat.options.model 표기는 2.0.2에서 여전히 동작하지만 deprecated입니다.
5.2. 모델 클래스와 옵션 업데이트
별도 모듈의 타입을 참조하던 코드는 다음과 같이 교체해야 합니다:
- OpenAiSdkChatModel → OpenAiChatModel
- OpenAiSdkChatOptions → OpenAiChatOptions
패키지 경로는 org.springframework.ai.openaisdk에서 org.springframework.ai.openai로 변경됩니다. 이는 명시적 모델 생성이나 프로그래매틱한 옵션 사용 시 영향을 미칩니다.
이전 OpenAiSdkChatModel 빌더는 이미 openAiClient()와 options()를 사용했으므로 이름 변경 시 메서드 호출 방식은 유사합니다.
우리 예제 서비스는 ChatClient.Builder와 ChatClient만 사용하므로 SDK 특정 클래스를 직접 참조하지 않아 서비스 코드 자체는 변경할 필요가 없습니다. 즉, 스타터와 설정만 바꾸면 됩니다.
6. 결론
Spring AI의 표준 OpenAI starter와 공식 Java SDK를 사용해 지원 요청 요약 서비스를 만들고, 엔드포인트·자격증명·모델 옵션을 바꾸어 Gemini로도 동일한 서비스를 구동할 수 있음을 보았습니다. 별도 SDK 모듈을 사용하던 애플리케이션은 스타터, 프로퍼티 프리픽스, SDK 관련 클래스 이름을 교체하면 마이그레이션이 가능합니다. ChatClient 중심의 애플리케이션 구조는 서비스 레이어 수정 최소화에 도움이 됩니다.
정리
- Spring AI 2.0은 공식 OpenAI Java SDK를 내부적으로 사용하며 별도 spring-ai-openai-sdk 모듈은 제거되었다.
- Spring Boot 자동 구성이 ChatClient.Builder와 모델을 제공하므로 애플리케이션 코드는 간결하게 유지된다.
- Spring AI 2.0.2는 Chat Completions API를 사용하며 Responses API는 지원하지 않는다.
- 구성 변경: 의존성은 spring-ai-starter-model-openai(2.0.2), 프로퍼티 프리픽스는 spring.ai.openai로 변경된다.
- Gemini를 대안으로 사용할 수 있으며 모델별 옵션(reasoning-effort, max-completion-tokens, timeout)을 조정해야 한다.
실무 코멘트
- Spring Boot 4 및 Java 21 등 호환성 요구사항을 확인하라(예제는 Java 21, Spring Boot 4.1.2, Spring AI 2.0.2 기준).
- Spring AI 2.0.2는 openai-java-core 4.80.0을 전이적으로 가져오므로 별도 SDK 의존성 추가 불필요.
- 프로덕션에서는 timeout, max-retries, max-completion-tokens 같은 설정을 서비스 특성 및 비용 제약에 맞춰 조정해야 한다.
- 기존 코드가 OpenAiApi 등 제거된 API를 직접 참조하면 OpenAIClient 전달 방식(openAiClient())과 옵션(options())으로 변경이 필요하다.
원문: Using the Official OpenAI Java SDK With Spring AI (Baeldung)



