跳转至

系统架构

本文档基于当前代码仓库梳理系统组件、数据流与运行拓扑，聚焦已实现能力。

文档定位

这是“当前态总览”页面，用来回答：

  • 系统由哪些组件组成
  • 数据和请求在各组件之间如何流动
  • 主要目录和职责如何映射

如果你已经知道问题落在哪个子系统，可直接跳到对应页面：

你想回答的问题 优先阅读
聊天运行时内部阶段怎么串起来 编排器
当前 RAG 到底按什么顺序检索 当前 RAG 全链路
这是目标设计还是当前实现 Agent Runtime v1 设计
高层设计如何映射到代码结构 Agent Runtime 架构实现指南
数据存储分层如何划分 存储架构

架构目标

  • 提供可扩展的对话服务入口，支持 SSE 与 WebSocket。
  • 支持 Agent 与知识源管理，并以 RAG 方式增强回答。
  • 支持 Agent 级 MCP Server 挂载，按策略调用外部工具（出站）。
  • 支持文档上传、解析、分块与向量检索。

应用域边界

当前仓库在控制面与运行面上至少有 3 个需要明确区分的应用能力：

应用域 主要 owner 代码入口 说明
Conversations Session、ConversationTurn、人工接管与会话排查 ai_service/conversations/interfaces/http/router.py、admin-frontend/shared/api/conversations.ts、admin-frontend/studio/src/shadcn-admin/pages/conversations-page.tsx 这是会话运营域，不是通用 history 域。
Document Recognition DocumentExtractionJob、DocumentExtractionFieldReview、review projection ai_service/document_recognition/interfaces/http/router.py、ai_service/document_recognition/application/projections.py、admin-frontend/shared/api/documentRecognition.ts 这是单证识别域，不与 conversations 共享业务 DTO 或详情结构。
Fusion Agent draft / version snapshot、FusionRun ai_service/fusion/interfaces/http/router.py、admin-frontend/shared/api/fusion.ts Fusion 是独立 runtime / control-plane 能力，不与上述两者合并。

共享层只承接技术能力，例如分页、查询参数、鉴权辅助、通用 UI primitives。它不拥有跨应用的“统一 history 业务模型”。

组件清单

组件 目录 说明
AI 服务 ai_service/ FastAPI + LangGraph 编排器与 RAG 能力
Demo 后端 demo-backend/ Socket IO 中转服务
Demo 前端 demo-frontend/ 对话演示前端
Admin 前端 admin-frontend/ Agent 与知识源管理界面
文档与配置 docs/ mkdocs.yml 文档系统与导航

运行拓扑

flowchart LR
  User[用户浏览器]
  DemoFE[Demo 前端]
  AdminFE[Admin 前端]
  DemoBE[Demo 后端 Socket IO]
  API[AI 服务 FastAPI]
  Orchestrator[编排器 LangGraph]
  ModelLoader[模型加载器]
  DB[关系型数据库]
  MinIO[对象存储 MinIO]
  Qdrant[向量库 Qdrant]

  User --> DemoFE
  User --> AdminFE
  DemoFE --> DemoBE
  DemoBE --> API
  AdminFE --> API
  API --> Orchestrator
  Orchestrator --> ModelLoader
  API --> DB
  API --> MinIO
  API --> Qdrant

系统上下文

下面这张图强调“谁是控制面，谁是执行面，数据落到哪里”。

flowchart TB
  subgraph Clients[客户端入口]
    User[终端用户]
    Operator[运营管理员]
    DemoFE[Demo 前端]
    AdminFE[Studio Admin]
    DemoBE[Demo 后端]
  end

  subgraph ControlPlane[控制面]
    API[FastAPI API]
    Agents[Agent Registry]
    FusionDrafts[Fusion Drafts on Agents]
    Eval[Evaluation and Audit]
    Scheduler[Scheduled Tasks]
  end

  subgraph RuntimePlane[执行面]
    ChatRuntime[Chat Orchestrator]
    FusionRuntime[Fusion Runtime]
    MCP[MCP Adapter]
    RAG[RAG Retrieval]
    Model[Model Loader and LLM]
  end

  subgraph Storage[存储层]
    DB[(PostgreSQL)]
    Blob[(MinIO)]
    Vector[(Qdrant)]
  end

  User --> DemoFE
  DemoFE --> DemoBE
  DemoBE --> API
  Operator --> AdminFE
  AdminFE --> API

  API --> Agents
  API --> FusionDrafts
  API --> Eval
  API --> Scheduler

  API --> ChatRuntime
  API --> FusionRuntime

  ChatRuntime --> RAG
  ChatRuntime --> MCP
  ChatRuntime --> Model

  FusionRuntime --> RAG
  FusionRuntime --> MCP
  FusionRuntime --> Model

  Agents --> DB
  FusionDrafts --> DB
  Eval --> DB
  Scheduler --> DB
  RAG --> Vector
  RAG --> DB
  MCP --> DB
  ChatRuntime --> DB
  FusionRuntime --> DB
  FusionRuntime --> Blob
  API --> Blob

关键数据流

对话请求

flowchart LR
  Client[客户端] --> API[FastAPI]
  API --> Orchestrator[LangGraph 编排器]
  Orchestrator --> LLM[聊天模型]
  Orchestrator -->|可选| RAG[RAG 检索]
  RAG --> Qdrant[向量库]
  Qdrant --> DB[文本块数据库]
  Orchestrator --> MCP[MCP Client]
  MCP --> ExtMCP[外部 MCP Server]
  Orchestrator --> API
  API --> Client

文档摄取

flowchart LR
  Upload[上传文档] --> MinIO[MinIO 存储]
  MinIO --> Parser[解析器]
  Parser --> Chunker[分块服务]
  Chunker --> Embedder[嵌入服务]
  Embedder --> Qdrant[向量库]
  Chunker --> DB[文本块数据库]

Agent 与 Fusion 关系

flowchart LR
  Agent[Agent<br/>统一业务实体]
  Draft[Fusion Draft<br/>live editable runtime config]
  Ver[Agent Version<br/>不可变 runtime 快照]
  Run[Fusion Run<br/>一次执行]
  Gov[Agent 治理上下文<br/>知识源 MCP 预算 评测]

  Agent -->|owns| Draft
  Agent -->|1:N snapshots| Ver
  Ver -->|1:N| Run
  Agent -->|inherits| Gov
  Gov -->|applies to| Run

这层关系的关键点是：

  • Agent 继续作为统一控制面实体。
  • Fusion 是一种 runtime implementation，而不是独立产品主体。
  • live draft 保存在 Agent 上，不可变快照保存在 AgentVersion 上。
  • Fusion Run 会同时绑定 agent_id 与 agent_version_id，这样执行结果和审计都能直接落在统一快照边界上。

目录与职责映射

  • ai_service/api/：API 路由与协议定义
  • ai_service/conversations/：会话应用域的显式 HTTP 入口
  • ai_service/document_recognition/：单证识别应用域的显式 HTTP 与 projection 入口
  • ai_service/orchestrator/：LangGraph 编排器与状态模型
  • ai_service/services/：RAG、摄取、分块、嵌入
  • ai_service/services/mcp_*：MCP 挂载解析、策略、客户端、审计、密钥管理与工具适配（mcp_tool_adapter.py）
  • ai_service/storage/：数据库模型、MinIO 与 Qdrant 客户端
  • ai_service/utils/：配置、日志、模型加载

如需了解具体 API 端点，请查看「核心概念 → API 服务」与「API 参考」。