基于 RAG 的知识库问答与文档处理平台

简介 • 核心能力 • 项目结构 • 快速开始 • 配置说明 • API 概览 • 常见问题

## 简介 RAG Web UI 是一个面向企业知识库场景的全栈项目，提供从文档接入、向量化检索、对话问答到文档工程化处理的完整链路。项目采用前后端分离架构： - 后端基于 FastAPI，负责认证、知识库、向量检索、文档处理任务与工具调用。 - 前端基于 Next.js，提供知识库管理、聊天、文档处理等可视化页面。 - 基础设施使用 MySQL、ChromaDB、MinIO，可通过 Docker Compose 一键启动。 ## 核心能力 - 知识库管理：支持 PDF、DOCX、Markdown、TXT 上传，预览、异步处理、状态追踪。 - RAG 对话：支持多轮上下文问答，结合知识库检索结果生成回答。 - 文档处理中心：提供需求提取、测试内容生成等工程化能力。 - 工具中心：后端内置工具注册与调用机制，支持后续扩展更多可被模型调用的工具。 - 多模型支持：支持 OpenAI、DashScope、DeepSeek、Ollama 等配置方式。 ## 项目结构 ```text rag-web-ui/ backend/ # FastAPI 后端 app/ api/api_v1/ # 业务 API 路由（auth/chat/knowledge-base/testing/tools） services/ # 文档处理、检索、向量存储等服务层 tools/ # 工具中心（包含 SRS 需求提取工具） models/ # SQLAlchemy 模型 schemas/ # Pydantic 数据模型 alembic/ # 数据库迁移 frontend/ # Next.js 前端 src/app/ # 页面与路由 src/components/ # 组件 src/lib/ # API 封装、工具调用封装 docs/ # 文档与教程 docker-compose.yml # 标准部署编排 docker-compose.dev.yml # 开发调试编排 ``` ## 快速开始 ### 环境要求 - Docker 与 Docker Compose v2+ - Node.js 18+ - Python 3.9+ - 推荐 8GB 及以上内存 ### 1. 准备环境变量 ```bash cp .env.example .env ``` ### 2. 启动服务 ```bash docker compose up -d --build ``` ### 3. 访问服务 - 前端页面: http://127.0.0.1.nip.io - API 文档: http://127.0.0.1.nip.io/redoc - MinIO 控制台: http://127.0.0.1.nip.io:9001 ## 配置说明 ### 核心配置 | 配置项 | 说明 | 示例 | | --- | --- | --- | | MYSQL_SERVER | MySQL 主机 | localhost 或 db | | MYSQL_PORT | MySQL 端口 | 3306 | | MYSQL_USER | MySQL 用户名 | ragagent | | MYSQL_PASSWORD | MySQL 密码 | ragagent | | MYSQL_DATABASE | MySQL 库名 | ragagent | | SECRET_KEY | JWT 密钥 | 自定义随机字符串 | | ACCESS_TOKEN_EXPIRE_MINUTES | Token 过期时间（分钟） | 10080 | ### 模型与向量配置 | 配置项 | 说明 | 示例 | | --- | --- | --- | | CHAT_PROVIDER | 对话模型提供商 | dashscope/openai/deepseek/ollama | | EMBEDDINGS_PROVIDER | 向量模型提供商 | dashscope/openai/ollama | | DASH_SCOPE_API_KEY | DashScope Key | sk-xxx | | DASH_SCOPE_CHAT_MODEL | DashScope 对话模型 | qwen3.5-plus| | DASH_SCOPE_EMBEDDINGS_MODEL | DashScope 向量模型 | text-embedding-v4 | | VECTOR_STORE_TYPE | 向量库类型 | chroma 或 qdrant | 说明： - 当使用 DashScope 兼容模式时，建议使用文本向量模型（例如 text-embedding-v4）。 - 项目支持通过 API_KEY 作为统一兜底密钥，再由各 provider 配置覆盖。 ### 存储配置 | 配置项 | 说明 | 示例 | | --- | --- | --- | | MINIO_ENDPOINT | MinIO 地址 | localhost:9000 | | MINIO_ACCESS_KEY | MinIO 用户名 | minioadmin | | MINIO_SECRET_KEY | MinIO 密码 | minioadmin | | MINIO_BUCKET_NAME | 桶名 | documents | ## API 概览后端统一前缀为 /api。主要路由： - /api/auth: 登录、注册、令牌。 - /api/knowledge-base: 知识库与文档上传/处理/任务状态。 - /api/chat: 会话与消息。 - /api/testing: 测试内容生成流水线。 - /api/tools: 工具中心（包含 SRS 需求提取任务接口）。 ## 开发与测试 ### 前端类型检查 ```bash cd frontend pnpm exec tsc --noEmit ``` ### 后端测试 ```bash cd backend python -m pytest tests/test_testing_pipeline.py ``` ### 数据库迁移 ```bash cd backend alembic upgrade head ``` ## 常见问题 ### 1) 提示某张表不存在（例如 tool_jobs）原因：数据库迁移未执行到最新版本。处理：执行 alembic upgrade head，或重启后端让启动迁移自动执行。 ### 2) 知识库文档处理失败并出现向量模型错误原因：模型配置与 provider 兼容性不匹配，或账号配额不足。处理： - 检查 EMBEDDINGS_PROVIDER 与模型名是否匹配。 - DashScope 兼容模式优先使用 text-embedding-v4。 - 若报配额不足（AllocationQuota.FreeTierOnly），请切换可用 API Key 或开通付费资源。 ### 3) 重复点击“开始处理”后状态异常后端已增加幂等处理与重试兜底，仍建议单次提交后等待任务轮询完成再重复操作。 ## 许可证本项目基于 LICENSE 文件中定义的条款发布。