Spring AI 통합 시작하기
이 페이지의 내용
Atlas Vector Search를 Spring AI와 통합한 후 MongoDB Java Sync Driver를 사용하여 생성형 인공지능 애플리케이션을 빌드할 수 있습니다. 이 튜토리얼에서는 Atlas Vector Search를 Spring AI의 벡터 저장소로 사용하는 방법과 데이터에서 시맨틱 검색을 수행하는 방법을 설명합니다.
구체적으로 다음 조치를 수행합니다.
환경을 설정합니다.
Atlas Vector Search 인덱스를 생성합니다.
벡터 임베딩 데이터를 Atlas에 저장합니다.
데이터에 대해 시맨틱 검색 쿼리를 실행합니다.
배경
Spring AI는 Spring의 애플리케이션 프레임워크로, 다양한 AI 서비스 및 플러그인을 애플리케이션과 결합할 수 있습니다. 다양한 텍스트 기반 AI 사용 사례에 Spring AI를 사용할 수 있습니다.
Atlas를 벡터 데이터베이스로 사용하고 Atlas Vector Search를 사용하여 데이터에서 의미상 유사한 문서를 검색하여 RAG를 구현할 수 있습니다. RAG에 대해 자세히 알아보려면 Atlas Vector Search를 사용한 검색 증강 생성(RAG)을 참조하세요.
전제 조건
이 튜토리얼을 완료하려면 다음 조건을 충족해야 합니다.
MongoDB 버전 6.0.11, 7.0.2, 이상을 실행하는 Atlas 클러스터입니다. 귀하의 IP 주소가 Atlas 프로젝트의 액세스 목록에 포함되어 있는지 확인하세요.
OpenAI API 키. API 요청에 사용할 수 있는 크레딧이 있는 유료 OpenAI 계정이 있어야 합니다. OpenAI 계정 등록에 대한 자세한 내용은 OpenAI API 웹사이트를 참조하세요.
Java 애플리케이션을 설정하고 실행하기 위한 환경입니다. IntelliJ IDEA 또는 Eclipse IDE와 같은 통합 개발 환경(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 및 자동 구성 라이브러리를 애플리케이션에 추가합니다.pom.xml<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 Materials)에 대한dependencyManagement
항목이 포함되어 있는지 확인합니다.중요
Spring AI BOM에 사용되는
spring-ai.version
상수를1.0.0-SNAPSHOT
으로 설정하여 최신 Spring AI 기능을 애플리케이션에 구현합니다.Spring AI BOM에 대해 자세히 알아보려면 Spring AI 문서의 종속성 관리를 섹션을 참조하세요.
마지막으로,
pom.xml
파일의repositories
항목에 Spring AI Snapshot 리포지토리를 추가합니다.pom.xml<repository> <id>spring-snapshots</id> <name>Spring Snapshots</name> <url>https://repo.spring.io/snapshot</url> <releases> <enabled>false</enabled> </releases> </repository> 이러한 리포지토리에 대한 자세한 내용은 Spring AI 설명서의 마일스톤 및 스냅샷 리포지토리 추가 섹션을 참조하세요.
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 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
객체를 만드는 방법을 보여줍니다.
import 문을 추가합니다.
다음 코드를 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;
참조 애플리케이션 속성.
애플리케이션 속성 파일에 설정한 값을 참조하기 위해 다음 코드를 Config.java
파일에 붙여 넣습니다.
public class Config { private String openAiKey; private String databaseName; private String collectionName; private String indexName; private String mongoUri; private Boolean initSchema; // Add beans here... }
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()
메서드를 사용하여 시맨틱 검색 쿼리를 실행하는 방법을 보여줍니다.
import 문을 추가합니다.
다음 코드를 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 Sync Driver의 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
Documents added successfully!
팁
엔드포인트에 액세스한 후 클러스터의 springai_test.vector_store
컬렉션으로 이동하여 Atlas UI에서 벡터 임베딩을 볼 수 있습니다.
그런 다음 터미널에서 다음 명령을 실행하여 search
엔드포인트에 액세스하여 시맨틱 검색을 수행합니다.
curl -X GET http://localhost:8080/tutorial/search
[{"content":"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.","metadata":{"type":"post","author":"B"}},{"content":"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.","metadata":{"type":"post","author":"A"}}]
다음 단계
GitHub에서 이 앱의 완성된 버전을 확인하고 다운로드할 수 있습니다. 전체 앱을 사용하여 자체 애플리케이션의 문제를 해결하거나 기능을 빠르게 테스트할 수 있습니다.
MongoDB는 다음과 같은 개발자 리소스도 제공합니다.