# HR_RAG

**Repository Path**: empireFramework/HR_RAG

## Basic Information

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

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-08
- **Last Updated**: 2026-03-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG 智能问答系统

基于 Flask + LangChain + ChromaDB 的企业级 RAG（检索增强生成）问答系统。

## 功能特性

- ✅ **多选知识库检索** - 支持同时勾选多个知识库进行联合查询
- ✅ **用户认证系统** - 注册/登录/登出，数据按用户隔离
- ✅ **知识库管理** - 创建/编辑/删除知识库，支持中文名称自动转换
- ✅ **文档管理** - 上传/列表/删除（支持 PDF/DOCX/TXT/MD），MIME 类型验证
- ✅ **智能问答** - 基于向量检索 + LLM 生成答案，显示来源引用
- ✅ **文档预览** - 点击来源可查看文档块原文
- ✅ **聊天历史记录** - 对话自动保存，支持查看历史会话
- ✅ **流式响应** - SSE 流式返回 AI 回答
- ✅ **批量删除** - 支持一次删除多个文档
- ✅ **同步删除** - 删除文档时自动清理向量数据库
- ✅ **速率限制** - 登录/注册接口防暴力破解
- ✅ **现代化 UI** - 响应式设计，渐变视觉效果

## 技术栈

| 组件 | 技术 |
|------|------|
| 后端框架 | Flask 3.1.3 |
| 用户认证 | Flask-Login 0.6.3 |
| 数据库 ORM | SQLAlchemy (SQLite) |
| 向量数据库 | ChromaDB 1.5.2 |
| LLM 框架 | LangChain Text Splitters 1.1.1 |
| LLM 模型 | 阿里通义千问 / DeepSeek（可切换） |
| Embedding | text-embedding-v4（DashScope） |
| 文档处理 | python-docx, pypdf, PyPDF2 |
| 文件验证 | python-magic-bin |
| 速率限制 | flask-limiter |
| 工具库 | pypinyin (中文转拼音) |

## 快速开始

### 1. 安装依赖

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

### 2. 配置环境变量

```bash
# 复制示例配置
cp .env.example .env

# 编辑 .env 文件，填入你的 API 密钥
# DASHSCOPE_API_KEY=your-key-here

# 可选：选择 LLM 提供商（默认使用 DashScope）
# LLM_PROVIDER=dashscope   # 阿里通义千问
# LLM_PROVIDER=deepseek    # DeepSeek
```

### 3. 初始化数据库

```bash
python init_db.py
```

### 4. 启动服务

```bash
python app.py
```

访问 http://localhost:5000

## 项目结构

```
HR_RAG/
├── app.py                  # Flask 应用入口
├── config.py               # 配置管理（开发/生产/测试）
├── extensions.py           # 扩展初始化 (SQLAlchemy, LoginManager, Limiter)
├── init_db.py              # 数据库初始化脚本
├── requirements.txt        # 依赖列表
├── .env                    # 环境变量（需自行创建）
├── .env.example            # 环境变量示例
├── .gitignore              # Git 忽略文件
│
├── models/
│   ├── __init__.py
│   ├── user.py             # 用户模型
│   ├── collection.py       # 知识库模型
│   ├── document.py         # 文档模型
│   └── conversation.py     # 聊天会话和消息模型
│
├── routes/
│   ├── __init__.py
│   ├── auth.py             # 认证路由（登录/注册/登出，带速率限制）
│   ├── chat.py             # 聊天路由（问答/知识库选择/聊天历史/流式响应）
│   ├── document.py         # 文档路由（上传/列表/删除/预览/批量删除）
│   └── collection_management.py  # 知识库管理路由
│
├── services/
│   ├── __init__.py
│   ├── rag_service.py      # RAG 服务（文本提取/分块/问答）
│   └── vector_store.py     # 向量存储服务（ChromaDB 操作）
│
├── templates/
│   ├── auth/
│   │   ├── login.html      # 登录页面
│   │   └── register.html   # 注册页面
│   ├── chat/
│   │   └── chat.html       # 聊天主页面
│   ├── collection/
│   │   ├── create.html     # 创建知识库
│   │   ├── edit.html       # 编辑知识库
│   │   ├── list.html       # 知识库列表
│   │   └── documents.html  # 知识库文档管理
│   └── documents/
│       ├── list.html       # 文档管理列表
│       └── upload.html     # 独立上传页面
│
├── tests/
│   ├── conftest.py         # pytest 配置和 fixture
│   ├── test_user.py        # 用户模型测试
│   ├── test_auth.py        # 认证路由测试
│   └── test_vector_store.py # 向量存储服务测试
│
├── static/                 # 静态资源（如有）
├── uploads/                # 上传的文件（运行时创建）
├── chroma/                 # ChromaDB 数据（运行时创建）
└── logs/                   # 日志文件（运行时创建）
```

## API 接口

### 认证

| 路由 | 方法 | 说明 |
|------|------|------|
| `/auth/login` | GET/POST | 用户登录（速率限制：5 次/分钟） |
| `/auth/register` | GET/POST | 用户注册（速率限制：3 次/分钟） |
| `/auth/logout` | GET | 用户登出 |

### 聊天

| 路由 | 方法 | 说明 |
|------|------|------|
| `/chat/` | GET | 聊天页面 |
| `/chat/` | POST | 发送消息，返回答案和来源，自动保存历史 |
| `/chat/stream/` | POST | 流式聊天（SSE） |
| `/collections/` | GET | 获取知识库列表（JSON） |
| `/collections/` | POST | 更新选中的知识库（Session） |
| `/conversations/` | GET | 获取聊天历史列表 |
| `/conversations/<id>/` | GET | 获取特定会话详情 |
| `/conversations/<id>/` | DELETE | 删除会话 |

### 知识库管理

| 路由 | 方法 | 说明 |
|------|------|------|
| `/collection/` | GET | 知识库列表页面 |
| `/collection/create` | GET/POST | 创建知识库 |
| `/collection/edit/<id>` | GET/POST | 编辑知识库 |
| `/collection/delete/<id>` | POST | 删除知识库 |
| `/collection/<id>/documents` | GET | 查看知识库中的文档 |
| `/collection/api/list` | GET | 获取知识库列表（API） |

### 文档管理

| 路由 | 方法 | 说明 |
|------|------|------|
| `/document/` | GET | 文档管理列表页面 |
| `/document/upload` | GET/POST | 上传文档（支持 AJAX，MIME 验证） |
| `/document/delete/<id>` | POST | 删除文档（同步删除向量） |
| `/document/api/list` | GET | 获取文档列表（API） |
| `/document/api/preview/<id>` | GET | 获取文档预览内容 |
| `/document/api/preview/<id>/<chunk>` | GET | 获取特定 chunk 内容 |
| `/document/api/batch-delete` | POST | 批量删除文档 |
| `/document/api/collection/<id>/documents` | GET | 获取知识库中的文档 |

## 使用说明

### 1. 注册账户

访问 `/auth/register` 创建账户，系统会为你的数据建立隔离。

### 2. 创建知识库

- 点击"知识库管理" → "创建知识库"
- 输入知识库名称和描述（可选）
- 中文名称会自动转换为拼音存储到 ChromaDB

### 3. 上传文档

有两种方式：
- **方式一**：知识库列表 → 点击"上传文档"按钮 → 选择文件
- **方式二**：知识库 → 查看文档 → "上传文档"按钮 → 选择文件

支持格式：PDF, DOCX, TXT, MD
上传后会进行 MIME 类型验证，显示加载进度条，处理完成后自动刷新。

### 4. 选择知识库

在聊天页面底部勾选一个或多个知识库，系统会在这些知识库中检索。

### 5. 开始提问

输入问题后：
1. 系统在选中的知识库中检索相关内容（按向量相似度）
2. 检索结果按距离过滤（默认阈值 1.5）
3. 将检索结果和问题发送给 LLM
4. 返回基于知识库的答案，并显示来源引用
5. 点击来源可查看文档块原文
6. 对话自动保存到聊天历史

### 6. 查看聊天历史

- 访问 `/conversations/` 查看所有历史会话
- 点击会话查看详情
- 可删除不需要的会话

## 配置说明

### 环境变量 (.env)

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `SECRET_KEY` | Flask 安全密钥 | 自动生成 |
| `DASHSCOPE_API_KEY` | 阿里 DashScope API 密钥 | - |
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥 | - |
| `LLM_PROVIDER` | LLM 提供商（dashscope/deepseek） | 自动选择 |
| `DATABASE_URL` | SQLite 数据库连接 | `sqlite:///rag.db` |
| `CHROMA_PERSIST_DIRECTORY` | ChromaDB 持久化路径 | `./chroma` |
| `DEFAULT_N_RESULTS` | 默认检索数量 | 5 |
| `DEFAULT_CHUNK_SIZE` | 分块大小 | 300 |
| `DEFAULT_CHUNK_OVERLAP` | 分块重叠 | 30 |
| `DEFAULT_SIMILARITY_THRESHOLD` | 相似度阈值（距离） | 1.5 |
| `LOG_LEVEL` | 日志级别 | INFO |
| `LOG_FILE` | 日志文件路径 | logs/app.log |

### 关键配置 (config.py)

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `LLM_PROVIDER` | LLM 提供商选择 | 自动（优先 DashScope） |
| `LLM_MODEL` | 当前使用的 LLM 模型 | `qwen-turbo-latest` |
| `EMBEDDING_MODEL` | Embedding 模型 | `text-embedding-v4` |
| `DEFAULT_SIMILARITY_THRESHOLD` | 相似度阈值（距离） | 1.5 |

## 模型切换

系统支持两种 LLM 提供商，通过 `.env` 中的 `LLM_PROVIDER` 变量控制：

```bash
# 使用阿里通义千问（默认）
LLM_PROVIDER=dashscope
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxx

# 使用 DeepSeek
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxx
```

**自动选择规则**：
1. 如果配置了 `LLM_PROVIDER`，则使用指定提供商
2. 如果未配置，优先使用 `DASHSCOPE_API_KEY`
3. 如果只有 `DEEPSEEK_API_KEY`，则使用 DeepSeek

**注意**：Embedding 固定使用 DashScope 的 `text-embedding-v4`，无论选择哪个 LLM 提供商。

## 知识库管理策略

推荐按主题分类组织知识库：

```
📚 公司制度
  ├── 考勤管理制度.pdf
  ├── 财务报销流程.docx
  └── 员工招聘管理办法.txt

📚 技术资料
  ├── API 接口文档.md
  ├── 系统架构设计.pdf
  └── 数据库设计规范.docx

📚 产品手册
  ├── 产品使用说明.pdf
  └── 常见问题 FAQ.txt
```

聊天时可多选知识库进行联合检索，例如同时选择"公司制度"和"技术资料"。

## 注意事项

1. **API 密钥**: 使用前请确保在 `.env` 中配置有效的 API 密钥（`DASHSCOPE_API_KEY` 用于 Embedding，`LLM_API_KEY` 用于 LLM）
2. **Embedding 必须**：无论使用哪个 LLM，都必须配置 `DASHSCOPE_API_KEY`（用于向量嵌入）
3. **文件编码**: 上传的 TXT/MD 文件请使用 UTF-8 编码
4. **中文集合名**: 系统会自动将中文知识库名称转换为拼音
5. **权限控制**: 用户只能访问和删除自己上传的文档和知识库
6. **向量同步删除**: 删除文档时会自动从 ChromaDB 删除对应的向量数据
7. **上传大小限制**: 建议单个文件不超过 50MB
8. **速率限制**: 登录 5 次/分钟，注册 3 次/分钟

## 测试

```bash
# 运行所有测试
pytest tests/ -v

# 运行特定测试文件
pytest tests/test_user.py -v
pytest tests/test_auth.py -v

# 带覆盖率报告
pytest tests/ -v --cov=. --cov-report=html
```

## 常见问题

**Q: 上传文档后检索不到内容？**
A: 检查文件是否成功分块（查看文档列表中的 chunk 数），确认知识库已勾选。

**Q: 删除文档后还能搜索到？**
A: 这是缓存问题，重启应用或手动清理 ChromaDB 数据目录 (`./chroma/`)。

**Q: 答案不准确？**
A: 尝试调整 `DEFAULT_N_RESULTS` 增加检索数量，或优化知识库文档质量。

**Q: 提示"请求过于频繁"？**
A: 触发了速率限制，请等待 1 分钟后重试。

**Q: 聊天历史在哪里查看？**
A: 访问 `/conversations/` 查看所有历史会话。

## 依赖列表

详见 `requirements.txt`：

- Flask 3.1.3
- Flask-Login 0.6.3
- Flask-SQLAlchemy 3.1.1
- ChromaDB 1.5.2
- langchain-text-splitters 1.1.1
- openai 2.26.0
- dashscope 1.25.13
- flask-limiter 4.1.1
- python-magic-bin 0.4.14
- pytest 8.0.0

## License

MIT License