Ragflow_plugs 项目设计文档

1. 项目概述

Ragflow_plugs是一个基于RAG（检索增强生成）技术的多模态混合检索系统，支持文本和图像的联合检索，并提供灵活的HTTP API服务。该系统旨在为智能应用提供高效、准确的多模态信息检索能力。

1.1 核心功能

多模态嵌入生成：支持文本和图像的联合嵌入生成
混合检索：结合文本检索和向量检索，提供更准确的检索结果
HTTP API服务：提供RESTful API，方便外部系统集成
文档处理：支持PDF文档解析、图像提取和处理
向量数据库集成：与Infinity向量数据库无缝集成
灵活配置：支持多环境配置，便于部署和管理

1.2 应用场景

智能问答系统
图像搜索和内容推荐
多模态内容管理系统
教育资源检索
儿童绘本智能分析

2. 设计思路

2.1 架构设计原则

模块化设计：将系统拆分为多个独立模块，便于维护和扩展
松耦合：模块之间通过明确的接口进行通信，降低依赖关系
可扩展性：支持多种模型、多种向量数据库的扩展
高可用性：设计合理的错误处理和重试机制
性能优化：针对检索和嵌入生成进行性能优化

2.2 核心设计理念

多模态融合：将文本和图像信息融合为统一的向量表示
检索增强生成：先检索相关信息，再结合大模型生成高质量回答
分层设计：分为数据层、服务层、API层，各层职责明确
配置驱动：通过配置文件灵活调整系统行为

3. 系统架构

3.1 整体架构

┌───────────────────────────────────────────────────────────────────┐
│                      Client Applications                          │
└───────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌───────────────────────────────────────────────────────────────────┐
│                          API Layer                               │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                     hybrid_search_http.py                   │  │
│  └─────────────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                    hybrid_search_mcp.py                    │  │
│  └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌───────────────────────────────────────────────────────────────────┐
│                         Service Layer                            │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                      Agent Module                           │  │
│  │  ┌───────────────────────────────────────────────────────┐  │  │
│  │  │                  test_image_agent.py                  │  │  │
│  │  └───────────────────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                     Workflow Module                        │  │
│  │  ┌───────────────────────────────────────────────────────┐  │  │
│  │  │               image_parsing_workflow.py               │  │  │
│  │  └───────────────────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌───────────────────────────────────────────────────────────────────┐
│                         Model Layer                              │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                 multimodal_embedding.py                    │  │
│  └─────────────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                         qwen_vl.py                         │  │
│  └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌───────────────────────────────────────────────────────────────────┐
│                         Data Layer                               │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                      Parser Module                         │  │
│  │  ┌───────────────────────────────────────────────────────┐  │  │
│  │  │                      pdf_parser                       │  │  │
│  │  └───────────────────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                      Utils Module                          │  │
│  │  ┌───────────────────────────────────────────────────────┐  │  │
│  │  │                      http_client.py                   │  │  │
│  │  └───────────────────────────────────────────────────────┘  │  │
│  │  ┌───────────────────────────────────────────────────────┐  │  │
│  │  │                    infinity_util                      │  │  │
│  │  └───────────────────────────────────────────────────────┘  │  │
│  │  └───────────────────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌───────────────────────────────────────────────────────────────────┐
│                       External Services                          │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                    Infinity Vector DB                      │  │
│  └─────────────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                 AI Model APIs (DashScope, etc.)            │  │
│  └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘

3.2 核心模块关系

3.2.1 多模态嵌入模块

功能：生成文本和图像的联合嵌入向量
依赖：AI模型API（如DashScope、SiliconFlow等）
调用关系：被hybrid_search_http.py和agent模块调用

3.2.2 混合检索模块

功能：结合文本检索和向量检索，返回综合结果
依赖：infinity_util、vector_db等工具模块
调用关系：被HTTP API模块和agent模块调用

3.2.3 HTTP API模块

功能：提供RESTful API服务
依赖：FastAPI框架、混合检索模块
调用关系：被外部客户端调用

3.2.4 Agent模块

功能：提供智能代理功能，结合检索结果生成回答
依赖：混合检索模块、LLM模型
调用关系：可被外部系统直接调用

3.2.5 Workflow模块

功能：管理系统工作流，如文档处理、图像分析等
依赖：Parser模块、Model模块
调用关系：被外部系统或定时任务调用

4. 核心模块设计

4.1 多模态嵌入模块

4.1.1 设计目标

支持文本和图像的联合嵌入生成
兼容多种AI模型API
提供统一的嵌入接口
支持配置不同的模型参数

4.1.2 核心类与方法

class Embedding:
    def __init__(self, model_name: str, api_key: str):
        # 初始化嵌入模型
        pass
    
    def get_multimodal_embedding(self, text: str, image: Image.Image) -> List[float]:
        # 生成多模态嵌入向量
        pass

4.1.3 支持的模型

Qwen VL（通过DashScope API）
其他多模态模型（可扩展）

4.2 混合检索模块

4.2.1 设计目标

结合文本检索和向量检索
支持灵活的检索参数配置
提供准确的检索结果
支持分页和排序

4.2.2 核心类与方法

class InfinityVectorDB:
    def hybrid_search(self, index_name: str, match_method: str, vector_field: str, 
                     query_vector: List[float], element_type: str, metric_type: str,
                     topn: int, text_query: str, text_field: str) -> Dict[str, Any]:
        # 执行混合检索
        pass
    
    def vector_search(self, index_name: str, vector_field: str, vector: List[float], 
                     size: int = 10, filter: Dict[str, Any] = None) -> Dict[str, Any]:
        # 执行向量检索
        pass

4.2.3 检索流程

接收检索请求，包括文本查询、图像和检索参数
生成多模态嵌入向量
调用Infinity向量数据库进行混合检索
处理检索结果，转换为统一格式
返回检索结果

4.3 HTTP API模块

4.3.1 设计目标

提供RESTful API接口
支持请求参数验证
提供统一的响应格式
支持错误处理和日志记录

4.3.2 核心API

API路径	方法	功能
/hybrid_search	POST	执行混合检索
/health	GET	健康检查

4.3.3 请求和响应模型

class HybridSearchRequest(BaseModel):
    text_query: str
    image: str
    topn: int = 2
    
class HybridSearchResponse(BaseModel):
    success: bool
    message: str
    output: List[Dict[str, Any]] = []
    total: int = 0

4.4 HTTP客户端模块

4.4.1 设计目标

提供统一的HTTP请求接口
支持重试机制
支持不同的HTTP方法
支持文件上传

4.4.2 核心类与方法

class HTTPClient:
    def post(self, endpoint: str, data: Optional[Dict] = None, 
             json_data: Optional[Dict] = None, files: Optional[Dict] = None,
             headers: Optional[Dict] = None) -> Dict[str, Any]:
        # 发送POST请求
        pass
    
    def get(self, endpoint: str, params: Optional[Dict] = None,
            headers: Optional[Dict] = None) -> Dict[str, Any]:
        # 发送GET请求
        pass
    
    def get_json(self, endpoint: str, json_data: Optional[Dict] = None,
                headers: Optional[Dict] = None) -> Dict[str, Any]:
        # 发送带有JSON数据的GET请求
        pass
    
    def put(self, endpoint: str, data: Optional[Dict] = None, 
            json_data: Optional[Dict] = None, headers: Optional[Dict] = None) -> Dict[str, Any]:
        # 发送PUT请求
        pass
    
    def delete(self, endpoint: str, data: Optional[Dict] = None, 
               json_data: Optional[Dict] = None, headers: Optional[Dict] = None) -> Dict[str, Any]:
        # 发送DELETE请求
        pass

5. 数据流程

5.1 多模态检索流程

1. 客户端发送检索请求，包括文本查询和图像URL
2. API层接收请求，解析参数
3. 下载图像，转换为Image对象
4. 调用多模态嵌入模块生成嵌入向量
5. 调用混合检索模块执行检索
6. 处理检索结果，转换为统一格式
7. 返回JSON响应给客户端

5.2 文档处理流程

1. 上传PDF文档
2. 解析PDF，提取文本和图像
3. 生成文档的多模态嵌入
4. 将嵌入向量和元数据存储到向量数据库
5. 建立索引，便于后续检索

6. 配置管理

6.1 配置文件结构

├── conf/
│   ├── config.py          # 配置管理类
│   ├── infinity_mapping.json  # Infinity数据库映射配置
│   └── __init__.py
└── .env                   # 环境变量配置

6.2 配置管理类

class ModelConfig:
    @staticmethod
    def get_multimodal_embedding_model_name() -> str:
        # 获取多模态嵌入模型名称
        pass
    
    @staticmethod
    def get_dashscope_api_key() -> str:
        # 获取DashScope API密钥
        pass
    
    # 其他模型配置方法
    
class VectorDBConfig:
    @staticmethod
    def get_infinity_database() -> str:
        # 获取Infinity数据库名称
        pass
    
    @staticmethod
    def get_infinity_table_name() -> str:
        # 获取Infinity表名称
        pass
    
    # 其他向量数据库配置方法

6.3 环境变量配置

# 模型API配置
DASHSCOPE_API_KEY=your_api_key
SILICONFLOW_API_KEY=your_api_key

# 向量数据库配置
INFINITY_HOST=http://localhost:23820
INFINITY_DATABASE=image_db

# 应用配置
LOG_LEVEL=INFO

7. 技术栈

类别	技术/框架	用途
编程语言	Python 3.12	主要开发语言
Web框架	FastAPI	HTTP API服务
HTTP客户端	Requests	HTTP请求处理
图像处理	PIL/Pillow	图像加载和处理
向量数据库	Infinity	向量存储和检索
LLM集成	LangChain	大语言模型集成
AI模型API	DashScope, SiliconFlow	多模态嵌入和生成
配置管理	python-dotenv	环境变量管理
测试框架	pytest	单元测试和集成测试

8. 部署和运行

8.1 依赖安装

pip install -r requirements.txt

8.2 运行HTTP服务

python -m api.hybrid_search_http

8.3 测试运行

python -m pytest test/

9. 测试策略

9.1 单元测试

针对核心模块的单元测试
测试覆盖主要功能点
使用模拟对象减少外部依赖

9.2 集成测试

测试模块之间的集成
测试与外部服务的集成
测试完整的业务流程

9.3 性能测试

测试多模态嵌入生成的性能
测试混合检索的响应时间
测试系统的并发处理能力

10. 扩展和维护

10.1 扩展方向

支持更多的多模态模型
支持更多的向量数据库
增强文档处理能力，支持更多文档格式
添加更多的检索算法和优化策略
增强API功能，支持更复杂的检索请求

10.2 维护建议

定期更新依赖库
监控系统性能和错误日志
定期备份数据
进行安全审计和漏洞修复
保持文档更新

11. 结论

Ragflow_plugs是一个功能强大的多模态混合检索系统，具有良好的架构设计和灵活的扩展能力。该系统支持文本和图像的联合检索，提供高效、准确的检索结果，并通过HTTP API方便外部系统集成。

通过模块化设计和清晰的接口定义，系统具有良好的可维护性和可扩展性。配置驱动的设计使得系统可以轻松适应不同的环境和需求。

该系统可以广泛应用于智能问答、图像搜索、内容推荐等场景，为智能应用提供强大的多模态信息检索能力。

design.md 20 KB Trvalý odkaz Historie Surový