SuperBizAgent-java/interview/rag-vectorstore-live-acceptance.md

RAG VectorStore Live 验收说明

1. 目的

本文记录 RAG 检索重构的 live 验收结论。

这次重构的目标不只是接入 Spring AI 抽象，而是证明线上读路径能够：

• 优先使用 Spring AI VectorStore 做 Milvus 检索。
• 保留原 Milvus SDK 作为 fallback。
• 保持 lookup_knowledge 工具契约稳定。
• 保持基于 L2 distance 的相关性归一化兼容。

2. 当前检索形态

lookup_knowledge / /api/search/similar
  -> VectorSearchService.searchSimilarDocuments(...)
      -> retrieval.vector-store.mode
          -> auto
              -> Spring AI VectorStore
              -> VectorStore 失败时 fallback 到 Milvus SDK
          -> spring-ai
              -> 只走 Spring AI VectorStore
          -> sdk
              -> 只走 Milvus SDK

3. 已验证配置

live Milvus/Zilliz 数据库中存在 collection：

biz

Spring AI VectorStore 配置与 SDK 使用的 collection 对齐：

spring:
  ai:
    vectorstore:
      type: milvus
      milvus:
        initialize-schema: false
        database-name: ${milvus.database}
        collection-name: biz
        embedding-dimension: ${milvus.vector-dim}
        metric-type: L2
        id-field-name: id
        content-field-name: content
        metadata-field-name: metadata
        embedding-field-name: vector

为什么重要：早期配置使用 business_knowledge，而真实 collection 是 biz。这个错配证明了 fallback 生效，但也说明修正前 VectorStore 不是成功主路径。

4. 验收命令

健康检查：

Invoke-RestMethod `
  -Uri "http://127.0.0.1:9900/milvus/health" `
  -Method Get

期望：

{
  "collections": ["biz"],
  "message": "ok"
}

直接检索：

Invoke-RestMethod `
  -Uri "http://127.0.0.1:9900/api/search/similar?query=ERR_TIMEOUT&topK=3" `
  -Method Get

期望结果形态：

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "content": "### ERR_TIMEOUT ...",
      "score": 0.5662,
      "rawScore": 0.4337,
      "scoreLabel": "similarity",
      "metadata": {
        "distance": 0.5662,
        "title": "ERR_TIMEOUT",
        "category": "api"
      }
    }
  ]
}

5. 日志证明了什么

collection 修正前：

Starting Spring AI VectorStore search
Spring AI VectorStore retrieval failed, falling back to Milvus SDK
Starting Milvus SDK search

collection 修正后：

Starting Spring AI VectorStore search: query=ERR_TIMEOUT
Spring AI VectorStore search complete, candidates=3

这证明：

• auto 模式确实先尝试 VectorStore。
• VectorStore 失败时 fallback 可用。
• 配置对齐后，主路径是 Spring AI VectorStore，而不是 SDK fallback。

6. 分数语义

项目保留三个分数字段：

rawScore    -> 当前检索实现的原始分数
scoreLabel  -> rawScore 的语义
score       -> lookup relevance normalization 使用的兼容分数

SDK：

rawScore = L2 distance
scoreLabel = l2_distance
score = L2 distance

Spring AI VectorStore：

rawScore = Spring AI similarity score
scoreLabel = similarity
score = Milvus distance metadata when available

使用 metadata.distance 的原因：LookupKnowledgeTool 已经基于 L2 distance 做相关性归一化。Spring AI Milvus 主分数是 similarity，但 metadata 中仍有 Milvus distance。用 distance 保持旧逻辑稳定，同时通过 rawScore 暴露新语义。

7. 回归检查

目标测试：

mvn -q "-Dtest=VectorSearchServiceTest,LookupKnowledgeToolTest" test

相关 spec：

openspec.cmd validate rag-knowledge-retrieval --specs
openspec.cmd validate rag-retrieval-evaluation --specs

diff 检查：

git diff --check

验收结论：

目标测试通过。
相关 spec 通过。
diff-check 无错误。

8. 验收结论

VectorStore 读路径可以接受：

• Spring AI VectorStore 已集成，并在 auto 模式中优先使用。
• SDK fallback 保留且已被实际验证。
• live collection 配置与现有 Milvus collection 对齐。
• lookup_knowledge 对外契约保持稳定。
• 旧的 L2 relevance normalization 仍兼容。

写入和索引路径仍使用 Milvus SDK。这是有意的分阶段迁移，不是验收失败项。