OpenAI Chat

OpenAI Chat

Spring AI는 ChatGPT를 만든 회사인 OpenAI의 다양한 AI 언어 모델을 지원해요. OpenAI는 업계를 선도하는 텍스트 생성 모델과 임베딩을 만들어 AI 기반 텍스트 생성에 대한 관심을 촉발한 회사로 잘 알려져 있어요.

출처: 공식문서

2.0.0-M5부터 Spring AI는 모든 OpenAI 모델에 공식 openai-java SDK를 사용해요. 전환은 매끄러울 것으로 예상되며, 기존 OpenAI API 속성과 빌더 사용자에게는 깨지는 변경이 없어요. 문제를 발견하면 Spring AI GitHub Issues에 보고해주세요.

사전 준비

ChatGPT 모델에 접근하려면 OpenAI에서 API 키를 만들어야 해요.

Spring AI 프로젝트는 spring.ai.openai.api-key라는 구성 속성을 정의하는데, openai.com에서 얻은 API Key 값을 이 속성에 설정하면 돼요. application.properties 파일에 다음과 같이 설정해요.

spring.ai.openai.api-key=<your-openai-api-key>

API 키 같은 민감 정보를 다룰 때 보안을 강화하려면 Spring Expression Language(SpEL)로 사용자 정의 환경 변수를 참조할 수 있어요.

# In application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}

# In your environment or .env file
export OPENAI_API_KEY=<your-openai-api-key>

애플리케이션 코드에서 프로그래밍 방식으로도 설정할 수 있어요.

// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("OPENAI_API_KEY");

저장소와 BOM 추가

Spring AI 아티팩트는 Maven Central과 Spring Snapshot 저장소에 게시돼요. Artifact Repositories 섹션을 참고해 빌드 시스템에 저장소를 추가해요. 의존성 관리를 위해 Spring AI는 일관된 버전을 보장하는 BOM을 제공해요. Dependency Management 섹션을 참고해 추가해요.

자동 설정 (Auto-configuration)

Spring AI의 자동 설정과 스타터 모듈의 아티팩트 이름이 크게 바뀌었어요. 자세한 내용은 업그레이드 노트를 확인해주세요.

Spring AI는 OpenAI 채팅 클라이언트를 위한 Spring Boot 자동 설정을 제공해요. Maven pom.xml이나 Gradle build.gradle에 다음 의존성을 추가하면 돼요.

• Maven
• Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

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

채팅 속성 (Chat Properties)

재시도 속성

연결 속성

여러 조직에 속한 사용자(또는 레거시 사용자 API 키로 프로젝트에 접근하는 사용자)는 API 요청에 어떤 조직·프로젝트를 사용할지 선택적으로 지정할 수 있어요. 이 요청들의 사용량은 지정된 조직·프로젝트로 집계돼요.

User-Agent 헤더

Spring AI는 모든 OpenAI 요청에 User-Agent: spring-ai 헤더를 자동으로 보내요. 이는 OpenAI가 분석·지원 목적으로 Spring AI에서 온 요청을 식별하는 데 도움을 줘요. 이 헤더는 자동으로 보내지며 Spring AI 사용자가 별도로 구성할 필요가 없어요.

OpenAI 호환 서비스를 만드는 API 제공자라면 서버에서 수신 요청의 User-Agent HTTP 헤더를 읽어 Spring AI 사용량을 추적할 수 있어요.

구성 속성

채팅 자동 설정의 활성·비활성은 프리픽스 spring.ai.model.chat로 관리해요. 활성화하려면 spring.ai.model.chat=openai(기본값), 비활성화하려면 spring.ai.model.chat=none을 쓰면 돼요.

Reasoning 콘텐츠 접근

reasoning 모델(예: o1, o3 계열, DeepSeek R1 같은 사고 과정을 노출하는 모델)은 최종 답변과 별도로 모델의 추론 과정을 포함하는 reasoning_content를 반환할 수 있어요. Spring AI는 reasoningContent라는 메타데이터 키로 이 내용을 노출해요.

reasoning_content의 가용성은 전적으로 사용 중인 추론 서버에 달려 있어요. reasoning 가능 모델을 쓰더라도 모든 OpenAI 호환 서버가 reasoning 콘텐츠를 노출하는 건 아니에요. 응답에 어떤 필드가 있는지 항상 서버의 API 문서를 참고하세요.

더 알아보기

• OpenAI models 문서
• OpenAI Structured Outputs
• Spring AI 업그레이드 노트