rag_agent/README.md at main

zhoujl/rag_agent

Fork 0

Files

junlan c7c0659a85 init. project

2026-04-13 11:34:23 +08:00

5.9 KiB

Raw Permalink Blame History

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

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

简介

RAG Web UI 是一个面向企业知识库场景的全栈项目，提供从文档接入、向量化检索、对话问答到文档工程化处理的完整链路。

项目采用前后端分离架构：

后端基于 FastAPI，负责认证、知识库、向量检索、文档处理任务与工具调用。
前端基于 Next.js，提供知识库管理、聊天、文档处理等可视化页面。
基础设施使用 MySQL、ChromaDB、MinIO，可通过 Docker Compose 一键启动。

核心能力

知识库管理：支持 PDF、DOCX、Markdown、TXT 上传，预览、异步处理、状态追踪。
RAG 对话：支持多轮上下文问答，结合知识库检索结果生成回答。
文档处理中心：提供需求提取、测试内容生成等工程化能力。
工具中心：后端内置工具注册与调用机制，支持后续扩展更多可被模型调用的工具。
多模型支持：支持 OpenAI、DashScope、DeepSeek、Ollama 等配置方式。

项目结构

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. 准备环境变量

cp .env.example .env

2. 启动服务

docker compose up -d --build

3. 访问服务

配置说明

核心配置

配置项	说明	示例
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 需求提取任务接口）。

开发与测试

前端类型检查

cd frontend
pnpm exec tsc --noEmit

后端测试

cd backend
python -m pytest tests/test_testing_pipeline.py

数据库迁移

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 文件中定义的条款发布。

5.9 KiB Raw Permalink Blame History Unescape Escape

简介