328 lines
7.2 KiB
Markdown
328 lines
7.2 KiB
Markdown
# Jarvis RAG 升级执行清单
|
||
|
||
日期：2026-04-03
|
||
状态：执行清单
|
||
借鉴来源：VCPToolBox TagMemo V6 架构
|
||
|
||
---
|
||
|
||
## 使用说明
|
||
|
||
- 完成前使用 `- [ ]`
|
||
- 完成后改成 `- [x]`
|
||
- Day R.2 默认依赖 Day R.1 的分块优化完成后再推进
|
||
- Day R.3 默认依赖 Day R.1 的分块优化完成后再推进
|
||
- Day R.4 为可选特性
|
||
|
||
---
|
||
|
||
## Day R.1：Token 感知分块优化（3天）
|
||
|
||
Day R.1 目标：解决跨块边界信息丢失问题，实现精确的 token 计数和重叠分块。
|
||
|
||
### Task R.1.1：集成 tiktoken
|
||
|
||
- [ ] 安装 tiktoken 依赖
|
||
```bash
|
||
uv add tiktoken
|
||
```
|
||
|
||
- [ ] 新增 `backend/app/services/chunker.py`
|
||
实现 `TokenAwareChunker` 类，支持 85% 安全边界
|
||
|
||
- [ ] 实现 `count_tokens()` 方法
|
||
|
||
### Task R.1.2：实现智能断句
|
||
|
||
- [ ] 实现 `find_best_breakpoint()` 函数
|
||
在断点处（标点/空白）智能断开
|
||
|
||
- [ ] 实现 `_force_split_long_text()` 方法
|
||
处理超长句子强制分割
|
||
|
||
### Task R.1.3：实现重叠分块
|
||
|
||
- [ ] 实现 `chunk_with_overlap()` 方法
|
||
10% token 重叠，保证上下文连续性
|
||
|
||
- [ ] 实现 `_create_overlap()` 方法
|
||
创建重叠部分
|
||
|
||
### Task R.1.4：集成到 DocumentService
|
||
|
||
- [ ] 修改 `backend/app/services/document_service.py`
|
||
集成新的 TokenAwareChunker
|
||
|
||
- [ ] 替换原有的 `_build_chunks()` 方法
|
||
|
||
### Task R.1.5：补测试
|
||
|
||
- [ ] 新增 `backend/tests/services/test_chunker.py`
|
||
|
||
- [ ] 测试 Token 计数准确性
|
||
|
||
- [ ] 测试智能断句
|
||
|
||
- [ ] 测试重叠分块
|
||
|
||
### Day R.1 验收
|
||
|
||
- [ ] tiktoken 正确集成，token 计数误差 < 1%
|
||
- [ ] 超长句子不在词汇中间断开
|
||
- [ ] 重叠分块保证上下文连续性
|
||
- [ ] 单元测试覆盖率 > 80%
|
||
- [ ] 文档上传→分块→检索 集成测试通过
|
||
|
||
---
|
||
|
||
## Day R.2：多索引架构（4天）
|
||
|
||
Day R.2 目标：按知识类型/重要性分层，支持懒加载和 LRU 淘汰。
|
||
|
||
### Task R.2.1：设计 Collection 分离策略
|
||
|
||
- [ ] 新增 `backend/app/services/multi_index.py`
|
||
|
||
- [ ] 定义 `MultiIndexManager` 类
|
||
|
||
- [ ] 实现 `INDEX_STRATEGIES` 配置
|
||
- default: 通用文档
|
||
- important: 重要文档
|
||
- code: 代码片段
|
||
- meeting: 会议记录
|
||
|
||
- [ ] 实现 `get_collection()` 方法
|
||
|
||
### Task R.2.2：实现懒加载 + LRU TTL
|
||
|
||
- [ ] 实现 `LazyIndexLoader` 类
|
||
|
||
- [ ] 实现 `get_or_load()` 方法
|
||
|
||
- [ ] 实现 `sweep()` 方法
|
||
2小时 TTL 淘汰机制
|
||
|
||
### Task R.2.3：实现重要性感知检索
|
||
|
||
- [ ] 实现 `retrieve_with_importance()` 方法
|
||
|
||
- [ ] important 索引加权 1.2x
|
||
|
||
### Task R.2.4：修改 Document 模型
|
||
|
||
- [ ] 修改 `backend/app/models/document.py`
|
||
|
||
- [ ] 增加 `importance` 字段（Float, default=0.5）
|
||
|
||
### Task R.2.5：集成到 KnowledgeService
|
||
|
||
- [ ] 修改 `backend/app/services/knowledge_service.py`
|
||
|
||
- [ ] 集成 MultiIndexManager
|
||
|
||
- [ ] 集成 LazyIndexLoader
|
||
|
||
- [ ] 根据 importance 选择索引
|
||
|
||
### Task R.2.6：补测试
|
||
|
||
- [ ] 新增 `backend/tests/services/test_multi_index.py`
|
||
|
||
- [ ] 测试多 Collection 创建
|
||
|
||
- [ ] 测试懒加载
|
||
|
||
- [ ] 测试 TTL 淘汰
|
||
|
||
### Day R.2 验收
|
||
|
||
- [ ] 多 Collection 创建成功
|
||
- [ ] 懒加载索引生效
|
||
- [ ] TTL 淘汰机制工作
|
||
- [ ] 重要性感知检索加权生效
|
||
- [ ] 单元测试覆盖率 > 80%
|
||
|
||
---
|
||
|
||
## Day R.3：动态权重增强（4.5天）
|
||
|
||
Day R.3 目标：根据查询特性动态调整检索策略，支持核心标签加权。
|
||
|
||
### Task R.3.1：实现查询特性分析
|
||
|
||
- [ ] 新增 `backend/app/services/query_analyzer.py`
|
||
|
||
- [ ] 定义 `QueryProfile` 数据类
|
||
|
||
- [ ] 实现 `QueryAnalyzer` 类
|
||
|
||
- [ ] 实现查询类型检测
|
||
- 代码相关
|
||
- 表格相关
|
||
- 对话式
|
||
|
||
- [ ] 实现 `_calc_logic_depth()` 方法
|
||
|
||
### Task R.3.2：实现动态 Reranker
|
||
|
||
- [ ] 新增 `backend/app/services/dynamic_reranker.py`
|
||
|
||
- [ ] 实现 `DynamicReranker` 类
|
||
|
||
- [ ] 实现 `_get_weights()` 方法
|
||
- 代码查询：关键词权重高
|
||
- 表格查询：标题权重高
|
||
- 对话式：语义权重高
|
||
|
||
- [ ] 实现 `_calc_beta()` 方法
|
||
|
||
- [ ] 实现 `rerank()` 方法
|
||
|
||
### Task R.3.3：实现核心标签系统
|
||
|
||
- [ ] 新增 `backend/app/services/core_tag_search.py`
|
||
|
||
- [ ] 实现 `CoreTagAwareSearch` 类
|
||
|
||
- [ ] 实现 `CORE_BOOST_FACTOR = 1.33`
|
||
|
||
- [ ] 实现 `search()` 方法
|
||
|
||
### Task R.3.4：修改 DocumentChunk 模型
|
||
|
||
- [ ] 修改 `backend/app/models/document.py`
|
||
|
||
- [ ] 增加 `tags` 字段（JSON, default=list）
|
||
|
||
- [ ] 增加 `is_core` 字段（Boolean, default=False）
|
||
|
||
### Task R.3.5：集成到 KnowledgeService
|
||
|
||
- [ ] 修改 `backend/app/services/knowledge_service.py`
|
||
|
||
- [ ] 集成 QueryAnalyzer
|
||
|
||
- [ ] 集成 DynamicReranker
|
||
|
||
- [ ] 集成 CoreTagAwareSearch
|
||
|
||
- [ ] 修改 `retrieve()` 方法支持动态权重
|
||
|
||
### Task R.3.6：补测试
|
||
|
||
- [ ] 新增 `backend/tests/services/test_dynamic_reranker.py`
|
||
|
||
- [ ] 测试查询特性分析
|
||
|
||
- [ ] 测试动态权重调整
|
||
|
||
- [ ] 测试核心标签加权
|
||
|
||
### Day R.3 验收
|
||
|
||
- [ ] 查询特性分析准确（代码/表格/对话式识别）
|
||
- [ ] 动态权重根据查询类型调整
|
||
- [ ] 核心标签检索加权 1.33x
|
||
- [ ] Rerank 集成测试通过
|
||
|
||
---
|
||
|
||
## Day R.4：高级特性（可选）（4.5天）
|
||
|
||
Day R.4 目标：探索更高级的 RAG 增强技术。
|
||
|
||
### Task R.4.1：语义去重
|
||
|
||
- [ ] 新增 `backend/app/services/deduplicator.py`
|
||
|
||
- [ ] 实现 `SemanticDeduplicator` 类
|
||
|
||
- [ ] 实现 `_cosine_similarity()` 方法
|
||
|
||
- [ ] 实现 `deduplicate()` 方法
|
||
|
||
### Task R.4.2：语义分桶（可选）
|
||
|
||
- [ ] 新增 `backend/app/services/semantic_bucket.py`
|
||
|
||
- [ ] 实现 `SemanticBucketing` 类
|
||
|
||
- [ ] 实现 `bucket_by_topic()` 方法
|
||
|
||
### Task R.4.3：EPA 分析设计（可选探索）
|
||
|
||
- [ ] 设计 EPA 模块架构
|
||
|
||
- [ ] 定义 EPA 接口
|
||
|
||
- [ ] 实现残差金字塔算法（伪代码）
|
||
|
||
### Day R.4 验收（可选）
|
||
|
||
- [ ] 语义去重测试通过
|
||
- [ ] 语义分桶原型完成（可选）
|
||
- [ ] EPA 分析方案设计完成（可选实现）
|
||
|
||
---
|
||
|
||
## 总验收清单
|
||
|
||
### Phase R.1-R.3 必须完成
|
||
|
||
- [ ] Token 感知分块正常工作
|
||
- [ ] 多索引架构正常工作
|
||
- [ ] 动态权重增强正常工作
|
||
- [ ] 单元测试覆盖率 > 80%
|
||
- [ ] 集成测试通过
|
||
- [ ] 原有检索功能无回退
|
||
|
||
### Phase R.4 可选完成
|
||
|
||
- [ ] 语义去重正常工作
|
||
- [ ] 语义分桶正常工作（可选）
|
||
- [ ] EPA 设计文档完成（可选）
|
||
|
||
---
|
||
|
||
## 总工作量估算
|
||
|
||
| Phase | 工作量 |
|
||
|-------|--------|
|
||
| R.1 Token 感知分块 | 3 天 |
|
||
| R.2 多索引架构 | 4 天 |
|
||
| R.3 动态权重增强 | 4.5 天 |
|
||
| R.4 高级特性（可选） | 4.5 天 |
|
||
| **R.1-R.3 必须** | **11.5 天** |
|
||
| **R.1-R.4 含可选** | **16 天** |
|
||
|
||
---
|
||
|
||
## 产出清单
|
||
|
||
| 产出 | 对应 Phase |
|
||
|------|-----------|
|
||
| `services/chunker.py` | R.1 |
|
||
| `services/multi_index.py` | R.2 |
|
||
| `services/query_analyzer.py` | R.3 |
|
||
| `services/dynamic_reranker.py` | R.3 |
|
||
| `services/core_tag_search.py` | R.3 |
|
||
| `services/deduplicator.py` | R.4 |
|
||
| `services/semantic_bucket.py` | R.4（可选） |
|
||
| `models/document.py` 更新 | R.2, R.3 |
|
||
| 单元测试 > 80% | R.1, R.2, R.3 |
|
||
| 集成测试通过 | R.1, R.2, R.3 |
|
||
|
||
---
|
||
|
||
## 与 Agent Phase 关系
|
||
|
||
| Agent Phase | RAG 协作内容 |
|
||
|-------------|-------------|
|
||
| Phase 1 | Task Schema 追踪 RAG 任务 |
|
||
| Phase 2 | RAG 任务可分解给 Librarian Agent |
|
||
| Phase 3 | 支持多索引动态选择 |
|
||
| Phase 4 | RAG 检索过程可视化 |
|
||
| Phase 5 | EPA 分析、语义分桶 |
|
||
|
||
**Phase R 可与 Agent Phase 1-5 并行推进。**
|