Skip to content

Commit f30c5de

Browse files
abhiraj2abhiraj2
committed
Added new spring-ai demo tutorial
1 parent 7533d57 commit f30c5de

File tree

1 file changed

+222
-0
lines changed

1 file changed

+222
-0
lines changed

‎tutorial/markdown/java/spring-ai.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
---
2+
# frontmatter
3+
path: "/tutorial-java-spring-ai"
4+
title: Couchbase Vector Search using Spring AI
5+
short_title: Spring AI Vector Storage
6+
description:
7+
- Learn how to configure and use couchbase vector search with Spring AI
8+
- Learn how to vectorize data with Spring AI
9+
- Learn how to retrieve vector data from Couchbase
10+
content_type: tutorial
11+
filter: sdk
12+
technology:
13+
- connectors
14+
- vector search
15+
tags:
16+
- LangChain
17+
- Artificial Intelligence
18+
- Data Ingestion
19+
sdk_language:
20+
- java
21+
length: 10 Mins
22+
---
23+
24+
## About This Tutorial
25+
This tutorial will show how to use a Couchbase database cluster as a Spring AI embedding storage.
26+
27+
## Example Source code
28+
Example source code for this tutorial can be obtained from [Spring AI demo application with Couchbase Vector Store](https://github.com/couchbase-examples/couchbase-spring-ai-demo).
29+
To do this, clone the repository using git:
30+
```shell
31+
git clone https://github.com/couchbase-examples/couchbase-spring-ai-demo.git
32+
cd couchbase-spring-ai-demo
33+
```
34+
35+
### What is Spring AI?
36+
37+
Spring AI is an extension of the Spring Framework that simplifies the integration of AI capabilities into Spring applications. It provides abstractions and integrations for working with various AI services and models, making it easier for developers to incorporate AI functionality without having to manage low-level implementation details.
38+
39+
Key features of Spring AI include:
40+
- **Model integrations**: Pre-built connectors to popular AI models (like OpenAI)
41+
- **Prompt engineering**: Tools for crafting and managing prompts
42+
- **Vector stores**: Abstractions for storing and retrieving vector embeddings
43+
- **Document processing**: Utilities for working with unstructured data
44+
45+
### Why Use Spring AI?
46+
47+
Spring AI brings several benefits to Java developers:
48+
1. **Familiar programming model**: Uses Spring's dependency injection and configuration
49+
2. **Abstraction layer**: Provides consistent interfaces across different AI providers
50+
3. **Enterprise-ready**: Built with production use cases in mind
51+
4. **Simplified development**: Reduces boilerplate code for AI integrations
52+
53+
54+
## Couchbase Embedding Store
55+
Couchbase spring-ai integration stores each embedding in a separate document and uses an FTS vector index to perform
56+
queries against stored vectors. Currently, it supports storing embeddings and their metadata, as well as removing
57+
embeddings. Filtering selected by vector search embeddings by their metadata was not supported at the moment of writing
58+
this tutorial.
59+
60+
## Project Structure
61+
62+
```
63+
src/main/java/com/couchbase_spring_ai/demo/
64+
├── Config.java # Application configuration
65+
├── Controller.java # REST API endpoints
66+
└── CouchbaseSpringAiDemoApplications.java # Application entry point
67+
68+
src/main/resources/
69+
├── application.properties # Application settings
70+
└── bbc_news_data.json # Sample data
71+
```
72+
73+
## Setup and Configuration
74+
75+
### Prerequisites
76+
- [Couchbase Capella](https://docs.couchbase.com/cloud/get-started/create-account.html) account or locally installed [Couchbase Server](/tutorial-couchbase-installation-options)
77+
- Java 21
78+
- Maven
79+
- Couchbase Server running locally
80+
- OpenAI API key
81+
82+
### Configuration Details
83+
84+
The application is configured in `application.properties`:
85+
86+
```properties
87+
spring.application.name=spring-ai-demo
88+
spring.ai.openai.api-key=your-openai-api-key
89+
spring.couchbase.connection-string=couchbase://127.0.0.1
90+
spring.couchbase.username=Administrator
91+
spring.couchbase.password=password
92+
```
93+
94+
## Key Components
95+
96+
### Configuration Class (`Config.java`)
97+
98+
This class creates the necessary beans for:
99+
- Connecting to Couchbase cluster
100+
- Setting up the OpenAI embedding model (OpenAI key is assumed to be stored as an environment variable.)
101+
- Configuring the Couchbase vector store
102+
103+
```java
104+
public class Config {
105+
@Value("${spring.couchbase.connection-string}")
106+
private String connectionUrl;
107+
@Value("${spring.couchbase.username}")
108+
private String username;
109+
@Value("${spring.couchbase.password}")
110+
private String password;
111+
@Value("${spring.ai.openai.api-key}")
112+
private String openaiKey;
113+
114+
public Config() {
115+
}
116+
117+
@Bean
118+
public Cluster cluster() {
119+
return Cluster.connect(this.connectionUrl, this.username, this.password);
120+
}
121+
122+
@Bean
123+
public Boolean initializeSchema() {
124+
return true;
125+
}
126+
127+
@Bean
128+
public EmbeddingModel embeddingModel() {
129+
return new OpenAiEmbeddingModel(OpenAiApi.builder().apiKey(this.openaiKey).build());
130+
}
131+
132+
@Bean
133+
public VectorStore couchbaseSearchVectorStore(Cluster cluster,
134+
EmbeddingModel embeddingModel,
135+
Boolean initializeSchema) {
136+
return CouchbaseSearchVectorStore
137+
.builder(cluster, embeddingModel)
138+
.bucketName("test")
139+
.scopeName("test")
140+
.collectionName("test")
141+
.initializeSchema(initializeSchema)
142+
.build();
143+
}
144+
}
145+
```
146+
147+
The vector store is configured to use:
148+
- Bucket: "test"
149+
- Scope: "test"
150+
- Collection: "test"
151+
152+
### Vector Store Integration
153+
154+
The application uses `CouchbaseSearchVectorStore`, which:
155+
- Stores document embeddings in Couchbase
156+
- Provides similarity search capabilities
157+
- Maintains metadata alongside vector embeddings
158+
159+
### Vector Index
160+
The embedding store uses an FTS vector index in order to perform vector similarity lookups. If provided with a name for
161+
vector index that does not exist on the cluster, the store will attempt to create a new index with default
162+
configuration based on the provided initialization settings. It is recommended to manually review the settings for the
163+
created index and adjust them according to specific use cases. More information about vector search and FTS index
164+
configuration can be found at [Couchbase Documentation](https://docs.couchbase.com/server/current/vector-search/vector-search.html).
165+
166+
### Controller Class (`Controller.java`)
167+
168+
Provides REST API endpoints:
169+
- `/tutorial/load`: Loads sample BBC news data into Couchbase
170+
- `/tutorial/search`: Performs a semantic search for sports-related news articles
171+
172+
##### Load functionality
173+
```java
174+
...
175+
Document doc = new Document(String.format("%s", i + 1), j.getString("content"), Map.of("title", j.getString("title")))
176+
...
177+
this.couchbaseSearchVectorStore.add(doc);
178+
...
179+
```
180+
181+
- A new Document object is created. The document's ID is generated using String.format("%s", i + 1), which increments an index i to ensure unique IDs and same ID across calls. Metadata is added as a map with a key "title" and its corresponding value from a previously parsed JSON.
182+
- The document is then added to the couchbaseSearchVectorStore, which is an instance of a class that handles storing documents in Couchbase. This operation involves vectorizing the document content and storing it in a format suitable for vector search.
183+
184+
185+
##### Search functionality
186+
```java
187+
List<Document> results = this.couchbaseSearchVectorStore.similaritySearch(SearchRequest.builder()
188+
.query("Give me some sports news")
189+
.similarityThreshold((double)0.75F)
190+
.topK(15)
191+
.build());
192+
193+
return (List)results.stream()
194+
.map((doc) -> Map.of("content", doc.getText(), "metadata", doc.getMetadata()))
195+
.collect(Collectors.toList());
196+
```
197+
198+
- A SearchRequest is built with a query string "Give me some sports news". The similarityThreshold is set to 0.75, meaning only documents with a similarity score above this threshold will be considered relevant. The topK parameter is set to 15, indicating that the top 15 most similar documents should be returned.
199+
- The similaritySearch method of couchbaseSearchVectorStore is called with the built SearchRequest. This method performs a vector similarity search against the stored documents.
200+
- The results, which are a list of Document objects, are processed using Java Streams. Each document is mapped to a simplified structure containing its text content and metadata. The final result is a list of maps, each representing a document with its content and metadata.
201+
202+
## Using the Application
203+
204+
### Loading Data
205+
206+
1. Start the application
207+
2. Make a GET request to `http://localhost:8080/tutorial/load`
208+
3. This loads BBC news articles from the included JSON file into Couchbase, creating embeddings via OpenAI
209+
210+
### Performing Similarity Searches
211+
212+
1. Make a GET request to `http://localhost:8080/tutorial/search`
213+
2. The application will search for documents semantically similar to "Give me some sports news"
214+
3. Results are returned with content and metadata, sorted by similarity score
215+
216+
217+
## Resources
218+
219+
- [Spring AI Documentation](https://docs.spring.io/spring-ai/reference/index.html)
220+
- [Couchbase Vector Search](https://docs.couchbase.com/server/current/fts/vector-search.html)
221+
- [OpenAI Embeddings Documentation](https://platform.openai.com/docs/guides/embeddings)
222+
- [Spring Boot Documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/)

0 commit comments

Comments
 (0)