# 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 核心类与方法 ```python 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 核心类与方法 ```python 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 检索流程 1. 接收检索请求，包括文本查询、图像和检索参数 2. 生成多模态嵌入向量 3. 调用Infinity向量数据库进行混合检索 4. 处理检索结果，转换为统一格式 5. 返回检索结果 ### 4.3 HTTP API模块 #### 4.3.1 设计目标 - 提供RESTful API接口 - 支持请求参数验证 - 提供统一的响应格式 - 支持错误处理和日志记录 #### 4.3.2 核心API | API路径 | 方法 | 功能 | |--------|------|------| | /hybrid_search | POST | 执行混合检索 | | /health | GET | 健康检查 | #### 4.3.3 请求和响应模型 ```python 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 核心类与方法 ```python 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 配置管理类 ```python 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 依赖安装 ```bash pip install -r requirements.txt ``` ### 8.2 运行HTTP服务 ```bash python -m api.hybrid_search_http ``` ### 8.3 测试运行 ```bash python -m pytest test/ ``` ## 9. 测试策略 ### 9.1 单元测试 - 针对核心模块的单元测试 - 测试覆盖主要功能点 - 使用模拟对象减少外部依赖 ### 9.2 集成测试 - 测试模块之间的集成 - 测试与外部服务的集成 - 测试完整的业务流程 ### 9.3 性能测试 - 测试多模态嵌入生成的性能 - 测试混合检索的响应时间 - 测试系统的并发处理能力 ## 10. 扩展和维护 ### 10.1 扩展方向 - 支持更多的多模态模型 - 支持更多的向量数据库 - 增强文档处理能力，支持更多文档格式 - 添加更多的检索算法和优化策略 - 增强API功能，支持更复杂的检索请求 ### 10.2 维护建议 - 定期更新依赖库 - 监控系统性能和错误日志 - 定期备份数据 - 进行安全审计和漏洞修复 - 保持文档更新 ## 11. 结论 Ragflow_plugs是一个功能强大的多模态混合检索系统，具有良好的架构设计和灵活的扩展能力。该系统支持文本和图像的联合检索，提供高效、准确的检索结果，并通过HTTP API方便外部系统集成。 通过模块化设计和清晰的接口定义，系统具有良好的可维护性和可扩展性。配置驱动的设计使得系统可以轻松适应不同的环境和需求。 该系统可以广泛应用于智能问答、图像搜索、内容推荐等场景，为智能应用提供强大的多模态信息检索能力。