# school-chat-ai

**Repository Path**: wdep/school-chat-ai

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-19
- **Last Updated**: 2025-11-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 学校知识库RAG系统

基于 Langchain + Starrocks + FastAPI + Vue 3 的智能问答系统

> **特色**：使用 Starrocks 同时作为数据库和向量存储，无需额外的向量数据库！

## 📋 目录

- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [快速开始（从零到运行）](#快速开始从零到运行)
- [项目架构](#项目架构)
- [API接口](#api接口)
- [开发指南](#开发指南)
- [常见问题](#常见问题)

## 功能特性

- 🤖 **智能问答**：基于 RAG 技术的语义检索问答系统
- 📚 **知识库管理**：支持知识的增删改查和批量导入
- 💬 **多轮对话**：支持上下文理解的连续对话
- 🎯 **向量检索**：使用 Starrocks 存储和检索文档向量
- 🏫 **学校推荐**：智能推荐学校特色和优势
- 👨‍🎓 **学生指导**：为学生提供专业的咨询服务
- 📱 **前后台分离**：Monorepo MPA 架构，用户端和管理端独立部署

## 技术栈

### 后端
- **FastAPI** - 现代高性能 Web 框架
- **Langchain** - LLM 应用开发框架
- **OpenAI API** - 大语言模型和文本嵌入
- **Starrocks** - 分析型数据库（同时存储数据和向量）
- **SQLAlchemy** - Python ORM
- **Pydantic** - 数据验证

### 前端
- **Vue 3 + TypeScript** - 渐进式前端框架
- **Vite** - 下一代构建工具
- **Element Plus** - Vue 3 UI 组件库
- **Pinia** - Vue 状态管理
- **Axios** - HTTP 客户端

## 快速开始（从零到运行）

### 第一步：环境要求

| 软件 | 版本要求 | 说明 |
|------|---------|------|
| Python | 3.11 或 3.12 | ❌ 不支持 3.13 |
| Node.js | 20.19+ 或 22.12+ | 推荐使用 LTS 版本 |
| pnpm | 最新版 | 前端包管理器 |
| Starrocks | 3.0+ | 数据库和向量存储 |
| MySQL 客户端 | 任意版本 | 用于连接 Starrocks |

### 第二步：安装 Starrocks

#### Windows 安装

```powershell
# 1. 下载 Starrocks
# 访问: https://www.starrocks.io/download
# 下载 Windows 版本并解压到 D:\starrocks

# 2. 配置环境变量
$env:STARROCKS_HOME = "D:\starrocks"

# 3. 启动 FE (Frontend)
cd D:\starrocks\fe
.\bin\start_fe.bat

# 4. 启动 BE (Backend) - 打开新窗口
cd D:\starrocks\be
.\bin\start_be.bat
```

#### Linux/Mac 安装

```bash
# 1. 下载并解压
wget https://releases.starrocks.io/starrocks/StarRocks-xxx.tar.gz
tar -xzf StarRocks-xxx.tar.gz
cd StarRocks-xxx

# 2. 启动 FE
sh fe/bin/start_fe.sh --daemon

# 3. 启动 BE
sh be/bin/start_be.sh --daemon

# 4. 验证启动
# FE 端口：8030 (HTTP), 9030 (MySQL)
# BE 端口：8040 (HTTP), 9050 (Heartbeat)
```

#### 使用 Docker（可选）

```bash
# 快速启动 Starrocks
docker run -d \
  --name starrocks \
  -p 8030:8030 \
  -p 9030:9030 \
  starrocks/allin1-ubuntu:latest
```

### 第三步：初始化 Starrocks 数据库

1. **连接到 Starrocks**

```bash
# 使用 MySQL 客户端连接
mysql -h localhost -P 9030 -u root
```

2. **执行初始化 SQL**

```sql
-- 创建数据库
CREATE DATABASE IF NOT EXISTS knowledge_base;
USE knowledge_base;

-- 创建知识库表
CREATE TABLE IF NOT EXISTS knowledge_items (
    id BIGINT NOT NULL,
    title VARCHAR(500),
    content TEXT,
    category VARCHAR(100),
    metadata JSON,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=OLAP
DUPLICATE KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 10
PROPERTIES ("replication_num" = "1");

-- 创建向量存储表
CREATE TABLE IF NOT EXISTS document_vectors (
    id BIGINT NOT NULL AUTO_INCREMENT,
    knowledge_id BIGINT,
    chunk_index INT,
    chunk_text TEXT,
    embedding_json TEXT,
    title VARCHAR(500),
    category VARCHAR(100),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=OLAP
PRIMARY KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 10
PROPERTIES ("replication_num" = "1");

-- 验证
SHOW TABLES;
```

> 💡 **提示**：也可以直接执行 `mysql -h localhost -P 9030 -u root < init_starrocks.sql`

### 第四步：安装后端依赖

1. **创建 Python 虚拟环境**

```bash
# 检查 Python 版本（必须是 3.11 或 3.12）
python --version

# 如果是 3.13，需要降级
uv venv --python 3.11
# 或
python3.11 -m venv venv
```

2. **激活虚拟环境**

```bash
# Windows
venv\Scripts\activate
# 或使用 uv
.venv\Scripts\activate

# Linux/Mac
source venv/bin/activate
```

3. **安装依赖包**

```bash
# 使用 pip
pip install -r requirements.txt

# 或使用 uv（更快）
uv pip install -r requirements.txt
```

4. **验证安装**

```bash
python -c "from langchain_openai import ChatOpenAI; print('安装成功！')"
```

### 第五步：配置环境变量

1. **创建配置文件**

```bash
# Windows
copy env.example .env

# Linux/Mac
cp env.example .env
```

2. **编辑 `.env` 文件**

```env
# OpenAI 配置（必填）
OPENAI_API_KEY=sk-你的OpenAI密钥
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-3.5-turbo
EMBEDDING_MODEL=text-embedding-ada-002

# Starrocks 配置
STARROCKS_HOST=localhost
STARROCKS_PORT=9030
STARROCKS_USER=root
STARROCKS_PASSWORD=
STARROCKS_DATABASE=knowledge_base

# 服务器配置
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
```

> ⚠️ **重要**：
> - 必须填写有效的 `OPENAI_API_KEY`
> - 如果使用国内 API 代理，修改 `OPENAI_BASE_URL`
> - Starrocks 默认无密码，如有密码请填写

### 第六步：启动后端服务

```bash
# 确保在项目根目录且虚拟环境已激活
python -m uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
```

**看到以下输出表示成功：**

```
INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     127.0.0.1 - "GET /health HTTP/1.1" 200 OK
```

**测试后端：**

```bash
# 健康检查
curl http://localhost:8000/health

# 访问 API 文档
浏览器打开: http://localhost:8000/docs
```

### 第七步：安装前端依赖

```bash
cd app

# 安装 pnpm（如果没有）
npm install -g pnpm

# 安装依赖
pnpm install
```

### 第八步：启动前端应用

```bash
# 在 app 目录下

# 方式一：同时启动用户端和管理端
pnpm dev

# 方式二：单独启动
pnpm dev:user   # 用户对话页面 http://localhost:5173
pnpm dev:admin  # 管理后台 http://localhost:5174
```

### 第九步：导入示例数据（可选）

```bash
# 回到项目根目录
cd ..

# 导入 8 条示例知识库数据
python scripts/init_knowledge.py
```

### ✅ 完成！访问应用

- 📱 **用户对话页面**: http://localhost:5173
- 🔧 **管理后台**: http://localhost:5174
- 📚 **API 文档**: http://localhost:8000/docs

## 项目架构

### 目录结构

```
chat-ai/
├── backend/                    # 后端服务
│   ├── config.py              # 配置管理
│   ├── database.py            # Starrocks 连接
│   ├── models.py              # 数据模型
│   ├── rag_service.py         # RAG 核心（向量检索）
│   └── main.py                # FastAPI 应用
│
├── app/                        # 前端应用（Monorepo MPA）
│   ├── packages/
│   │   ├── user-chat/         # 用户对话应用（5173）
│   │   └── admin/             # 管理后台（5174）
│   ├── shared/                # 共享模块
│   │   ├── api/              # API 接口
│   │   ├── types/            # 类型定义
│   │   └── utils/            # 工具函数
│   ├── vite.config.user.ts   # 用户端配置
│   └── vite.config.admin.ts  # 管理端配置
│
├── data/
│   └── sample_knowledge.json # 示例数据
│
├── scripts/
│   └── init_knowledge.py     # 数据初始化脚本
│
├── init_starrocks.sql        # 数据库初始化 SQL
├── requirements.txt          # Python 依赖
├── .env                      # 环境配置（需创建）
└── README.md                 # 本文档
```

### 架构特点

#### 1. Starrocks 双重角色

```
┌─────────────────────────────────┐
│        Starrocks                │
├─────────────────────────────────┤
│ knowledge_items      │ 原始数据 │
│ document_vectors     │ 向量存储 │
│ (embedding_json 字段) │ 向量检索 │
└─────────────────────────────────┘
```

#### 2. RAG 工作流程

```
用户提问
   ↓
生成查询向量 (OpenAI Embeddings)
   ↓
Starrocks 余弦相似度检索
   ↓
获取相关文档 Top-K
   ↓
构建 Prompt + 上下文
   ↓
LLM 生成回答 (OpenAI ChatGPT)
   ↓
返回答案 + 来源文档
```

#### 3. Monorepo MPA 架构

- **Monorepo**：一个仓库管理多个应用
- **MPA**：多页应用，每个应用独立运行
- **共享模块**：API、类型、工具统一管理

**优势：**
- ✅ 用户端和管理端完全独立
- ✅ 可独立部署到不同服务器
- ✅ 代码复用，统一依赖管理

## API 接口

### 知识库管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/knowledge` | 创建知识 |
| GET | `/api/knowledge` | 获取列表（支持分类筛选） |
| GET | `/api/knowledge/{id}` | 获取详情 |
| PUT | `/api/knowledge/{id}` | 更新知识 |
| DELETE | `/api/knowledge/{id}` | 删除知识 |
| POST | `/api/knowledge/batch` | 批量导入 |

### 对话接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/chat` | 发送消息（支持多轮对话） |
| DELETE | `/api/chat/{session_id}` | 清除会话 |

### 使用示例

#### 添加知识

```bash
curl -X POST "http://localhost:8000/api/knowledge" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "学校简介",
    "content": "我们学校创建于1950年...",
    "category": "school_info",
    "metadata": {"author": "admin"}
  }'
```

#### 智能问答

```bash
curl -X POST "http://localhost:8000/api/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "学校有哪些特色专业？",
    "top_k": 3
  }'
```

## 开发指南

### 后端开发

#### 自定义提示词

编辑 `backend/rag_service.py`：

```python
self.prompt_template = """你是一个专业的助手...

知识库内容：
{context}

用户问题：{question}

回答："""
```

#### 调整 RAG 参数

```python
# backend/rag_service.py

# 文本分割大小
chunk_size=1000,      # 每块文本大小
chunk_overlap=200,    # 块之间重叠

# 检索数量
top_k=3              # 返回最相关的 3 个文档
```

#### 添加知识分类

1. 在 `app/shared/types/index.ts` 添加：

```typescript
export const KNOWLEDGE_CATEGORIES = {
  school_info: '学校信息',
  // 添加新分类
  your_category: '你的分类'
}
```

2. 在管理后台即可使用新分类

### 前端开发

#### 添加新页面

```bash
# 在 user-chat 或 admin 的 views/ 下创建组件
app/packages/user-chat/src/views/NewPage.vue

# 在 router/index.ts 中添加路由
{
  path: '/new-page',
  component: () => import('../views/NewPage.vue')
}
```

#### 使用共享 API

```typescript
import { sendMessage } from '@shared/api/chat'
import { getKnowledgeList } from '@shared/api/knowledge'

// 发送消息
const result = await sendMessage({ question: '你好' })

// 获取知识列表
const list = await getKnowledgeList()
```

#### 构建生产版本

```bash
cd app

# 构建所有应用
pnpm build

# 输出目录
# dist/user/   - 用户端
# dist/admin/  - 管理端
```

## 常见问题

### Q: Python 版本错误

**问题**：使用 Python 3.13 安装依赖失败

**解决**：

```bash
# 卸载 3.13，安装 3.11
uv venv --python 3.11
.venv\Scripts\activate
uv pip install -r requirements.txt
```

### Q: Starrocks 连接失败

**错误**：`Unknown database 'knowledge_base'`

**解决**：

```bash
# 1. 检查 Starrocks 是否启动
netstat -an | findstr 9030  # Windows
lsof -i:9030  # Linux/Mac

# 2. 执行初始化 SQL
mysql -h localhost -P 9030 -u root < init_starrocks.sql

# 3. 验证数据库
mysql -h localhost -P 9030 -u root -e "SHOW DATABASES;"
```

### Q: OpenAI API 调用失败

**错误**：`Invalid API Key`

**解决**：

1. 检查 `.env` 文件中的 `OPENAI_API_KEY` 是否正确
2. 确认 API Key 有效且有额度
3. 如使用代理，检查 `OPENAI_BASE_URL`

```bash
# 测试 API Key
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

### Q: 前端启动失败

**错误**：`Node.js version too low`

**解决**：

```bash
# 升级 Node.js
nvm install 20.19.0
nvm use 20.19.0

# 或使用 n
npm install -g n
n lts
```

### Q: 向量检索不准确

**解决**：

1. 增加 `top_k` 值（检索更多文档）
2. 调整 `chunk_size`（更小的块更精确）
3. 优化知识库内容（添加更多相关信息）
4. 调整提示词模板

### Q: 如何批量导入知识库

**方法一**：使用脚本

```bash
python scripts/init_knowledge.py
```

**方法二**：通过 API

```bash
curl -X POST "http://localhost:8000/api/knowledge/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"title": "标题1", "content": "内容1", "category": "school_info"},
      {"title": "标题2", "content": "内容2", "category": "admissions"}
    ]
  }'
```

**方法三**：在管理后台

1. 访问 http://localhost:5174
2. 点击"批量导入"
3. 粘贴 JSON 格式数据

## 生产部署

### 后端部署

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 使用 Gunicorn 运行
pip install gunicorn
gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

# 3. 使用 Supervisor 守护进程
[program:chat-ai-backend]
command=/path/to/venv/bin/gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker
directory=/path/to/chat-ai
user=www-data
autostart=true
autorestart=true
```

### 前端部署（Nginx）

```bash
# 1. 构建前端
cd app
pnpm build

# 2. Nginx 配置
server {
    listen 80;
    server_name example.com;

    # 用户端
    location / {
        root /var/www/chat-ai/dist/user;
        try_files $uri $uri/ /index.html;
    }

    # 管理端
    location /admin {
        alias /var/www/chat-ai/dist/admin;
        try_files $uri $uri/ /admin/index.html;
    }

    # API 代理
    location /api {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 性能优化建议

1. **Starrocks 优化**
   - 增加 replication_num（生产环境建议 3）
   - 合理设置 buckets 数量
   - 定期运行 OPTIMIZE TABLE

2. **向量检索优化**
   - 使用 FAISS 或 Milvus（大规模数据）
   - 实现向量索引缓存
   - 批量生成 embeddings

3. **应用优化**
   - 使用 Redis 缓存热点数据
   - 实现 API 限流
   - CDN 加速静态资源

## 许可证

MIT License

## 联系方式

- 📧 问题反馈：提交 GitHub Issue
- 💬 讨论交流：GitHub Discussions
- 📖 详细文档：查看 `PROJECT_STRUCTURE.md`

---

**项目版本**: v1.0.0  
**最后更新**: 2024年11月  
**作者**: Your Name

**⭐ 如果这个项目对你有帮助，请给个 Star！**