nianjie/README.md

念界智能客服（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+）

   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）

运行

后端

source .venv/bin/activate
python app.py   # 默认 0.0.0.0:8081

前端

开发模式：

cd frontend
npm install
npm run dev

生产构建：

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 环境变量后，启动后端即可。