# 个人知识库 RAG 平台

**Repository Path**: ye-bingbei/ai_-knowledge-base

## Basic Information

- **Project Name**: 个人知识库 RAG 平台
- **Description**: 个人 AI 知识库系统，支持上传/解析/切片/向量化、混合检索、多轮问答、引用溯源，通过 MCP 暴露给外部 AI 客户端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI KnowledgeBase 个人知识库 RAG + Agent 平台

单用户、本地部署的个人知识库。把自己的文档丢进去，用自然语言提问，系统从**你自己的文档**里检索依据、流式生成回答，并给出可点击的引用来源。

不只是「能问答的 RAG」—— 后期把它 Agent 化了：**MCP Server**（对外暴露给 AI 客户端）、**Function Calling**（模型自主决定调用）、**Graph 状态机**（后端编排多步流程）三条路径并存，共用同一个检索能力。

---

## 项目定位

- **原始文件是唯一事实源**：文件躺在 `data/knowledge/`，MySQL 只存元数据与切片，Redis Stack 只存向量与会话记忆。索引层坏了不用慌 —— 扫一遍文件夹就能重建。
- **全本地部署**：中间件跑在本机 Docker Compose，只有大模型和 embedding 调用外部 API（阿里云百炼）。
- **单用户、不做登录**：因此后端只绑回环地址 `127.0.0.1`（见下方「已知边界」）。

---

## 技术栈

| 层 | 技术 | 说明 |
|---|---|---|
| 语言 / 运行时 | Java | 17 |
| 后端框架 | Spring Boot | 4.1.1 |
| AI 框架 | Spring AI | 2.0.1（OpenAI 兼容 + Redis 向量库 + Redis 会话记忆 + MCP Server） |
| ORM | MyBatis-Plus | 3.5.17 |
| 文档解析 | Apache Tika | 4.1.0（`tika-parsers-standard-package`） |
| API 文档 | springdoc-openapi | 3.1.1（`/swagger-ui.html`） |
| 前端 | Vue 3.5 + TypeScript + Vite | Element Plus + Pinia + Vue Router；markdown-it + highlight.js + pdfjs-dist |
| 关系库 | MySQL | 8.4（Docker，宿主机端口 **3307**） |
| 向量库 / 会话记忆 | Redis Stack | `redis/redis-stack-server`，宿主机端口 **6380**，开 AOF `everysec` |
| 大模型 | 阿里云百炼（OpenAI 兼容端点） | chat：`qwen3.8-flash` |
| Embedding | 阿里云百炼 | `text-embedding-v4`，**1024 维**，单请求上限 10 条 |
| 密钥 | Windows 环境变量 | `aliQwen-api`，配置里 `${aliQwen-api:}` 读取，不硬编码 |

---

## 功能全景（七个阶段）

### 主线（1-4）：一个完整的 RAG 应用

1. **文件进出**：上传（SHA-256 去重）、列表（分页）、删除（级联清理磁盘）、详情预览（PDF.js / Markdown / 纯文本）。
2. **解析 → 切片 → 向量化**：Tika 解析纯文本 → 每块约 800 token（约 650 中文字）切片 → `text-embedding-v4` 出 1024 维向量 → 按 10 条一批写 Redis Stack（百炼硬上限）。上传后**异步**自动建索引，不阻塞 HTTP。详情页「切片」标签可直接看切块效果。
3. **三种检索**：关键词（MySQL LIKE）/ 语义（Redis 向量 COSINE）/ 混合（**RRF 融合**，两路各取 20 条候选取前 5）。批量重建索引幂等（`POST /api/files/reindex-all`）。
4. **RAG 问答**：白盒手写全链路 —— `hybrid()` 取 5 个切片 → 拼系统提示词（规则 + 参考资料）→ ChatClient 流式生成 → SSE 推送 `sources / delta / done`。答案 `[1] [2]` 编号对应引用卡片，可点进原文。会话记忆走 Redis（窗口 20 条），关掉页面能真正掐断上游大模型调用。

### 扩展（5-7）：AI 生态接入 + Agent 化

5. **MCP Server**：把检索能力包成 `@McpTool` 工具 `search_knowledge`，Streamable HTTP（`POST /mcp`）暴露，Cursor / Cline / Claude Desktop 跨进程直连。
6. **Function Calling**：`@Tool(name="search_knowledge")` + 独立裸 ChatClient，`POST /api/agent` 让**模型自主**决定调不调、调几次、传什么 query。
7. **Graph Agent**：手写状态机 `INTENT → [QA] RETRIEVE → GENERATE → END`，`POST /api/agent/graph` 由**后端转移表**决定下一步，带 `MAX_STEPS=10` 循环护栏，兜底建模成「节点」而非「分支」。

三条 Agent 路径的关系一句话：**谁决定下一步** —— 线性链路是后端写死、Function Calling 是模型自主、Graph Agent 是后端状态机编排。

---

## 快速启动

```bash
# 1. 基础设施（MySQL 3307 / Redis 6380）
cd docker && docker compose up -d && docker compose ps   # 两个服务 healthy

# 2. 后端（只绑 127.0.0.1:8080）
cd backend && mvn spring-boot:run

# 3. 前端（5173，已配 /api 代理到 8080）
cd frontend && npm run dev
```

> 前置：Windows 用户环境变量 `aliQwen-api`（阿里云百炼 API Key）。
> 端口：MySQL 3307、Redis 6380（本机 3306/6379 被其他项目占用）。前端依赖走 npmmirror（`frontend/.npmrc`）。

---

## 接口一览

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/files/upload` | 上传（SHA-256 去重） |
| GET | `/api/files` | 文件列表（分页） |
| GET | `/api/files/{id}/raw\|text\|chunks\|status` | 原文 / 解析文本 / 切片 / 索引状态 |
| POST | `/api/files/{id}/index` | 单篇建索引 |
| POST | `/api/files/reindex-all` | 批量重建索引（幂等，带进度） |
| GET | `/api/search/semantic\|keyword\|hybrid` | 三种检索（`?topK=&threshold=&rewrite=&rerank=` 可临时覆盖） |
| POST | `/api/chat/stream` | 提问（SSE：`sources → delta → done`） |
| GET / DELETE | `/api/chat/history` | 会话历史 / 清空 |
| GET | `/api/chat/sessions` | 会话列表 |
| POST | `/api/agent` | Function Calling（模型自主） |
| POST | `/api/agent/graph` | Graph Agent（状态机编排） |
| POST | `/mcp` | MCP Server（Streamable HTTP，外部 AI 客户端直连） |
| GET | `/api/ping` | 健康探针 |

---

## 验证与评估

测试不在 `backend/src/test`，而在 `scripts/` 下用 **Node 直接打接口** —— 要验的是**跨进程事实**（Redis 里的 key 到底写没写进去、上游大模型连接断没断、存储层和接口层是否一致），JUnit + mock 验等于自欺。

- **`scripts/verify/`**：11 个 `_test_*` 端到端验证脚本 + 假上游（`_mock_upstream.mjs`）+ MCP / Agent 探针。纪律：每条断言先看到它失败才算数；判据用**数量**不用**耗时比值**；依赖别的项目的断言探不到就响亮 SKIP。前置条件、判据、已知坑见 [`scripts/verify/README.md`](scripts/verify/README.md)。
- **`scripts/eval/`**：固定 26 题评测集（24 非陷阱 + 2 陷阱题），输出通过率 / MRR / 召回@5 / 假阳性率，同版代码两次结果一致（可复现）。基线：**通过 23/26、MRR 0.9167、召回@5=100%、假阳性率 11.5%**。详见 [`scripts/eval/README.md`](scripts/eval/README.md)。

---

## 项目结构

```
backend/                 Spring Boot 后端
  src/main/java/com/knowledgebase/
    agent/               Graph 状态机（AgentNode / AgentContext / GraphAgentService）
    config/              ChatClient / ChatMemory / SearchProperties 等配置
    controller/          File / Chat / Search / Agent / Health
    mcp/                 MCP Server 工具（@McpTool）
    parser/              Tika 解析 + 切片
    search/              检索（SearchService / Reranker / QueryRewriter）
    service/             Chat / File / Index / Reindex / Parse 等业务
    storage/             文件落盘
    tool/                Function Calling 工具（@Tool）
frontend/                Vue3 前端（上传/列表/详情/检索/对话）
scripts/
  verify/                Node 跨进程验证脚本 + 探针 + 假上游
  eval/                  Python 评测集与评分脚本
docker/                  docker-compose + MySQL 建表 SQL
data/                    运行数据（knowledge 原始文件 / temp / index / logs）
docs/                    spec / plan / 完工总结 / 面试素材
```

---

## 关键决策与已知边界

**关键决策**（完整依据见 [`docs/项目完工总结.md`](docs/项目完工总结.md)）：

- **RRF 融合、不设相似度阈值**：两路分数量纲不可比，融**排名**绕过归一化（k=60，candidate-k=20 > top-k=5）。不设阈值是实测结论 —— COSINE 分数被压在 0.55~0.90，无关问题也能到 0.70，没有干净的分界点。
- **白盒手写 RAG，不用 `QuestionAnswerAdvisor`**：字节码分析否决 —— 构造器只收 VectorStore（接不住 RRF 结果）、内部不排序（继承 Redis 乱序）。
- **参考资料放 system、不放 user**：`MessageChatMemoryAdvisor` 只把最后一条 user 写进记忆，拼进 user 会导致每轮永久写入、token 爆炸、读到过期上下文。
- **Rerank 被数据否掉，默认 OFF**：加 qwen3-rerank 后假阳性率纹丝不动、MRR 反降（长度偏差 + 重排≠过滤）。截短到 300 字 + 保守阈值能压假阳性到 3.8%，但「重排不能剔除无关文档」的可分性问题无解，真解法在检索层。

**已知边界 / 非目标**：

- **无鉴权**：`X-User-Id` 只是请求头，谁都能填。当前止血方案是后端只绑 `127.0.0.1`（真解法是鉴权，届时再对外开放）。
- **不做多用户 / 登录 / 单篇文档问答 / 相关性分数门槛**（分数区间压缩，没有干净分界点）。
- **中文多词查询关键词通道退化**（MySQL LIKE 对中文弱）：三通道对比已证实纯语义 = 混合（23/26），关键词通道当前零贡献，ES + IK 因收益为负暂搁置。
- 更多小遗留（兜底气泡 0.0s、流式错误双提示等）见 [`docs/项目完工总结.md`](docs/项目完工总结.md) §7。

---

## 文档索引

| 文档 | 内容 |
|---|---|
| [`docs/项目完工总结.md`](docs/项目完工总结.md) | 七阶段全量总结：设计决策依据、踩坑记录、验证体系、已知边界 |
| [`docs/superpowers/specs/`](docs/superpowers/specs/) | 关键阶段的设计 spec（决策依据） |
| [`docs/superpowers/plans/`](docs/superpowers/plans/) | 实现计划（含 Agent 平台升级计划） |
| [`scripts/verify/README.md`](scripts/verify/README.md) | 验证脚本前置条件、断言判据、已知坑、脚本规范 |
| [`scripts/eval/README.md`](scripts/eval/README.md) | 评测集说明与基线分数 |
| [`docs/面试素材清单.md`](docs/面试素材清单.md) | 面试素材（48 条素材 + 高频问题索引） |