# python-18-智能文档

**Repository Path**: sanxiadaer/python18zhinengwen

## Basic Information

- **Project Name**: python-18-智能文档
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能文档问答系统

基于 RAG（检索增强生成）技术的 AI 知识库问答系统，支持上传文档建立知识库，进行智能问答并返回参考来源。界面参考腾讯 ima 设计，采用淡粉蓝白渐变风格。

## 功能特性

### 核心功能
- **文档管理**：支持上传 PDF、DOCX、TXT 格式文档，自动解析并建立向量索引
- **知识库问答**：基于知识库内容进行智能问答，支持单文档和多文档对比分析
- **普通对话**：不依赖知识库的通用 AI 对话，类似聊天机器人
- **参考来源**：回答时显示引用的文档片段，支持溯源
- **对话历史**：自动保存对话记录，支持查看和继续历史对话

### 用户管理
- **管理员账号**：用户管理后台，可查看和管理所有用户
- **普通用户**：产品界面，可创建知识库、上传文档、进行问答
- **分开登录**：管理员和普通用户登录后跳转到不同界面

### 界面设计
- 参考腾讯 ima 的清爽界面设计
- 淡粉 → 淡蓝 → 白色渐变背景（从右向左）
- 毛玻璃半透明卡片风格
- Markdown 美观渲染，支持代码块、列表、表格等

## 技术栈

### 后端
- **框架**：FastAPI
- **数据库**：SQLite（用户、知识库、对话记录）
- **向量数据库**：ChromaDB（文档向量存储与检索）
- **大模型**：DashScope（通义千问 qwen-plus）
- **向量化模型**：DashScope text-embedding-v2
- **认证**：JWT（JSON Web Token）
- **密码加密**：bcrypt

### 前端
- **框架**：React 18 + TypeScript
- **构建工具**：Vite
- **样式**：Tailwind CSS
- **路由**：React Router
- **Markdown 渲染**：react-markdown + remark-gfm
- **图标**：lucide-react

## 项目结构

```
python-web/
├── app/
│   ├── backend/
│   │   ├── main.py              # 应用入口
│   │   ├── core/                # 核心模块
│   │   │   ├── security.py      # JWT 认证
│   │   │   ├── deps.py          # 认证依赖
│   │   │   ├── llm.py           # 大模型调用
│   │   │   ├── vector_store.py  # 向量检索
│   │   │   └── embeddings.py    # 向量化
│   │   ├── databases/           # 数据库连接
│   │   │   └── database.py      # SQLAlchemy 引擎与会话
│   │   ├── models/              # 数据模型
│   │   │   ├── user.py          # 用户模型
│   │   │   ├── knowledge_base.py # 知识库模型
│   │   │   ├── document.py      # 文档模型
│   │   │   └── history.py       # 对话历史模型
│   │   ├── schemas/             # Pydantic 模式
│   │   │   ├── user.py
│   │   │   ├── document.py
│   │   │   └── query.py
│   │   ├── routers/             # 路由（API 接口）
│   │   │   ├── auth.py          # 注册/登录/认证
│   │   │   ├── admin.py         # 管理员用户管理
│   │   │   ├── knowledge_bases.py # 知识库 CRUD
│   │   │   ├── documents.py     # 文档上传/列表/删除
│   │   │   ├── chat.py          # 智能问答（知识库RAG + 通用对话）
│   │   │   ├── conversations.py # 会话管理
│   │   │   └── temp_chat.py     # 临时文档问答
│   │   └── services/            # 业务服务
│   │       ├── user_service.py  # 用户业务
│   │       ├── index_service.py # 文档索引与向量化
│   │       ├── rag_service.py   # RAG 检索增强生成
│   │       ├── file_service.py  # 文件解析（PDF/DOCX/TXT）
│   │       └── history_service.py # 对话历史服务
│   └── frontend/                # 前端项目（React + TypeScript + Vite）
│       ├── src/
│       │   ├── pages/           # 页面组件
│       │   ├── components/      # 通用组件
│       │   ├── lib/             # 工具库（认证等）
│       │   └── types/           # TypeScript 类型定义
│       ├── vite.config.ts       # Vite 配置（代理 /api → 8010）
│       └── package.json
├── uploads/                      # 上传文件存储（按用户/知识库分目录）
├── chroma_db/                    # 向量数据库存储
├── doc/                          # 项目文档与日报
├── .env                          # 环境配置（含 DashScope API Key）
├── .env.example                  # 环境配置示例
├── .gitignore
├── requirements.txt              # Python 依赖
├── start.ps1                     # 一键启动脚本
├── stop.ps1                      # 一键停止脚本
├── README.md
└── 演示说明.md                   # 演示步骤说明
```

## 环境要求

- Python 3.11+
- Node.js 18+
- DashScope API Key（通义千问）

## 快速开始

### 1. 克隆仓库

```bash
git clone https://gitee.com/sanxiadaer/python18zhinengwen.git
cd python18zhinengwen
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env`，填入你的 DashScope API Key：

```env
DASHSCOPE_API_KEY=你的APIKey
LLM_MODEL=qwen-plus
EMBEDDING_MODEL=text-embedding-v2
```

### 3. 安装后端依赖

```bash
pip install -r requirements.txt
```

> 注意：bcrypt 版本必须为 4.0.1，5.0 与 passlib 不兼容。

### 4. 安装前端依赖

```bash
cd app/frontend
npm install
cd ../..
```

### 5. 启动服务

**方式一：一键启动（推荐）**

```powershell
.\start.ps1
```

**方式二：手动启动**

```bash
# 启动后端（端口 8010）
uvicorn app.backend.main:app --host 0.0.0.0 --port 8010

# 启动前端（端口 5173）
cd app/frontend
npm run dev
```

### 6. 访问系统

打开浏览器访问：http://localhost:5173

## 默认账号

| 角色 | 用户名 | 密码 |
|------|--------|------|
| 管理员 | admin | admin123 |

> 管理员账号在首次启动时自动创建。普通用户可在登录页面自行注册。

## 使用说明

### 管理员
1. 使用 admin 账号登录
2. 进入用户管理后台，可查看所有用户、禁用/启用用户
3. 也可切换到产品界面使用知识库功能

### 普通用户
1. 注册账号并登录
2. **首页（普通对话）**：直接与 AI 对话，不需要知识库
3. **我的知识库**：
   - 创建知识库
   - 上传文档（PDF/DOCX/TXT）
   - 等待文档解析完成
   - 进入知识库详情页，选择文档进行问答
4. **问答历史**：查看所有对话记录，区分普通对话和知识库问答

### 多文档对比
在知识库详情页的问答面板中，点击右上角的文档选择按钮，可选择多个文档进行对比问答，系统会分别分析每个文档并给出对比结果。

## API 文档

启动后端后，访问 http://localhost:8010/docs 可查看完整的 API 文档（Swagger UI）。

## 注意事项

- 后端端口固定为 **8010**（8000 端口可能被其他服务占用）
- 前端通过 Vite 代理将 `/api` 请求转发到 `http://localhost:8010`
- 首次上传文档时需要调用 DashScope API 进行向量化，请确保网络通畅
- 上传的文档和向量数据库存储在本地，不会上传到远程服务器
- `.env` 文件包含 API Key，请勿提交到公开仓库

## 演示说明

详细的演示步骤请参考 [演示说明.md](./演示说明.md)。

## 许可证

本项目仅用于课程设计学习用途。