diff --git a/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/.openspec.yaml b/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/.openspec.yaml new file mode 100644 index 0000000..e089cfa --- /dev/null +++ b/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-07-05 diff --git a/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/design.md b/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/design.md new file mode 100644 index 0000000..7bb9f11 --- /dev/null +++ b/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/design.md @@ -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. diff --git a/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/proposal.md b/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/proposal.md new file mode 100644 index 0000000..75a71e7 --- /dev/null +++ b/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/proposal.md @@ -0,0 +1,28 @@ +## Why + +The previous sidecar change proved the project can normalize Spring AI `VectorStore` results without changing the Agent tool boundary. The next step is to integrate the official Spring AI Milvus VectorStore into the main retrieval service while preserving the existing Milvus SDK path as a fallback. + +## What Changes + +- Add the official Spring AI Milvus VectorStore starter dependency. +- Configure Spring AI Milvus to reuse the existing collection, field names, embedding dimension, metric type, and connection settings. +- Update `VectorSearchService` to support selectable retrieval modes: Spring AI VectorStore, SDK, or automatic fallback. +- Preserve the existing `searchSimilarDocuments(query, topK, category)` API used by `lookup_knowledge`. +- Keep the current Milvus SDK implementation available and covered by tests. +- Add tests proving SDK fallback is used when VectorStore is unavailable or fails. +- No breaking API changes. + +## Capabilities + +### New Capabilities +- None. + +### Modified Capabilities +- `rag-knowledge-retrieval`: Add requirements for using Spring AI VectorStore as the preferred retrieval abstraction while preserving SDK fallback and traceable score semantics. +- `rag-retrieval-evaluation`: Add requirements that the offline baseline remains stable after the retrieval implementation changes. + +## Impact + +- Affects `pom.xml`, RAG/Milvus configuration, `VectorSearchService`, and related tests. +- Does not change `lookup_knowledge` tool signature, evidence block format, document chunking, upload API, or `tool_invocation` schema. +- Uses Spring AI Milvus integration but keeps the existing Milvus SDK code path for rollback and compatibility. diff --git a/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/specs/rag-knowledge-retrieval/spec.md b/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/specs/rag-knowledge-retrieval/spec.md new file mode 100644 index 0000000..9f7d9af --- /dev/null +++ b/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/specs/rag-knowledge-retrieval/spec.md @@ -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 diff --git a/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/specs/rag-retrieval-evaluation/spec.md b/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/specs/rag-retrieval-evaluation/spec.md new file mode 100644 index 0000000..91481da --- /dev/null +++ b/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/specs/rag-retrieval-evaluation/spec.md @@ -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 diff --git a/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/tasks.md b/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/tasks.md new file mode 100644 index 0000000..be4244f --- /dev/null +++ b/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/tasks.md @@ -0,0 +1,26 @@ +## 1. Spring AI Milvus Setup + +- [x] 1.1 Add the official Spring AI Milvus VectorStore starter dependency. +- [x] 1.2 Configure Spring AI Milvus to reuse the existing collection field names, dimension, metric type, and connection settings. +- [x] 1.3 Add retrieval mode configuration for `auto`, `spring-ai`, and `sdk`. + +## 2. Retrieval Service Refactor + +- [x] 2.1 Refactor `VectorSearchService` to inject optional Spring AI `VectorStore`. +- [x] 2.2 Implement VectorStore search and map Spring AI `Document` results to existing `SearchResult`. +- [x] 2.3 Preserve the existing SDK search path as a dedicated fallback method. +- [x] 2.4 Route retrieval by configured mode and fallback rules. + +## 3. Tests + +- [x] 3.1 Add tests for SDK mode bypassing VectorStore. +- [x] 3.2 Add tests for auto mode using VectorStore when available. +- [x] 3.3 Add tests for auto mode falling back to SDK when VectorStore fails or is unavailable. +- [x] 3.4 Add tests for category metadata filter behavior. + +## 4. Validation And Archive + +- [x] 4.1 Run targeted retrieval tests. +- [x] 4.2 Run the offline RAG retrieval baseline evaluator. +- [x] 4.3 Run OpenSpec validation. +- [x] 4.4 Review git diff to confirm `lookup_knowledge` API and evidence output remain compatible. diff --git a/openspec/specs/rag-knowledge-retrieval/spec.md b/openspec/specs/rag-knowledge-retrieval/spec.md index e1b520a..8ea61d2 100644 --- a/openspec/specs/rag-knowledge-retrieval/spec.md +++ b/openspec/specs/rag-knowledge-retrieval/spec.md @@ -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 diff --git a/openspec/specs/rag-retrieval-evaluation/spec.md b/openspec/specs/rag-retrieval-evaluation/spec.md index 5f81cea..9689f18 100644 --- a/openspec/specs/rag-retrieval-evaluation/spec.md +++ b/openspec/specs/rag-retrieval-evaluation/spec.md @@ -82,3 +82,14 @@ The sidecar comparison report SHALL show whether the Spring AI sidecar was runna - **WHEN** sidecar comparison is requested but the sidecar is disabled or unavailable - **THEN** the report SHALL mark sidecar status as unavailable - **AND** it SHALL keep current-path baseline results available for review + +### 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 diff --git a/pom.xml b/pom.xml index 46e7893..1608993 100644 --- a/pom.xml +++ b/pom.xml @@ -101,6 +101,10 @@ milvus-sdk-java 2.6.10 + + org.springframework.ai + spring-ai-starter-vector-store-milvus + org.springframework.boot spring-boot-configuration-processor @@ -223,4 +227,4 @@ - \ No newline at end of file + diff --git a/src/main/java/com/superbiz/agent/service/VectorSearchService.java b/src/main/java/com/superbiz/agent/service/VectorSearchService.java index e9baee7..a98d551 100644 --- a/src/main/java/com/superbiz/agent/service/VectorSearchService.java +++ b/src/main/java/com/superbiz/agent/service/VectorSearchService.java @@ -1,5 +1,8 @@ package com.superbiz.agent.service; +import com.fasterxml.jackson.core.JsonProcessingException; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.superbiz.agent.constant.MilvusConstants; import io.milvus.client.MilvusServiceClient; import io.milvus.grpc.SearchResults; import io.milvus.param.R; @@ -7,19 +10,26 @@ import io.milvus.param.dml.SearchParam; import io.milvus.response.SearchResultsWrapper; import lombok.Getter; import lombok.Setter; -import com.superbiz.agent.constant.MilvusConstants; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +import org.springframework.ai.document.Document; +import org.springframework.ai.vectorstore.SearchRequest; +import org.springframework.ai.vectorstore.VectorStore; +import org.springframework.beans.factory.ObjectProvider; import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Service; import java.util.ArrayList; import java.util.Collections; import java.util.List; +import java.util.Map; /** - * 向量搜索服务 - * 负责从 Milvus 中搜索相似向量 + * Vector retrieval facade used by lookup_knowledge. + * + *

The public API stays stable while the implementation can route to Spring AI + * VectorStore, the original Milvus SDK path, or automatic fallback.

*/ @Service public class VectorSearchService { @@ -32,34 +42,84 @@ public class VectorSearchService { @Autowired private VectorEmbeddingService embeddingService; - /** - * 搜索相似文档 - * - * @param query 查询文本 - * @param topK 返回最相似的K个结果 - * @return 搜索结果列表 - */ + @Autowired + private ObjectProvider vectorStoreProvider; + + @Autowired + private ObjectMapper objectMapper; + + @Value("${retrieval.vector-store.mode:auto}") + private String vectorStoreMode = "auto"; + + @Value("${retrieval.normalization.max-l2-distance:2.0}") + private double maxL2Distance = 2.0; + public List searchSimilarDocuments(String query, int topK) { return searchSimilarDocuments(query, topK, null); } - /** - * 搜索相似文档（支持类别过滤） - * - * @param query 查询文本 - * @param topK 返回最相似的K个结果 - * @param category 类别过滤（可选，null 表示不过滤） - * @return 搜索结果列表 - */ public List searchSimilarDocuments(String query, int topK, String category) { + String mode = vectorStoreMode == null ? "auto" : vectorStoreMode.trim().toLowerCase(); + return switch (mode) { + case "sdk" -> searchSimilarDocumentsWithSdk(query, topK, category); + case "spring-ai" -> searchSimilarDocumentsWithVectorStore(query, topK, category); + case "auto" -> searchWithAutoFallback(query, topK, category); + default -> { + logger.warn("Unknown retrieval.vector-store.mode={}, using auto mode", vectorStoreMode); + yield searchWithAutoFallback(query, topK, category); + } + }; + } + + private List searchWithAutoFallback(String query, int topK, String category) { try { - logger.info("开始搜索相似文档, 查询: {}, topK: {}, 类别: {}", query, topK, category); + return searchSimilarDocumentsWithVectorStore(query, topK, category); + } catch (Exception e) { + logger.warn("Spring AI VectorStore retrieval failed, falling back to Milvus SDK: {}", e.getMessage()); + return searchSimilarDocumentsWithSdk(query, topK, category); + } + } + + List searchSimilarDocumentsWithVectorStore(String query, int topK, String category) { + VectorStore vectorStore = vectorStoreProvider != null ? vectorStoreProvider.getIfAvailable() : null; + if (vectorStore == null) { + throw new IllegalStateException("Spring AI VectorStore bean is unavailable"); + } + + logger.info("Starting Spring AI VectorStore search: query={}, topK={}, category={}", query, topK, category); + SearchRequest.Builder builder = SearchRequest.builder() + .query(query) + .topK(topK) + .similarityThresholdAll(); + if (category != null && !category.trim().isEmpty()) { + String filterExpression = "category == '" + escapeFilterValue(category.trim()) + "'"; + builder.filterExpression(filterExpression); + logger.info("Spring AI VectorStore category filter: {}", filterExpression); + } + + List documents = vectorStore.similaritySearch(builder.build()); + List results = new ArrayList<>(); + for (Document document : documents) { + SearchResult result = new SearchResult(); + result.setId(document.getId()); + result.setContent(document.getText()); + result.setMetadata(toJson(document.getMetadata())); + result.setRawScore(document.getScore()); + result.setScoreLabel("similarity"); + result.setScore(toCompatibleL2Distance(document.getScore())); + results.add(result); + } + logger.info("Spring AI VectorStore search complete, candidates={}", results.size()); + return results; + } + + List searchSimilarDocumentsWithSdk(String query, int topK, String category) { + try { + logger.info("Starting Milvus SDK search: query={}, topK={}, category={}", query, topK, category); - // 1. 将查询文本向量化 List queryVector = embeddingService.generateQueryVector(query); - logger.debug("查询向量生成成功, 维度: {}", queryVector.size()); + logger.debug("Query vector generated, dimension={}", queryVector.size()); - // 2. 构建搜索参数 SearchParam.Builder searchParamBuilder = SearchParam.newBuilder() .withCollectionName(MilvusConstants.MILVUS_COLLECTION_NAME) .withVectorFieldName("vector") @@ -69,33 +129,27 @@ public class VectorSearchService { .withOutFields(List.of("id", "content", "metadata")) .withParams("{\"nprobe\":10}"); - // 添加类别过滤 if (category != null && !category.trim().isEmpty()) { String expr = String.format("metadata[\"category\"] == \"%s\"", category); searchParamBuilder.withExpr(expr); - logger.info("添加类别过滤: {}", expr); + logger.info("Milvus SDK category filter: {}", expr); } - SearchParam searchParam = searchParamBuilder.build(); - - // 3. 执行搜索 - R searchResponse = milvusClient.search(searchParam); - + R searchResponse = milvusClient.search(searchParamBuilder.build()); if (searchResponse.getStatus() != 0) { - throw new RuntimeException("向量搜索失败: " + searchResponse.getMessage()); + throw new RuntimeException("Vector search failed: " + searchResponse.getMessage()); } - // 4. 解析搜索结果 SearchResultsWrapper wrapper = new SearchResultsWrapper(searchResponse.getData().getResults()); List results = new ArrayList<>(); - for (int i = 0; i < wrapper.getRowRecords(0).size(); i++) { SearchResult result = new SearchResult(); result.setId((String) wrapper.getIDScore(0).get(i).get("id")); result.setContent((String) wrapper.getFieldData("content", 0).get(i)); result.setScore(wrapper.getIDScore(0).get(i).getScore()); + result.setRawScore((double) result.getScore()); + result.setScoreLabel("l2_distance"); - // 解析 metadata Object metadataObj = wrapper.getFieldData("metadata", 0).get(i); if (metadataObj != null) { result.setMetadata(metadataObj.toString()); @@ -104,25 +158,50 @@ public class VectorSearchService { results.add(result); } - logger.info("搜索完成, 找到 {} 个相似文档", results.size()); + logger.info("Milvus SDK search complete, candidates={}", results.size()); return results; - } catch (Exception e) { - logger.error("搜索相似文档失败", e); - throw new RuntimeException("搜索失败: " + e.getMessage(), e); + logger.error("Milvus SDK vector search failed", e); + throw new RuntimeException("Vector search failed: " + e.getMessage(), e); } } - /** - * 搜索结果类 - */ + private float toCompatibleL2Distance(Double similarity) { + if (similarity == null) { + return (float) maxL2Distance; + } + double bounded = Math.max(0.0, Math.min(1.0, similarity)); + return (float) ((1.0 - bounded) * maxL2Distance); + } + + private String toJson(Map metadata) { + if (metadata == null || metadata.isEmpty()) { + return null; + } + try { + return objectMapper.writeValueAsString(metadata); + } catch (JsonProcessingException e) { + return metadata.toString(); + } + } + + private String escapeFilterValue(String value) { + return value.replace("'", "\\'"); + } + @Setter @Getter public static class SearchResult { private String id; private String content; + /** + * Compatibility score used by existing lookup relevance normalization. + * SDK mode keeps L2 distance; VectorStore mode maps similarity into a + * L2-like distance using retrieval.normalization.max-l2-distance. + */ private float score; + private Double rawScore; + private String scoreLabel; private String metadata; - } } diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml index f6a255d..b921a3f 100644 --- a/src/main/resources/application.yml +++ b/src/main/resources/application.yml @@ -93,6 +93,30 @@ spring: min-idle: 0 ai: + vectorstore: + type: milvus + milvus: + initialize-schema: false + database-name: ${milvus.database} + collection-name: business_knowledge + embedding-dimension: ${milvus.vector-dim} + index-type: IVF_FLAT + metric-type: L2 + index-parameters: '{"nlist":128}' + id-field-name: id + auto-id: false + content-field-name: content + metadata-field-name: metadata + embedding-field-name: vector + client: + host: ${milvus.host} + port: ${milvus.port} + token: ${milvus.token} + username: ${milvus.username} + password: ${milvus.password} + secure: ${milvus.secure} + connect-timeout-ms: ${milvus.timeout} + # --- Chat: DeepSeek (原生) --- deepseek: api-key: sk-1f44696abe644bd684f09cc43f12c557 @@ -133,6 +157,8 @@ rag: # 检索归一化配置 retrieval: + vector-store: + mode: auto # auto | spring-ai | sdk normalization: max-l2-distance: 2.0 # L2 距离上界（BGE-M3 单位向量 = 2.0） highly-relevant-threshold: 0.75 # similarity >= 0.75 → HIGHLY_RELEVANT diff --git a/src/test/java/com/superbiz/agent/service/VectorSearchServiceTest.java b/src/test/java/com/superbiz/agent/service/VectorSearchServiceTest.java new file mode 100644 index 0000000..a867fbb --- /dev/null +++ b/src/test/java/com/superbiz/agent/service/VectorSearchServiceTest.java @@ -0,0 +1,148 @@ +package com.superbiz.agent.service; + +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.Test; +import org.mockito.ArgumentCaptor; +import org.springframework.ai.document.Document; +import org.springframework.ai.vectorstore.SearchRequest; +import org.springframework.ai.vectorstore.VectorStore; +import org.springframework.beans.factory.ObjectProvider; +import org.springframework.test.util.ReflectionTestUtils; + +import java.util.List; +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.doReturn; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.spy; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +class VectorSearchServiceTest { + + @Test + void sdkModeBypassesVectorStore() { + VectorSearchService service = spy(new VectorSearchService()); + setMode(service, "sdk"); + VectorSearchService.SearchResult expected = result("sdk-doc", 0.2f); + doReturn(List.of(expected)) + .when(service).searchSimilarDocumentsWithSdk("query", 3, null); + + List results = service.searchSimilarDocuments("query", 3, null); + + assertEquals(List.of(expected), results); + verify(service, never()).searchSimilarDocumentsWithVectorStore(any(), eq(3), any()); + } + + @Test + void autoModeUsesVectorStoreWhenAvailable() { + VectorStore vectorStore = mock(VectorStore.class); + ObjectProvider provider = mock(ObjectProvider.class); + when(provider.getIfAvailable()).thenReturn(vectorStore); + when(vectorStore.similaritySearch(any(SearchRequest.class))).thenReturn(List.of( + Document.builder() + .id("spring-doc") + .text("spring content") + .metadata(Map.of("_source", "spring.md", "category", "api")) + .score(0.8) + .build() + )); + + VectorSearchService service = new VectorSearchService(); + setMode(service, "auto"); + setVectorStore(service, provider); + + List results = service.searchSimilarDocuments("query", 3, null); + + assertEquals(1, results.size()); + assertEquals("spring-doc", results.get(0).getId()); + assertEquals("similarity", results.get(0).getScoreLabel()); + assertEquals(0.8, results.get(0).getRawScore(), 0.0001); + assertEquals(0.4f, results.get(0).getScore(), 0.0001); + assertTrue(results.get(0).getMetadata().contains("spring.md")); + } + + @Test + void autoModeFallsBackToSdkWhenVectorStoreFails() { + VectorStore vectorStore = mock(VectorStore.class); + ObjectProvider provider = mock(ObjectProvider.class); + when(provider.getIfAvailable()).thenReturn(vectorStore); + when(vectorStore.similaritySearch(any(SearchRequest.class))).thenThrow(new RuntimeException("vectorstore down")); + + VectorSearchService service = spy(new VectorSearchService()); + setMode(service, "auto"); + setVectorStore(service, provider); + VectorSearchService.SearchResult fallback = result("sdk-doc", 0.3f); + doReturn(List.of(fallback)) + .when(service).searchSimilarDocumentsWithSdk("query", 3, null); + + List results = service.searchSimilarDocuments("query", 3, null); + + assertEquals(List.of(fallback), results); + } + + @Test + void autoModeFallsBackToSdkWhenVectorStoreUnavailable() { + ObjectProvider provider = mock(ObjectProvider.class); + when(provider.getIfAvailable()).thenReturn(null); + + VectorSearchService service = spy(new VectorSearchService()); + setMode(service, "auto"); + setVectorStore(service, provider); + VectorSearchService.SearchResult fallback = result("sdk-doc", 0.3f); + doReturn(List.of(fallback)) + .when(service).searchSimilarDocumentsWithSdk("query", 3, null); + + List results = service.searchSimilarDocuments("query", 3, null); + + assertEquals(List.of(fallback), results); + } + + @Test + void vectorStoreSearchUsesCategoryFilter() { + VectorStore vectorStore = mock(VectorStore.class); + ObjectProvider provider = mock(ObjectProvider.class); + when(provider.getIfAvailable()).thenReturn(vectorStore); + when(vectorStore.similaritySearch(any(SearchRequest.class))).thenReturn(List.of()); + VectorSearchService service = new VectorSearchService(); + setMode(service, "spring-ai"); + setVectorStore(service, provider); + + service.searchSimilarDocuments("query", 5, "api"); + + ArgumentCaptor requestCaptor = ArgumentCaptor.forClass(SearchRequest.class); + verify(vectorStore).similaritySearch(requestCaptor.capture()); + SearchRequest request = requestCaptor.getValue(); + assertEquals("query", request.getQuery()); + assertEquals(5, request.getTopK()); + assertTrue(request.hasFilterExpression()); + assertTrue(request.toString().contains("category")); + assertTrue(request.toString().contains("api")); + } + + private static void setMode(VectorSearchService service, String mode) { + ReflectionTestUtils.setField(service, "vectorStoreMode", mode); + } + + private static void setVectorStore(VectorSearchService service, ObjectProvider provider) { + ReflectionTestUtils.setField(service, "vectorStoreProvider", provider); + ReflectionTestUtils.setField(service, "objectMapper", new ObjectMapper()); + ReflectionTestUtils.setField(service, "maxL2Distance", 2.0); + } + + private static VectorSearchService.SearchResult result(String id, float score) { + VectorSearchService.SearchResult result = new VectorSearchService.SearchResult(); + result.setId(id); + result.setScore(score); + result.setRawScore((double) score); + result.setScoreLabel("l2_distance"); + result.setContent("content"); + result.setMetadata("{}"); + return result; + } +}