Spring AI 시작하기

Spring AI 시작하기 (Getting Started)

Spring AI를 실제 프로젝트에 얹어 보려면 어디서부터 손을 대야 할지 막막할 수 있어요. 이 문서는 스프링 부트 기반 앱에 Spring AI를 추가하는 출발점을 하나씩 짚어 줘요 — 의존성을 어디서 받고, 어떤 저장소를 쓰고, 필요한 모듈을 어떻게 골라 넣는지 순서대로 따라가면 돼요.

출처: 공식문서

Spring Initializr

새 애플리케이션을 만들 때는 https://start.spring.io/[start.spring.io]로 가서 사용하고 싶은 AI 모델과 벡터 스토어를 골라 추가하면 돼요.

아티팩트 저장소 (Artifact Repositories)

릴리스 버전 — Maven Central 사용

Spring AI 아티팩트는 Maven Central에 배포돼 있어요. 별도의 저장소 설정이 필요 없고, 빌드 파일에서 Maven Central만 활성화돼 있으면 돼요.

<!-- Maven Central is included by default in Maven builds.
     You usually don’t need to configure it explicitly,
     but it's shown here for clarity. -->
<repositories>
    <repository>
        <id>central</id>
        <url>https://repo.maven.apache.org/maven2</url>
    </repository>
</repositories>

Gradle이라면 이렇게 하면 돼요:

repositories {
    mavenCentral()
}

스냅샷 버전 — 스냅샷 저장소 추가

최신 개발 버전(예: 2.0.0-SNAPSHOT)을 쓰려면 빌드 파일에 아래 스냅샷 저장소를 추가해야 해요.

  <repositories>
    <repository>
      <id>spring-snapshots</id>
      <name>Spring Snapshots</name>
      <url>https://repo.spring.io/snapshot</url>
      <releases>
        <enabled>false</enabled>
      </releases>
    </repository>
    <repository>
      <name>Central Portal Snapshots</name>
      <id>central-portal-snapshots</id>
      <url>https://central.sonatype.com/repository/maven-snapshots/</url>
      <releases>
        <enabled>false</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
  </repositories>

Gradle에서는 이렇게 추가해요:

repositories {
  mavenCentral()
  maven { url 'https://repo.spring.io/milestone' }
  maven { url 'https://repo.spring.io/snapshot' }
  maven {
    name = 'Central Portal Snapshots'
    url = 'https://central.sonatype.com/repository/maven-snapshots/'
  }  
}

주의: Maven으로 Spring AI 스냅샷을 쓸 때는 미러 설정을 확인해야 해요. settings.xml에 미러를 이렇게 구성했다면:

<mirror>
    <id>my-mirror</id>
    <mirrorOf>*</mirrorOf>
    <url>https://my-company-repository.com/maven</url>
</mirror>

와일드카드 *가 모든 저장소 요청을 미러로 보내서 Spring 스냅샷 저장소에 접근하지 못하게 돼요. 이럴 때는 mirrorOf 설정을 고쳐 Spring 저장소를 제외해 주면 됩니다:

<mirror>
    <id>my-mirror</id>
    <mirrorOf>*,!spring-snapshots,!central-portal-snapshots</mirrorOf>
    <url>https://my-company-repository.com/maven</url>
</mirror>

이렇게 하면 다른 의존성은 미러를 쓰면서도 Spring 스냅샷 저장소에는 직접 접근할 수 있어요.

의존성 관리 (Dependency Management)

Spring AI의 BOM(Bill of Materials)은 해당 릴리스가 사용하는 모든 의존성의 권장 버전을 선언해 줘요. 이건 BOM 전용 버전이라 의존성 관리만 담고, 플러그인 선언이나 Spring·Spring Boot에 대한 직접 참조는 없어요. Spring Boot 버전 관리는 Spring Boot 부모 POM을 쓰거나 Spring Boot의 BOM(spring-boot-dependencies)을 쓰면 돼요.

프로젝트에 BOM을 추가해 볼게요:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>2.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Gradle에서는 이렇게요:

dependencies {
  implementation platform("org.springframework.ai:spring-ai-bom:2.0.0")
  // Replace the following with the specific module dependencies (e.g., spring-ai-openai) or starter modules (e.g., spring-ai-starter-model-openai) that you wish to use
  implementation 'org.springframework.ai:spring-ai-openai'
}

Gradle 사용자는 Maven BOM을 이용해 의존성 제약을 선언하는 Gradle 네이티브 지원으로도 Spring AI BOM을 쓸 수 있어요. 이를 위해 Gradle 빌드 스크립트의 dependencies 섹션에 platform 의존성 핸들러 메서드를 추가하면 되죠.

특정 컴포넌트 의존성 추가

문서의 각 섹션은 프로젝트 빌드 시스템에 어떤 의존성을 추가해야 하는지 보여줘요.

Spring AI 샘플

Spring AI와 관련된 더 많은 리소스와 샘플은 https://github.com/spring-ai-community/awesome-spring-ai[이 페이지]를 참고하면 돼요.

Spring AI 시작하기