Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
524 lines (461 loc) · 18.6 KB

ARCHITECTURE.md

File metadata and controls

524 lines (461 loc) · 18.6 KB

系统架构文档

本文档详细说明 RAG Demo 项目的系统架构、设计原则和技术实现。

📐 整体架构

系统分层

┌─────────────────────────────────────────────────────────────┐
│                        用户层                                │
│                    Web Browser / API Client                 │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP/HTTPS
┌────────────────────────▼────────────────────────────────────┐
│                      表现层（Presentation）                  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │          React SPA (Single Page Application)         │  │
│  │  - 组件化 UI (Components)                             │  │
│  │  - 状态管理 (React Hooks)                             │  │
│  │  - API 调用封装 (Axios/Fetch)                         │  │
│  │  - SSE 流式处理                                        │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────┘
                         │ REST API / SSE
┌────────────────────────▼────────────────────────────────────┐
│                    接口层（API Layer）                       │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                  Gin Web Framework                    │  │
│  │  - 路由管理 (Router)                                   │  │
│  │  - 中间件 (CORS, Logger, Recovery)                    │  │
│  │  - 请求验证                                            │  │
│  │  - 响应格式化                                          │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   处理层（Handler Layer）                    │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │   Chat      │  │  Knowledge   │  │    System       │   │
│  │  Handler    │  │   Handler    │  │   Handler       │   │
│  └──────┬──────┘  └──────┬───────┘  └────────┬────────┘   │
│         │                 │                   │             │
└─────────┼─────────────────┼───────────────────┼─────────────┘
          │                 │                   │
┌─────────▼─────────────────▼───────────────────▼─────────────┐
│                  业务层（Business Layer）                    │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Service Components                       │  │
│  │  ┌─────────────────┐      ┌──────────────────────┐  │  │
│  │  │ Knowledge       │      │    Conversation      │  │  │
│  │  │  Service        │      │     Service          │  │  │
│  │  └─────────────────┘      └──────────────────────┘  │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   AI 编排层（AI Orchestration）              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │               Eino Agent Framework                    │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │  │
│  │  │  Prompt  │  │  Tools   │  │   Orchestrator   │  │  │
│  │  │ Template │  │ Manager  │  │                  │  │  │
│  │  └──────────┘  └──────────┘  └──────────────────┘  │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────┬────────────────────┬──────────────────────────┘
             │                    │
    ┌────────▼────────┐  ┌────────▼─────────┐
    │   LLM Provider  │  │   MCP Client     │
    │   (OpenAI API)  │  │   (Tools Call)   │
    └─────────────────┘  └──────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   数据层（Data Layer）                       │
│  ┌─────────────────┐         ┌──────────────────────────┐  │
│  │  Store Layer    │         │    Embedder Layer        │  │
│  │  - Vector CRUD  │         │  - Text Embedding        │  │
│  │  - Retrieval    │         │  - Similarity Search     │  │
│  └────────┬────────┘         └─────────┬────────────────┘  │
└───────────┼──────────────────────────────┼──────────────────┘
            │                              │
┌───────────▼──────────────────────────────▼──────────────────┐
│                   存储层（Storage Layer）                    │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                   Redis                               │  │
│  │  - Vector Storage (向量存储)                          │  │
│  │  - Cache (缓存)                                        │  │
│  │  - Session Storage (会话存储)                         │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

🔄 核心流程

1. 对话流程

用户输入
   │
   ▼
前端验证
   │
   ▼
API 请求 ──────────────────┐
   │                       │
   ▼                       │
Handler 接收               │ SSE 连接
   │                       │ (流式模式)
   ▼                       │
Service 处理               │
   │                       │
   ├─► 获取对话历史         │
   │                       │
   ├─► 知识检索 (可选)      │
   │   └─► Embedder        │
   │       └─► Vector Search
   │                       │
   ▼                       │
Agent 编排                 │
   │                       │
   ├─► Prompt 构建         │
   │                       │
   ├─► Tools 准备          │
   │                       │
   ▼                       │
LLM 调用 ◄─────────────────┘
   │
   ├─► 判断是否需要工具调用
   │   │
   │   ▼ Yes
   │   MCP Client
   │   └─► Tool Handler
   │       └─► 执行工具
   │           └─► 返回结果
   │               └─► 再次调用 LLM
   │
   ▼ No
生成回复
   │
   ▼
保存对话历史
   │
   ▼
返回响应 ──────────────────► 前端展示

2. 知识检索流程 (RAG)

用户查询
   │
   ▼
问题理解
   │
   ▼
文本嵌入
   │
   ▼
向量检索 ──► Redis Vector Search
   │
   ▼
相似度排序
   │
   ▼
Top-K 筛选
   │
   ▼
上下文构建
   │
   ▼
Prompt 增强
   │
   ▼
LLM 生成
   │
   ▼
返回答案

3. MCP 工具调用流程

LLM 输出
   │
   ▼
解析 Tool Calls
   │
   ├─► 提取工具名称
   ├─► 提取参数
   │
   ▼
MCP Client
   │
   ├─► 查找 Tool Handler
   │
   ▼
Tool Handler
   │
   ├─► 参数验证
   ├─► 执行逻辑
   │   ├─► 计算器
   │   ├─► 时间查询
   │   └─► 其他工具
   │
   ▼
返回结果
   │
   ▼
格式化输出
   │
   ▼
反馈给 LLM
   │
   ▼
生成最终回答

🏗 模块设计

前端架构

web/src/
├── api/                    # API 调用层
│   ├── config.ts          # API 配置
│   ├── conversation.ts    # 对话 API
│   ├── qa.ts              # 问答 API
│   └── stream.ts          # 流式 API
│
├── components/            # 组件层
│   ├── chat/             # 聊天相关组件
│   │   ├── ChatContainer.tsx
│   │   ├── ChatInput.tsx
│   │   └── MessageList.tsx
│   │
│   ├── message/          # 消息组件
│   │   ├── MessageItem.tsx
│   │   └── LoadingMessage.tsx
│   │
│   └── common/           # 通用组件
│       └── Sidebar.tsx
│
├── hooks/                # 自定义 Hooks
│   └── index.ts
│
├── types/                # TypeScript 类型定义
│   └── index.ts
│
└── utils/                # 工具函数
    └── index.ts

后端架构

internal/
├── handler/              # HTTP 处理器层
│   ├── base_handler.go   # 基础处理器
│   ├── knowledge_handler.go
│   └── system_handler.go
│
├── service/              # 业务服务层
│   └── knowledge_service.go
│
├── agent/                # AI Agent 层
│   ├── agent.go          # Agent 主逻辑
│   ├── prompt.go         # Prompt 管理
│   └── tools.go          # 工具管理
│
├── store/                # 数据存储层
│   ├── store.go          # 存储接口
│   ├── embedder.go       # 嵌入接口
│   └── simple_embedder.go
│
├── models/               # 数据模型
│   ├── base_models.go
│   └── sse_model.go
│
└── config/               # 配置管理
    └── config.go

MCP 模块架构

mcp/
├── server.go             # MCP Server 入口
│
├── internal/
│   ├── handlers/         # 工具处理器
│   │   ├── calculator/
│   │   ├── time/
│   │   └── kuaikuawo/
│   │
│   ├── tools/            # 工具定义
│   │   ├── calculator/
│   │   ├── time/
│   │   └── kuaikuawo/
│   │
│   └── utils/            # 工具函数
│       ├── errors.go
│       └── helpers.go
│
└── docs/                 # MCP 文档

🔐 安全设计

1. 认证与授权

┌─────────────┐
│   Request   │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│ Authentication  │  (计划实现)
│  Middleware     │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│ Authorization   │  (计划实现)
│  Middleware     │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│    Handler      │
└─────────────────┘

2. 数据安全

  • 传输层安全: HTTPS/TLS 加密
  • 存储安全: Redis 密码认证
  • API Key 管理: 环境变量隔离
  • 输入验证: 参数校验和消毒

3. 限流策略

请求 ──► Rate Limiter ──► Handler
         │
         ├─► IP 限流
         ├─► 用户限流
         └─► API 限流

📊 数据模型

核心数据结构

1. 消息模型

type Message struct {
    ID             string    `json:"id"`
    ConversationID string    `json:"conversation_id"`
    Role           string    `json:"role"` // user, assistant, system
    Content        string    `json:"content"`
    ToolCalls      []ToolCall `json:"tool_calls,omitempty"`
    Timestamp      time.Time `json:"timestamp"`
}

2. 对话模型

type Conversation struct {
    ID        string    `json:"id"`
    UserID    string    `json:"user_id"`
    Title     string    `json:"title"`
    Messages  []Message `json:"messages"`
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
}

3. 知识模型

type Knowledge struct {
    ID        string                 `json:"id"`
    Content   string                 `json:"content"`
    Embedding []float32              `json:"embedding"`
    Metadata  map[string]interface{} `json:"metadata"`
    CreatedAt time.Time              `json:"created_at"`
}

4. 工具调用模型

type ToolCall struct {
    ID       string                 `json:"id"`
    Name     string                 `json:"name"`
    Arguments map[string]interface{} `json:"arguments"`
    Result   interface{}            `json:"result,omitempty"`
}

🔌 接口设计

RESTful API 规范

POST   /api/chat              # 非流式对话
POST   /api/chat/stream       # 流式对话
POST   /api/knowledge/add     # 添加知识
POST   /api/knowledge/search  # 搜索知识
DELETE /api/knowledge/:id     # 删除知识
GET    /api/health            # 健康检查

响应格式

{
  "code": 0,
  "message": "success",
  "data": {
    // 业务数据
  }
}

错误码

0      - 成功
1000   - 参数错误
2000   - 业务错误
3000   - 系统错误
4000   - 第三方服务错误

🚀 性能优化

1. 缓存策略

┌──────────────┐
│   Request    │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Cache Check  │ ──Yes──► Return Cached Data
└──────┬───────┘
       │ No
       ▼
┌──────────────┐
│ Process Data │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Cache Set   │
└──────┬───────┘
       │
       ▼
   Return

2. 并发处理

  • Goroutine 池化
  • Channel 通信
  • Context 超时控制

3. 连接池

  • Redis 连接池
  • HTTP 客户端连接复用

📈 可扩展性

水平扩展

         ┌─── Backend Instance 1
Load     ├─── Backend Instance 2
Balancer ├─── Backend Instance 3
         └─── Backend Instance N
              │
              ▼
           Redis Cluster

功能扩展

  • 插件系统: 支持动态加载工具
  • Provider 抽象: 轻松切换 LLM 提供商
  • 存储抽象: 支持多种存储后端

🔍 监控与日志

日志级别

  • DEBUG: 调试信息
  • INFO: 一般信息
  • WARN: 警告信息
  • ERROR: 错误信息

监控指标

  • 请求量 (QPS)
  • 响应时间
  • 错误率
  • 资源使用率

📝 设计原则

  1. 单一职责: 每个模块只负责一个功能
  2. 开闭原则: 对扩展开放，对修改关闭
  3. 依赖倒置: 依赖抽象而非具体实现
  4. 接口隔离: 使用小而专的接口
  5. DRY: Don't Repeat Yourself

本架构文档会随着项目演进持续更新。