80 lines
3.3 KiB
Markdown
80 lines
3.3 KiB
Markdown
# 念界智能客服（RAG 版）
|
||
|
||
## 项目概览
|
||
- 前端：Vue3 + Vite，提供 FAQ 引导、AI 客服对话与会话列表。
|
||
- 后端：Flask，流式调用大模型，并通过本地 MiniRAG 做检索。
|
||
- 数据：单一文件 `data/qa.json`，问答成对存储，RAG 与 FAQ 共用。
|
||
- 模型：本地向量模型 `bge-small-zh-v1.5`（**未纳入仓库**，需自行放置）。
|
||
|
||
## 目录结构（关键部分）
|
||
```
|
||
app.py # Flask 入口
|
||
backend/ # 后端逻辑
|
||
rag.py # MiniRAG 接入（内置轻量存储补丁）
|
||
routes/ # /api/chat, /api/faq, /api/conversations
|
||
config.py # 配置，依赖环境变量 OPENAI_API_KEY 等
|
||
data/
|
||
qa.json # 唯一问答库（需保留）
|
||
frontend/ # 前端源码；dist 为构建产物
|
||
requirements.txt # 后端依赖
|
||
.gitignore # 已排除 node_modules、对话历史、cache、模型等
|
||
```
|
||
|
||
## 准备工作
|
||
1. **模型文件**（需自备，不随仓库）
|
||
将 `bge-small-zh-v1.5` 放到 `minirag/minirag/models/`（相对路径：`../minirag/minirag/models/bge-small-zh-v1.5`，即与本项目同级的 `minirag` 目录）。
|
||
2. **数据文件**
|
||
确保 `data/qa.json` 在仓库中（已包含）。不要删除或更名。
|
||
3. **Python 依赖**（建议 Python 3.9+）
|
||
```bash
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
|
||
```
|
||
说明：`backend/rag.py` 内置对 pip 版 `minirag-hku` 的补丁（轻量存储），无需额外修改源码。
|
||
4. **环境变量**
|
||
- `OPENAI_API_KEY`：Kimi/OpenAI 兼容接口密钥
|
||
- 可选：`OPENAI_BASE_URL`（默认 `https://api.moonshot.cn/v1`）、`MODEL_NAME`（默认 `kimi-k2-turbo-preview`）
|
||
|
||
## 运行
|
||
### 后端
|
||
```bash
|
||
source .venv/bin/activate
|
||
python app.py # 默认 0.0.0.0:8081
|
||
```
|
||
|
||
### 前端
|
||
开发模式：
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
生产构建：
|
||
```bash
|
||
cd frontend
|
||
npm run build # 产物在 frontend/dist
|
||
```
|
||
Flask 会直接将 `frontend/dist` 作为静态资源目录。
|
||
|
||
## RAG 行为说明
|
||
- 问答索引来源：`data/qa.json` 中的每条 Q/A 被拼成一个 chunk（“Q{id}：问题\nA：答案”），无额外切片。
|
||
- 前端 FAQ 与 AI 客服工具调用都使用同一套检索：
|
||
- FAQ：有查询词时取前 10 条；无查询词返回固定 Top 问题列表。
|
||
- AI 客服：模型工具调用 `search_rag`，返回前 5 条匹配，模型据此作答。
|
||
- 无回退机制：检索失败或空结果时，模型按系统提示输出“问题待补充”。
|
||
|
||
## 不纳入仓库的内容
|
||
- 模型目录：`minirag/minirag/models/bge-small-zh-v1.5/`
|
||
- 向量/索引缓存：`minirag_cache/`
|
||
- 会话历史：`data/conversations/`（如存在）
|
||
- node_modules：`frontend/node_modules/`
|
||
|
||
## 常见问题
|
||
- **导入 minirag 报缺少 kg 模块**：已在 `backend/rag.py` 内注入简化存储实现，无需改动，只要安装依赖即可。
|
||
- **检索为空**：确认 `data/qa.json` 存在且内容正确；模型路径正确；首次运行会自动重建索引。
|
||
|
||
## 部署要点
|
||
- 仅需把代码、`data/qa.json`、前端构建产物（或源码）同步到服务器；模型需单独放置在指定路径。
|
||
- 设置 `OPENAI_API_KEY` 环境变量后，启动后端即可。
|