# RAGDocHub **Repository Path**: wangchito/document-hub-of-rag ## Basic Information - **Project Name**: RAGDocHub - **Description**: 基于 RAG（Retrieval-Augmented Generation）架构的智能文档管理与问答平台。支持多种文档格式的上传、自动文本抽取、向量化存储，并提供智能问答、文档总结、关键字段抽取等功能。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2025-11-29 - **Last Updated**: 2026-01-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: Python ## README # AI 文档知识库系统 基于 RAG（Retrieval-Augmented Generation）架构的智能文档管理与问答平台。支持多种文档格式的上传、自动文本抽取、向量化存储，并提供智能问答、文档总结、关键字段抽取等功能。 ## ✨ 功能特性 ### 文档管理 - 📄 支持 PDF、Word (.docx)、Excel (.xlsx) 文档上传 - 🔍 自动文本抽取与结构保留 - 📊 智能分段与向量化存储 ### 智能问答 - 💬 基于 RAG 的智能问答 - 📚 多文档检索与聚合 - 🎯 答案来源引用追溯 - 🔄 多轮对话记忆 ### 文档分析 - 📝 自动文档总结 - 🏷️ 关键字段抽取 - 📈 置信度评分 ### 系统特性 - 🔐 API 认证与授权 - 📜 历史记录管理 - 🔧 动态嵌入模型切换 - 🚀 高性能向量检索 ## 🏗️ 系统架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ 前端 (React + TypeScript) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 文档上传 │ │ 智能对话 │ │ 历史记录 │ │ 仪表板 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 后端 (FastAPI) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 文档服务 │ │ RAG服务 │ │ 对话服务 │ │ 历史服务 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 文档解析 │ │ 智能分段 │ │ 嵌入服务 │ │ 重排序器 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 存储层 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Qdrant 向量库 │ │ SQLite 元数据 │ │ 文件存储 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## 🛠️ 技术栈 ### 后端 - **框架**: FastAPI - **向量数据库**: Qdrant - **嵌入模型**: OpenAI / Sentence-Transformers - **文档解析**: PyMuPDF, python-docx, openpyxl - **数据库**: SQLite + SQLAlchemy - **测试**: pytest + Hypothesis (属性测试) ### 前端 - **框架**: React 18 + TypeScript - **构建工具**: Vite - **路由**: React Router v6 - **样式**: Tailwind CSS - **HTTP 客户端**: Axios - **测试**: Vitest + React Testing Library ## 📁 项目结构 ``` ai-doc-knowledge-base/ ├── backend/ # 后端服务 │ ├── app/ │ │ ├── api/ # API 路由和中间件 │ │ ├── chunking/ # 智能分段模块 │ │ ├── conversation/ # 对话服务模块 │ │ ├── documents/ # 文档管理模块 │ │ ├── embedding/ # 嵌入服务模块 │ │ ├── history/ # 历史记录模块 │ │ ├── parsers/ # 文档解析器 │ │ ├── rag/ # RAG 服务模块 │ │ ├── retrieval/ # 检索与重排序 │ │ ├── summarization/ # 总结与抽取 │ │ ├── vectorstore/ # 向量存储服务 │ │ ├── config.py # 配置管理 │ │ └── main.py # 应用入口 │ ├── tests/ # 测试文件 │ ├── data/ # 数据存储 │ ├── uploads/ # 上传文件存储 │ └── requirements.txt # Python 依赖 ├── frontend/ # 前端应用 │ ├── src/ │ │ ├── components/ # 可复用组件 │ │ ├── pages/ # 页面组件 │ │ ├── layouts/ # 布局组件 │ │ └── services/ # API 服务 │ └── package.json # Node.js 依赖 └── .kiro/ # Kiro 规范文档 └── specs/ └── ai-doc-knowledge-base/ ├── requirements.md # 需求文档 ├── design.md # 设计文档 └── tasks.md # 任务清单 ``` ## 🚀 快速开始 ### 环境要求 - Python 3.10+ - Node.js 18+ - Qdrant (可选，使用内存模式) ### 后端安装 ```bash cd backend # 创建虚拟环境 python -m venv venv # 激活虚拟环境 # Windows venv\Scripts\activate # Linux/Mac source venv/bin/activate # 安装依赖 pip install -r requirements.txt # 配置环境变量 cp .env.example .env # 编辑 .env 文件，配置 API 密钥等 # 启动服务 uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 ``` ### 前端安装 ```bash cd frontend # 安装依赖 npm install # 配置环境变量 cp .env.example .env # 编辑 .env 文件，配置 API 地址 # 启动开发服务器 npm run dev ``` ### 访问应用 - 前端: http://localhost:5173 - 后端 API: http://localhost:8000 - API 文档: http://localhost:8000/docs ## ⚙️ 配置说明 ### 后端配置 (.env) ```env # API 配置 API_KEY=your-api-key API_HOST=0.0.0.0 API_PORT=8000 # 嵌入模型配置 EMBEDDING_PROVIDER=openai # openai / huggingface / local EMBEDDING_MODEL=text-embedding-3-small EMBEDDING_DIMENSION=1536 OPENAI_API_KEY=your-openai-key # Qdrant 配置 QDRANT_HOST=localhost QDRANT_PORT=6333 QDRANT_COLLECTION=documents # LLM 配置 LLM_PROVIDER=openai LLM_MODEL=gpt-4o-mini # 分段配置 CHUNK_SIZE=512 CHUNK_OVERLAP=50 CHUNK_STRATEGY=hybrid ``` ### 前端配置 (.env) ```env VITE_API_BASE_URL=http://localhost:8000 VITE_API_KEY=your-api-key ``` ## 📖 API 接口 ### 文档管理 | 方法 | 路径 | 描述 | |------|------|------| | POST | /api/documents/upload | 上传文档 | | GET | /api/documents | 获取文档列表 | | GET | /api/documents/{id} | 获取文档详情 | | DELETE | /api/documents/{id} | 删除文档 | ### 智能问答 | 方法 | 路径 | 描述 | |------|------|------| | POST | /api/chat | 发送消息 | | GET | /api/conversations | 获取对话列表 | | GET | /api/conversations/{id} | 获取对话详情 | ### RAG 功能 | 方法 | 路径 | 描述 | |------|------|------| | POST | /api/search | 语义搜索 | | POST | /api/summarize/{document_id} | 文档总结 | | POST | /api/extract/{document_id} | 字段抽取 | ### 历史记录 | 方法 | 路径 | 描述 | |------|------|------| | GET | /api/history | 获取历史记录 | | GET | /api/history/search | 搜索历史 | ## 🧪 测试 ### 后端测试 ```bash cd backend # 运行所有测试 pytest # 运行属性测试（详细输出） pytest tests/ -v # 运行特定测试文件 pytest tests/test_rag_properties.py -v ``` ### 前端测试 ```bash cd frontend # 运行测试 npm run test # 代码检查 npm run lint ``` ## 📊 测试覆盖 项目包含 128 个测试用例，覆盖以下模块： - ✅ API 认证与响应格式 - ✅ 文档解析与存储 - ✅ 智能分段 - ✅ 嵌入模型验证与回退 - ✅ 向量存储操作 - ✅ 检索与重排序 - ✅ RAG 服务（引用、置信度、无匹配处理） - ✅ 总结与字段抽取 - ✅ 对话上下文与持久化 - ✅ 历史记录管理 ## 🔧 开发指南 ### 添加新的文档解析器 1. 在 `backend/app/parsers/` 创建新的解析器类 2. 继承 `DocumentParser` 基类 3. 实现 `parse()` 和 `supports()` 方法 4. 在 `ParserFactory` 中注册新解析器 ### 添加新的嵌入模型 1. 在 `backend/app/embedding/` 创建新的服务类 2. 继承 `EmbeddingService` 基类 3. 实现 `embed()` 和 `embed_query()` 方法 4. 在 `EmbeddingManager` 中注册新服务 ## 📝 更新日志 ### v0.1.0 (2024-01) - 初始版本发布 - 支持 PDF、Word、Excel 文档解析 - 实现 RAG 智能问答 - 多轮对话记忆 - 文档总结与字段抽取 - 历史记录管理 ## 📄 License MIT License ## 🤝 贡献 欢迎提交 Issue 和 Pull Request！ ## 📧 联系 如有问题，请提交 Issue 或联系项目维护者。