graph_rag_server/docs/architecture.md

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
• Domain-Driven Design by Eric Evans
• FastAPI Documentation
• SQLAlchemy Documentation