# LambdaRAG Architecture — 统一知识检索智能体

> Version 3.1 | 2026-04-08
> Maritime: 91.7% (180题) | Finance: 52% (95题)

---

## 一、整体架构

```
┌──────────────────────────────────────────────────────────────────┐
│                        LambdaRAG v3.1                            │
│                                                                  │
│  Query                                                           │
│    │                                                             │
│    ▼                                                             │
│  ┌─────────────────────────────────────┐                        │
│  │ Step 1: Intent + Entity Extract     │  评分制分类(8类)       │
│  │   规则优先 → LLM fallback           │  + 规则实体提取       │
│  └─────────────┬───────────────────────┘                        │
│                │ {intent, entities, keywords}                    │
│                ▼                                                  │
│  ┌─────────────────────────────────────┐                        │
│  │ Step 2: Entity-Enhanced Fusion      │                        │
│  │   ┌─────┬────────┬───────┬──────┐  │                        │
│  │   │BM25 │Vector  │Graph  │Wiki  │  │  4路并行              │
│  │   │     │bge-m3  │Entity │Pages │  │  实体增强查询         │
│  │   └──┬──┴───┬────┴──┬────┴──┬───┘  │  compare跳过增强     │
│  │      └──────┴───────┴──────┘       │  temporal时间展开     │
│  │              │ Weighted RRF         │                        │
│  └──────────────┼──────────────────────┘                        │
│                 │                                                │
│                 ▼                                                │
│  ┌─────────────────────────────────────┐                        │
│  │ Step 2b: Corrective RAG (P1-1)     │  检索质量门控          │
│  │   质量不足 → 改写query → 重试1次   │                        │
│  └──────────────┬──────────────────────┘                        │
│                 │                                                │
│                 ▼                                                │
│  ┌─────────────────────────────────────┐                        │
│  │ Step 3: Slot Fill                   │  person/process/data  │
│  │   person → 人员槽位 JSON           │  fact等跳过(省LLM)    │
│  │   process → 流程槽位 JSON          │  领域模板从instance   │
│  │   data → 表格行列定位 JSON         │                        │
│  └──────────────┬──────────────────────┘                        │
│                 │                                                │
│                 ▼                                                │
│  ┌─────────────────────────────────────┐                        │
│  │ Step 4: Build Enriched Context      │  槽位+关系+Wiki+文档 │
│  │   → 3500字符上下文 → LLM生成回答   │                        │
│  └──────────────┬──────────────────────┘                        │
│                 │                                                │
│                 ▼                                                │
│  ┌─────────────────────────────────────┐                        │
│  │ Step 5: Feedback Logging            │  P0-3 query_log      │
│  │   查询日志 + 未找到日志             │  P0-4 missing_queries │
│  └─────────────────────────────────────┘                        │
└──────────────────────────────────────────────────────────────────┘
```

---

## 二、三层抽象

```
Layer 3 Orchestration    intent_entity_extract → Route → Feedback
Layer 2 Pattern          fusion_search | slot_fill | corrective_retry
Layer 1 Skill            bm25 | vector | graph | wiki | rrf | time_filter | table_boost
```

### Layer 1: Skill (原子能力)

| Skill | 类型 | 依赖 | 说明 |
|-------|------|------|------|
| bm25_search | 本地 | pickle索引 | 关键词倒排索引 (bigram/trigram) |
| vector_search | 本地+NPU | numpy + bge-m3 | 1024维余弦相似度 |
| graph_walk | 本地 | relations.json | BFS N跳实体图遍历 |
| wiki_read | 本地 | wiki/*.md | 编译知识页面匹配 |
| rrf_merge | 纯计算 | — | Weighted Reciprocal Rank Fusion |
| time_filter | 纯计算 | — | 时效性排序增强 |
| table_boost | 纯计算 | — | 表格chunk优先 |
| slot_fill | LLM | vLLM | 结构化信息提取 |
| quality_check | 纯计算 | — | 检索质量门控 |

### Layer 2: Pattern (组合模式)

| Pattern | 组成 | 何时触发 |
|---------|------|---------|
| fusion_search | Par(bm25, vector, graph, wiki) >> rrf | 所有查询 |
| entity_enhance | extract_entities >> expand_query >> fusion | 非compare查询 |
| slot_pipeline | fusion >> slot_fill >> build_context | person/process/data |
| corrective_retry | fusion >> quality_check >> reformulate >> retry | 质量不足时 |
| temporal_expand | expand_time_words >> fusion >> time_filter | temporal查询 |

### Layer 3: Orchestration (编排)

```python
Pipeline = Compose(
    IntentEntityExtract,         # 评分分类 + 实体提取
    EntityEnhancedFusionSearch,  # 4路并行 + 加权RRF
    CorrectiveRAGCheck,          # 检索质量门控
    SlotFill,                    # 结构化提取 (按intent)
    BuildEnrichedContext,        # 组装上下文
    FeedbackLog,                 # 日志记录
)
```

---

## 三、意图分类 (8 类)

### 评分制分类 (P0-2)

不是 first-match，而是所有规则同时评分，最高分胜出。

| 意图 | 关键词 (部分) | 权重配置 |
|------|-------------|---------|
| person | 谁负责/找谁/电话/联系人 | bm25:0.8 vec:0.5 graph:0.3 wiki:0.5 |
| process | 怎么办/能不能报销/流程/审批 | bm25:0.7 vec:0.5 graph:0.3 wiki:0.6 |
| data | 及格率/排名/统计/收费表 | bm25:1.0 vec:0.3 graph:0.05 wiki:0.1 |
| fact | 多少/标准/税率/有效期 | bm25:1.0 vec:0.5 graph:0.1 wiki:0.1 |
| compare | 异同/区别/对比 | bm25:0.5 vec:0.8 graph:0.4 wiki:0.7 |
| relation | 隶属/依据/由谁制定 | bm25:0.5 vec:0.3 graph:0.7 wiki:0.8 |
| synthesis | 总结/梳理/体系/框架 | bm25:0.6 vec:0.5 graph:0.5 wiki:0.6 |
| temporal | 最新/修订/什么时候/截止 | bm25:1.0 vec:0.2 graph:0.05 wiki:0.2 |

### 速度优化

- 规则能分类的 → 0 次 LLM 调用 (~0s)
- person/process 或无法分类 → 1 次 LLM 调用 (~3s)
- fact/compare/temporal → 跳过槽位填充 (省 1 次 LLM)

---

## 四、核心技术点

### 4.1 True Fusion (非 Router)

所有 4 路检索对**每个**查询都运行，通过权重控制各路贡献：

```
score(doc) = Σ weight_i / (k + rank_i)
```

分类器调的是**权重**，不是选路。

### 4.2 Entity-Enhanced Search

Step 1 提取的实体扩展 BM25 查询词：
```
原始: "横向经费报销接待餐费的标准"
增强: "横向经费报销接待餐费的标准 横向经费 接待餐费 报销标准"
```

**例外**: compare 类跳过增强（两个实体名本身就是最好的关键词）

### 4.3 Corrective RAG (P1-1)

检索后检查 top-3 文档与 query 的关键词重叠率：
- ≥ 30% → 质量通过
- < 30% → 自动改写 query（提取核心名词）→ 重试一次

### 4.4 Temporal Time Expansion (P1-5)

```
"近五年" → "2022年至2026年"
"近三年" → "2024年至2026年"
"最新"   → "2026年最新"
```

### 4.5 Slot Fill (按意图)

| 意图 | 提取内容 | LLM调用 |
|------|---------|---------|
| person | 姓名/职位/部门/电话/职责 | ✅ 1次 |
| process | 流程类型/步骤/条件/政策依据 | ✅ 1次 |
| data | 数值/表格行列/来源 | ✅ 1次 |
| fact/compare/temporal | — | ❌ 跳过 |

### 4.6 Feedback Loop

```
feedback/
├── query_log.jsonl         # 每次查询记录
└── missing_queries.jsonl   # "未找到"的查询
```

用途：指导知识库补充、路由权重调优、评估改动效果。

---

## 五、部署架构

### 代码与数据分离

```
agentexample/qaagent67lambda/   ← 代码 (版本控制)
├── agent-config.yml             # 通用模板
├── scripts/                     # 通用脚本 (12个)
│   ├── config.py                # 统一配置加载
│   ├── search_unified.py        # v3.1 统一检索
│   ├── search_engine.py         # BM25
│   ├── search_engine_v2.py      # Hybrid
│   ├── graph_engine.py          # 实体图谱
│   ├── extract_docs.py          # 多格式文档提取
│   ├── rebuild_index.py         # BM25索引
│   ├── build_vector_index.py    # 向量索引
│   ├── wiki_compile.py          # Wiki编译
│   └── ...
└── workspace/                   # 运行时产物

/home/67/knowledge/{domain}/    ← 数据 (不版本控制)
├── instance.yml                 # 领域配置 (覆盖通用模板)
├── raw/                         # 原始文件
├── processed/                   # 提取文本
├── wiki/                        # Wiki编译知识
├── rag_index.pkl                # BM25索引
├── rag_vectors_v2.npy           # 向量索引
├── metadata.json                # 元数据
└── feedback/                    # 反馈日志
```

### instance.yml 领域覆盖

```yaml
# agent-config.yml (通用)     →  instance.yml (领域覆盖)
systemPrompt: 通用助手          →  南京大学财务处知识库问答助手
prompts.classify: 通用分类      →  +报销/预约/退回 关键词
prompts.person_answer: 通用     →  +财务处官方风格/网址
knowledge.baseDir: ./knowledge  →  /home/67/knowledge/finance
```

### 服务器服务

| 服务 | 端口 | 用途 |
|------|------|------|
| Maritime QA | 8080 | 海事法规问答 |
| Finance QA | 8082 | 财务服务问答 |
| Travel API | 8081 | 旅行规划 (Function Calling + 高德API) |
| vLLM | 8000 | LLM推理 (NPU 3,4,5,7) |
| bge-m3 | 11435 | Embedding (NPU 0) |

---

## 六、Pipeline 构建流程

新领域部署 4 步：

```bash
# 1. 文档提取 (PDF/DOCX/PPTX/XLSX/MD → TXT)
python scripts/extract_docs.py

# 2. 构建索引
python scripts/rebuild_index.py           # BM25 (~30s)
python scripts/build_vector_index.py      # 向量 (~2min NPU)

# 3. Wiki编译 (时间规范化 + 关系提取)
python scripts/wiki_compile.py            # ~45min for 261 files

# 4. 启动服务
docker run ... python scripts/app.py
```

---

## 七、测试结果

### Maritime (手写 180 题)

| 版本 | Unified | U:B | 关键改进 |
|------|---------|-----|---------|
| v2 | 89.8% | 8:6 | True Fusion |
| v3 | 90.8% | 10:7 | Intent+Slot |
| **v3.1** | **91.7%** | **14:9** | 评分分类+CRAG+compare修复 |

### Finance (95 题真实用户)

| 版本 | 有效回答 | 关键改进 |
|------|---------|---------|
| v2 | 48% | BM25基线 |
| **v3** | **55%** | 实体增强+槽位填充 |
| v3.1 | 52% | 评分分类 (需排查回退) |

---

## 八、待优化项 (TODO)

| 优先级 | 项目 | 预期效果 |
|--------|------|---------|
| P1-3 | FAIR-RAG 内联证据评估 | 减少编造 |
| P1-4 | 语义查询缓存 | 30-50%命中→0.5s延迟 |
| P2-1 | RAGAS自动评估框架 | 量化每次改动效果 |
| P2-2 | 上下文分块 (Contextual Chunking) | 向量检索+10% |
| P2-3 | 领域同义词表 | 检索召回+5% |
| P2-4 | MinerU深度文档解析 | +84个扫描PDF |
| P2-5 | 路由成功率自适应 | 自动调优权重 |
