init. project

2026-04-13 11:34:23 +08:00
commit c7c0659a85
202 changed files with 31196 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,164 @@
+<div align="center">
+  <img src="./docs/images/github-cover-new.png" alt="RAG Web UI" />
+  <br />
+  <p>
+    <strong>基于 RAG 的知识库问答与文档处理平台</strong>
+  </p>
+
+  <p>
+    <a href="https://github.com/rag-web-ui/rag-web-ui/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rag-web-ui/rag-web-ui" alt="License" /></a>
+    <a href="#"><img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python" /></a>
+    <a href="#"><img src="https://img.shields.io/badge/node-%3E%3D18-green.svg" alt="Node" /></a>
+    <a href="#"><img src="https://github.com/rag-web-ui/rag-web-ui/actions/workflows/test.yml/badge.svg" alt="CI" /></a>
+  </p>
+
+  <p>
+    <a href="#简介">简介</a> •
+    <a href="#核心能力">核心能力</a> •
+    <a href="#项目结构">项目结构</a> •
+    <a href="#快速开始">快速开始</a> •
+    <a href="#配置说明">配置说明</a> •
+    <a href="#api-概览">API 概览</a> •
+    <a href="#常见问题">常见问题</a>
+  </p>
+</div>
+
+## 简介
+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 文件中定义的条款发布。