11 KiB
11 KiB
Tip
注意，本文档仅为开发过程中团队交流使用，非正式的readme文档。
技术栈
| 层次 | 组件 | 说明 |
|---|---|---|
| 前端 | Vue 3 / React + Element Plus | 文件上传、表格配置、聊天界面 |
| 后端 | FastAPI | 提供 RESTful API，异步任务调度 |
| 异步任务 | Celery + Redis | 处理耗时的解析与 AI 提取 |
| 数据库 | MongoDB（元数据、提取结果） | 存储文档块、最终结构化数据 |
| 向量检索 | faiss-cpu + 本地索引文件 | 高效相似性搜索，配合 MongoDB 使用 |
| AI 集成 | LangChain + 国内大模型 API | RAG 流水线、提示词管理 |
| 文档解析 | python-docx, pandas, markdown, 原生文件操作 | 多格式支持 |
| 部署 | Docker + Nginx + Gunicorn | 打包演示，本地或云服务器运行 |
环境配置
部署好项目后，一般在终端都显示目前操作路径为 xx\FilesReadSystem 在终端输入：
cd backend
以进入后端项目目录 此时终端显示目前操作路径为 xx\FilesReadSystem\backend 接着在终端输入：
python312 -m venv venv
以指定python创建python虚拟环境，可确保软件包不会与系统python版本冲突 创建虚拟环境成功后，在终端输入：
.\venv\Scripts\Activate.ps1 #如果你的终端是powershell，请使用此命令
.\venv\Scripts\Activate.bat #如果你的终端是cmd，请使用此命令
激活虚拟环境成功后，在终端输入：
pip install -r requirements.txt
以安装项目需要的依赖包
如果你用的是vscode，那么现在我们要配置自动启动python的虚拟环境 在项目的根目录下（即与backend同级）创建一个名为.vscode的文件夹 在.vscode文件夹中创建一个名为settings.json的文件 settings.json内容如下：
{
"python.defaultInterpreterPath": "${workspaceFolder}/backend/venv/Scripts/python.exe"
}
保存即可
关于.gitignore
为了在上传git仓库时，不把venv中的软件包和其他关于项目的特殊api key暴露，请将.gitignore文件放在项目根目录下，并添加以下内容：
/.git/
/.gitignore
/.idea/
/.vscode/
/backend/venv/
/backend/command/
/backend/.env
/backend/.env.local
/backend/.env.*.local
关于env的说明
为了数据安全，请不要把api key暴露，请将api key保存在.env文件中，并添加到.gitignore中（正如前文所示），这样git就不会将api key上传到git仓库中。 但，可以保留.env.example文件，以示需要调用的api key
预计项目结构：
FilesReadSystem/
├── backend/ # 后端服务（Python + FastAPI）
│ ├── app/ # 主应用代码
│ │ ├── api/ # API 路由层
│ │ │ ├── __init__.py
│ │ │ ├── endpoints/ # 各功能模块的路由
│ │ │ │ ├── __init__.py
│ │ │ │ ├── upload.py # 文件上传接口
│ │ │ │ ├── task.py # 任务状态查询接口
│ │ │ │ ├── result.py # 结果获取接口
│ │ │ │ ├── instruction.py # 自然语言指令接口
│ │ │ │ └── template.py # 表格模板管理接口
│ │ │ └── dependencies.py # 通用依赖（如数据库会话）
│ │ ├── core/ # 核心业务逻辑
│ │ │ ├── __init__.py
│ │ │ ├── document_parser/ # 文档解析模块（第二阶段）
│ │ │ │ ├── __init__.py
│ │ │ │ ├── base.py # 解析器基类
│ │ │ │ ├── docx_parser.py # .docx 解析
│ │ │ │ ├── xlsx_parser.py # .xlsx 解析
│ │ │ │ ├── md_parser.py # .md 解析
│ │ │ │ ├── txt_parser.py # .txt 解析
│ │ │ │ └── utils.py # 清洗、分块等工具函数
│ │ │ ├── rag/ # RAG 检索增强生成模块（第三阶段）
│ │ │ │ ├── __init__.py
│ │ │ │ ├── embeddings.py # Embedding 模型封装
│ │ │ │ ├── vector_store.py # faiss 向量索引管理
│ │ │ │ ├── retriever.py # 检索器（从 faiss 取回 + MongoDB 补充元数据）
│ │ │ │ └── llm_chain.py # LLM 调用链（Prompt 模板、解析输出）
│ │ │ ├── table_filler/ # 表格自动填写模块（第三阶段）
│ │ │ │ ├── __init__.py
│ │ │ │ ├── template_reader.py # 读取表格模板结构
│ │ │ │ ├── data_extractor.py # 根据模板提取数据（调用 RAG + LLM）
│ │ │ │ └── excel_writer.py # 将数据回填到 Excel
│ │ │ └── instruction/ # 自然语言指令解析模块（第一阶段）
│ │ │ ├── __init__.py
│ │ │ ├── intent_parser.py # 意图识别
│ │ │ └── executor.py # 指令执行（调用其他核心模块）
│ │ ├── models/ # 数据库模型（MongoDB 文档模型）
│ │ │ ├── __init__.py
│ │ │ ├── document.py # 文档元数据模型
│ │ │ ├── chunk.py # 文档块模型（用于 faiss 元数据）
│ │ │ ├── task.py # 异步任务模型
│ │ │ └── result.py # 提取结果模型
│ │ ├── schemas/ # Pydantic 模型（请求/响应校验）
│ │ │ ├── __init__.py
│ │ │ ├── file.py
│ │ │ ├── task.py
│ │ │ ├── result.py
│ │ │ └── instruction.py
│ │ ├── services/ # 服务层（封装数据库操作等）
│ │ │ ├── __init__.py
│ │ │ ├── mongo_service.py # MongoDB 通用操作
│ │ │ └── file_service.py # 文件存储服务
│ │ ├── tasks/ # Celery 异步任务定义
│ │ │ ├── __init__.py
│ │ │ ├── celery_app.py # Celery 实例
│ │ │ ├── document_tasks.py # 文档处理任务（解析、向量化、提取）
│ │ │ └── table_tasks.py # 表格填写任务
│ │ ├── utils/ # 工具函数
│ │ │ ├── __init__.py
│ │ │ ├── logger.py # 日志配置
│ │ │ ├── file_utils.py # 文件操作
│ │ │ └── exceptions.py # 自定义异常
│ │ ├── config.py # 应用配置（环境变量读取）
│ │ ├── main.py # FastAPI 应用入口
│ │ └── dependencies.py # 全局依赖
│ ├── tests/ # 测试目录（原有 MongoDBConnectionTest.py 保留）
│ │ ├── __init__.py
│ │ ├── conftest.py # pytest fixtures
│ │ ├── test_api/ # API 测试
│ │ │ ├── test_upload.py
│ │ │ └── ...
│ │ ├── test_core/ # 核心模块单元测试
│ │ │ ├── test_document_parser.py
│ │ │ └── ...
│ │ ├── test_tasks/ # 任务测试
│ │ └── MongoDBConnectionTest.py # 已存在的 MongoDB 连接测试
│ ├── venv/ # Python 虚拟环境（gitignore）
│ ├── requirements.txt # Python 依赖
│ ├── requirements-dev.txt # 开发依赖（如 pytest, black）
│ ├── .env.example # 环境变量示例
│ ├── Dockerfile # 后端 Docker 镜像构建文件
│ ├── docker-compose.yml # 本地开发服务编排（MongoDB, Redis, 后端）
│ └── README.md # 后端说明文档
│
├── frontend/ # 前端项目（Vue/React）
│ ├── public/
│ ├── src/
│ │ ├── api/ # 后端 API 调用封装
│ │ ├── components/ # 通用组件
│ │ ├── views/ # 页面视图
│ │ │ ├── UploadView.vue # 文件上传页
│ │ │ ├── TaskStatusView.vue # 任务状态页
│ │ │ ├── ResultView.vue # 结果展示页
│ │ │ └── InstructionView.vue # 自然语言指令交互页
│ │ ├── router/ # 路由配置
│ │ ├── store/ # 状态管理
│ │ ├── App.vue
│ │ └── main.js
│ ├── package.json
│ ├── vue.config.js / vite.config.js
│ ├── Dockerfile # 前端 Docker 镜像构建文件
│ └── README.md
│
├── data/ # 本地数据目录（gitignore）
│ ├── uploads/ # 上传文件临时存储
│ ├── faiss_index/ # faiss 索引文件保存位置
│ └── outputs/ # 生成的表格文件下载缓存
│
├── docs/ # 项目文档（提交材料准备）
│ ├── 01_项目概要介绍.md
│ ├── 02_项目简介PPT.pptx
│ ├── 03_项目详细方案.md
│ ├── 04_演示视频说明.md
│ ├── 05_企业要求材料/
│ │ ├── 训练素材来源说明.md
│ │ ├── 关键模块概要设计与创新要点.md
│ │ └── Demo运行说明.md
│ └── 06_其他补充材料/
│
├── scripts/ # 辅助脚本
│ ├── build_faiss_index.py # 预构建向量索引（基于已有文档集）
│ ├── generate_test_data.py # 生成模拟测试数据
│ └── evaluate.py # 准确率评估脚本
│
├── .gitignore
├── README.md # 项目总 README
└── docker-compose.yml # 全局编排（包含前端、后端、数据库、Redis）