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
@@ -106,3 +106,48 @@ The sidecar retrieval path SHALL expose results in a comparable structure aligne
 #### Scenario: Score semantics are explicit
 - **WHEN** current retrieval and sidecar retrieval scores are compared
 - **THEN** the report SHALL label score semantics by path instead of assuming direct numeric equivalence
+
+### 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