SuperBizAgent-java/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/design.md

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.