架构设计 on 姚玉亮的网络日志

企业级 LLM 问答服务架构总览

Wed, 18 Dec 2024 10:30:00 +0800

各自管 Key 的日子

2024 年初，公司内部好几条业务线都想接大模型：客服要做智能问答，研发要做代码助手，数据团队要做自然语言查数。各团队自己调 OpenAI 或本地部署的模型，结果就是 Key 管理混乱，提示词和知识库没法复用，鉴权和审计更谈不上。

所以我们做了一个企业级的知识库问答服务：对上提供统一 API，对下屏蔽不同模型供应商的差异，RAG 检索增强、多轮对话、工具调用、流式输出都收进来。

六层，各管一摊

服务用 Go（Gin）做网关层，从上到下分六层：

接入层：统一鉴权（复用统一认证中心的 JWT）、限流、SSE 流式输出；
会话层：多轮对话历史管理、Token 预算控制、对话摘要；
检索层：混合检索（BM25 + 向量）、light_rag 轻量检索、知识图谱增强；
模型层：统一 LLM 适配层，封装 OpenAI、Azure、VLLM、HuggingFace 等，支持多模型路由和降级；
工具层：MCP 工具调用、Function Calling、外部 API 编排；
数据层：PostgreSQL 存对话和元数据，Milvus/Qdrant 存向量，Redis 做缓存和会话状态。文档解析和向量化不在本服务里，交给数据集管理服务做（eino + pond 高并发），问答服务只做检索和生成，职责清楚。

网关入口

路由注册和中间件链长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


func NewRouter(h *Handler, auth *AuthMiddleware) *gin.Engine {
 r := gin.New()
 r.Use(gin.Recovery(), zaplogger.GinLogger(), auth.Verify())

 v1 := r.Group("/api/v1")
 {
 v1.POST("/chat/completions", h.ChatCompletions) // 类 OpenAI 接口
 v1.POST("/chat/stream", h.ChatStream) // SSE 流式
 v1.GET("/conversations/:id", h.GetConversation)
 v1.POST("/conversations/:id/messages", h.SendMessage)
 v1.POST("/tools/call", h.CallTool) // MCP 工具
 }
 return r
}

对话主流程

编排长这样（伪代码，展示核心链路）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


func (h *Handler) ChatStream(c *gin.Context) {
 var req ChatRequest
 if err := c.ShouldBindJSON(&req); err != nil {
 respondError(c, 400, err)
 return
 }

 // 1. 加载历史 + 滑动窗口裁剪
 history, err := h.convSvc.LoadHistory(c, req.ConversationID, req.TokenBudget)
 if err != nil {
 respondError(c, 500, err)
 return
 }

 // 2. RAG 检索
 contexts, err := h.retriever.Retrieve(c, req.Query, req.KnowledgeBaseIDs,
 retriever.WithHybrid(true), retriever.WithTopK(5))
 if err != nil {
 // 检索降级：不阻断主流程，用纯对话兜底
 h.log.Warn("retrieve failed, fallback to chat-only", zap.Error(err))
 }

 // 3. 构造消息
 messages := h.promptBuilder.Build(req.Query, history, contexts, req.SystemPrompt)

 // 4. 选择模型 + 流式生成
 model := h.router.Route(req.Model, req.Priority)
 stream, err := h.llm.ChatCompletionStream(c, model, messages)
 if err != nil {
 respondError(c, 502, err)
 return
 }

 // 5. SSE 推流 + 异步落库
 c.Stream(func(w io.Writer) bool {
 chunk, ok := <-stream
 if !ok {
 go h.convSvc.SaveMessage(req.ConversationID, messages, accumulated)
 return false
 }
 accumulated += chunk.Content
 c.SSEvent("message.delta", chunk)
 return true
 })
}

四个权衡

SSE 的错误处理是个坑：Header 一旦写出去，就回不去标准 JSON 错误了。所以先同步等模型连接成功（拿到第一个 chunk 或错误），再切换到 SSE 流；生成中途出错，用 event: error 事件推给客户端，客户端统一按事件处理。

检索不能绑架主流程。向量库偶尔抖动超时，不能让整个问答跟着挂。检索设了 800ms 超时，超时就走纯对话模式，并在响应头标注 X-Retrieval-Mode: fallback，前端可以提示用户：这条答案没过知识库。

对话历史不全塞 Redis。长对话的内存占用大，最后是 PostgreSQL 持久化 + Redis 缓存最近 N 轮的混合策略，超出窗口的历史通过摘要压缩。

模型路由先规则后智能。简单问题给便宜模型，复杂问题路由到强模型。路由策略初期基于规则（关键词 + 长度），后续计划加一个小模型做意图分类。

后来

回头看，这个服务的价值不在封装了多少个模型，而在把鉴权、检索、上下文、工具调用这些共性能力沉淀成平台，让业务方只需要关心自己的知识库和提示词。统一接入后，Key 管理、成本统计、审计日志都有了着落，新业务接入 LLM 的周期从周级降到了天级。

封面图：robert.claypool / Flickr · CC BY 2.0

支付平台三端分离架构设计：多场景统一支付的落地

Sat, 09 Dec 2023 10:30:00 +0800

支付场景太散了

我在某科技公司主导统一支付平台。支付场景很散：有面向终端用户的充值、订阅付费，有面向机构客户的对公转账和批量打款，还有运营后台的手工调账、退款审批。要是把这些逻辑全塞进一个应用，权限边界会搅在一起，发版互相影响，接口粒度也没法统一。

我的做法是三端分离、共用一个支付内核：用户端、商户端、管理端各自独立部署，底层共用支付订单、状态机、渠道适配和对账能力。

三端，一个内核

接入层用 Gin 起了三个独立服务，各自有自己的路由组和中间件链。用户端对接前端，OAuth2 登录，只有下单、查单、回调接收；商户端对接机构客户的系统，走 AppID/AppSecret 的 OpenAPI 签名认证，提供统一下单、退款、查询；管理端对接运营后台，RBAC 权限，审批、调账、对账导出都在这。

三端都不直接碰数据库，统一走 gRPC 调 payment-core。支付核心封装了订单状态机和支付渠道适配：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


type PaymentService struct {
 db *gorm.DB
 channels map[string]Channel // channelCode -> adapter
 engine *billing.Engine // 动态计费引擎
}

type Channel interface {
 CreateOrder(ctx context.Context, order *Order) (payURL string, err error)
 QueryOrder(ctx context.Context, orderNo string) (*ChannelOrder, error)
 Refund(ctx context.Context, orderNo string, amount int64) error
 ParseCallback(req *http.Request) (*CallbackResult, error)
}

// 统一下单入口，三端最终都走到这里
func (s *PaymentService) CreateOrder(ctx context.Context, req *CreateOrderReq) (*Order, error) {
 // 1. 计费引擎算出应付金额
 amount, err := s.engine.Calculate(ctx, req.BizCode, req.Params)
 if err != nil {
 return nil, err
 }

 order := &Order{
 OrderNo: snowflake.New().NextID().String(),
 BizCode: req.BizCode,
 BizID: req.BizID,
 PayerID: req.PayerID,
 Amount: amount,
 Status: OrderStatusPending,
 Channel: req.ChannelCode,
 CreatedAt: time.Now(),
 }

 // 2. 落库
 if err := s.db.Create(order).Error; err != nil {
 return nil, err
 }

 // 3. 调起对应渠道
 ch, ok := s.channels[req.ChannelCode]
 if !ok {
 return nil, ErrChannelNotSupported
 }
 payURL, err := ch.CreateOrder(ctx, order)
 if err != nil {
 order.Status = OrderStatusFailed
 s.db.Model(order).Update("status", OrderStatusFailed)
 return nil, err
 }
 order.PayURL = payURL
 return order, nil
}

商户端的签名认证是独立中间件，除了验签还带防重放，5 分钟时间窗加 nonce 去重：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


func MerchantSignAuth(redis *redis.Client, merchantSvc MerchantService) gin.HandlerFunc {
 return func(c *gin.Context) {
 appID := c.GetHeader("X-App-Id")
 sign := c.GetHeader("X-Sign")
 timestamp := c.GetHeader("X-Timestamp")
 nonce := c.GetHeader("X-Nonce")

 if appID == "" || sign == "" {
 c.AbortWithStatusJSON(401, gin.H{"msg": "missing auth headers"})
 return
 }
 // 防重放：5 分钟时间窗 + nonce 去重
 if math.Abs(float64(time.Now().Unix()-toInt64(timestamp))) > 300 {
 c.AbortWithStatusJSON(401, gin.H{"msg": "timestamp expired"})
 return
 }
 if ok, _ := redis.SetNX(c, "nonce:"+nonce, 1, 5*time.Minute).Result(); !ok {
 c.AbortWithStatusJSON(401, gin.H{"msg": "replayed request"})
 return
 }

 secret, err := merchantSvc.GetAppSecret(c, appID)
 if err != nil {
 c.AbortWithStatusJSON(401, gin.H{"msg": "invalid app"})
 return
 }
 // 按 method + path + timestamp + nonce + body 拼接待签名字符串
 signStr := buildSignString(c, timestamp, nonce)
 if err := rsa.Verify(secret.PublicKey, []byte(signStr), sign); err != nil {
 c.AbortWithStatusJSON(401, gin.H{"msg": "sign verify failed"})
 return
 }
 c.Set("merchant_id", secret.MerchantID)
 c.Next()
 }
}

四个权衡

第一是接口粒度。结果发现三端要的东西完全不一样：用户端要聚合后的 DTO，订单里带商品名、状态文案；商户端要稳定精简的字段，OpenAPI 不能随便加字段；管理端要全量字段加筛选分页。我们没有让 payment-core 做接口裁剪，而是三端 API 层各自组装 DTO，core 只返回领域模型，别让核心服务被展示逻辑污染。

第二是回调幂等。支付渠道的回调可能重复投递。我们用 order_no 加 channel_trade_no 做唯一索引，重复回调直接返回成功，不重复触发流转。状态机自己还有一层防护：Paid 状态再收到 PaySuccess 是空操作，不会重复发货。

第三是对账。三端共用一个对账内核，每天凌晨拉渠道对账单跟本地订单比对，差异进差错池。导出用 Excelize 流式写入，机构客户一次能导几十万行，全量加载会 OOM。数据隔离在 DAO 层用 merchant_id 强制过滤，商户端只能导出自己名下的订单。

第四是计费规则。按次、包月、阶梯价、渠道费率，不同业务线算法不一样。我们把规则抽成 Rule 接口，配置驱动，新增业务线只加规则实现和配置，不用动下单主流程。

后来

三端分离拆的其实是"谁在用"和"怎么支付"这两件事：认证、权限、DTO 组装留在接入层，状态机一致性和渠道扩展性收在核心层。支付系统还有条底线：业务代码不许直接改订单状态，所有流转都过状态机校验。

封面图：The City of Toronto / Flickr · CC BY 2.0