Spring AI Part-5
Spring AI Tutorial – Part 5
Read a text file, split it into chunks and search it with Oracle AI Vector Search.
1What You Will Learn
Part 4 kept three snippets in memory. Now read a fictional support policy file and store chunks and embeddings in Oracle Database. Data remains after an application restart while the database volume remains.
This part focuses on retrieval and returns matching text, not an AI-generated answer. Part 4's endpoint still uses its separate in-memory store; it does not automatically read Oracle data.
Official documentation: ETL pipeline and Oracle Vector Store.
2Document Indexing Flow
Text file -> TextReader + metadata -> TokenTextSplitter
-> Ollama embeddings -> Oracle Vector Store (persistent)
Question -> Ollama embedding -> filtered similarity search
-> matching chunks for an agent to review
Chunks allow smaller passages to be retrieved instead of a whole document. TokenTextSplitter copies metadata to the chunks. This small file may produce only one chunk; evaluate settings and retrieval quality for larger documents.
3Local Oracle Setup
Oracle Database 23ai (23.4+) with AI Vector Search is required; ordinary SQL on older Oracle versions is not sufficient. For the local example, Docker Desktop and Ollama are required. First ensure the container name, volume and port are not already in use.
Choose separate admin and application passwords for a new demo. They are visible while typing and stored in the container environment; use credentials only for this local demo.
$env:ORACLE_PASSWORD = Read-Host "Choose a local Oracle admin password"
$env:APP_USER_PASSWORD = Read-Host "Choose a local Oracle application password"
$env:SPRING_DATASOURCE_PASSWORD = $env:APP_USER_PASSWORD
docker run -d --name springai-oracle-demo -p 127.0.0.1:1521:1521 `
-e ORACLE_PASSWORD -e APP_USER=springai -e APP_USER_PASSWORD `
-v springai-oracle-demo-data:/opt/oracle/oradata gvenzl/oracle-free:23-slim
docker logs springai-oracle-demo
Wait for the database-ready message in the logs. On first initialization the app user is created in FREEPDB1; new environment passwords do not change existing credentials on a reused volume. Start the application in the same PowerShell session so the datasource password is available. The named volume retains data after container removal; deleting the volume deletes the data.
As in Part 4, run Ollama and pull llama3.2 and nomic-embed-text. The embedding model must be available during indexing and search.
4Project Configuration
Keep the Java 17+, Spring Boot 3.5.16 and Spring AI 1.1.8 project from Parts 1–4. Add the Oracle vector store and JDBC starters to the existing dependencies. If you added the old Part 5 pgvector starter, remove it and its PostgreSQL properties.
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-vector-store-oracle</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
Add the following to the existing application.properties. The password comes from the environment variable above, not the file.
spring.datasource.url=jdbc:oracle:thin:@//127.0.0.1:1521/FREEPDB1
spring.datasource.username=springai
spring.ai.vectorstore.oracle.initialize-schema=true
spring.ai.vectorstore.oracle.dimensions=768
spring.ai.vectorstore.oracle.index-type=NONE
spring.ai.vectorstore.oracle.distance-type=COSINE
spring.ai.vectorstore.oracle.forced-normalization=true
768 dimensions are for this example's nomic-embed-text model. Schema initialization creates the Oracle vector table; the app user needs permission and quota to create it. If changing models or dimensions, plan a migration and re-embedding; do not delete a shared table.
The Oracle Vector Store requires forced-normalization=true and COSINE or DOT distance for the 0.60 similarity threshold. This normalizes vectors during ingestion and search; re-index any previously indexed unnormalized data.
NONE uses exact search for the small demo dataset. Evaluate index type and recall against your production workload.
5Example Text File
Create the UTF-8 file src/main/resources/support-policy.txt. This is a fictional policy, not a real business rule.
Delivery support: If an order is delayed, ask for the order reference.
Check the latest tracking status before advising the customer.
Do not promise a delivery date without verification.
Billing support: Ask for an invoice reference and review the charge.
Never ask the customer to send full payment card details.
Account support: Direct the customer to the account recovery page.
Never request a customer's password.
The file is on the classpath, so after changing it rebuild and restart the application, then run the index endpoint again. Restarting alone does not update previously indexed text.
6Java Indexing and Search API
Create src/main/java/com/example/support/SupportDocumentController.java in the same package. Fixed metadata is a demo filter, not authorization.
package com.example.support;
import java.util.List;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import org.springframework.ai.document.Document;
import org.springframework.ai.reader.TextReader;
import org.springframework.ai.transformer.splitter.TokenTextSplitter;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@Service
class DemoDocumentService {
private static final String FILTER =
"tenant == 'demo' && source_id == 'support-policy-v1'";
private final VectorStore store;
DemoDocumentService(VectorStore store) {
this.store = store;
}
@Transactional
public int index() {
TextReader reader = new TextReader(
new ClassPathResource("support-policy.txt"));
reader.getCustomMetadata().put("tenant", "demo");
reader.getCustomMetadata().put("source_id", "support-policy-v1");
List<Document> chunks = new TokenTextSplitter().apply(reader.read());
if (chunks.isEmpty()) {
throw new IllegalStateException("The policy produced no chunks");
}
store.delete(FILTER);
store.add(chunks);
return chunks.size();
}
public List<SearchHit> search(String question) {
return store.similaritySearch(SearchRequest.builder()
.query(question)
.topK(3)
.similarityThreshold(0.60)
.filterExpression(FILTER)
.build()).stream()
.map(d -> new SearchHit(d.getId(), d.getText()))
.toList();
}
record SearchHit(String id, String text) {}
}
@RestController
@RequestMapping("/api/support/documents")
class SupportDocumentController {
private final DemoDocumentService service;
SupportDocumentController(DemoDocumentService service) {
this.service = service;
}
@PostMapping("/index")
IndexReply index() {
return new IndexReply(service.index());
}
@PostMapping("/search")
SearchReply search(@Valid @RequestBody SearchInput request) {
return new SearchReply(service.search(request.question()));
}
record SearchInput(@NotBlank @Size(max = 1500) String question) {}
record IndexReply(int chunks) {}
record SearchReply(List<DemoDocumentService.SearchHit> matches) {}
}
The index endpoint deletes old chunks with the fixed demo metadata and adds new chunks. Delete and insert run in a database transaction; errors roll it back. This example assumes one indexing request at a time; concurrent indexing needs locking and versioned publishing.
The 0.60 search threshold is illustrative; evaluate it for your model and data. Indexing does not call an AI chat model.
7Index and Search
With the database and Ollama running, start the application in the same PowerShell session. Then index and search from another PowerShell. Indexing is explicit; application startup does not index the file itself.
mvn spring-boot:run
$base = "http://127.0.0.1:8080/api/support/documents"
Invoke-RestMethod -Method Post -Uri "$base/index"
$body = @{ question = "What should I ask for a delayed order?" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "$base/search" `
-ContentType "application/json" -Body $body
The index response contains a chunks count. Search returns a matches array with id and text per item; it is empty when there is no match. IDs may change after re-indexing. Blank or over-1,500-character questions return HTTP 400.
Connect to FREEPDB1 as the demo app user in Oracle SQL Developer and use this SQL to count all rows in the demo table. This is not a tenant-filtered search.
SELECT COUNT(*) AS chunk_count FROM SPRING_AI_VECTORS;
Restart the application and search without re-indexing: the database retains the old chunks. Results depend on the model and threshold. If the database or Ollama is unavailable, inspect logs and fix the problem before retrying.
8Live Chunk Simulation
This browser-only demo treats each non-empty line as a chunk. It does not run the real token splitter, embeddings, database or API, and sends no network requests.
9Production Limitations
- The fixed tenant filter is not access control. A real service must enforce server-side authorization and tenant/document isolation from authenticated identity.
- Use restricted database roles, secret management, backups, retention, deletion and auditing. Replace demo schema initialization with a production migration process.
- Untrusted documents can contain prompt injection and sensitive data. Measure retrieval quality, validate output and keep human review.
- Plan versioning, failure recovery, concurrent updates and embedding-model migrations for production ingestion.
10Quiz and Next Learning
Next: supply retrieved Oracle chunks to ChatClient as context for grounded answers, then explore citations, retrieval evaluation and secure document access.
Practice: add a fictional policy, rebuild and re-index, then test retrieval with known and unrelated questions.
You completed Part 5 of the Spring AI series. — A143MK
No comments :
Post a Comment
Please Write a Message for Programming or something else 🙏