기술과 산업/언어 및 프레임워크

Spring AI 시리즈 2화 – Spring AI 프로젝트 구조와 주요 모듈 개요

B컷개발자 2025. 5. 30. 18:03
728x90

Spring AI는 OpenAI, Hugging Face, Chroma 등 다양한 AI 서비스를 선언적으로 연동할 수 있도록 돕는 Spring 기반 프레임워크입니다. 본 글에서는 프로젝트 구조와 주요 모듈 역할을 중심으로, Spring AI의 구성 원리를 소개합니다.

 

 

AI 기능을 애플리케이션에 녹여내기 위해 Spring AI를 도입하려 할 때, 가장 먼저 부딪히는 질문은 이것입니다.

 

“Spring AI는 정확히 어떤 구조로 구성돼 있고, 어떤 모듈을 어떻게 의존해야 하지?”

 

이 질문은 단순히 설정을 어떻게 하느냐를 넘어,

AI 기능을 어떻게 확장할 수 있는가,

어떤 모듈이 어떤 기능을 담당하는가,

그리고

내가 사용하는 LLM과 Vector DB는 어떤 식으로 연동되는가를 이해하는 데 매우 중요합니다.

 

이번 글에서는 Spring AI의 전체적인 구조를 하나의 큰 그림처럼 정리해보겠습니다.

 

 

Spring AI 프로젝트 구조: Overview

 

Spring AI는 단일 프로젝트가 아니라 여러 개의 모듈로 구성된 멀티모듈 프로젝트입니다.

공식 저장소 기준 주요 모듈은 아래와 같습니다:

 

 

📦 Core Layer

 

  • spring-ai-core: Spring AI의 핵심 추상화 계층
    • ChatClient, PromptTemplate, EmbeddingClient, VectorStore 등의 인터페이스 정의
    • 기본적인 API 규약과 구성 방식, 오류 처리 로직 등을 포함

 

🤖 LLM Provider Layer

  • spring-ai-openai: OpenAI GPT 연동
  • spring-ai-huggingface: Hugging Face Inference API 연동
  • spring-ai-azure-openai: Azure 기반 OpenAI 연동
  • spring-ai-ollama: 로컬에서 실행 가능한 모델 연동 (예: Mistral 등)

 

 

🧠 Embedding + 벡터 저장소 Layer

  • spring-ai-embedding-openai: OpenAI의 임베딩 API 연동
  • spring-ai-vectorstore-chroma: Chroma DB 연동
  • spring-ai-vectorstore-milvus: Milvus 연동
  • spring-ai-vectorstore-weaviate: Weaviate 연동
  • spring-ai-vectorstore-pgvector: PostgreSQL 기반 벡터 저장소 연동

 

 

📄 문서 처리 Layer

  • spring-ai-document: PDF, TXT, MD, HTML 등 다양한 문서 형식을 로딩하여 청크로 분할하는 기능
    • DocumentReader, TextSplitter, Metadata 등을 포함

 

 

🧪 실습 및 테스트 Layer

  • spring-ai-examples: 전체 기능을 종합한 샘플 프로젝트 모음
  • spring-ai-bom: 의존성 정리를 위한 BOM(Bill of Materials)

 

 

모듈 간 계층 구조

[Application Layer]
      ↓
[LLM/Embedding/VectorStore Client]
      ↓
[Core Abstractions (spring-ai-core)]
      ↓
[Spring Boot Integration + Config]

예를 들어, OpenAI 기반 챗봇을 구성한다고 할 때,

 

  • spring-ai-core에서 제공하는 ChatClient를 인터페이스로 사용하고
  • spring-ai-openai가 이를 실제 구현체로 제공합니다.
  • 설정은 application.yml을 통해 Spring Boot 방식으로 주입됩니다.

 

 

실전 연동 예: OpenAI 연동

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
@Autowired
private ChatClient chatClient;

public String callAI(String input) {
    return chatClient.call(input).getResult().getOutput().getContent();
}

▶ 위 코드 흐름에서 중요한 점은, 개발자는 ChatClient 인터페이스만 사용하면 된다는 점입니다.

구체적인 모델 호출 로직, HTTP 처리, JSON 파싱 등은 모두 내부에서 처리되며, 선언적이고 간결한 구조를 유지합니다.

 

 

Embedding + Vector Store 연동 구조

 

Spring AI는 LLM만 연결하는 게 아닙니다.

문서 기반 Q&A, 검색 기능, 요약 시스템을 만들기 위해선 다음 세 가지가 함께 필요합니다:

 

  1. 임베딩 생성 (예: OpenAI Embedding)
  2. 벡터 저장소 (예: Chroma, Weaviate)
  3. 검색 및 유사도 비교 → RAG 구성

 

이를 위한 구조도 Spring AI 내부에서 다음과 같이 추상화되어 있습니다:

interface EmbeddingClient {
    List<Float> embed(String text);
}

interface VectorStore {
    void add(Document doc);
    List<Document> findRelevant(String query);
}

벡터 DB마다 구현체만 달라지고, API 사용 방식은 동일합니다.

 

 

실전에서 어떤 모듈을 선택해야 하나?

목적선택해야 할 모듈

GPT-4 사용 spring-ai-openai
HuggingFace 모델 사용 spring-ai-huggingface
로컬 모델 실행 (Mistral 등) spring-ai-ollama
문서 요약/검색 시스템 spring-ai-document, spring-ai-embedding-*, spring-ai-vectorstore-*
Azure 기반 OpenAI spring-ai-azure-openai
Vector DB 연동 spring-ai-vectorstore-chroma, milvus, pgvector 등

 

 

핵심 포인트 요약

 

  • Spring AI는 단일 API가 아니라 모듈화된 구성체계다.
  • spring-ai-core가 모든 기능의 중심이고, Provider/Store/Embedding 계층이 이를 구현한다.
  • Vector Store, PromptTemplate, Embedding API 등을 통합적으로 다루기 때문에 AI 기능의 전체 흐름을 일관된 구조로 통제할 수 있다.
  • Spring Boot Starter 방식으로 구성되어 개발자가 진입장벽 없이 사용 가능하다.
728x90