# rag

**Repository Path**: tianlq/rag

## Basic Information

- **Project Name**: rag
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-31
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业知识库 RAG 问答系统

最小可用版（MVP）RAG 系统：**上传文档 → 自动切片 + 向量化存入本地向量库 → 用户提问 → 检索知识库片段 + 结合 DeepSeek 流式生成答案**，前端打字机效果。

- 后端：Express + TypeScript（ESM）
- 向量库：`chromadb`（纯 Node 本地运行，**无需 Docker / Python / 单独启动服务**，数据持久化在 `backend/chroma-db`）
- 向量化：**本地模型 `bge-small-zh-v1.5`**（免费离线，中文优先，不消耗 API 余额）
  - 说明：DeepSeek 官方 API **没有** embedding 接口（已从官方文档确认），故采用本地 embedding；DeepSeek 仅用于对话问答。
- 大模型：DeepSeek（OpenAI 兼容接口，SSE 流式）
- 前端：Vue3 + Vite + TypeScript + Element-Plus

---

## 1. 环境要求

- **Node.js ≥ 18**（建议 20+，实测 v20.19.0）
- npm ≥ 9
- **DeepSeek API Key**（用于问答；`api.deepseek.com` 控制台获取）

> ⚠️ 首次向量化会联网从 HuggingFace 下载 embedding 模型（量化版约 24MB）。国内网络若无法访问 `huggingface.co`，在 `.env` 设置 `HF_ENDPOINT=https://hf-mirror.com`（本项目 `.env` 已默认配置）。

---

## 2. 后端启动

```bash
cd backend
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY=sk-xxxx（必填，否则问答接口不可用）
# 其余项一般保持默认即可

npm run dev
```

启动成功后日志应显示：

```
[chroma] 集合就绪: "knowledge_base"，数据目录 D:\...\chroma-db
[server] 后端已启动: http://localhost:3000
```

后端启动时**会自动拉起内置的 Chroma 服务端**（监听 127.0.0.1:8000），无需手动启动任何中间件。

---

## 3. 前端启动

```bash
cd frontend
npm install
npm run dev
```

浏览器打开 Vite 输出中的地址（默认 `http://localhost:5173`，若端口被占用会自动顺延，以终端输出为准）。Vite 已将 `/api` 代理到后端 3000 端口。

> 注意：本机若已运行其他 Vite 项目（5173/5176/5177/5178 等），本前端会自动选一个空闲端口，**以终端输出的端口为准**。

---

## 4. 使用流程

1. **Tab「文档上传」**：多选上传 `.pdf / .docx / .md / .txt` 文件。
   - 后端同步执行：解析文本 → 切片（每块 ≤700 token，重叠 150）→ 本地向量化 → 写入 Chroma。
   - 上传完成后列表展示已入库文档，可删除（同时清理其向量分片）。
   - 大文件入库会稍慢，属正常现象。
2. **Tab「智能问答」**：输入问题回车发送。
   - 后端将问题向量化 → Chroma 召回 Top-4 相关片段 → 拼接固定系统提示词 → 调 DeepSeek 流式返回。
   - 回答以打字机效果增量显示，答案下方展示引用的知识库片段。

---

## 5. 后端接口

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/upload` | form-data 字段 `file`，返回 `{code, data:{docId, fileName}}` |
| GET | `/api/chat/stream?question=...` | SSE：`sources`（引用片段，JSON）→ `answer`（增量文本，JSON 编码）→ `done`；失败发 `error` |
| GET | `/api/documents` | 已入库文档列表 |
| DELETE | `/api/documents/:id` | 删除文档并清理向量库分片 |

---

## 6. 环境变量（`.env`）

| 变量 | 默认 | 说明 |
|---|---|---|
| `DEEPSEEK_API_KEY` | （必填） | DeepSeek API Key，未配置时问答接口返回明确错误 |
| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | OpenAI 兼容接口地址 |
| `DEEPSEEK_MODEL` | `deepseek-chat` | 对话模型 |
| `PORT` | `3000` | 后端端口 |
| `EMBEDDING_MODEL` | `Xenova/bge-small-zh-v1.5` | 本地 embedding 模型 |
| `HF_ENDPOINT` | 空 | HuggingFace 镜像，如 `https://hf-mirror.com` |
| `CHROMA_PORT` | `8000` | 内置 Chroma 端口 |
| `CHROMA_PATH` | `./chroma-db` | 向量库持久化目录 |
| `CHROMA_COLLECTION` | `knowledge_base` | 集合名 |
| `CHUNK_SIZE` / `CHUNK_OVERLAP` | `700` / `150` | 分块策略（token 估算） |

---

## 7. 已知限制 & 排障

- **DeepSeek 余额不足**：调用会返回 4xx（如 403 预扣费失败），前端会收到 `error` 事件并提示。请到 DeepSeek 控制台充值。**向量化是本地免费的，不受影响。**
- **模型下载失败 / 很慢**：确认能访问 `huggingface.co`；不行就保持 `HF_ENDPOINT=https://hf-mirror.com`。
- **Chroma 8000 端口被占用**：后端启动时会优先复用已在运行的 Chroma 服务；若端口被其他程序占用，请改 `CHROMA_PORT`。
- **重启后文档列表为空**：MVP 用内存保存文档元数据（规格要求），重启会清空列表；向量分片仍在 `chroma-db`，重新上传同名文档即恢复可用。
- **分块与 bge 输入上限**：bge-small-zh 输入上限 512 token，超过 512 的切片在向量化时会被截断。MVP 已足够；如需更精确可调小 `CHUNK_SIZE`。

---

## 8. 目录结构

```
backend/   Express + TS 后端（服务、路由、SSE、配置）
frontend/  Vue3 + Vite 前端（上传 / 问答双 Tab）
```