# AI Agent 企业级 RAG引擎

**Repository Path**: north-dream-testing/ai-agent-RAG-engine

## Basic Information

- **Project Name**: AI Agent 企业级 RAG引擎
- **Description**: RAGFlow 是一款开源的 RAG（Retrieval-Augmented Generation）引擎，旨在为大语言模型（LLM）提供基于深度文档理解的上下文增强能力。平台支持多种文档格式的解析、向量化存储、智能检索和对话式问答，是企业级知识库建设的理想选择。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-25
- **Last Updated**: 2026-09-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAGFlow - 知识库与大模型对话平台

<div align="center">

**基于深度文档理解的开源 RAG（检索增强生成）引擎**

[![版本](https://img.shields.io/badge/版本-v0.27.2-blue.svg)](https://github.com/infiniflow/ragflow/releases)
[![许可证](https://img.shields.io/badge/许可证-Apache--2.0-green.svg)](https://github.com/infiniflow/ragflow/blob/main/LICENSE)
[![Docker](https://img.shields.io/badge/Docker-支持-blue.svg)](https://www.docker.com/)
[![Python](https://img.shields.io/badge/Python-3.13+-yellow.svg)](https://www.python.org/)

[快速开始](#-快速开始) · [功能特性](#-功能特性) · [界面预览](#-界面预览) · [技术架构](#-技术架构) · [API 文档](#-api-文档)

</div>

---

## 📋 目录

- [项目简介](#-项目简介)
- [功能特性](#-功能特性)
- [界面预览](#-界面预览)
- [技术架构](#-技术架构)
- [快速开始](#-快速开始)
- [配置说明](#-配置说明)
- [API 文档](#-api-文档)
- [常见问题](#-常见问题)
- [贡献指南](#-贡献指南)
- [许可证](#-许可证)

---

## 📖 项目简介

RAGFlow 是一款开源的 RAG（Retrieval-Augmented Generation）引擎，旨在为大语言模型（LLM）提供基于深度文档理解的上下文增强能力。平台支持多种文档格式的解析、向量化存储、智能检索和对话式问答，是企业级知识库建设的理想选择。

### 核心优势

- **深度文档理解**：支持 PDF、Word、Excel、PPT、图片等多种格式的精确解析
- **灵活的检索策略**：混合检索（向量 + 全文 + 知识图谱），支持重排序优化
- **可视化工作流**：拖拽式智能体编排，支持复杂业务逻辑定制
- **企业级安全**：多租户隔离、RBAC 权限控制、审计日志
- **开箱即用**：Docker 一键部署，内置主流大模型支持

---

## ✨ 功能特性

### 📚 知识库管理

| 功能 | 说明 |
|------|------|
| 多格式文档解析 | 支持 PDF、DOCX、XLSX、PPTX、TXT、Markdown、HTML 等 20+ 格式 |
| 智能分块策略 | 按段落、标题、表格、图片等语义单元自动分块 |
| 向量化存储 | 集成多种 Embedding 模型，支持 Milvus/Qdrant/ES 等向量数据库 |
| 知识图谱 | 自动抽取实体关系，构建结构化知识网络 |
| 版本控制 | 文档更新追踪，支持回滚和历史对比 |

###  智能对话

| 功能 | 说明 |
|------|------|
| 多轮对话 | 支持上下文记忆的多轮交互 |
| 引用溯源 | 回答自动标注来源文档和段落 |
| 多模型支持 | OpenAI、DeepSeek、通义千问、文心一言等 50+ 模型 |
| 对话模板 | 预设多种场景模板（客服、问答、摘要等） |
| 分享部署 | 一键生成对话链接或嵌入 Widget |

### 🤖 智能体（Agent）

| 功能 | 说明 |
|------|------|
| 可视化编排 | 拖拽式工作流设计，支持条件分支、循环 |
| 工具调用 | 内置搜索、计算、代码执行等工具 |
| MCP 集成 | 支持 Model Context Protocol 扩展 |
| 模板市场 | 丰富的预置智能体模板 |
| 日志追踪 | 完整的执行日志和性能监控 |

###  智能搜索

| 功能 | 说明 |
|------|------|
| 混合检索 | 向量相似度 + 关键词匹配 + 知识图谱 |
| 重排序优化 | 支持 Cross-Encoder 重排序提升精度 |
| 多路召回 | 并行检索多知识库结果融合 |
| 搜索分享 | 生成独立搜索页面链接 |

### 🧠 记忆系统

| 功能 | 说明 |
|------|------|
| 长期记忆 | 跨会话的用户偏好和上下文存储 |
| 短期记忆 | 会话内的对话历史管理 |
| 记忆检索 | 基于语义的相关记忆自动召回 |

### 📁 文件管理

| 功能 | 说明 |
|------|------|
| 统一存储 | 集中管理所有上传文档 |
| 批量操作 | 支持批量上传、删除、移动 |
| 格式预览 | 在线预览 PDF、图片等文件 |
| 权限控制 | 文件级别的访问权限管理 |

---

## 🖼️ 界面预览

### 首页仪表盘

![首页](screenshots/01-home-page.png)

首页展示知识库和聊天应用的快速入口，支持一键创建新资源。

### 知识库管理

![知识库](screenshots/02-datasets-page.png)

知识库模块支持文档上传、解析配置、分块策略调整和检索测试。

### 聊天应用

![聊天](screenshots/03-chats-page.png)

聊天应用提供多轮对话界面，支持引用溯源和多模型切换。

### 智能搜索

![搜索](screenshots/04-searches-page.png)

搜索模块提供混合检索能力，支持多知识库联合查询。

### 智能体编排

![智能体](screenshots/05-agents-page.png)

智能体模块支持可视化工作流编排和工具调用配置。

### 记忆系统

![记忆](screenshots/06-memories-page.png)

记忆系统管理长期和短期记忆，支持语义检索。

### 文件管理

![文件管理](screenshots/07-files-page.png)

文件管理模块提供统一的文档存储和批量操作能力。

### 系统设置

#### 模型提供商配置

![模型设置](screenshots/08-user-setting-page.png)

支持 50+ 大模型提供商配置，包括 LLM、Embedding、VLM、ASR、Rerank、TTS 等模型类型。

#### 数据源管理

![数据源](screenshots/09-data-source-page.png)

管理外部数据源连接，支持数据库、API、文件系统等接入方式。

#### 聊天渠道配置

![聊天渠道](screenshots/10-chat-channels-page.png)

配置多渠道接入，支持 Web、API、Widget 等部署方式。

#### MCP 服务集成

![MCP](screenshots/11-mcp-page.png)

集成 Model Context Protocol，扩展智能体工具能力。

#### 团队管理

![团队](screenshots/12-team-page.png)

多租户团队管理，支持成员邀请和权限分配。

#### 个人概要

![概要](screenshots/13-profile-page.png)

用户个人信息和使用统计概览。

#### API 密钥管理

![API](screenshots/14-api-page.png)

生成和管理 API 密钥，用于程序化访问平台功能。

---

## 🏗️ 技术架构

### 系统架构图

```
┌─────────────────────────────────────────────────────────────┐
│                      前端层 (React + TypeScript)              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐  │
│  │ 知识库   │ │  聊天    │ │ 智能体   │ │  系统设置    │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────  │
└─────────────────────────────────────────────────────────────┘
                            │ HTTP/WebSocket
┌─────────────────────────────────────────────────────────────┐
│                    API 网关层 (Nginx)                         │
─────────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────────┐
│                   应用服务层 (Python Quart)                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐  │
│  │ 用户服务 │ │ 文档服务 │ │ 检索服务 │ │  对话服务    │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘  │
└─────────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────────┐
│                      数据层                                   │
│  ┌──────────┐ ──────────┐ ┌──────────┐ ──────────────┐  │
│  │  MySQL   │ │   ES     │ │  MinIO   │ │   Redis      │  │
│  │  8.0.40  │ │  8.11.3  │ │          │ │   Valkey 8   │  │
│  └──────────┘ └────────── └──────────┘ └──────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

### 技术栈

| 层级 | 技术选型 | 说明 |
|------|----------|------|
| 前端 | React 18 + TypeScript + Vite | 现代化 SPA 架构 |
| UI 组件 | Radix UI + Tailwind CSS | 无障碍优先的组件库 |
| 状态管理 | Zustand | 轻量级状态管理 |
| 路由 | React Router v6 | 客户端路由 |
| 后端 | Python 3.13 + Quart | 异步 Web 框架 |
| ORM | Peewee | 轻量级 ORM |
| 数据库 | MySQL 8.0 | 关系型数据存储 |
| 搜索引擎 | Elasticsearch 8.11 | 全文检索 + 向量存储 |
| 对象存储 | MinIO | S3 兼容的对象存储 |
| 缓存 | Redis/Valkey 8 | 会话缓存 + 消息队列 |
| 容器化 | Docker + Docker Compose | 一键部署 |

---

## 🚀 快速开始

### 环境要求

- **操作系统**：Linux / macOS / Windows 10+
- **Docker**：20.10+
- **Docker Compose**：2.0+
- **内存**：建议 8GB+
- **磁盘**：建议 50GB+

### Docker 部署

#### 1. 克隆项目

```bash
git clone https://gitee.com/north-dream-testing/ai-agent-RAG-engine.git
cd ragflow/docker
```

#### 2. 配置环境变量

编辑 `.env` 文件：

```bash
# RAGFlow 镜像配置
RAGFLOW_IMAGE=docker.1ms.run/infiniflow/ragflow:v0.27.2

# HuggingFace 镜像（国内用户）
HF_ENDPOINT=https://hf-mirror.com

# 服务端口配置
EXPOSE_MYSQL_PORT=3306
ES_PORT=1200
MINIO_PORT=9000
REDIS_PORT=6379
SVR_WEB_HTTP_PORT=80
```

#### 3. 启动服务

```bash
docker compose up -d
```

#### 4. 访问系统

打开浏览器访问：http://localhost

首次访问需要注册管理员账号。

### 服务组件

| 服务 | 端口 | 说明 |
|------|------|------|
| RAGFlow Web | 80/443 | 主应用服务 |
| MySQL | 3306 | 关系型数据库 |
| Elasticsearch | 1200 | 搜索引擎 |
| MinIO | 9000/9001 | 对象存储 |
| Redis | 6379 | 缓存服务 |

---

## ⚙️ 配置说明

### 大模型配置

1. 进入 **系统设置** → **模型提供商**
2. 选择模型提供商（如 OpenAI、DeepSeek 等）
3. 输入 API Key 和 Base URL
4. 设置默认模型（LLM、Embedding、Rerank 等）

### 知识库配置

#### 分块策略

| 策略 | 适用场景 |
|------|----------|
| 自动分块 | 通用文档，按语义自动分割 |
| 按段落分块 | 结构化文档，保持段落完整性 |
| 按标题分块 | 层次化文档，按标题层级分割 |
| 表格分块 | 表格密集型文档 |
| 图片分块 | 图片为主的文档 |

#### 检索配置

- **相似度阈值**：0.0 - 1.0，越高越严格
- **返回数量**：每次检索返回的文档块数量
- **重排序**：启用 Cross-Encoder 重排序提升精度

### 智能体配置

#### 工作流组件

- **开始节点**：定义输入参数
- **LLM 节点**：调用大模型生成内容
- **检索节点**：从知识库检索相关文档
- **条件节点**：基于条件分支执行
- **工具节点**：调用外部工具（搜索、计算等）
- **结束节点**：定义输出格式

---

## 📡 API 文档

### 认证方式

所有 API 请求需要在 Header 中携带 Authorization Token：

```http
Authorization: <your-api-token>
```

### 核心 API

#### 知识库 API

```http
# 创建知识库
POST /api/v1/datasets
{
  "name": "知识库名称",
  "description": "知识库描述"
}

# 上传文档
POST /api/v1/datasets/{dataset_id}/documents
Content-Type: multipart/form-data

# 检索文档
POST /api/v1/datasets/{dataset_id}/retrieval
{
  "query": "查询内容",
  "top_k": 5
}
```

#### 聊天 API

```http
# 创建聊天应用
POST /api/v1/chats
{
  "name": "聊天应用名称",
  "dataset_ids": ["知识库ID"],
  "llm_id": "模型ID"
}

# 发送消息
POST /api/v1/chats/{chat_id}/completions
{
  "message": "用户消息",
  "stream": true
}
```

#### 智能体 API

```http
# 创建智能体
POST /api/v1/agents
{
  "name": "智能体名称",
  "description": "智能体描述",
  "workflow": {...}
}

# 执行智能体
POST /api/v1/agents/{agent_id}/completions
{
  "message": "用户输入"
}
```

### API 密钥管理

1. 进入 **系统设置** → **API**
2. 点击 **创建 API 密钥**
3. 复制并保存密钥（仅显示一次）

---

## ❓ 常见问题

### Q1: 服务启动失败

**问题**：`docker compose up` 后服务无法正常启动

**解决方案**：

```bash
# 1. 检查容器状态
docker compose ps

# 2. 查看服务日志
docker compose logs -f ragflow-cpu

# 3. 重启服务
docker compose down
docker compose up -d
```

### Q2: 数据库连接失败

**问题**：RAGFlow 无法连接 MySQL

**解决方案**：

```bash
# 等待 MySQL 完全启动
docker compose ps mysql

# 确认状态为 healthy 后重启 RAGFlow
docker compose restart ragflow-cpu
```

### Q3: 模型配置后无法使用

**问题**：配置了大模型但对话时报错

**解决方案**：

1. 检查 API Key 是否正确
2. 确认 Base URL 配置（国内模型需配置对应地址）
3. 在 **设置默认模型** 中选择已配置的模型
4. 检查网络连接和防火墙设置

### Q4: 文档解析失败

**问题**：上传文档后解析状态显示失败

**解决方案**：

1. 检查文档格式是否支持
2. 确认文档未加密或损坏
3. 查看解析日志定位具体错误
4. 尝试重新上传或转换格式

### Q5: 检索结果不相关

**问题**：对话或搜索返回的结果与问题不相关

**解决方案**：

1. 调整相似度阈值（建议 0.5-0.7）
2. 启用重排序功能
3. 优化文档分块策略
4. 检查 Embedding 模型配置

---

## 🤝 贡献指南

我们欢迎所有形式的贡献！

### 贡献流程

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 开发环境

```bash
# 后端开发
uv sync --python 3.13 --all-extras
uv run python3 ragflow_deps/download_deps.py
docker compose -f docker/docker-compose-base.yml up -d
source .venv/bin/activate
export PYTHONPATH=$(pwd)
bash docker/launch_backend_service.sh

# 前端开发
cd web
npm install
npm run dev
```

### 代码规范

- 遵循 [PEP 8](https://pep8.org/) Python 代码规范
- 使用 [Ruff](https://github.com/astral-sh/ruff) 进行代码检查
- 提交前运行测试：`uv run pytest`
- 前端代码遵循 ESLint 规则