# fronted_ai

**Repository Path**: raegey/fronted_ai

## Basic Information

- **Project Name**: fronted_ai
- **Description**: ai智参平台前端开发
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-26
- **Last Updated**: 2026-06-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MinIO Knowledge File Manager

仓库地址：`https://gitee.com/raegey/fronted_ai.git`

当前开发分支：`msy_dev`

基于 **FastAPI + Vue 3 + MySQL + MinIO + Milvus** 的知识库文件管理与向量入库服务。当前功能聚焦在文件上传、文件元数据管理、上传任务状态、文件预览下载、文本解析、结构感知切片、embedding 和 Milvus 入库。

> 项目状态：本地开发可用。本文档只覆盖当前已实现的知识库文件管理能力。

## 中文说明

### 已实现功能

| 模块 | 当前能力 |
| --- | --- |
| 文件上传 | 单文件上传、批量上传、MinIO 预签名直传 |
| 文件管理 | MySQL 元数据保存、分页列表、筛选、预览、下载、更新、删除 |
| 任务状态 | 上传任务创建、状态查询、SSE 状态推送 |
| MinIO 同步 | 扫描 `knowledge-base` bucket，将未登记对象补录进 MySQL |
| 向量入库 | 上传后自动解析、切片、embedding，并写入 Milvus |
| 重新切片 | 按 `file_id` 异步重建指定文件的 Milvus chunks |
| 切片查询 | 从 Milvus 分页查询 chunk，支持文件、集合和关键字筛选 |
| 前端页面 | `/#/agents/knowledge` 已接入上传、列表、筛选、任务状态、预览、下载、删除、切片查看 |

### 技术栈

| 组件 | 用途 |
| --- | --- |
| FastAPI | 后端 HTTP API |
| Vue 3 + Vite + Element Plus | 前端管理页面 |
| MySQL + SQLAlchemy | 文件元数据、上传任务状态持久化 |
| MinIO | 文件对象存储 |
| Milvus | chunk 元数据与向量存储 |
| BGEM3 embedding | 文本向量化 |
| SSE | 上传与索引状态推送 |
| Docker Compose | 本地 MySQL、MinIO、Milvus、Attu 基础设施 |

### 目录结构

```text
.
├── main.py                         # FastAPI 应用入口
├── config.py                       # 环境变量配置
├── routers/
│   ├── file_handle_router.py        # 文件上传、列表、预览、下载、同步、重新切片
│   └── chunk_router.py              # Milvus chunk 查询
├── services/                       # 文件元数据、解析、embedding、Milvus、索引编排
├── dao/                            # MySQL 数据访问层
├── models/mysql/                   # SQLAlchemy ORM
├── schemas/                        # Pydantic Schema
├── utils/
│   ├── file_handler.py             # 文件上传处理
│   ├── minio_client.py             # MinIO 封装
│   └── upload_progress.py          # 上传任务状态与进度
├── middlewares/response.py          # JSON 响应封装中间件
├── frontend-ai-main/               # Vue 前端工程
├── scripts/                        # 本地启动脚本
├── docker-compose.yaml             # 本地 MySQL + MinIO + Milvus + Attu
├── requirements.txt
├── .env.example                    # 后端环境变量模板
└── .env.compose.example            # Docker Compose 环境变量模板
```

### 快速开始

Windows 本地推荐直接执行：

```powershell
.\scripts\bootstrap-local.ps1
```

脚本会复制环境变量模板、启动 Docker 基础设施、安装依赖，并启动后端和前端。

手动启动基础设施：

```powershell
copy .env.compose.example .env.compose
docker compose --env-file .env.compose up -d
```

启动后端：

```powershell
copy .env.example .env
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe main.py
```

启动前端：

```powershell
cd frontend-ai-main
pnpm install --frozen-lockfile
pnpm dev
```

### 默认服务地址

| 服务 | 地址 |
| --- | --- |
| 后端 API | `http://127.0.0.1:8019` |
| Swagger 文档 | `http://127.0.0.1:8019/docs` |
| 前端页面 | `http://127.0.0.1:8248/#/agents/knowledge` |
| MySQL | `127.0.0.1:3306` |
| MinIO API | `127.0.0.1:9000` |
| MinIO Console | `http://127.0.0.1:9001` |
| Milvus | `127.0.0.1:19530` |
| Milvus Health | `http://127.0.0.1:9091/healthz` |
| Attu | `http://127.0.0.1:3000` |

MinIO Console 查看上传文件时，进入 `knowledge-base` bucket。后端会给对象名追加 8 位随机后缀防止重名覆盖，例如 `nrs2002_full.md` 可能存成 `nrs2002_full_86d69feb.md`，所以在 Console 里按原文件名前缀搜索。

### 后端环境变量说明

| 变量 | 说明 | 默认值 / 示例 |
| --- | --- | --- |
| `API_HOST` | 后端监听地址 | `0.0.0.0` |
| `API_PORT` | 后端端口 | `8019` |
| `CORS_ALLOW_ORIGINS` | CORS 允许来源，逗号分隔 | `*` |
| `MYSQL_URI` | SQLAlchemy MySQL 连接串 | `mysql+pymysql://root:123456@127.0.0.1:3306/train` |
| `MINIO_ENDPOINT` | MinIO API 地址 | `127.0.0.1:9000` |
| `MINIO_ACCESS_KEY` | MinIO 用户名 | `minioadmin` |
| `MINIO_SECRET_KEY` | MinIO 密码 | `minioadmin` |
| `MINIO_BUCKET` | 默认 bucket | `knowledge-base` |
| `KB_BUCKET_NAME` | 知识库文件 bucket，空值时使用 `MINIO_BUCKET` | `knowledge-base` |
| `MINIO_CONSOLE_URL` | MinIO Console 地址 | `http://127.0.0.1:9001` |
| `MILVUS_HOST` | Milvus 地址 | `127.0.0.1` |
| `MILVUS_PORT` | Milvus gRPC 端口 | `19530` |
| `MILVUS_COLLECTION` | 默认向量 collection | `knowledge_chunks` |
| `MILVUS_DATABASE` | Milvus database | `default` |
| `MILVUS_VECTOR_FIELD` | 向量字段名 | `embedding` |
| `EMBEDDING_PROVIDER` | embedding provider | `cloud` / `openai` / `http` / `ollama` |
| `EMBEDDING_API_URL` | 云端 embedding API 地址 | 空 |
| `EMBEDDING_API_KEY` | 云端 embedding API Key | 空 |
| `EMBEDDING_API_MODEL` | 云端 embedding 模型 | `BAAI/bge-m3` |
| `EMBEDDING_MODEL` | Ollama embedding 模型 | `bge-m3:latest` |
| `EMBEDDING_DIM` | 向量维度 | `1024` |
| `KNOWLEDGE_INDEX_ENABLED` | 上传后是否自动入 Milvus | `true` |
| `KNOWLEDGE_CHUNK_SIZE` | 普通文本切片大小 | `1000` |
| `KNOWLEDGE_CHUNK_OVERLAP` | 相邻切片重叠字符数 | `150` |
| `KNOWLEDGE_CHUNK_MIN_CHARS` | 最小切片字符数 | `20` |
| `KNOWLEDGE_STRUCTURED_CHUNK_SIZE` | 结构块合并目标大小 | `1800` |
| `KNOWLEDGE_INDEX_MAX_FILE_BYTES` | 单文件解析入库大小上限 | `52428800` |
| `UPLOAD_MAX_FILE_SIZE` | 上传文件大小上限，`0` 表示不限制 | `0` |
| `UPLOAD_MAX_CONCURRENCY` | 批量上传后端并发上限 | `3` |
| `UPLOAD_TASK_TTL_SECONDS` | 上传任务状态保留时间 | `3600` |
| `UPLOAD_SSE_POLL_INTERVAL_SECONDS` | SSE 状态轮询间隔 | `1` |
| `MINIO_PRESIGNED_UPLOAD_EXPIRES_SECONDS` | 预签名上传 URL 过期时间 | `900` |
| `MINIO_UPLOAD_PART_SIZE` | MinIO 分片上传大小 | `10485760` |
| `MINIO_UPLOAD_PARALLELISM` | MinIO 分片上传并发数 | `3` |

### API 概览

文件接口根路径：`/api/v1/file`

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `POST` | `/uploadFile` | 单文件上传 |
| `POST` | `/uploadFiles` | 批量上传 |
| `POST` | `/uploadTasks` | 创建上传任务 |
| `GET` | `/uploadTasks/{task_id}` | 查询上传任务状态 |
| `GET` | `/uploadTasks/{task_id}/events` | SSE 订阅上传任务状态 |
| `POST` | `/directUploads/presign` | 创建 MinIO 预签名直传 URL |
| `POST` | `/directUploads/{task_id}/complete` | 直传完成后保存元数据并触发索引 |
| `GET` | `/listFiles` | 分页查询文件列表 |
| `POST` | `/syncMinioFiles` | 扫描 MinIO bucket 并补录 MySQL 元数据 |
| `GET` | `/{file_id}/preview` | 文件预览 |
| `GET` | `/{file_id}/download` | 文件下载 |
| `PATCH` | `/{file_id}` | 更新文件元数据 |
| `POST` | `/{file_id}/reindex` | 重新解析、切片、向量化并写入 Milvus |
| `DELETE` | `/{file_id}` | 删除文件、MySQL 元数据和 Milvus chunks |

`/syncMinioFiles` 常用参数：

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `collection_name` | `default` | 补录到 MySQL 时使用的知识库集合名 |
| `prefix` | 空 | 只扫描指定 MinIO 对象名前缀 |
| `limit` | `1000` | 单次最多扫描对象数 |
| `reindex` | `false` | 是否补录后立即触发向量入库 |

切片接口根路径：`/api/v1/chunks`

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/chunks` | 分页查询 Milvus chunks |
| `GET` | `/api/v1/chunks/files/{file_id}` | 查询指定文件的 chunks |

`/api/v1/chunks` 支持 `file_id`、`file_name`、`collection_name`、`keyword`、`include_vector`、`page`、`page_size` 查询参数。默认不返回向量字段。

详细接口以运行时 Swagger 文档为准：`http://127.0.0.1:8019/docs`。

### 切片策略

当前默认策略名为 `adaptive`，实现为结构感知自适应切片：

- 普通文本按段落、换行、中英文标点寻找切片边界
- PDF 解析时保留 `[Page: N]`
- Excel/CSV 类表格文本保留 `[Sheet: name]`
- Markdown 标题、分隔线、`示例1：`、NRS2002 评分规则块会优先作为结构边界
- NRS2002 这类规则文档会尽量把评分规则和示例分成独立 chunk

### 当前限制

- 上传任务状态使用进程内存存储，单 worker 本地开发可用；多 worker 或多实例需要改为 Redis 等集中式状态存储。
- 上传后自动入库依赖 Milvus 和 embedding 服务可用。
- 旧 Milvus collection 不会自动增加新 metadata 字段；Attu 要看到新增字段，需要新建 collection 或重建旧 collection 后重新入库。

### 提交前检查

```powershell
python -m py_compile main.py routers\file_handle_router.py routers\chunk_router.py services\knowledge_file_service.py services\knowledge_index_service.py services\milvus_vector_service.py dao\knowledge_file_dao.py middlewares\response.py config.py utils\file_handler.py utils\minio_client.py utils\upload_progress.py
ruff check routers\file_handle_router.py routers\chunk_router.py services\knowledge_index_service.py services\milvus_vector_service.py utils\file_handler.py utils\minio_client.py utils\upload_progress.py config.py
cd frontend-ai-main
pnpm build
```

### Git 约定

- 不提交 `.env`
- 不提交 `node_modules/`
- 不提交 `dist/`
- 不提交 `__pycache__/`
- 不提交本地数据库、MinIO 数据卷或临时文件