# RagApp

**Repository Path**: edq/rag-app

## Basic Information

- **Project Name**: RagApp
- **Description**: 个人 / 小团队用的本地 RAG 知识库 — 上传文档 → 自动构建混合检索索引 → 浏览器问答。完全本地化,数据不出机器。

支持 markdown / txt / pdf,支持整个文件夹上传,自带现代化 Web UI。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-09-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RagApp

个人 / 小团队用的本地 RAG 知识库 — 上传文档 → 自动构建混合检索索引 → 浏览器问答。**完全本地化,数据不出机器**。

支持 markdown / txt / pdf,支持整个文件夹上传,自带现代化 Web UI。

## 截图

> ![img.png](img.png) — 启动后访问 `http://localhost:5173`,主界面是左侧抽屉(上传 + 文件管理)+ 右侧问答区。

## 特性

- 🔍 **混合检索** — BGE-M3 稠密向量 + BM25 稀疏词权重 + RRF 融合
- 🎯 **重排精排** — BGE-reranker 二阶段排序,hits 准很多
- 📁 **拖拽上传** — 单文件 / 多文件 / 整个文件夹,自动遍历子目录
- 🗂️ **文件管理** — 列表 / 搜索 / 删除,全量索引重 build
- 💬 **Web 问答** — 浏览器即可用,显示召回 chunks + 重排分数
- 🔌 **双 LLM 后端** — 智谱 GLM-4 (API,默认) / Ollama (本地)
- 📊 **4 指标评估** — Context Precision / Recall / Faithfulness / Answer Relevancy
- 🎨 **现代化 UI** — Vue 3 + Vite + daisyUI 5 + Tailwind 4(drawer / modal / toast)

## 5 分钟跑通

### 1. 准备环境

- Python 3.11+
- 下载两个模型到本地(可换路径,见 `rag/config.py`):
  - **BGE-M3**(~2.3 GB)→ `D:/AI/model/bge-m3/`(默认)
  - **BGE-reranker-v2-m3**(~570 MB)→ `D:/AI/model/bge-reranker-v2-m3/`
- 智谱 API Key(注册:https://open.bigmodel.cn/)

### 2. 克隆 + 装包

```bash
git clone <this-repo>
cd RagApp
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

### 3. 设置环境变量

```bash
export ZHIPUAI_API_KEY="your-key-here"   # Windows PowerShell: $env:ZHIPUAI_API_KEY = "..."
```

### 4. 启动后端

```bash
python -m rag.server
# → http://127.0.0.1:8000,首次启动会加载 BGE-M3 + reranker(几秒)
```

### 5. 启动前端(另一个终端)

```bash
cd frontend
npm install
npm run dev
# → http://localhost:5173
```

浏览器打开 `http://localhost:5173` 就能用了。

## 进阶用法

### 命令行(脚本化批处理)

`scripts/` 下有 4 个 CLI 入口,适合自动化场景:

```bash
# 索引构建
python -m scripts.ingest data/samples

# 单次问答
python -m scripts.query "RAG 是什么" --top-k 3

# 评估:生成 QA 集 + 跑 4 指标 + 出 HTML 报告
python -m scripts.gen_qa --max-chunks 10
python -m scripts.eval --top-k 3
# → 浏览器打开 storage/eval/report_YYYYMMDD_HHMMSS.html
```

### Gradio 备用 UI

```bash
python -m rag.app_gradio
# → http://127.0.0.1:7860
```

### 后端 API

| Method | Path | 说明 |
|--------|------|------|
| GET | `/health` | 服务状态 |
| POST | `/query` | 单次问答(`question`, `top_k`) |
| POST | `/ingest` | 文件上传(multipart,支持子目录) |
| GET | `/files` | 已索引文件列表 |
| DELETE | `/files?filename=xxx` | 删除文件 + 重 build 索引 |

## 技术栈

| 层 | 选型 |
|---|---|
| 嵌入 | BGE-M3 (本地) |
| 稠密检索 | FAISS IndexFlatIP |
| 稀疏检索 | BM25 (rank_bm25 + jieba) |
| 融合 | RRF (Reciprocal Rank Fusion) |
| 重排 | BGE-reranker-v2-m3 |
| LLM | 智谱 GLM-4 / Ollama |
| 后端 | FastAPI |
| 前端 | Vue 3 + Vite + daisyUI 5 + Tailwind 4 |
| 评估 | 手写 4 指标(无外部评估库依赖) |

## 配置

主要配置在 `rag/config.py`(`Settings` 单例),可通过环境变量覆盖:

| 变量 | 说明 | 默认 |
|------|------|------|
| `ZHIPUAI_API_KEY` | 智谱 API key | (必填) |
| `BGE_M3_PATH` | BGE-M3 模型路径 | `D:/AI/model/bge-m3` |
| `BGE_RERANKER_PATH` | BGE-reranker 模型路径 | `D:/AI/model/bge-reranker-v2-m3` |

模型路径在 Windows / Mac / Linux 上要相应改,推荐改 `rag/config.py` 而非环境变量。

## 项目结构

```
RagApp/
├── rag/                          ← 核心代码
│   ├── config.py                 ← 30+ 项配置(settings)
│   ├── server.py                 ← FastAPI 后端
│   ├── app_gradio.py             ← Gradio 备用 UI
│   ├── loaders/                  ← MD / TXT / PDF / 论文 PDF
│   ├── splitters/                ← TwoStageSplitter 两阶段切分
│   ├── embedders/                ← BGE-M3 封装
│   ├── retrievers/               ← dense / bm25 / hybrid(RRF)
│   ├── rerankers/                ← BGE-reranker(CrossEncoder)
│   ├── llms/                     ← 智谱 / Ollama / 工厂
│   ├── chains/                   ← RAGChain + RAGResult
│   ├── storage/                  ← SHA256 manifest(去重)
│   └── eval/                     ← QA 生成 + 4 指标 + HTML 报告
├── scripts/                      ← CLI 入口
│   └── ingest.py / query.py / gen_qa.py / eval.py
├── frontend/                     ← Vue 3 SPA
│   └── src/App.vue + main.js + style.css
├── data/
│   ├── samples/                  ← 示例文档(进 git)
│   └── uploads/                  ← 用户上传(进 .gitignore)
├── storage/                      ← 索引 + 评估产物(进 .gitignore)
├── tests/                        ← 单元测试
└── docs/superpowers/             ← 设计 + 实施计划
```

## 评估指标

`rag/eval/metrics_hand.py` 手写的 4 个指标:

| 指标 | 含义 | 1.0 = |
|---|---|---|
| **Context Precision** | top-k 召回里相关文档占比 | 召回来的都相关 |
| **Context Recall** | 所有相关文档里召回了多少 | 没漏 |
| **Faithfulness** | 答案里每句话有资料依据 | 无幻觉 |
| **Answer Relevancy** | 答案扣题程度 | 没跑题 |

## 已知限制

- **Ollama 需 ≥12GB 显存** — 8GB 显卡上 BGE-M3 + Ollama 7B OOM,默认走智谱 API
- **小语料(3-5 文档)调参意义不大** — 噪声主导,真实数据再调
- **删除是全量重 build** — `IndexFlatIP` 不支持 `remove_ids`,规模小所以可接受
- **OS 文件选择器无法自定义样式** — `<input type="file">` 走系统对话框

## 跑测试

```bash
pytest tests/ -v
```