# CBCC全栈实践-AI问答助手

**Repository Path**: mdalang/cbcc_rag

## Basic Information

- **Project Name**: CBCC全栈实践-AI问答助手
- **Description**: AI智能问答助手是一款基于RAG（检索增强生成）技术的智能问答系统，支持用户上传PDF和Word文档，通过大语言模型进行智能问答。系统采用前后端分离架构，提供流式输出、文档预览、会话管理等核心功能
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-26
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI智能问答助手系统

基于RAG技术的智能文档问答系统，支持上传PDF/Word文档，通过向量检索和大语言模型实现智能问答。

## 技术架构

### 后端
- **框架**: FastAPI + Uvicorn
- **数据库**: SQLite + SQLAlchemy
- **认证**: JWT + bcrypt
- **文档解析**: PyPDF2 + python-docx
- **向量数据库**: ChromaDB
- **嵌入模型**: BAAI/bge-small-zh
- **LLM**: 阿里云 Qwen3.5-Plus

### 前端
- **框架**: Vue 3 + TypeScript + Vite
- **UI库**: Arco Design Vue
- **样式**: Tailwind CSS
- **状态管理**: Pinia

## 快速开始

### 后端启动

```bash
# 进入后端目录
cd backend

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# 例如 .\env\Scripts\Activate.ps1
# Linux/Mac:
source venv/bin/activate

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

# 启动服务
python -m uvicorn app.main:app --reload --port 8000
```

后端API文档：http://localhost:8000/docs

### 前端启动

```bash
# 进入前端目录
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

前端访问地址：http://localhost:5173

## 功能特性

### 核心功能
- ✅ 用户注册与登录（JWT认证）
- ✅ 历史会话管理（创建、删除、切换、重命名）
- ✅ 文档上传（支持PDF、Word格式，10MB限制）
- ✅ 文档自动解析和向量化处理
- ✅ 基于文档内容的智能问答（RAG）
- ✅ 答案来源引用展示
- ✅ 流式输出（打字机效果）
- ✅ 消息撤回（级联删除）
- ✅ 重新生成（取消后可重新生成）
- ✅ 响应式界面设计

### 管理员功能
- ✅ 用户权限管理（角色分配）
- ✅ 敏感词管理（增删改查、批量导入）
- ✅ 文档敏感词过滤

### 交互优化
- ✅ 骨架屏加载
- ✅ 平滑滚动
- ✅ 模型选择持久化

## 项目结构

```
CBCC_AI/
├── backend/                    # 后端代码
│   ├── app/
│   │   ├── api/               # API路由
│   │   │   ├── auth.py        # 认证API
│   │   │   ├── conversations.py # 会话API
│   │   │   ├── documents.py   # 文档API
│   │   │   └── qa.py          # 问答API
│   │   ├── core/              # 核心配置
│   │   │   ├── config.py      # 应用配置
│   │   │   └── database.py    # 数据库连接
│   │   ├── models/            # ORM模型
│   │   ├── schemas/           # Pydantic模型
│   │   ├── services/          # 业务服务
│   │   │   ├── document_processor.py # 文档处理
│   │   │   ├── vector_store.py       # 向量存储
│   │   │   ├── llm_service.py        # LLM服务
│   │   │   ├── rag_service.py        # RAG服务
│   │   │   └── conversation_service.py # 会话服务
│   │   ├── utils/             # 工具函数
│   │   └── main.py            # 应用入口
│   ├── data/                  # 数据存储
│   ├── uploads/               # 上传文件
│   ├── requirements.txt       # Python依赖
│   └── .env                   # 环境变量
│
├── frontend/                   # 前端代码
│   ├── src/
│   │   ├── api/               # API封装
│   │   ├── assets/            # 静态资源
│   │   ├── router/            # 路由配置
│   │   ├── stores/            # 状态管理
│   │   ├── types/             # TypeScript类型
│   │   ├── views/             # 页面组件
│   │   ├── App.vue
│   │   └── main.ts
│   ├── package.json
│   ├── vite.config.ts
│   └── tailwind.config.js
│
└── README.md
```

## API端点

### 认证接口
| 方法 | 端点 | 说明 |
|------|------|------|
| POST | `/api/auth/register` | 用户注册 |
| POST | `/api/auth/login` | 用户登录 |
| GET | `/api/auth/me` | 获取当前用户 |

### 会话管理
| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/api/conversations` | 获取会话列表 |
| POST | `/api/conversations` | 创建会话 |
| GET | `/api/conversations/{id}` | 获取会话详情 |
| PUT | `/api/conversations/{id}` | 更新会话（重命名） |
| DELETE | `/api/conversations/{id}` | 删除会话 |
| GET | `/api/conversations/{id}/messages` | 获取会话消息 |
| DELETE | `/api/conversations/{id}/messages/{msg_id}` | 删除问答对 |
| POST | `/api/conversations/{id}/messages/{msg_id}/withdraw` | 撤回消息 |

### 文档管理
| 方法 | 端点 | 说明 |
|------|------|------|
| POST | `/api/documents/upload` | 上传文档 |
| GET | `/api/documents` | 获取文档列表 |
| GET | `/api/documents/{id}` | 获取文档详情 |
| GET | `/api/documents/{id}/status` | 获取处理状态 |
| GET | `/api/documents/{id}/preview` | 获取文档预览 |
| DELETE | `/api/documents/{id}` | 删除文档 |

### 问答接口
| 方法 | 端点 | 说明 |
|------|------|------|
| POST | `/api/qa` | 同步问答 |
| POST | `/api/qa/stream` | 流式问答(SSE) |

### 管理员接口
| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/api/admin/users` | 获取所有用户 |
| PUT | `/api/admin/users/{id}/role` | 修改用户角色 |

### 敏感词接口
| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/api/sensitive-words` | 获取敏感词列表 |
| POST | `/api/sensitive-words` | 添加敏感词 |
| POST | `/api/sensitive-words/batch` | 批量添加敏感词 |
| DELETE | `/api/sensitive-words/{id}` | 删除敏感词 |

## 使用流程

1. 注册账户并登录
2. 创建新对话
3. 上传PDF或Word文档
4. 等待文档处理完成
5. 输入问题，获取AI回答
6. 查看答案来源引用

## 测试

### 后端测试
```bash
cd backend
pytest --cov=app --cov-report=html
```
- 测试数：295个
- 覆盖率：86.50%

### 前端测试
```bash
cd frontend
npm run test:coverage
```
- 测试数：113个
- 覆盖率：87.42%

## 相关文档

- [系统设计文档](./系统设计文档.md)
- [需求文档](./需求文档.md)
- [测试文档](./测试文档.md)
- [测试报告](./测试报告_全栈完整版.md)

## 注意事项

- 首次运行时，嵌入模型(BAAI/bge-small-zh)会自动下载，约100MB
- 支持的文档格式：PDF、DOCX、DOC
- 文档大小限制：10MB
- 建议使用Chrome或Firefox浏览器
- 管理员账号默认为 `admin/admin`（首次启动后建议修改密码）