10. 系统设计模板

十、系统设计模板¶

工业级 AI 系统设计架构蓝图与设计方法论¶

在构建工业级 AI 系统（如高并发检索增强生成系统、自主体执行引擎及多租户 Agent 平台）时，系统设计必须兼顾传统分布式架构的确定性要求与概率性大模型计算的非确定性特征。优秀的系统架构设计应避免堆砌学术概念或沦为单一的传统后端系统变体，而必须围绕“分层控制、状态感知、可观测性及安全治理”构建统一的工程图景。

flowchart TD A["API 接入与网关层 (鉴权、限流、流式网关、会话控制)"] --> B["业务编排与状态层 (Conversation State、路由分支、OODA 循环)"] B --> C["知识与数据检索层 (多路召回、Rerank、向量/元数据混合引擎)"] B --> D["模型调度与路由层 (Token 路由、并发预算、分级回退)"] C --> E["存储与缓存中台 (pgvector / ES、Query Cache、Entity Registry)"] D --> F["运行时治理与可观测中台 (Trace、审计日志、在线评测、ACL 网关)"]

工业级 AI 系统的分层架构体系：¶

API 接入与网关层（Access & Gateway Layer）：负责多租户隔离、高并发限流（Token-based Rate Limiting）、会话状态（Session State）初始化，以及面向客户端的单向流式推送（SSE）或双向长连接（WebSocket）生命周期管理。
业务编排与状态层（Orchestration & State Layer）：作为系统的“神经网络”，控制多步 OODA（Observe-Orient-Decide-Act）循环的执行逻辑，维护共享状态机快照，并根据动态决策执行 Task Handoff。
知识与数据检索层（Retrieval & Data Layer）：实现离线/在线的数据加工与高精检索，包含文档解析清洗管线、多路混合召回引擎（Sparse/Dense Retrieval）以及二次重排（Rerank）决策。
模型调度与路由层（Model Routing & Inf Layer）：负责跨模型服务商的负载均衡、冷启动预热、并发配额（Concurrency Quota）精细控制，以及高成本/高延迟模型的降级容灾流转。
存储与缓存中台（Persistence & Cache Layer）：承载关系型元数据、向量数据、会话 Checkpoint 镜像及多级缓存（Query Cache, Embedding Cache）。
运行时治理与可观测中台（Governance & Observability Layer）：提供跨节点的 Trace 链路追踪、无损 Prompt 版本化管理、实时安全合规审计以及在线/离线回归评测。

高并发检索增强生成（RAG）系统设计蓝图¶

在企业级场景中，构建 RAG 系统的核心挑战在于：如何将海量异构文档加工为高精准度的可检索资产，并在保证严格多租户权限隔离的前提下，提供亚秒级的端到端问答响应。

1. 离线数据加工与建库链路（Offline Data Pipeline）¶

离线链路必须采用异步任务驱动的分布式微服务架构，以隔离高耗时的文档处理压力与在线查询压力。

flowchart LR A["文档上传接口"] --> B["对象存储 (S3)"] B --> C["异步任务创建 (Celery / RabbitMQ)"] C --> D["文档解析与 OCR 服务"] D --> E["智能文本切块 (Chunking)"] E --> F["分布式向量化服务 (Embedding Batch)"] F --> G["向量与关系型数据库 (pgvector)"]

异步任务队列：文档解析、OCR、切块及 Embedding 属于重 CPU/GPU 消耗型操作。必须通过分布式消息队列（如 RabbitMQ, Kafka）将任务异步下发至 Worker 集群执行，前端通过 Polling 或 Webhook 接收任务状态。
存储选型与一致性控制：推荐采用 PostgreSQL 加 pgvector 扩展。其核心优势在于：可在单一数据库实例内，以强 ACID 特性同时存储文档原始元数据、关系型权限控制字段（ACL）与高维向量数据，极大降低了 ES + 向量库“双栈架构”带来的多数据源同步延时与一致性维护成本。

2. 在线检索与生成问答链路（Online Query Pipeline）¶

在线链路的核心在于亚秒级的 P95 延迟控制与绝对可信的权限过滤。

flowchart TD A["用户 Query 注入"] --> B["租户鉴权与权限过滤 (Pre-filtering)"] B --> C["多路并发召回 (BM25 + Dense Vector)"] C --> D["混合检索融合 (RRF)"] D --> E["二次重排 (Rerank)"] E --> F["上下文组装与 Prompt 注入"] F --> G["模型流式生成 (SSE)"]

多租户权限硬隔离：系统必须在向量检索阶段执行 Pre-filtering（前置过滤），而非召回后过滤（Post-filtering），防止因 Top-K 召回结果被权限规则大量过滤后导致可用上下文枯竭。在 pgvector 中，利用 SQL 的 WHERE tenant_id = :tenant_id AND user_role IN (:roles) 结合向量距离索引，实现物理级安全隔离。
多路召回融合与重排：通过 BM25（精确术语召回）与向量检索（高维语义召回）并行查询，采用倒数排序融合（Reciprocal Rank Fusion, RRF）合并两路结果，最后通过 Rerank 模型（如 Cohere / BGE-Rerank）进行相关度精细排序，仅截取最具相关性的 Top-N 块送入大模型，平衡 Token 成本与推理耗时。

3. 容量设计与瓶颈控制指标¶

高并发 RAG 系统的架构师必须实时监控以下三条系统级控制线： - 在途请求控制线：

$$\text{在途请求数 (Active Requests)} = \text{系统 QPS} \times \text{P95 端到端延迟}$$

该指标直接决定了 API 网关的并发连接池大小、工作线程数以及模型服务商的并发槽位（TPM/RPM）预留额度。 - 检索扇出压力线：

$$\text{检索总调用量} = \text{系统 QPS} \times (\text{召回通道数} + \text{Rerank 批量数})$$

在高并发下，双路召回与重排会产生级联的 I/O 扇出，必须为向量库和 Rerank 服务配置独立的并发限流与连接池隔离。 - 多级缓存加速与回源率：

$$\text{回源压力} = \text{原始请求量} \times (1 - \text{Cache Hit Ratio})$$

系统应在 API 网关层部署 Query Cache（针对完全一致的提问直接返回缓存回答），在检索层部署 Embedding Cache（避免针对相同意图重复执行向量化计算），以实现极低延迟响应并平滑流量洪峰。

物理受控的智能助手与 Tool Calling 系统设计¶

在允许 AI 助手调用企业内部业务工具的场景中，系统的核心设计原则是：“模型提出建议，服务端执行控制”。必须在宿主系统底层架设防线，严防自然语言的越权注入与失控的物理 side effect。

1. 强类型工具契约与安全注册表（Tool Registry）¶

所有可供调用的工具必须在平台执行集中注册，声明强类型的输入输出 Schema，并定义严格的安全等级：

{
  "tool_name": "update_order_status",
  "description": "修改特定工单的流转状态",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticket_id": {"type": "string"},
      "new_status": {"type": "string", "enum": ["assigned", "resolved"]}
    },
    "required": ["ticket_id", "new_status"]
  },
  "security_level": "HIGH_WRITE",
  "idempotent": true,
  "timeout_ms": 3000
}

2. 副作用控制与读写分离治理¶

读写分流：对于只读类工具（如 query_inventory），平台执行快速并发通道；对于写副作用工具（如 cancel_subscription, transfer_funds），平台必须拦截执行，执行严格的安全机制。
幂等性保障：写操作工具在 API 契约层必须强制要求携带 idempotency_key。即使大模型在受控循环中由于超时重试多次触发相同调用，服务端也必须保证该动作仅执行一次。
人工审批中断（Human-in-the-Loop）：对于 HIGH_WRITE 等高风险工具调用，Harness 必须挂起当前执行流，同步将状态写入 Redis Checkpoint，向客户端返回 PENDING_APPROVAL 中断信号。在管理员或用户显式点击确认后，平台反序列化恢复执行上下文，沿着图边缘继续推进。

流式长连接接口设计与底层资源回收¶

流式对话接口（Streaming API）的系统级难点在于：当网络中断或用户主动取消时，服务端如何确保全链路的异步资源回收，防止孤儿协程（Orphan Goroutines）与 token 盗刷拖垮系统。

1. 传输协议选择（SSE vs. WebSocket）¶

服务器发送事件（Server-Sent Events, SSE）：基于标准 HTTP 协议，采用单向文本流（text/event-stream）推送，支持天然的断线重连，开发与运维复杂度极低。对于单向流式对话，应作为首选方案。
WebSocket：提供全双工通信，适用于高频双向音视频交互或复杂的白板协作场景。在纯文本流式生成场景下，由于其协议握手开销大、负载均衡穿透性差，不建议盲目选用。

2. 全链路取消信号传播与背压控制（Context Propagation）¶

在 Go 语言实现中，必须将 HTTP 请求的 r.Context() 显式传播至最底层的 LLM 客户端、向量库查询及数据库连接池。

func StreamHandler(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithCancel(r.Context())
    defer cancel()

    // 显式将 ctx 传递至底层 LLM 客户端
    stream, err := llmClient.CreateCompletionStream(ctx, req)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "text/event-stream")
    w.Header().Set("Cache-Control", "no-cache")
    w.Header().Set("Connection", "keep-alive")

    for {
        select {
        case <-ctx.Done():
            // 客户端主动断开连接，立即终止下游大模型流，避免 Token 持续消耗
            log.Printf("Client disconnected, releasing resources")
            return
        case chunk, ok := <-stream.Channel():
            if !ok {
                return
            }
            fmt.Fprintf(w, "data: %s\n\n", chunk.Text)
            w.(http.Flusher).Flush()
        }
    }
}

孤儿协程控制：当用户在流式输出第 3 秒关闭浏览器时，r.Context().Done() 触发。若未在底层库传播该 context，底座的下游网络请求将继续生成至结束，导致系统并发资源（Goroutine, File Descriptor）被慢慢耗尽。

多租户 Agent 运行平台（Agent Platform）中台化架构¶

当企业从单一智能体演进为跨部门多业务场景的 Agent 服务集群时，必须将底座能力彻底中台化，形成统一的 Agent 运行时公共平台（Agent Platform Baselines）。

1. 平台核心基础设施组件¶

标准化适配层（Uniform MCP Adapter）：提供基于 MCP（Model Context Protocol）的标准化网关，将各部门独立的内部微服务以标准协议暴露为 Tool 或 Resource，实现即插即用。
多租户状态与 Checkpoint 服务：提供高可用、版本化的分布式状态 management 中心（基于 Redis Cluster + PostgreSQL），自动承载各 Agent 运行时共享状态（Durable State）的原子读写与持久化快照。
多因子记忆治理中心：提供高可用的语义向量存储、滚动摘要压扁队列，以及多因子记忆排序引擎，防止多轮会话中的历史记忆污染与失效召回。
审计与风险评估平台：跨应用追踪每一次 OODA 循环的决策链路与 Tool side effect，生成不可篡改的安全审计日志，并提供流量回放（Playback）和离线 Red Teaming 评测能力。

2. 系统持续改进与三层评测体系（Evaluation Registry）¶

为了确保系统的每一次优化（如 Prompt 变更、检索算法微调、依赖注入修改）都是客观且可量化的，平台必须内建三层评测机制： 1. 离线黄金数据集（Golden Evaluation Set）：收集核心高频问题、边界测试用例、合规安全样本以及历史上发生过的典型坏例（Bad Cases）。在任何代码或 Prompt 上线前，自动化 CI/CD 流水线必须拉起 Grader 模型或规则引擎执行回归评测，确保核心指标（语义相关度、准确度、无幻觉率）不发生负向漂移。 2. 线上影子评测（Shadow Evaluation）：将线上真实 Query 并发复制一份流向待发布版本，在后台执行静默计算，对比两代系统输出的分布差异，执行发布前的最后校验。 3. 闭环失败沉淀管线（Failure Compaction Pipeline）：线上用户踩到的 Bad Cases（通过点踩、人工干预介入记录）必须由治理后台自动打标、清洗，并增量合并回离线黄金数据集，实现系统自我纠偏的工程闭环。