# RAG 系统架构文档 ## 概述 本文档描述了 RAG（Retrieval-Augmented Generation）系统的架构设计，该系统采用 Clean Architecture 和 Domain-Driven Design (DDD) 原则进行重构，实现了高内聚、低耦合的分层架构。 ## 架构原则 ### Clean Architecture 系统遵循 Clean Architecture 的核心原则： 1. **依赖规则**：依赖关系只能从外层指向内层，内层不依赖外层 2. **独立性**：业务逻辑独立于框架、UI、数据库和外部服务 3. **可测试性**：业务逻辑可以在没有外部依赖的情况下进行测试 4. **灵活性**：可以轻松替换框架、数据库或外部服务 ### Domain-Driven Design (DDD) 系统采用 DDD 的战术模式： 1. **实体（Entity）**：具有唯一标识的领域对象 2. **值对象（Value Object）**：不可变的、通过值比较的对象 3. **聚合（Aggregate）**：一组相关对象的集合，具有一致性边界 4. **仓储（Repository）**：提供对聚合的持久化和检索 5. **领域服务（Domain Service）**：不属于任何实体的业务逻辑 6. **领域事件（Domain Event）**：领域中发生的重要事件 ## 分层架构 系统分为四个主要层次，从内到外依次为： ``` ┌─────────────────────────────────────────────────────────┐ │ Presentation Layer │ │ (FastAPI, API Routes, Schemas) │ ├─────────────────────────────────────────────────────────┤ │ Application Layer │ │ (Use Cases, Commands, Queries, DTOs) │ ├─────────────────────────────────────────────────────────┤ │ Domain Layer │ │ (Entities, Value Objects, Domain Services) │ ├─────────────────────────────────────────────────────────┤ │ Infrastructure Layer │ │ (Database, Vector DB, Parsers, External Services) │ └─────────────────────────────────────────────────────────┘ ``` ### 1. 领域层（Domain Layer） **职责**：包含核心业务逻辑和业务规则，是系统的核心。 **组件**： - **实体（Entities）**： - `Document`：文档实体，包含内容、嵌入向量和元数据 - `SearchResult`：搜索结果实体 - `ParsedDocument`：解析后的文档实体 - `DocumentChunk`：文档块实体 - `KnowledgeBase`：知识库实体 - `PromptDimension`：提示词维度实体 - **值对象（Value Objects）**： - `EntityId`：实体唯一标识符 - `Timestamp`：时间戳 - `Vector`：向量表示 - `SearchQuery`：搜索查询 - `DocumentType`：文档类型枚举 - **领域服务（Domain Services）**： - `HybridSearchService`：混合搜索服务，实现向量搜索和全文搜索的结果合并 - `DocumentParser`：文档解析器接口 - `ChunkingStrategy`：分块策略接口 - **仓储接口（Repository Interfaces）**： - `DocumentRepository`：文档仓储接口 - `KnowledgeBaseRepository`：知识库仓储接口 **特点**： - 不依赖任何外部框架或库 - 包含纯粹的业务逻辑 - 高度可测试 ### 2. 应用层（Application Layer） **职责**：协调领域对象完成用例，处理应用逻辑。 **组件**： - **命令（Commands）**： - `CreateDocumentCommand`：创建文档命令 - `UpdateDocumentCommand`：更新文档命令 - `DeleteDocumentCommand`：删除文档命令 - `ParseDocumentCommand`：解析文档命令 - `CreateKnowledgeBaseCommand`：创建知识库命令 - **查询（Queries）**： - `SearchDocumentsQuery`：搜索文档查询 - `GetDocumentQuery`：获取文档查询 - **处理器（Handlers）**： - `CreateDocumentHandler`：处理创建文档命令 - `SearchDocumentsHandler`：处理搜索文档查询 - `ParseDocumentHandler`：处理文档解析命令 - **数据传输对象（DTOs）**： - `DocumentDTO`：文档数据传输对象 - `SearchResultDTO`：搜索结果数据传输对象 - `ParsedDocumentDTO`：解析文档数据传输对象 **模式**： - **CQRS（Command Query Responsibility Segregation）**：分离命令和查询 - **依赖注入**：通过构造函数注入依赖 ### 3. 基础设施层（Infrastructure Layer） **职责**：提供技术实现，与外部系统交互。 **组件**： - **数据库**： - `SQLAlchemy ORM 模型`：DocumentModel, KnowledgeBaseModel - `会话管理`：数据库连接和事务管理 - `仓储实现`：SQLDocumentRepository, SQLKnowledgeBaseRepository - **向量数据库**： - `VectorDatabase`：向量数据库抽象基类 - `InfinityVectorDB`：Infinity 向量数据库适配器 - `ElasticsearchVectorDB`：Elasticsearch 向量数据库适配器 - **文档解析器**： - `PDFParser`：PDF 文档解析器 - `ImageParser`：图片文档解析器 - `FixedSizeChunkingStrategy`：固定大小分块策略 - `SentenceChunkingStrategy`：句子分块策略 - **文件存储**： - `LocalFileStorage`：本地文件存储 - `S3FileStorage`：S3 对象存储 - **外部服务**： - `RagflowService`：Ragflow 服务集成 - `DifyService`：Dify 服务集成 **特点**： - 实现领域层定义的接口 - 处理技术细节和外部依赖 - 可替换的实现 ### 4. 表现层（Presentation Layer） **职责**：处理 HTTP 请求和响应，提供 RESTful API。 **组件**： - **API 路由**： - `vector_search.py`：文档管理 API - `documents.py`：文档解析 API - `knowledge_base.py`：知识库管理 API - `health.py`：健康检查和指标 API - **请求/响应模型**： - `CreateDocumentRequest`：创建文档请求 - `DocumentResponse`：文档响应 - `SearchDocumentsRequest`：搜索文档请求 - `ErrorResponse`：错误响应 - **中间件**： - `RequestLoggingMiddleware`：请求日志中间件 - `SecurityHeadersMiddleware`：安全响应头中间件 - **异常处理器**： - `domain_exception_handler`：领域异常处理器 - `application_exception_handler`：应用异常处理器 - `generic_exception_handler`：通用异常处理器 - **依赖注入**： - `dependencies.py`：FastAPI 依赖注入函数 **特点**： - 使用 FastAPI 框架 - 自动生成 OpenAPI 文档 - 统一的错误处理 - 结构化日志记录 ## 核心流程 ### 文档创建流程 ``` 1. API 接收请求 (Presentation Layer) ↓ 2. 验证请求数据 (Pydantic) ↓ 3. 创建命令对象 (Application Layer) ↓ 4. 命令处理器处理命令 ↓ 5. 创建领域实体 (Domain Layer) ↓ 6. 仓储保存实体 (Infrastructure Layer) ↓ 7. 生成嵌入向量并存储到向量数据库 ↓ 8. 返回响应 (Presentation Layer) ``` ### 文档搜索流程 ``` 1. API 接收搜索请求 (Presentation Layer) ↓ 2. 创建查询对象 (Application Layer) ↓ 3. 查询处理器处理查询 ↓ 4. 调用混合搜索服务 (Domain Layer) ↓ 5. 向量数据库搜索 (Infrastructure Layer) ↓ 6. 合并和排序结果 (Domain Layer) ↓ 7. 转换为 DTO (Application Layer) ↓ 8. 返回响应 (Presentation Layer) ``` ## 设计决策 ### 1. 为什么选择 Clean Architecture？ - **可维护性**：清晰的分层使代码易于理解和维护 - **可测试性**：业务逻辑可以独立测试，不依赖外部系统 - **灵活性**：可以轻松替换技术实现，如更换数据库或框架 - **团队协作**：不同层次可以并行开发 ### 2. 为什么使用 CQRS？ - **职责分离**：读写操作分离，各自优化 - **可扩展性**：读写可以独立扩展 - **性能优化**：查询可以使用不同的数据模型和优化策略 ### 3. 为什么使用依赖注入？ - **解耦**：组件之间松耦合 - **可测试性**：易于使用 Mock 对象进行测试 - **灵活性**：可以在运行时替换实现 ### 4. 为什么使用向量数据库适配器模式？ - **灵活性**：支持多种向量数据库（Infinity, Elasticsearch） - **可替换性**：可以轻松切换向量数据库 - **统一接口**：应用层不需要关心具体实现 ## 技术栈 ### 核心框架 - **FastAPI**：现代、高性能的 Web 框架 - **Pydantic**：数据验证和设置管理 - **SQLAlchemy**：ORM 和数据库工具 ### 数据存储 - **MySQL/PostgreSQL**：关系数据库 - **Infinity**：向量数据库 - **Elasticsearch**：搜索引擎和向量数据库 - **MinIO/S3**：对象存储 ### 测试 - **pytest**：测试框架 - **pytest-asyncio**：异步测试支持 - **hypothesis**：属性测试 - **pytest-cov**：覆盖率报告 ### 日志和监控 - **structlog**：结构化日志 - **psutil**：系统监控 ## 部署架构 ``` ┌─────────────────────────────────────────────────────────┐ │ Load Balancer │ └────────────────────┬────────────────────────────────────┘ │ ┌────────────┴────────────┐ │ │ ┌───────▼────────┐ ┌───────▼────────┐ │ FastAPI App │ │ FastAPI App │ │ (Worker 1) │ │ (Worker 2) │ └───────┬────────┘ └───────┬────────┘ │ │ └────────────┬────────────┘ │ ┌────────────┴────────────┐ │ │ ┌───────▼────────┐ ┌───────▼────────┐ │ MySQL/PG DB │ │ Vector DB │ │ │ │ (Infinity/ES) │ └────────────────┘ └────────────────┘ ``` ## 扩展性考虑 ### 水平扩展 - FastAPI 应用可以部署多个实例 - 使用负载均衡器分发请求 - 数据库使用连接池管理连接 ### 垂直扩展 - 增加服务器资源（CPU、内存） - 优化数据库查询和索引 - 使用缓存减少数据库访问 ### 性能优化 - 异步处理（async/await） - 批量操作 - 查询优化 - 缓存策略 ## 安全性 ### API 安全 - API 密钥认证 - CORS 配置 - 请求速率限制 - 输入验证 ### 数据安全 - 数据加密（传输和存储） - 访问控制 - 审计日志 - 敏感数据脱敏 ## 监控和日志 ### 日志 - 结构化日志（JSON 格式） - 请求 ID 追踪 - 错误日志和堆栈跟踪 - 性能指标日志 ### 监控 - 健康检查端点 - 性能指标端点 - 系统资源监控 - 应用性能监控（APM） ## 未来改进 1. **事件驱动架构**：引入领域事件和事件总线 2. **缓存层**：添加 Redis 缓存提高性能 3. **消息队列**：使用 RabbitMQ 或 Kafka 处理异步任务 4. **微服务化**：将不同功能拆分为独立的微服务 5. **GraphQL API**：提供更灵活的查询接口 6. **实时搜索**：支持实时索引和搜索 7. **多租户支持**：支持多个租户隔离数据 ## 参考资料 - [Clean Architecture by Robert C. Martin](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) - [Domain-Driven Design by Eric Evans](https://www.domainlanguage.com/ddd/) - [FastAPI Documentation](https://fastapi.tiangolo.com/) - [SQLAlchemy Documentation](https://www.sqlalchemy.org/)