ScienceOL 文档
  • 简体中文

      • 架构

      SciLaxy 各组件如何协同工作的概述，从用户浏览器到 LLM 提供商及返回。

      系统概览

      SciLaxy 由多个通过 Redis 和 PostgreSQL 进行通信的服务组成：

      ┌─────────┐     ┌─────────┐     ┌──────────────┐
│  Nginx  │────▶│ Next.js │     │   Casdoor    │
│ (代理)  │     │  (前端)  │     │   (OAuth)    │
└────┬────┘     └─────────┘     └──────────────┘
     │
     ├──▶ /scilaxy/api/* ──▶ ┌──────────────┐
     │                      │   FastAPI     │
     │                      │  (服务端)    │──┐
     │                      └──────────────┘  │
     │                                         │ Celery 任务
     └──▶ /docs/* ───────▶ ┌──────────────┐  │
                            │   Next.js    │  ▼
                            │   (文档)     │  ┌──────────────┐
                            └──────────────┘  │    Celery     │
                                              │  (Worker)    │
     ┌──────────────┐  ┌──────────────┐       └──────┬───────┘
     │  PostgreSQL  │  │    Redis     │              │
     │  (数据库)    │  │ (缓存/发布)  │◀─────────────┘
     └──────────────┘  └──────────────┘
      • Nginx — 反向代理，将流量路由到相应的后端服务
      • FastAPI (service) — REST API、SSE 流式传输、认证、文件上传
      • Celery (worker) — LLM 编排、智能体执行、后台任务
      • Next.js (web) — React 前端，使用 Zustand 状态管理
      • Rspress (docs) — MDX 文档站点（即本站）
      • PostgreSQL — 所有实体的持久化存储
      • Redis — 发布/订阅频道、流式事件持久化、缓存
      • Casdoor — OAuth/OIDC 身份提供商（可选）

      服务层

      后端采用分层架构：

      API 路由 (app/api/)
    ↓
核心服务 (app/core/)
    ↓
仓库 (app/repos/)
    ↓
数据库模型 (app/models/)
      • API 路由 处理 HTTP 相关事务：请求解析、认证、响应格式化
      • 核心服务 包含业务逻辑：智能体编排、订阅管理、文件管理
      • 仓库 提供数据访问：SQL 查询、缓存、分页
      • 模型 通过 SQLAlchemy 定义数据库 Schema

      流式传输管道

      当用户发送消息时，事件通过管道从 Celery Worker 流向浏览器：

      用户 ──POST──▶ FastAPI ──任务──▶ Celery Worker
                                      │
                                 LangGraph 执行
                                      │
                              Redis Streams (events:{topic_id})
                                      │
                              FastAPI SSE 端点 ◀── GET /events
                                      │
                                   浏览器

      事件类型

      流式事件系统使用一组结构化的事件类型：

      事件用途
      loading / processing在 UI 中显示加载指示器
      agent_start创建智能体执行消息
      node_start在执行中开始新阶段
      streaming_start标记消息为正在流式传输
      streaming_chunk向当前阶段追加文本内容
      thinking_chunk追加推理/思考内容
      node_end标记当前阶段完成
      streaming_end完成消息的流式传输
      agent_end标记整个执行完成
      message_saved确认消息已持久化到数据库

      断线重连

      事件通过 MAXLEN ~10000 持久化在 Redis Streams 中。当客户端重新连接时，会发送 Last-Event-ID 请求头。SSE 端点通过 XRANGE 回放遗漏的事件，然后切换到 XREAD 实时追踪。这保证了跨连接的零数据丢失。

      智能体编译

      智能体以 JSON 配置的形式定义，并编译为可执行的 LangGraph 工作流：

      智能体配置 (JSON)
    ↓ 规范化
规范配置
    ↓ 验证
已验证配置
    ↓ 编译
LangGraph StateGraph
    ↓ .compile()
可运行图
      1. 规范化 — 将配置归一化为确定性格式，解析组件引用
      2. 验证 — 检查结构完整性，验证节点连接，验证工具引用
      3. 编译 — 从规范配置构建 LangGraph 节点和边
      4. 执行 — 运行编译后的图，使用流式回调

      此管道支持内置的 ReAct 类智能体以及用户自定义的图配置。

      数据层

      PostgreSQL

      所有持久化实体存储在 PostgreSQL 中：

      • 智能体 — 配置、作用域（系统/用户）、提供商设置
      • 会话与话题 — 对话容器、消息历史
      • 消息 — 用户和智能体内容，包含引用
      • 文件 — 元数据、存储键、知识集关联
      • 技能 — 使用 SKILL.md 格式的自定义功能
      • 订阅 — 套餐、配额、用量追踪

      Redis

      Redis 承担多种角色：

      • 发布/订阅 — Worker 和 API Pod 之间的实时事件传递
      • Streams — SSE 重连的持久化事件存储
      • 缓存 — 会话数据、速率限制、临时状态

      对象存储

      文件存储在 S3 兼容的对象存储中（开发环境使用 MinIO，生产环境使用任意 S3 提供商）。PostgreSQL 存储元数据和引用；实际文件内容存储在对象存储中。