73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
## 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.
|