# ragframework

**Repository Path**: nnstn/ragframework

## Basic Information

- **Project Name**: ragframework
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-07
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG 管理系统 (RAG Framework)

一个基于 Retrieval-Augmented Generation (RAG) 技术的文档检索增强生成管理系统，提供完整的前端门户和后端管理台功能。

## 📋 功能特性

### 前端门户系统
- **门户首页**: 产品介绍、功能展示、快速导航到后端管理台
- **能力商店**: 展示RAG系统具备的核心能力
- **落地案例**: 展示RAG产品的实际应用案例
- **RAG对话页面**: 精简的用户对话界面，支持知识库选择

### 后端管理台
- **左侧菜单树**: 功能模块导航
- **参数配置区**: 各功能模块的参数设置
- **数据显示区**: Tab页展示结果和管理操作

### 核心功能模块
1. **Load File**: 文件上传加载，支持多种加载方法
2. **Chunk File**: 文档分块，支持按页/固定大小/按段/按语义分块
3. **Parse File**: 文件解析，一站式完成加载和分块
4. **Embedding File**: 文档嵌入，支持多种模型提供方
5. **Vector Database Indexing**: 向量数据库索引管理
6. **Similarity Search**: 相似度搜索功能
7. **Generation**: 基于RAG的文本生成
8. **Evaluation**: 生成结果评估

### RBAC权限管理
- 角色管理、用户管理、菜单管理
- 符合4A理念的权限配置

### 其他特性
- 一键换肤（明亮/黑暗模式）
- Mock数据支持开发模式
- 支持远程IP访问

## 🛠️ 技术栈

### 前端
- **Vue 3** - 渐进式JavaScript框架
- **Vite** - 下一代前端构建工具
- **TypeScript** - 类型安全的JavaScript超集
- **Vue Router** - Vue官方路由管理器
- **Axios** - HTTP客户端
- **Element Plus** - Vue 3组件库
- **Lucide Icons** - 图标库

### 后端
- **Python 3.10+** - 编程语言
- **FastAPI** - 高性能Web框架
- **LangChain** - LLM应用开发框架
- **LangGraph** - 多模态应用编排框架
- **uv** - Python包管理器
- **Chroma/Milvus** - 向量数据库

## 📁 项目结构

```
ragframework/
├── frontend/                    # 前端项目
│   ├── src/
│   │   ├── api/                # API接口管理
│   │   ├── components/         # 可复用组件
│   │   ├── config/             # 配置文件（含Mock配置）
│   │   ├── mock/               # Mock数据
│   │   ├── plugins/            # 插件（Mock插件）
│   │   ├── router/             # 路由配置
│   │   ├── store/              # 状态管理
│   │   ├── views/              # 页面视图
│   │   │   ├── portal/         # 门户页面
│   │   │   └── admin/          # 管理台页面
│   │   ├── App.vue             # 根组件
│   │   ├── main.ts             # 入口文件
│   │   └── style.css           # 全局样式
│   ├── index.html
│   ├── package.json
│   ├── vite.config.ts
│   └── tsconfig.json
├── backend/                    # 后端项目
│   ├── routes/                 # API路由
│   ├── utils/                  # 工具函数
│   ├── data/                   # 数据目录（向量数据库等）
│   ├── main.py                 # FastAPI入口
│   ├── pyproject.toml          # 项目配置
│   └── uv.lock                 # 依赖锁定文件
└── README.md
```

## 🚀 快速开始

### 前置要求

- **Node.js**: 24.15.0+ (使用nvm管理)
- **Python**: 3.10+ (使用uv管理)
- **npm**: 10+

### 安装依赖

#### 前端
```bash
cd frontend
npm install
```

#### 后端
```bash
cd backend
uv init
uv pip install -e .
```

### 运行项目

#### 开发模式

**前端**:
```bash
cd frontend
npm run dev
```
访问: http://localhost:5173

**后端**:
```bash
cd backend
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```
访问: http://localhost:8000

#### 生产构建

**前端**:
```bash
cd frontend
npm run build
```

**后端**:
```bash
cd backend
uv run uvicorn main:app --host 0.0.0.0 --port 8000
```

## 🔧 配置说明

### 前端配置

开发模式下，API请求会自动代理到后端（http://localhost:8000），配置在 `vite.config.ts` 中：

```typescript
proxy: {
  '/api': {
    target: 'http://localhost:8000',
    changeOrigin: true
  }
}
```

### 后端配置

环境变量配置（`.env`）:
- `DB_HOST`: 数据库地址（默认: 192.168.222.1）
- `DB_PORT`: 数据库端口（默认: 3306）
- `DB_USER`: 数据库用户名（默认: root）
- `DB_PASSWORD`: 数据库密码（默认: 123456）
- `DB_NAME`: 数据库名称（默认: ragframework）
- `APP_HOST`: 服务绑定地址（默认: 0.0.0.0）
- `APP_PORT`: 服务端口（默认: 8000）
- `OPENAI_API_KEY`: OpenAI API密钥
- `OLLAMA_HOST`: Ollama服务地址
- `MILVUS_HOST`: Milvus数据库地址
- `CHROMADB_PATH`: Chroma数据库路径

### 数据库配置

#### MySQL 数据库连接信息
- **地址**: 192.168.222.1:3306
- **用户名**: root
- **密码**: 123456
- **数据库名**: ragframework

#### 数据库初始化
```bash
cd backend

# 创建数据库（如不存在）
mysql -h 192.168.222.1 -u root -p123456 -e "CREATE DATABASE IF NOT EXISTS ragframework"

# 初始化数据库表和默认数据
uv run python -c "from database.config import engine, Base; Base.metadata.create_all(bind=engine)"
```

#### 初始化默认账号
系统会自动在启动时初始化以下默认数据：
- **管理员角色**: admin（拥有所有权限）
- **普通用户角色**: user（基本权限）
- **管理员账号**: admin / 123456

## 🔗 前后端联调指南

### 一、环境准备

#### 1. 启动后端服务
```bash
cd /home/rag/coding/ragframework/backend
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

#### 2. 启动前端服务
```bash
cd /home/rag/coding/ragframework/frontend
npm run dev
```

#### 3. 确认代理配置
前端已在 `vite.config.ts` 中配置了代理，所有 `/api` 请求会自动转发到后端。

### 二、Mock数据控制

前端支持灵活的Mock数据控制，配置文件位于 `src/config/mock.config.ts`：

```typescript
export const mockConfig = {
  enable: true,              // 全局Mock开关
  partialMode: true,         // 部分Mock模式
  mockEndpoints: [           // 使用Mock的接口列表
    '/api/auth/login',
    '/api/rbac/roles',
    // ...
  ],
  realEndpoints: [           // 强制使用真实接口的列表
    '/api/generation/chat',
    '/api/similarity-search/search',
    // ...
  ]
}
```

**关闭特定接口Mock**：将接口从 `mockEndpoints` 中移除或注释掉即可。

### 三、功能模块联调步骤

#### 1. Load File（文件加载）
- **接口**: `POST /api/load-file/load`
- **测试步骤**:
  1. 进入"文件管理"页面
  2. 点击"上传文件"按钮
  3. 选择PDF/Excel/文本文件上传
  4. 查看文件列表是否显示

#### 2. Chunk File（文档分块）
- **接口**: `POST /api/chunk-file/chunk`
- **测试步骤**:
  1. 上传文件后，选择"分块"操作
  2. 配置分块参数（大小、方式）
  3. 执行分块，查看分块结果

#### 3. Parse File（文件解析）
- **接口**: `POST /api/parse-file/parse`
- **测试步骤**:
  1. 上传文件后，选择"解析"操作
  2. 查看解析后的文本内容

#### 4. Embedding（文档嵌入）
- **接口**: `POST /api/embedding/embed`
- **测试步骤**:
  1. 选择已解析的文件
  2. 选择嵌入模型
  3. 执行嵌入，查看嵌入结果

#### 5. Vector Indexing（向量索引）
- **接口**: `POST /api/vector-indexing/index`
- **测试步骤**:
  1. 选择已嵌入的文档
  2. 创建向量索引
  3. 查看索引状态

#### 6. Similarity Search（相似度搜索）
- **接口**: `POST /api/similarity-search/search`
- **测试步骤**:
  1. 输入搜索关键词
  2. 执行搜索，查看匹配结果

#### 7. Generation（文本生成）
- **接口**: `POST /api/generation/generate`
- **测试步骤**:
  1. 输入问题
  2. 选择知识库
  3. 生成回答，查看结果

#### 8. Evaluation（结果评估）
- **接口**: `POST /api/evaluation/evaluate`
- **测试步骤**:
  1. 选择生成结果
  2. 执行评估，查看评分

### 四、日志查看途径

#### 1. 前端日志

**浏览器控制台**:
- 按 `F12` 打开开发者工具
- **Console**: 查看前端日志和错误信息
- **Network**: 查看所有API请求（筛选 `XHR`）

**代理日志**:
前端代理会输出请求日志到终端：
```
[Proxy] POST /api/load-file/upload -> http://localhost:8000
```

#### 2. 后端日志

**终端输出**:
```
INFO:     127.0.0.1:54321 - "POST /api/load-file/upload HTTP/1.1" 200 OK
```

**详细日志模式**:
```bash
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --reload --log-level debug
```

**日志持久化**:
```bash
uv run uvicorn main:app --host 0.0.0.0 --port 8000 > backend.log 2>&1 &
```

#### 3. API文档

启动后端后访问 Swagger UI：
- **地址**: http://localhost:8000/docs
- **功能**: 在线测试API、查看接口参数和返回值

### 五、常见问题排查

#### 1. 接口 404 错误
- ✅ 确认后端服务已启动
- ✅ 确认接口路径是否正确
- ✅ 检查路由定义文件

#### 2. 跨域错误
- ✅ 确认后端已启用CORS（FastAPI默认启用）
- ✅ 确认代理配置正确

#### 3. 文件上传失败
- ✅ 检查文件大小限制
- ✅ 检查文件格式是否支持
- ✅ 查看后端日志中的具体错误

#### 4. Mock不生效
- ✅ 检查 `mock.config.ts` 配置
- ✅ 确认 `enable` 为 `true`
- ✅ 确认接口路径匹配

### 六、联调验证清单

| 步骤 | 操作 | 预期结果 |
|------|------|----------|
| 1 | 启动后端 | 终端显示 `Uvicorn running on http://0.0.0.0:8000` |
| 2 | 启动前端 | 终端显示 `VITE v6.x.x ready in xxx ms` |
| 3 | 访问前端 | 页面正常加载，无控制台报错 |
| 4 | 上传文件 | 文件成功上传，显示在列表中 |
| 5 | 查看后端日志 | 显示请求记录 |

## 📝 API接口

### 功能模块
| 接口 | 路径 | 方法 | 描述 |
|------|------|------|------|
| 加载文件 | `/api/load-file/load` | POST | 上传并加载文件 |
| 获取文件列表 | `/api/load-file/files` | GET | 获取所有文件 |
| 获取文件详情 | `/api/load-file/files/{id}` | GET | 获取单个文件 |
| 更新文件 | `/api/load-file/files/{id}` | PUT | 更新文件信息 |
| 删除文件 | `/api/load-file/files/{id}` | DELETE | 删除文件 |
| 文件分块 | `/api/chunk-file/chunk` | POST | 对文件进行分块 |
| 获取分块列表 | `/api/chunk-file/chunks` | GET | 获取所有分块 |
| 文件解析 | `/api/parse-file/parse` | POST | 解析文件内容 |
| 文档嵌入 | `/api/embedding/embed` | POST | 生成文档嵌入向量 |
| 获取嵌入列表 | `/api/embedding/embeddings` | GET | 获取所有嵌入 |
| 获取嵌入提供者 | `/api/embedding/providers` | GET | 获取可用模型 |
| 向量索引 | `/api/vector-indexing/index` | POST | 创建向量索引 |
| 获取索引列表 | `/api/vector-indexing/indices` | GET | 获取所有索引 |
| 获取集合列表 | `/api/vector-indexing/collections` | GET | 获取数据库集合 |
| 获取数据库列表 | `/api/vector-indexing/databases` | GET | 获取可用数据库 |
| 相似度搜索 | `/api/similarity-search/search` | POST | 执行相似度搜索 |
| 获取搜索历史 | `/api/similarity-search/history` | GET | 获取搜索历史 |
| 文本生成 | `/api/generation/generate` | POST | 基于RAG生成文本 |
| 获取生成历史 | `/api/generation/history` | GET | 获取生成历史 |
| 结果评估 | `/api/evaluation/evaluate` | POST | 评估生成结果 |
| 获取评估列表 | `/api/evaluation/evaluations` | GET | 获取所有评估 |
| 获取评估统计 | `/api/evaluation/statistics` | GET | 获取评估统计 |

### RBAC管理
| 接口 | 路径 | 方法 | 描述 |
|------|------|------|------|
| 获取角色列表 | `/api/rbac/roles` | GET | 获取所有角色 |
| 创建角色 | `/api/rbac/roles` | POST | 创建新角色 |
| 获取用户列表 | `/api/rbac/users` | GET | 获取所有用户 |
| 创建用户 | `/api/rbac/users` | POST | 创建新用户 |
| 获取菜单列表 | `/api/rbac/menus` | GET | 获取所有菜单 |
| 创建菜单 | `/api/rbac/menus` | POST | 创建新菜单 |

### 认证管理
| 接口 | 路径 | 方法 | 描述 |
|------|------|------|------|
| 用户登录 | `/api/auth/login` | POST | 用户登录 |
| 用户登出 | `/api/auth/logout` | POST | 用户登出 |

## 📊 依赖管理指南

### 前端依赖更新
```bash
cd frontend
npm update              # 更新所有依赖
npm outdated            # 检查过时依赖
```

### 后端依赖更新
```bash
cd backend
uv pip compile --upgrade pyproject.toml    # 检查并编译更新
uv pip install -e .                        # 安装更新
```

### 定期维护建议

建议每月执行以下维护操作：

```bash
# 前端
cd frontend
npm audit               # 检查安全漏洞
npm update
npm run build           # 验证构建

# 后端
cd backend
uv pip compile --upgrade --dry-run         # 检查更新
uv pip compile --upgrade
uv pip install -e .
uv run python -c "import main; print('Backend OK')"
```

## 🎨 主题切换

系统支持明亮/黑暗两种主题模式，点击右上角的主题切换按钮即可切换，主题设置会持久化保存到localStorage。

## 🧪 Mock功能

开发模式下，前端会自动使用Mock数据，无需启动后端即可预览所有功能。通过 `src/config/mock.config.ts` 可以灵活配置哪些接口使用Mock，哪些接口使用真实后端。

## 🧪 测试环境操作说明

### 1. 环境检查清单

启动服务前，请确认以下服务已就绪：

| 服务 | 检查命令 | 预期结果 |
|------|---------|---------|
| MySQL | `mysql -h 192.168.222.1 -u root -p123456 -e "SELECT 1"` | 连接成功 |
| Ollama（可选） | `curl http://localhost:11434/api/version` | 返回版本信息 |
| ChromaDB（可选） | 检查 `backend/data/chroma` 目录 | 目录存在 |

### 2. 启动测试环境

#### 步骤1：启动后端
```bash
cd backend
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

#### 步骤2：启动前端
```bash
cd frontend
npm run dev
```

#### 步骤3：验证服务
```bash
# 检查后端健康状态
curl http://localhost:8000/health

# 检查前端访问
curl http://localhost:5173
```

### 3. 数据库连接测试

```bash
# 使用 mysql 客户端测试
mysql -h 192.168.222.1 -u root -p123456 -e "USE ragframework; SHOW TABLES;"

# 使用 Python 测试
uv run python -c "
from database.config import engine
from sqlalchemy import text
with engine.connect() as conn:
    result = conn.execute(text('SELECT 1'))
    print('数据库连接成功:', result.fetchone())
"
```

### 4. API 接口测试

#### 使用 Swagger UI 测试
启动后端后访问：http://localhost:8000/docs

#### 使用 curl 测试认证接口
```bash
# 测试登录
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "123456"}'

# 测试获取用户信息
curl -X GET http://localhost:8000/api/auth/user/profile \
  -H "Authorization: Bearer <token>"

# 测试获取角色列表
curl -X GET http://localhost:8000/api/rbac/roles

# 测试获取菜单列表
curl -X GET http://localhost:8000/api/rbac/menus
```

### 5. 日志查看

#### 后端日志
```bash
# 实时查看后端日志
tail -f backend.log

# 查看错误日志
grep -i error backend.log
```

#### 前端代理日志
前端终端会显示代理请求日志：
```
[Proxy] POST /api/auth/login -> http://localhost:8000
```

#### 浏览器开发者工具
- `F12` 打开控制台
- Network 标签查看 API 请求
- Console 标签查看前端日志

### 6. 常见测试问题排查

#### 数据库连接失败
```bash
# 检查 MySQL 服务
mysql -h 192.168.222.1 -u root -p123456 -e "SELECT 1"

# 检查端口是否开放
telnet 192.168.222.1 3306
```

#### 后端启动失败
```bash
# 检查依赖安装
uv pip list | grep -E "sqlalchemy|pymysql"

# 检查环境变量
cat .env

# 查看详细错误
uv run uvicorn main:app --reload --log-level debug
```

#### 前端无法连接后端
```bash
# 检查代理配置
cat frontend/vite.config.ts | grep -A 5 proxy

# 检查 CORS 配置
grep -A 5 CORSMiddleware backend/main.py
```

## 📄 许可证

MIT License

## 📮 联系方式

如有问题或建议，请通过以下方式联系：
- 邮箱: support@ragframework.io
- 项目地址: https://github.com/ragframework/frameworkrag