docs: reorganize MVP interview documentation
This commit is contained in:
aruo
@@ -1,17 +1,17 @@
|
||||
# RAG VectorStore Live Acceptance
|
||||
# RAG VectorStore Live 验收说明
|
||||
|
||||
## Purpose
|
||||
## 1. 目的
|
||||
|
||||
This note records the live acceptance result for the RAG retrieval refactor.
|
||||
本文记录 RAG 检索重构的 live 验收结论。
|
||||
|
||||
The goal of this refactor was not only to add a Spring AI abstraction, but to prove that the production retrieval path can:
|
||||
这次重构的目标不只是接入 Spring AI 抽象，而是证明线上读路径能够：
|
||||
|
||||
- Prefer Spring AI `VectorStore` for Milvus retrieval.
|
||||
- Preserve the existing Milvus SDK path as fallback.
|
||||
- Keep the `lookup_knowledge` tool contract stable.
|
||||
- Keep L2-distance based relevance normalization compatible.
|
||||
- 优先使用 Spring AI `VectorStore` 做 Milvus 检索。
|
||||
- 保留原 Milvus SDK 作为 fallback。
|
||||
- 保持 `lookup_knowledge` 工具契约稳定。
|
||||
- 保持基于 L2 distance 的相关性归一化兼容。
|
||||
|
||||
## Current Retrieval Shape
|
||||
## 2. 当前检索形态
|
||||
|
||||
```text
|
||||
lookup_knowledge / /api/search/similar
|
||||
@@ -19,22 +19,22 @@ lookup_knowledge / /api/search/similar
|
||||
-> retrieval.vector-store.mode
|
||||
-> auto
|
||||
-> Spring AI VectorStore
|
||||
-> fallback to Milvus SDK if VectorStore fails
|
||||
-> VectorStore 失败时 fallback 到 Milvus SDK
|
||||
-> spring-ai
|
||||
-> Spring AI VectorStore only
|
||||
-> 只走 Spring AI VectorStore
|
||||
-> sdk
|
||||
-> Milvus SDK only
|
||||
-> 只走 Milvus SDK
|
||||
```
|
||||
|
||||
## Configuration Verified
|
||||
## 3. 已验证配置
|
||||
|
||||
The live Milvus/Zilliz database contains the collection:
|
||||
live Milvus/Zilliz 数据库中存在 collection：
|
||||
|
||||
```text
|
||||
biz
|
||||
```
|
||||
|
||||
The Spring AI VectorStore configuration was aligned with the existing SDK collection:
|
||||
Spring AI VectorStore 配置与 SDK 使用的 collection 对齐：
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
@@ -53,11 +53,11 @@ spring:
|
||||
embedding-field-name: vector
|
||||
```
|
||||
|
||||
Why this matters: the earlier config used `business_knowledge`, but the SDK path and real collection use `biz`. That mismatch proved the fallback worked, but it also meant VectorStore was not the successful main path until the config was corrected.
|
||||
为什么重要：早期配置使用 `business_knowledge`，而真实 collection 是 `biz`。这个错配证明了 fallback 生效，但也说明修正前 VectorStore 不是成功主路径。
|
||||
|
||||
## Commands Used
|
||||
## 4. 验收命令
|
||||
|
||||
Health check:
|
||||
健康检查：
|
||||
|
||||
```powershell
|
||||
Invoke-RestMethod `
|
||||
@@ -65,7 +65,7 @@ Invoke-RestMethod `
|
||||
-Method Get
|
||||
```
|
||||
|
||||
Observed result:
|
||||
期望：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -74,7 +74,7 @@ Observed result:
|
||||
}
|
||||
```
|
||||
|
||||
Direct retrieval check:
|
||||
直接检索：
|
||||
|
||||
```powershell
|
||||
Invoke-RestMethod `
|
||||
@@ -82,7 +82,7 @@ Invoke-RestMethod `
|
||||
-Method Get
|
||||
```
|
||||
|
||||
Observed result shape:
|
||||
期望结果形态：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -90,7 +90,6 @@ Observed result shape:
|
||||
"message": "success",
|
||||
"data": [
|
||||
{
|
||||
"id": "f7dff7c8-5665-3145-9f75-ef741528b914",
|
||||
"content": "### ERR_TIMEOUT ...",
|
||||
"score": 0.5662,
|
||||
"rawScore": 0.4337,
|
||||
@@ -105,41 +104,40 @@ Observed result shape:
|
||||
}
|
||||
```
|
||||
|
||||
## What The Logs Proved
|
||||
## 5. 日志证明了什么
|
||||
|
||||
Before collection alignment:
|
||||
collection 修正前：
|
||||
|
||||
```text
|
||||
Starting Spring AI VectorStore search
|
||||
SearchRequest collectionName:business_knowledge failed
|
||||
Spring AI VectorStore retrieval failed, falling back to Milvus SDK
|
||||
Starting Milvus SDK search
|
||||
```
|
||||
|
||||
After collection alignment:
|
||||
collection 修正后：
|
||||
|
||||
```text
|
||||
Starting Spring AI VectorStore search: query=ERR_TIMEOUT
|
||||
Spring AI VectorStore search complete, candidates=3
|
||||
```
|
||||
|
||||
This proves:
|
||||
这证明：
|
||||
|
||||
- `auto` mode really attempts VectorStore first.
|
||||
- The fallback is functional when VectorStore fails.
|
||||
- After config alignment, the main path is Spring AI VectorStore rather than SDK fallback.
|
||||
- `auto` 模式确实先尝试 VectorStore。
|
||||
- VectorStore 失败时 fallback 可用。
|
||||
- 配置对齐后，主路径是 Spring AI VectorStore，而不是 SDK fallback。
|
||||
|
||||
## Score Semantics
|
||||
## 6. 分数语义
|
||||
|
||||
The project keeps three score fields intentionally:
|
||||
项目保留三个分数字段：
|
||||
|
||||
```text
|
||||
rawScore -> the raw score from the active retrieval implementation
|
||||
scoreLabel -> the semantic meaning of rawScore
|
||||
score -> compatibility score used by existing lookup relevance normalization
|
||||
rawScore -> 当前检索实现的原始分数
|
||||
scoreLabel -> rawScore 的语义
|
||||
score -> lookup relevance normalization 使用的兼容分数
|
||||
```
|
||||
|
||||
For SDK retrieval:
|
||||
SDK：
|
||||
|
||||
```text
|
||||
rawScore = L2 distance
|
||||
@@ -147,7 +145,7 @@ scoreLabel = l2_distance
|
||||
score = L2 distance
|
||||
```
|
||||
|
||||
For Spring AI VectorStore retrieval:
|
||||
Spring AI VectorStore：
|
||||
|
||||
```text
|
||||
rawScore = Spring AI similarity score
|
||||
@@ -155,45 +153,46 @@ scoreLabel = similarity
|
||||
score = Milvus distance metadata when available
|
||||
```
|
||||
|
||||
Why use `metadata.distance` for `score`: `LookupKnowledgeTool` already normalizes relevance from L2 distance. Spring AI Milvus returns similarity as the document score, but also includes the Milvus distance in metadata. Using distance preserves the old relevance behavior while still exposing the new VectorStore score semantics through `rawScore` and `scoreLabel`.
|
||||
使用 `metadata.distance` 的原因：`LookupKnowledgeTool` 已经基于 L2 distance 做相关性归一化。Spring AI Milvus 主分数是 similarity，但 metadata 中仍有 Milvus distance。用 distance 保持旧逻辑稳定，同时通过 `rawScore` 暴露新语义。
|
||||
|
||||
## Regression Checks
|
||||
## 7. 回归检查
|
||||
|
||||
Targeted tests:
|
||||
目标测试：
|
||||
|
||||
```powershell
|
||||
mvn -q "-Dtest=VectorSearchServiceTest,LookupKnowledgeToolTest" test
|
||||
```
|
||||
|
||||
Spec validation:
|
||||
相关 spec：
|
||||
|
||||
```powershell
|
||||
openspec.cmd validate rag-knowledge-retrieval --specs
|
||||
openspec.cmd validate rag-retrieval-evaluation --specs
|
||||
```
|
||||
|
||||
Whitespace check:
|
||||
diff 检查：
|
||||
|
||||
```powershell
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Observed result:
|
||||
验收结论：
|
||||
|
||||
```text
|
||||
All targeted tests passed.
|
||||
All related specs passed.
|
||||
No diff-check errors.
|
||||
目标测试通过。
|
||||
相关 spec 通过。
|
||||
diff-check 无错误。
|
||||
```
|
||||
|
||||
## Acceptance Conclusion
|
||||
## 8. 验收结论
|
||||
|
||||
The VectorStore refactor is accepted for the read path:
|
||||
VectorStore 读路径可以接受：
|
||||
|
||||
- Spring AI VectorStore is integrated and selected in `auto` mode.
|
||||
- The SDK path remains available and was proven by fallback behavior.
|
||||
- The live collection configuration is aligned with the existing Milvus collection.
|
||||
- The `lookup_knowledge` public contract remains stable.
|
||||
- Existing L2-based relevance normalization remains compatible.
|
||||
- Spring AI VectorStore 已集成，并在 `auto` 模式中优先使用。
|
||||
- SDK fallback 保留且已被实际验证。
|
||||
- live collection 配置与现有 Milvus collection 对齐。
|
||||
- `lookup_knowledge` 对外契约保持稳定。
|
||||
- 旧的 L2 relevance normalization 仍兼容。
|
||||
|
||||
写入和索引路径仍使用 Milvus SDK。这是有意的分阶段迁移，不是验收失败项。
|
||||
|
||||
The write/indexing path still uses the Milvus SDK. That is an intentional staged migration decision, not a failed acceptance item.
|
||||
|
||||
Reference in New Issue
Block a user