# 念界智能客服（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` 环境变量后，启动后端即可。