docs: reorganize MVP interview documentation
This commit is contained in:
aruo
@@ -1,22 +1,16 @@
|
||||
# RAG VectorStore Interview Notes
|
||||
# RAG VectorStore 面试要点
|
||||
|
||||
## 60-Second Explanation
|
||||
|
||||
I refactored the RAG retrieval path from a direct Milvus SDK-only implementation to a Spring AI `VectorStore` main path, while keeping the SDK path as a fallback.
|
||||
|
||||
The important part is not just the dependency change. I kept `VectorSearchService` as the boundary, so `lookup_knowledge` and the Agent workflow did not need to change. The system now supports three modes:
|
||||
## 1. 60 秒讲法
|
||||
|
||||
```text
|
||||
auto -> try Spring AI VectorStore, fallback to SDK
|
||||
spring-ai -> force VectorStore
|
||||
sdk -> force SDK
|
||||
我把 RAG 检索从 Milvus SDK-only 重构为 Spring AI VectorStore 主路径，同时保留 SDK fallback。
|
||||
关键不是换了一个依赖，而是保留 VectorSearchService 作为边界，所以 lookup_knowledge 和 Agent workflow 不需要改。
|
||||
现在支持 auto、spring-ai、sdk 三种模式。auto 会优先尝试 VectorStore，失败后 fallback 到 SDK。
|
||||
```
|
||||
|
||||
During live verification, the first run found a real config mismatch: VectorStore was pointed at `business_knowledge`, but the real Zilliz collection was `biz`. The fallback worked, so the system still returned results through SDK. After aligning the collection name, the same query went through Spring AI VectorStore successfully.
|
||||
现场验证时，第一次发现 VectorStore 指向了错误 collection：`business_knowledge`，而实际 Zilliz collection 是 `biz`。fallback 生效，所以系统仍能通过 SDK 返回结果。修正 collection 后，同一个 query 成功走 Spring AI VectorStore。
|
||||
|
||||
I also fixed score compatibility. Spring AI Milvus exposes similarity as the document score, but the old `lookup_knowledge` logic expects L2 distance. So I preserve `rawScore` and `scoreLabel`, and use Milvus `metadata.distance` as the compatibility `score` when available.
|
||||
|
||||
## Architecture Answer
|
||||
## 2. 架构回答
|
||||
|
||||
```text
|
||||
Agent / API
|
||||
@@ -27,69 +21,65 @@ Agent / API
|
||||
-> Milvus/Zilliz collection: biz
|
||||
```
|
||||
|
||||
The key design choice is that `VectorSearchService` remains the retrieval facade. This avoids spreading framework-specific code into the Agent tool layer.
|
||||
关键设计：`VectorSearchService` 是检索门面，避免 Spring AI 或 SDK 细节扩散到 Agent 工具层。
|
||||
|
||||
## Why Keep The SDK Path?
|
||||
## 3. 为什么保留 SDK
|
||||
|
||||
I kept SDK fallback for three reasons:
|
||||
- 迁移安全：原 SDK 路径已验证可用。
|
||||
- 运行韧性：VectorStore schema、filter 或配置失败时，检索仍可用。
|
||||
- Demo 稳定：检索抽象变化不应该破坏主诊断演示。
|
||||
|
||||
- Migration safety: the existing SDK path was already proven against the live collection.
|
||||
- Runtime resilience: if VectorStore schema mapping or filtering fails, retrieval still works.
|
||||
- Interview/demo stability: a retrieval abstraction change should not break the main Agent diagnosis demo.
|
||||
这在实际验证中发挥了作用：VectorStore 配置错时，`auto` 模式 fallback 到 SDK，API 没有失败。
|
||||
|
||||
This was validated in practice. When VectorStore pointed at the wrong collection, `auto` mode fell back to SDK and still returned results.
|
||||
## 4. 为什么引入 Spring AI VectorStore
|
||||
|
||||
## Why Use Spring AI VectorStore At All?
|
||||
使用 `VectorStore` 可以让项目更接近标准 RAG 抽象：
|
||||
|
||||
Using Spring AI `VectorStore` moves the project closer to a standard RAG abstraction:
|
||||
- 业务代码不再持有全部 Milvus search 细节。
|
||||
- 后续 QueryTransformer、DocumentPostProcessor、Retriever 等能力更容易接入。
|
||||
- 面试中也更容易解释和 Spring AI 生态的关系。
|
||||
|
||||
- Retrieval code no longer needs to own all Milvus-specific search details.
|
||||
- Later features such as query transformers, document postprocessors, advisors, or retrievers can be introduced more naturally.
|
||||
- The code becomes easier to compare with common Spring AI RAG patterns in an interview.
|
||||
但我没有一次性迁移写入，因为读写同时迁移会让问题难定位。当前先稳定读路径。
|
||||
|
||||
But I did not blindly replace everything. Writes/indexing still use SDK because changing read and write paths at the same time would make failures harder to isolate.
|
||||
## 5. 为什么保留 L0
|
||||
|
||||
## Why Keep L0?
|
||||
L0 现在不是最终答案来源，而是确定性 hint 层：
|
||||
|
||||
L0 is no longer treated as the final source of truth. It is a deterministic hint layer:
|
||||
- 提取 domain/entity。
|
||||
- 在可能时生成 category filter。
|
||||
- 给 trace 提供解释信号。
|
||||
|
||||
- It extracts domain/entity hints from indexed metadata.
|
||||
- It helps constrain L1 retrieval by category when possible.
|
||||
- It gives the Agent a stable clue even when semantic retrieval is weak.
|
||||
|
||||
The current design is:
|
||||
当前职责：
|
||||
|
||||
```text
|
||||
L0 = domain/entity hint
|
||||
L1 = semantic retrieval through VectorStore/SDK
|
||||
postprocess = evidence trace and relevance normalization
|
||||
postprocess = evidence trace + relevance normalization
|
||||
```
|
||||
|
||||
This is easier to defend than saying "we only use vector search." Real incident diagnosis often has exact identifiers, error codes, service names, and alert names. L0 is useful for those.
|
||||
真实故障诊断里有很多精确标识，完全只靠向量检索并不稳。
|
||||
|
||||
## Why Not Use Hidden Spring AI Advisors Directly?
|
||||
## 6. 为什么不用隐藏 Advisor
|
||||
|
||||
For this project, `lookup_knowledge` remains an explicit tool.
|
||||
`lookup_knowledge` 保持显式工具，因为：
|
||||
|
||||
Reason:
|
||||
- Trace 要展示什么时候检索。
|
||||
- `tool_invocation` 要记录输入、输出预览、相关性和 metadata。
|
||||
- 面试故事是可审计 Agent 执行，而不只是答案质量。
|
||||
|
||||
- The Agent trace needs to show when knowledge was retrieved.
|
||||
- `tool_invocation` records input, output preview, relevance level, and evidence metadata.
|
||||
- The interview story is about auditable Agent execution, not only answer quality.
|
||||
Advisor 后续可以接入，但需要先解决可观测性。
|
||||
|
||||
Spring AI Advisors may be useful later, but hiding retrieval inside an advisor would make the evidence chain less visible unless we rebuild trace hooks around it.
|
||||
## 7. 分数设计
|
||||
|
||||
## Score Design
|
||||
|
||||
The result object intentionally separates these fields:
|
||||
当前结果故意拆成：
|
||||
|
||||
```text
|
||||
score -> compatibility score used by old relevance normalization
|
||||
rawScore -> raw score from the retrieval implementation
|
||||
scoreLabel -> semantic label for rawScore
|
||||
score -> 兼容旧 relevance normalization 的分数
|
||||
rawScore -> 当前检索实现原始分数
|
||||
scoreLabel -> rawScore 的语义
|
||||
```
|
||||
|
||||
For SDK:
|
||||
SDK：
|
||||
|
||||
```text
|
||||
score = L2 distance
|
||||
@@ -97,7 +87,7 @@ rawScore = L2 distance
|
||||
scoreLabel = l2_distance
|
||||
```
|
||||
|
||||
For VectorStore:
|
||||
VectorStore：
|
||||
|
||||
```text
|
||||
score = metadata.distance if present
|
||||
@@ -105,63 +95,25 @@ rawScore = Spring AI document score
|
||||
scoreLabel = similarity
|
||||
```
|
||||
|
||||
This prevents a subtle bug: if we treat Spring AI similarity as L2 distance, relevance becomes wrong. If we only expose distance, we lose the ability to compare Spring AI behavior. Keeping both makes the migration inspectable.
|
||||
这样避免把 similarity 当成 L2 distance 的隐蔽 bug。
|
||||
|
||||
## How I Verified It
|
||||
## 8. 如何证明 VectorStore 被使用
|
||||
|
||||
I verified at three levels:
|
||||
- 日志出现 `Starting Spring AI VectorStore search` 和 `Spring AI VectorStore search complete`。
|
||||
- API 响应中 `scoreLabel=similarity`。
|
||||
- `rawScore` 是 Spring AI similarity，`score` 仍是兼容 distance。
|
||||
|
||||
- Unit tests: SDK mode, auto VectorStore mode, fallback mode, category filter, distance metadata mapping.
|
||||
- Live API: `/api/search/similar?query=ERR_TIMEOUT&topK=3`.
|
||||
- Logs: confirmed whether the path was VectorStore success or SDK fallback.
|
||||
## 9. 常见追问
|
||||
|
||||
The live API returned:
|
||||
### 为什么不删 SDK？
|
||||
|
||||
```text
|
||||
scoreLabel = similarity
|
||||
rawScore = Spring AI similarity
|
||||
score = Milvus distance metadata
|
||||
```
|
||||
这是迁移，不是重写。fallback 提供回滚安全，并且已经证明配置错误时仍能保证主链路可用。
|
||||
|
||||
That means the main path was Spring AI VectorStore and compatibility scoring remained stable.
|
||||
### `lookup_knowledge` 变了吗？
|
||||
|
||||
## What I Would Do Next
|
||||
外部契约没变。它仍然调用 `VectorSearchService.searchSimilarDocuments(...)`，变化在门面背后的实现。
|
||||
|
||||
I would not immediately migrate indexing writes. The next responsible steps are:
|
||||
### 这是完整 Spring AI RAG 了吗？
|
||||
|
||||
- Add a small live acceptance report for several golden queries.
|
||||
- Compare `sdk` and `spring-ai` mode side by side for topK overlap.
|
||||
- Decide whether `VectorIndexService` should move to `VectorStore.add(...)`.
|
||||
- Add query transformation or hybrid retrieval only after we have baseline metrics.
|
||||
还不是。当前是 Spring AI VectorStore 读路径 + 显式工具 + 自定义 evidence trace + SDK 写入。这样做是为了保留审计能力和分阶段迁移安全。
|
||||
|
||||
This staged approach is intentional: first stabilize the read path, then evaluate retrieval quality, then migrate writes if the abstraction proves reliable.
|
||||
|
||||
## Interview Questions And Short Answers
|
||||
|
||||
### Why did you not remove the SDK?
|
||||
|
||||
Because this is a migration, not a rewrite. SDK fallback gives rollback safety and proved useful when VectorStore config was initially wrong.
|
||||
|
||||
### What changed for `lookup_knowledge`?
|
||||
|
||||
The public contract did not change. It still calls `VectorSearchService.searchSimilarDocuments(...)`. The implementation behind that facade changed.
|
||||
|
||||
### How do you know VectorStore is actually used?
|
||||
|
||||
The logs show `Starting Spring AI VectorStore search` followed by `Spring AI VectorStore search complete`. The API response also has `scoreLabel=similarity`, which only comes from the VectorStore path.
|
||||
|
||||
### What was the main bug found during live validation?
|
||||
|
||||
The configured collection name was wrong. Spring AI looked for `business_knowledge`, but the actual Milvus collection was `biz`.
|
||||
|
||||
### What did fallback prove?
|
||||
|
||||
It proved that `auto` mode is resilient: VectorStore failed, SDK search still returned valid results, and the API did not fail.
|
||||
|
||||
### Why is `metadata.distance` important?
|
||||
|
||||
Because `lookup_knowledge` uses L2 distance normalization. Spring AI returns similarity as the main document score, but the Milvus distance is available in metadata. Using it preserves old relevance behavior.
|
||||
|
||||
### Is this full Spring AI RAG now?
|
||||
|
||||
Not yet. It uses Spring AI VectorStore for the main read path, but keeps explicit tools, custom evidence trace, L0 hints, and SDK indexing. That is deliberate because the project values auditability and staged migration.
|
||||
|
||||
Reference in New Issue
Block a user