Spring AI 통합 시작하기
이 페이지의 내용
Atlas Vector Search를 Spring AI 와 통합할 수 있습니다. MongoDB Java Sync 드라이버 를 사용하여 생성형 AI 애플리케이션을 빌드합니다. 이 튜토리얼에서는 Atlas Vector Search를 Spring AI의 벡터 저장소로 사용하여 시작한 다음 데이터에서 시맨틱 검색을 수행하는 방법을 보여 줍니다.
구체적으로 다음 조치를 수행합니다.
환경을 설정합니다.
Atlas Vector Search 인덱스를 생성합니다.
벡터 임베딩 데이터를 Atlas에 저장합니다.
데이터에 대해 시맨틱 검색 쿼리를 실행합니다.
배경
Spring AI는 Spring 의 애플리케이션 프레임워크입니다. 다양한 AI 서비스 및 플러그인을 애플리케이션과 결합할 수 있습니다. Spring AI는 다양한 텍스트 기반 AI 사용 사례에 사용할 수 있습니다.
Atlas를 벡터 데이터베이스로 사용하고 Atlas Vector Search를 사용하여 데이터에서 의미적으로 유사한 문서를 검색하여 RAG 를 구현할 수 있습니다. RAG 에 대해 자세히 알아보려면 Atlas Vector Search를 사용한 RAG(검색 보강 생성)를 참조하세요.
전제 조건
이 튜토리얼을 완료하려면 다음 조건을 충족해야 합니다.
MongoDB 버전 6 을(를) 실행하는 Atlas 클러스터입니다.0.11, 7.0.2 이상입니다. 사용자의 IP 주소 가 Atlas 프로젝트의 액세스 목록에 포함되어 있는지 확인하세요.
OpenAI API 키입니다. API 요청에 사용할 수 있는 크레딧이 있는 유료 OpenAI 계정이 있어야 합니다.OpenAI 계정 등록에 대해 자세히 알아보려면 OpenAI API 웹사이트를 참조하세요.
Java 애플리케이션을 설정하고 실행하기 위한 환경입니다.IntelliJ IDEA 와 같은 통합 개발 환경(IDE)을 사용하는 것이 좋습니다. 또는 Eclipse IDE 프로젝트를 빌드하고 실행하도록 Maven을 구성합니다.
환경 설정
이 튜토리얼에서는 먼저 필요한 종속성을 추가하고 구성 속성을 설정하는 등 환경을 설정해야 합니다.
Spring Java 애플리케이션을 생성합니다.
Spring Initializr 로 이동합니다. 다음 설정으로 프로젝트를 구성합니다.
프로젝트: Maven
언어 : Java
Spring Boot: 선택된 기본 버전을 사용할 수 있습니다.
프로젝트 메타데이터:
Java: 21
다른 모든 필드에는 기본값을 사용할 수 있습니다.
Spring Initializr의 오른쪽에서 ADD DEPENDENCIES 클릭한 다음, 다음 종속성을 검색하여 추가합니다.
MongoDB Atlas Vector Database
Spring Data MongoDB
마지막으로 GENERATE 를 클릭하여 Spring 프로젝트의 압축 버전을 다운로드합니다. 파일의 압축을 풀고 IDE에서 엽니다.
종속성을 추가합니다.
Spring AI는 Atlas Vector Search를 위한 Spring Boot 자동 구성을 제공합니다.
프로젝트의
pom.xml
파일에 있는dependencies
배열에 다음 종속성을 추가합니다. 이러한 종속성은 애플리케이션에 Spring AI와 자동 구성 라이브러리를 추가합니다.<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-spring-boot-autoconfigure</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> 다음으로,
pom.xml
파일에 Spring AI BOM(Bill of Material)에 대한dependencyManagement
항목이 포함되어 있는지 확인합니다.중요
Spring AI BOM에 사용되는
spring-ai.version
상수를1.0.0-SNAPSHOT
로 설정하여 애플리케이션에 최신 Spring AI 기능을 구현합니다.Spring AI BOM에 대해 자세히 알아보려면 종속성 관리 를 참조하세요. 섹션을 참조하세요.
마지막으로 Spring AI Snapshot 리포지토리를
pom.xml
파일의repositories
항목에 추가합니다.<repository> <id>spring-snapshots</id> <name>Spring Snapshots</name> <url>https://repo.spring.io/snapshot</url> <releases> <enabled>false</enabled> </releases> </repository> 이러한 리포지토리에 대해 자세히 알아보려면 마일스톤 및 스냅샷 리포지토리 추가 를 참조하세요. 섹션을 참조하세요.
pom.xml
파일 편집을 완료한 후 프로젝트를 다시 로드하여 종속성이 설치되었는지 확인합니다.
애플리케이션 속성을 정의합니다.
src/main/resources/application.properties
파일을 찾아 해당 파일의 내용을 다음 속성으로 바꿉니다. 자리 표시자를 OpenAI API 키 및 Atlas 연결 문자열로 바꿉니다.
spring.application.name=springai-mongodb spring.ai.openai.api-key=<OpenAI API Key> spring.ai.openai.embedding.options.model=text-embedding-ada-002 spring.data.mongodb.uri=<connection string> spring.data.mongodb.database=springai_test spring.ai.vectorstore.mongodb.indexName=vector_index spring.ai.vectorstore.mongodb.collection-name=vector_store
참고
연결 문자열은 다음 형식을 사용해야 합니다.
mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net/?<settings>
연결 문자열 검색에 대해 자세히 알아보려면 Atlas 시작하기 튜토리얼을 참조하세요.
Atlas Vector Search 인덱스 만들기
벡터 저장소에서 벡터 검색 쿼리를 활성화하려면 springai_test.vector_store
컬렉션에 Atlas Vector Search 인덱스를 만들어야 합니다.
참고
필요한 액세스 권한
Atlas Vector Search 검색 인덱스를 만들려면 Atlas 프로젝트에 대한 Project Data Access Admin
이상의 액세스 권한이 있어야 합니다.
스키마 초기화를 활성화합니다.
애플리케이션에서 Atlas를 벡터 저장소로 구성하면 Spring AI가 백엔드 스키마를 자동으로 초기화할 수 있습니다. 이 초기화에는 벡터 임베딩이 포함된 컬렉션에 Atlas Vector Search 인덱스를 생성하는 작업이 포함됩니다. application.properties
파일에 다음 설정을 추가하여 스키마 초기화를 활성화할 수 있습니다.
spring.ai.vectorstore.mongodb.initialize-schema=true
initialize-schema=true
를 지정하면 Spring AI가 클러스터에 프로그래밍 방식으로 Atlas Vector Search 인덱스를 생성합니다. 이 때문에 애플리케이션을 전용 클러스터에 연결해야 합니다. 무료 또는 공유 계층 클러스터를 실행하는 경우, Atlas UI, Atlas 관리 API 또는 Atlas CLI를 통해 인덱스를 별도로 생성해야 합니다.
자세히 알아보려면 Atlas Vector Search 인덱스 만들기를 참조하세요.
참고
알려진 문제: 기존 인덱스
springai_test.vector_store
컬렉션에 vector_index
(이)라는 기존 Atlas Vector Search 인덱스가 있는 경우 Spring AI는 추가 인덱스를 생성하지 않습니다. 이로 인해 기존 인덱스가 호환되지 않는 설정(예: 다른 차원 수)으로 구성된 경우 튜토리얼 뒷부분에서 오류가 발생할 수 있습니다.
인덱스에 다음과 같은 구성이 있는지 확인합니다.
{ "fields": [ { "numDimensions": 1536, "path": "embedding", "similarity": "cosine", "type": "vector" } ] }
Atlas를 Vector Store로 사용
이 섹션에서는 Atlas를 벡터 저장소라고도 하는 벡터 데이터베이스로 구성하여 사용자 지정 데이터의 벡터 임베딩을 저장할 수 있는 방법을 설명합니다.
프로젝트에서 src/main/java/com/example/demo/DemoApplication.java
파일을 찾습니다. 이 파일과 동일한 수준에서 config
디렉토리를 만든 다음 이 디렉토리에 Config.java
파일을 만들어 Spring App 구성을 설정합니다.
다음 단계에서는 벡터 저장소를 준비하는 데 필요한 Bean
객체를 만드는 방법을 보여 줍니다.
가져오기 문을 추가합니다.
다음 코드를 Config.java
파일에 붙여넣어 필요한 클래스를 가져옵니다.
import org.springframework.ai.embedding.EmbeddingModel; import org.springframework.ai.openai.OpenAiEmbeddingModel; import org.springframework.ai.openai.api.OpenAiApi; import org.springframework.ai.vectorstore.MongoDBAtlasVectorStore; import org.springframework.ai.vectorstore.VectorStore; import org.springframework.beans.factory.annotation.Value; import org.springframework.boot.SpringBootConfiguration; import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.data.mongodb.core.MongoTemplate;
VectorStore
Spring 빈을 생성합니다.
마지막으로 다음 코드를 붙여넣어 VectorStore
인스턴스를 반환하는 빈을 생성합니다. VectorStore
인스턴스는 배포에 해당하는 MongoTemplate
와 이전 단계에서 만든 OpenAiEmbeddingModel
를 사용합니다.
public VectorStore mongodbVectorStore(MongoTemplate mongoTemplate, EmbeddingModel embeddingModel) { return new MongoDBAtlasVectorStore(mongoTemplate, embeddingModel, MongoDBAtlasVectorStore.MongoDBVectorStoreConfig.builder().build(), initSchema); }
사용자 지정 데이터 저장 및 시맨틱 검색 쿼리 실행
이 섹션에서는 Java 애플리케이션에서 엔드포인트를 만들어 사용자 지정 데이터의 벡터 임베딩을 Atlas에 저장한 다음, 해당 데이터에 대해 시맨틱 검색 쿼리를 실행하는 방법을 알아봅니다.
엔드포인트 생성
config
폴더와 동일한 수준에서 controller
폴더를 만든 다음 Controller.java
파일을 만들어 API 엔드포인트를 설정합니다. 다음 단계에서는 GET
엔드포인트를 만들어 벡터 저장소에 데이터를 추가하고 similaritySearch()
메서드를 사용하여 시맨틱 검색 쿼리를 실행하는 방법을 보여 줍니다.
가져오기 문을 추가합니다.
다음 코드를 Controller.java
파일에 붙여넣어 필요한 클래스를 가져옵니다.
import org.springframework.ai.document.Document; import org.springframework.ai.vectorstore.VectorStore; import org.springframework.ai.vectorstore.SearchRequest; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import java.util.List; import java.util.Map; import java.util.stream.Collectors;
엔드포인트를 생성하여 벡터 저장소에 문서를 추가합니다.
컨트롤러에 다음 코드를 붙여넣어 샘플 문서를 생성하고 벡터 스토어에 벡터 임베딩으로 저장하는 GET
엔드포인트를 만듭니다.
public String addDocuments() { List<Document> docs = List.of( new Document("Proper tuber planting involves site selection, proper timing, and exceptional care. Choose spots with well-drained soil and adequate sun exposure. Tubers are generally planted in spring, but depending on the plant, timing varies. Always plant with the eyes facing upward at a depth two to three times the tuber's height. Ensure 4 inch spacing between small tubers, expand to 12 inches for large ones. Adequate moisture is needed, yet do not overwater. Mulching can help preserve moisture and prevent weed growth.", Map.of("author", "A", "type","post")), new Document("Successful oil painting necessitates patience, proper equipment, and technique. Begin with a carefully prepared, primed canvas. Sketch your composition lightly before applying paint. Use high-quality brushes and oils to create vibrant, long-lasting artworks. Remember to paint 'fat over lean,' meaning each subsequent layer should contain more oil to prevent cracking. Allow each layer to dry before applying another. Clean your brushes often and avoid solvents that might damage them. Finally, always work in a well-ventilated space.", Map.of("author", "A")), new Document("For a natural lawn, selection of the right grass type suitable for your climate is crucial. Balanced watering, generally 1 to 1.5 inches per week, is important; overwatering invites disease. Opt for organic fertilizers over synthetic versions to provide necessary nutrients and improve soil structure. Regular lawn aeration helps root growth and prevents soil compaction. Practice natural pest control and consider overseeding to maintain a dense sward, which naturally combats weeds and pest.", Map.of("author", "B", "type","post")) ); vectorStore.add(docs); return "Documents added successfully!\n"; }
시맨틱 검색을 수행할 엔드포인트를 생성합니다.
컨트롤러에 다음 코드를 붙여넣어 "learn how to grow things"
구문에 대한 시맨틱 검색 쿼리를 수행하고 가장 관련성이 높은 두 개의 결과를 반환하는 GET
엔드포인트를 만듭니다.
1 2 public List<Map<String, Object>> searchDocuments() { 3 4 List<Document> results = vectorStore.similaritySearch( 5 SearchRequest 6 .query("learn how to grow things") 7 .withTopK(2) 8 ); 9 10 return results.stream().map(doc -> Map.of( 11 "content", doc.getContent(), 12 "metadata", doc.getMetadata() 13 )).collect(Collectors.toList()); 14 }
(선택 사항) 메타데이터 필터링을 사용하여 시맨틱 검색을 수행합니다.
메타데이터 필터링을 사용하여 검색을 수행하려면 Java 동기화 드라이버의 Filter.Expression
빌더 클래스를 사용할 수 있습니다.
MQL 일치 표현식을 사용하여 문서를 사전 필터링할 수 있습니다. 이 예에서는 author
필드 값이 "A"
인 문서를 필터링합니다. 그런 다음 구문 "learn how to grow things"
에 대한 시맨틱 검색 쿼리를 수행합니다.
이전 단계에서 정의된 searchDocuments()
메서드 본문에서 similaritySearch()
메서드를 호출하는 코드(이전 블록의 4~8 줄)를 다음 코드로 바꿉니다.
FilterExpressionBuilder b = new FilterExpressionBuilder(); List<Document> results = vectorStore.similaritySearch( SearchRequest.defaults() .withQuery("learn how to grow things") .withTopK(2) .withSimilarityThreshold(0.5) .withFilterExpression(b.eq("author", "A").build()) );
참고
메타데이터 필드의 경로를 Atlas Vector Search 인덱스에 추가해야 합니다. 자세한 내용은 벡터 검색을 위한 필드 인덱스 방법 튜토리얼 의 filter
유형 정보 섹션을 참조하세요.
메타데이터 사전 필터링에 대해 자세히 알아보려면 Atlas Vector Search 사전 필터를 참조하세요.
액세스 엔드포인트
애플리케이션을 실행한 후 엔드포인트에 액세스하여 먼저 벡터 저장소에 문서를 추가한 다음 시맨틱 검색 쿼리를 수행할 수 있습니다.
터미널 내에서 엔드포인트에 액세스합니다.
애플리케이션이 실행 중인지 확인한 후 터미널에서 다음 명령을 실행하여 add
엔드포인트에 액세스하면 샘플 데이터를 벡터 임베딩으로 변환하고 Atlas에 임베딩을 삽입합니다.
curl -X GET http://localhost:8080/tutorial/add
팁
엔드포인트에 액세스한 후 클러스터의 springai_test.vector_store
컬렉션으로 이동 하여 Atlas UI에서 벡터 임베딩을 볼 수 있습니다.
그런 다음 터미널에서 다음 명령을 실행하여 search
엔드포인트에 액세스하여 시맨틱 검색을 수행합니다.
curl -X GET http://localhost:8080/tutorial/search
다음 단계
이 앱의 완성된 버전을 보고 다운로드할 수 있습니다. GitHub에서. 전체 앱을 사용하여 자체 애플리케이션의 문제를 해결하거나 기능을 빠르게 테스트할 수 있습니다.
MongoDB는 다음과 같은 개발자 리소스도 제공합니다.