# RAG 接入 Spring AI Query Transformer

**状态**：待规划  
**严重程度**：中  
**发现时间**：2026-07-05  
**范围**：查询改写、多查询扩展、AIOps 检索稳定性

---

## 背景

当前 `lookup_knowledge` 主要使用 Agent 传入的原始 query 进行 L0/L1 检索。query 的质量高度依赖 Agent 当次生成结果。

Spring AI 提供 Query Transformer / Query Expander 类能力，可以把用户问题或 Agent 子任务改写成更适合检索的查询。

---

## 问题

当前检索 query 存在几个风险：

1. 用户问题口语化时，缺少领域关键词。
2. AIOps payload 中的 alertName、service、metric 没有稳定拼入检索 query。
3. 同义表达没有扩展，例如“连接耗尽”和“连接池打满”。
4. 工具层无法复用框架提供的 rewrite / expansion 能力。

---

## 改造方向

在 `lookup_knowledge` 前增加查询改写层：

```text
raw query / alert payload
  -> query transformer
  -> rewritten query / expanded queries
  -> retriever
```

优先支持两类场景：

1. **AIOps 模板化改写**
   - alertName
   - service
   - metric
   - symptom
   - domain/category

2. **Spring AI Query Transformer**
   - rewrite 原始 query
   - multi-query expansion
   - 必要时做 query compression

---

## 验收标准

- `tool_invocation` 中记录原始 query 和改写后的 query。
- AIOps payload 存在时，检索 query 能稳定带上告警和服务上下文。
- 对同一个测试问题，改写前后 topK 命中结果可对比。
- 未配置 transformer 时，可以回退到原始 query。

---

## 相关文件

- `src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java`
- `src/main/java/com/superbiz/agent/service/AiOpsService.java`
- `src/main/java/com/superbiz/agent/service/VectorSearchService.java`
- `src/main/java/com/superbiz/agent/domain/entity/ToolInvocation.java`