feat: integrate spring ai vectorstore fallback

2026-07-05 10:20:29 +08:00
parent b9ec07de57
commit 5c71f5fc79
12 changed files with 541 additions and 42 deletions
@@ -0,0 +1,46 @@
+## ADDED Requirements
+
+### Requirement: Knowledge retrieval SHALL prefer Spring AI VectorStore when configured
+The retrieval service SHALL support Spring AI VectorStore as the preferred vector retrieval abstraction without changing the `lookup_knowledge` tool contract.
+
+#### Scenario: VectorStore mode uses Spring AI
+- **WHEN** retrieval vector store mode is configured as `spring-ai`
+- **THEN** semantic retrieval SHALL query through Spring AI `VectorStore`
+- **AND** the returned candidates SHALL be normalized into the existing vector search result shape
+
+#### Scenario: Auto mode prefers VectorStore
+- **WHEN** retrieval vector store mode is configured as `auto`
+- **AND** a Spring AI `VectorStore` bean is available
+- **THEN** semantic retrieval SHALL attempt Spring AI `VectorStore` before the SDK path
+
+### Requirement: Knowledge retrieval SHALL preserve SDK fallback
+The retrieval service SHALL keep the existing Milvus SDK retrieval implementation available.
+
+#### Scenario: SDK mode bypasses VectorStore
+- **WHEN** retrieval vector store mode is configured as `sdk`
+- **THEN** semantic retrieval SHALL use the existing Milvus SDK path
+
+#### Scenario: Auto fallback uses SDK
+- **WHEN** retrieval vector store mode is `auto`
+- **AND** Spring AI `VectorStore` is unavailable or fails
+- **THEN** semantic retrieval SHALL fall back to the existing Milvus SDK path
+
+### Requirement: Knowledge retrieval SHALL keep score semantics explicit
+The retrieval service SHALL preserve score semantics when results come from different retrieval implementations.
+
+#### Scenario: SDK score remains L2 distance
+- **WHEN** a candidate is returned by the SDK path
+- **THEN** its score semantics SHALL remain compatible with existing L2 distance normalization
+
+#### Scenario: VectorStore score is mapped without changing tool contract
+- **WHEN** a candidate is returned by Spring AI `VectorStore`
+- **THEN** it SHALL be mapped into the existing result shape
+- **AND** trace or comparison code SHALL be able to distinguish it as a VectorStore similarity score when needed
+
+### Requirement: Knowledge retrieval SHALL reuse the existing Milvus collection
+Spring AI Milvus integration SHALL be configured to use the existing collection schema unless explicitly changed.
+
+#### Scenario: Existing field mapping
+- **WHEN** Spring AI Milvus VectorStore is configured
+- **THEN** it SHALL use the existing id, content, vector, and metadata field names
+- **AND** it SHALL use the configured embedding dimension and metric type compatible with existing vectors
@@ -0,0 +1,12 @@
+## ADDED Requirements
+
+### Requirement: Retrieval evaluation SHALL remain stable after VectorStore migration
+The offline RAG retrieval baseline SHALL remain runnable after the main retrieval service gains Spring AI VectorStore support.
+
+#### Scenario: Offline evaluator remains service-free
+- **WHEN** the offline baseline evaluator is run
+- **THEN** it SHALL not require Spring Boot, live Milvus, Spring AI VectorStore, or the SDK path
+
+#### Scenario: Baseline is checked during migration
+- **WHEN** the VectorStore integration change is implemented
+- **THEN** the existing offline baseline evaluator SHALL be run and its generated report noise SHALL not be committed unless the baseline intentionally changes