# fengshui-rag

**Repository Path**: PipI58/fengshui-rag

## Basic Information

- **Project Name**: fengshui-rag
- **Description**: 风水AI
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-13
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 风水AI RAG智能问答系统

基于RAG架构的专业风水智能问答系统，使用BGE-M3模型和DeepSeek API，为用户提供专业的风水知识咨询服务。

## 系统特性

- 🔮 **专业风水知识库**：包含系统课程和秘课内容
- 🤖 **智能问答**：基于RAG架构的精准回答
- 📚 **知识追溯**：每个回答都标明知识来源
- 📖 **文档管理**：支持上传和管理风水相关文档
- 💬 **流式响应**：实时显示AI回答过程
- 🎯 **中文优化**：专为中文风水内容优化

## 技术架构

```
用户界面 (Next.js) → API网关 (FastAPI) → 处理层 (RAG) → 存储层 (ChromaDB + 智谱AI)
```

### 核心技术

- **前端**：Next.js 15 + React 19 + TypeScript + Tailwind CSS
- **后端**：FastAPI + Python 3.12
- **向量数据库**：ChromaDB
- **嵌入模型**：智谱 AI Embedding-3 (2048维)
- **语言模型**：DeepSeek API
- **稀疏检索**：BM25 + jieba 分词

## 快速开始

### 1. 环境要求

- Python 3.9+
- Node.js 16+
- 8GB+ RAM
- Windows 10/11

### 2. 安装部署

详细安装步骤请参考 [部署指南](./部署指南.md)

### 3. 快速启动

1. 双击运行 `start.bat`
2. 等待服务启动完成
3. 访问 http://localhost:5173

## 使用指南

### 智能问答

1. 在首页输入框中输入您的风水问题
2. 系统会基于知识库提供专业回答
3. 查看回答下方的知识来源

### 知识库管理

1. 点击"知识库管理"菜单
2. 上传新的风水文档（支持.docx格式）
3. 查看/重建知识库状态

## 项目结构

```
E:\工作区\rag_system\rag_system_pro\
├── knowledge_base\          # 知识库文件
│   └── 知识库\             # 风水课程文档
│       ├── 系统课程\       # 39课系统课程
│       └── 秘课内容\       # 4个秘传课程
├── backend\                 # Python后端
│   ├── app\               # 应用代码
│   │   ├── api/endpoints/ # API 路由
│   │   ├── services/      # 业务逻辑（RAG、检索等）
│   │   ├── models/        # 数据模型
│   │   └── main.py        # 入口文件
│   ├── requirements.txt    # Python依赖
│   └── .env.example       # 环境变量模板
├── frontend\               # 旧前端（Vue 3）- 保留参考
├── frontend-new\           # 新前端（Next.js 15）✨ 当前使用
│   ├── app/              # 页面路由
│   ├── components/       # UI组件
│   ├── lib/api/          # API客户端
│   ├── stores/           # 状态管理
│   └── HANDOVER.md       # 前端交接文档
├── docs/                   # 项目文档
│   ├── AI_HANDOVER.md      # 原始交接文档
│   ├── AI_HANDOVER_V2.md   # 后端交接文档
│   ├── ISSUE_LOG.md        # 问题解决日志 ✨ NEW
│   ├── P1_P2_OPTIMIZATION_REPORT.md
│   └── RAG_OPTIMIZATION_PLAN.md
├── chroma_db\            # 向量数据库（自动生成）
├── uploads\              # 文档上传目录
└── 部署指南.md           # 详细部署文档
```

## 知识库内容

### 系统课程
- 风水基础理论
- 罗盘使用方法
- 形煞识别与化解
- 元运与飞星
- 八宅风水
- 阴宅风水
- 等共39课内容

### 秘课内容
- 五鬼运财
- 以形制形
- 生基做法
- 天地相应

## API文档

启动服务后访问 http://localhost:8000/docs 查看完整API文档

## 主要API

- `POST /api/chat/ask` - 问答接口
- `POST /api/chat/ask/stream` - 流式问答
- `GET /api/knowledge/status` - 知识库状态
- `POST /api/knowledge/upload` - 上传文档
- `POST /api/knowledge/rebuild` - 重建知识库

## 开发进度

### 已完成 ✅
- [x] JWT 用户认证系统
- [x] 智谱 AI 嵌入集成
- [x] ChromaDB 向量存储
- [x] BM25 稀疏检索
- [x] 混合检索（BM25 + 向量）
- [x] 查询改写
- [x] HyDE 假设文档嵌入
- [x] RAGAS 质量评估
- [x] Next.js 15 前端重构
- [x] 服务器部署上线

### 进行中 🔄
- [ ] 管理员知识库管理页面

### 待开发 📋
- [ ] 递归语义切分
- [ ] Rerank 重排序
- [ ] 多模态支持（图片、图表）
- [ ] 知识图谱集成
- [ ] 移动端适配优化

## 在线访问

- 网站地址：https://www.masyun.site/rag/
- API 文档：https://www.masyun.site/rag/api/docs

## 常见问题

1. **首次启动慢**：需要初始化向量数据库，请耐心等待
2. **回答不准确**：确保知识库文件完整，可以尝试重建知识库
3. **API调用失败**：检查DeepSeek API Key配置

## 技术支持

如遇到问题，请：
1. 查看 [部署指南](./部署指南.md)
2. 检查系统日志
3. 提交Issue或联系技术支持

## 许可证

本项目仅供学习和研究使用。

---

**免责声明**：本系统提供的风水知识仅供参考，不构成专业建议。