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,72 @@
+## Context
+
+The project currently uses `VectorSearchService` to call Milvus directly through the Java SDK. A previous change added a Spring AI `VectorStore` sidecar and normalized its results, but the production path still uses SDK-only retrieval. Spring AI provides an official Milvus VectorStore starter, so the main path can now move to the framework abstraction without deleting the proven SDK implementation.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Use official Spring AI Milvus VectorStore integration.
+- Keep existing Milvus collection compatibility by configuring field names and embedding dimension.
+- Preserve current `VectorSearchService` public API.
+- Support retrieval mode selection:
+  - `spring-ai`: use VectorStore and fail if unavailable.
+  - `sdk`: use existing SDK path.
+  - `auto`: try VectorStore, then fall back to SDK.
+- Preserve existing score semantics in normalized results by labeling Spring AI scores as `similarity` and SDK scores as `l2_distance`.
+
+**Non-Goals:**
+
+- Do not remove Milvus SDK code.
+- Do not migrate document writes/indexing to Spring AI in this change.
+- Do not change chunking, metadata shape, or evidence post-processing behavior.
+- Do not introduce QueryTransformer, MultiQuery, rerank, or neighbor chunk expansion.
+
+## Decisions
+
+### Decision: VectorSearchService remains the boundary
+
+`LookupKnowledgeTool` will keep calling `VectorSearchService.searchSimilarDocuments(...)`.
+
+Rationale: this protects Agent and AIOps behavior from retrieval implementation churn and keeps the refactor testable.
+
+### Decision: Auto fallback is the default
+
+Configure `retrieval.vector-store.mode=auto` so the system prefers Spring AI VectorStore when available but falls back to the existing SDK path on missing beans or runtime errors.
+
+Rationale: official VectorStore integration may expose schema or scoring differences; fallback keeps the MVP runnable.
+
+### Decision: Existing collection is reused
+
+Spring AI Milvus configuration will map to the current collection:
+
+- id field: `id`
+- content field: `content`
+- embedding field: `vector`
+- metadata field: `metadata`
+- embedding dimension: `1024`
+- metric type: `L2`
+
+Rationale: this avoids reindexing as part of this change and lets golden cases reveal behavior differences first.
+
+### Decision: SDK indexing remains for now
+
+`VectorIndexService` continues writing to Milvus using SDK.
+
+Rationale: replacing both read and write paths at once would make failures harder to isolate. The current change is read-path migration.
+
+## Risks / Trade-offs
+
+- Spring AI filter syntax may not map perfectly to Milvus JSON metadata filters -> keep SDK fallback and add tests for filter expression creation.
+- Spring AI score may be similarity while SDK score is L2 distance -> keep score label explicit.
+- Auto-configuration could create a VectorStore bean against an incompatible collection -> make retrieval mode configurable and validate with golden cases.
+- Keeping two paths adds temporary complexity -> isolate SDK and VectorStore code paths inside `VectorSearchService`.
+
+## Migration Plan
+
+1. Add Spring AI Milvus starter dependency and configuration.
+2. Add retrieval mode properties.
+3. Refactor `VectorSearchService` to prefer VectorStore based on mode.
+4. Preserve and test SDK fallback.
+5. Run targeted tests and the offline RAG baseline.
+6. In a later change, decide whether to migrate indexing/writes after read-path behavior is stable.