AI提示系统从单体到分布式架构的转型实战

"AI提示系统"这四个字，在我过去两年里几乎成了工作群里的高频词。它干的事情听起来很简单：把业务请求翻译成大模型能理解的提示词，再调用模型接口拿结果。但真正把它做成一个稳定、高效、多人协作的服务，复杂度并不比一个普通的后端系统低。我们最早把它实现成一个单体应用，业务少的时候一切岁月静好，后面随着业务线增加、流量上涨，单体方案开始露出各种疲态，逼着我们走完了从单体到分布式的转型之路。这篇文章不聊PPT式的架构愿景，只讲我们实际踩过的坑、做过的选择，以及每一步背后的理由，希望对正在规划同类系统的人有参考价值。

1. 单体提示系统是怎么一步步撑不住的

1.1 一开始的单体是什么样

最初的系统非常简单，一个服务、一个数据库、一张接口文档，基本上就是"能跑就行"。我们用常见的Web框架搭了一个HTTP服务，数据库里有两张核心表，一张存提示词模板，一张存模板变量和默认参数。业务方调用时传入一个业务场景ID和请求参数，服务内部做这几件事：根据场景ID查出对应模板，把参数填进去完成渲染，带上模型相关配置去调用模型接口，最后把返回结果透传给调用方。

这个阶段其实没有太多架构可言。模板的增删改查直接走管理后台接口，模板内容存在数据库里；渲染逻辑就是一段模板字符串的变量替换，偶尔加一些条件分支；模型调用相关的超时、温度、最大Token等参数，有一部分写在代码配置里，有一部分存在模板表的字段里；日志就是最普通的访问日志，出了问题只能靠人工翻。

这样跑了一段时间，问题开始一件一件冒出来。第一个感受是发布变得越来越重。模板内容虽然是存在数据库的，但模板字段变更、渲染逻辑调整、模型参数调整，经常需要改代码再发版。一次发版要等构建、测试、滚动更新，高峰期根本不敢动。第二个感受是性能瓶颈开始集中。渲染本身是CPU密集操作，而调用模型接口是典型的IO等待，这两类负载混在同一个进程里，高峰期互相拖累，表现为接口P95延迟偶尔飙到不可接受的程度。

1.2 压垮单体的几根稻草

单体架构的崩溃往往不是某一件事导致的，而是好几根稻草同时压下来。我们的情况大概集中在四个方面。

第一，模板管理和业务逻辑完全耦合。模板不是简单的内容，它里面会带条件判断、循环、变量默认值，甚至一小段自定义脚本。一旦模板语法升级或字段改名，必须同步改渲染逻辑，改完一起发版。不同业务线的模板想走不同的发布节奏，根本做不到，只能排队等同一个发版窗口。

第二，故障影响面被放大。有一次某个业务线在模板里引入了一个有语法问题的脚本，渲染进程在解析时直接抛异常，异常没有被隔离，导致整个服务的可用性下降。那个业务线的流量占比其实不高，但因为它和别人的模板在同一个渲染引擎里跑，一个坏模板拖垮了所有调用方。这就是典型的缺少故障隔离。

第三，资源分配无法精细化。单体服务里所有业务线共享同一份CPU、内存和连接池。某一个大流量业务线在高峰期把线程池占满，其他业务线的请求就会被连带阻塞。想给重点业务线划分独立的资源配额，单体架构根本做不到。

第四，多人协作变得痛苦。模板数量上千之后，不同业务线的人在同一套代码、同一个数据库里改东西，经常出现互相覆盖、格式混乱、审批流形同虚设的情况。代码评审和模板内容评审完全混在一起，效率非常低。

1.3 什么时候必须动手

不是所有单体都需要拆，得看信号。我们真正决定动手，是在连续出现这几个信号之后：业务线超过五条，模板数量突破一千，发布窗口排到一周两次都费劲，高峰期P95延迟开始抖动，以及每一次故障排查都要从入口日志一路翻到模板内容才能定位。任何一个信号单独出现可能还能忍，但当四五个信号同时出现时，继续在单体上打补丁就是在透支未来。

我当时给团队定的判断标准很简单：如果未来三个月内预计有两次以上跨团队改模板的需求，或者高峰期预计出现存量流量之外的突发流量，那就应该启动改造。反之，如果业务量稳定、团队小、改动不频繁，单体反而是最高效的，没必要为了架构的"先进性"去制造复杂度。

2. 转型前的盘算：别急着拆

2.1 先画清楚调用链路和依赖

很多人拆架构是一上来就画目标图，然后照着图开始写代码。我吃过这个亏，后来的经验是：先把现状盘清楚，再谈目标架构。

我们花了大概一周时间做现状盘点。第一步是梳理调用方清单，把线上所有调用提示系统的接口、服务、定时任务、后台管理页面全部列出来，记清楚每个调用方用的什么参数、期望什么返回、对延迟的容忍度是多少。第二步是梳理数据模型，把模板表里的字段逐个过一遍，找出哪些字段是真正被渲染逻辑使用的，哪些字段只是历史遗留、已经没有任何代码在引用。第三步是梳理隐藏依赖，比如有没有调用方在绕过接口直接连数据库查模板，有没有别的地方在通过订阅数据库变更来感知模板更新。

盘完之后的结论很扎心：至少有十几个隐藏依赖，垃圾桶里还有三个没人维护的定时任务在定期扫描模板表。这些历史债务如果不清理，拆出来的分布式系统会继承它们，最后变成分布式的灾难而不是分布式的红利。

2.2 目标架构怎么切分

做完盘点之后，我们确定了两个方向的切分逻辑。

第一个方向是横向分层，按照调用链的位置拆成四层：管理面、渲染面、接入面、数据面。管理面负责模板的创建、编辑、审批、发布，是面向内部团队的；渲染面负责把模板和参数渲染成最终字符串并调用模型接口，是面向在线流量的；接入面负责统一的入口网关，做路由、限流、鉴权和灰度；数据面负责模板存储、缓存、事件消息，是底层支撑。

第二个方向是纵向按业务域切分。不同业务线有完全不同的模板内容和参数结构，我们把模板按业务域做隔离，每个域有自己的命名空间、变量约定、权限边界。渲染服务虽然是统一的，但通过租户和业务域字段做逻辑隔离，避免一个域的异常直接影响另一个域。

切分原则只有一句话：先切数据边界，再切服务边界。如果两个模块共享同一张表而且字段互相依赖，就不应该硬拆成两个服务。我们当时把模板元数据、版本历史、渲染配置分开建模，确认了各自的数据归属，才开始拆代码。

2.3 技术选型的避坑清单

技术选型这部分，我们踩过不少弯路，总结几条比较实际的建议。

第一，不要在架构转型的同时引入一套全新的大规模基础设施。如果团队一直用的应用框架能继续用，就继续用，换个新框架只会让问题变复杂。我们的节奏是保留原技术栈，先用模块化方式在代码仓库内部隔离出独立模块，等跑通之后再拆成独立服务进程。

第二，消息队列不要追新，选团队运维经验最丰富的那一个。模板发布事件的数据量很小，真正重要的是可靠投递和消费幂等，不用为了吞吐量去选一个没人会用的大杀器。

第三，缓存选业内成熟的那个基本不用犹豫，但千万别忽略序列化和Key设计。不同服务不要混用Key前缀，否则版本兼容问题会让人崩溃。

第四，网关选择上也别过度设计。我们一开始考虑过引入服务网格，后来发现现阶段根本用不到那么多能力，一个轻量级的API网关加上应用层限流就够了。服务网格那套能力，等服务数量真正上百再考虑也不迟。

3. 四步拆解：从单体到分布式的实操路径

3.1 第一步：把提示资产管理独立成服务

转型的第一步，也是收益最明显的一步，就是把提示词资产的管理能力从单体里剥离出来，形成一个独立的资产管理服务。提示词在那个时候已经不只是一段字符串，而是一个有版本、有审批流、有租户隔离、有灰度策略的完整资产，再塞在业务系统里只会不断积累技术债。

这个服务负责的核心功能有四块：模板的CRUD和版本管理、模板变更的审批流、租户和权限隔离、模板发布与灰度策略。数据模型上，我们设计了模板主表、版本表、变量定义表、发布策略表。模板主表只存当前生效的元数据信息，版本表存每次发布的历史快照，变量定义表描述模板可以接收哪些参数以及参数默认值，发布策略表记录灰度比例和生效时间。

一条模板从修改到生效走的完整链路是：提交草稿、发起评审、审批通过、创建新版本、按灰度策略逐步放量、最终全量生效。改动模板内容不再需要发代码版本，运营同学可以在管理后台直接操作，整个过程有完整的操作审计。

迁移过程我们没有采取"一刀切切换"的方式，而是用了双写过渡。老系统和新资产管理服务同时写模板数据，线上流量仍然读老系统，等两边数据校验一致后再切读。这个方法听起来笨，但胜在安全，尤其适合线上流量已经很大的情况。双写大约持续了两周，确认没有数据差异之后才把老系统的写入口关掉。

3.2 第二步：渲染服务做无状态化改造

资产管理服务独立之后，下一步就是把渲染能力从单体中拆出来。这一步的核心不是简单地新建一个服务，而是把渲染逻辑真正改造成无状态服务。

无状态化的本质是让渲染进程不持有任何与业务状态相关的数据。渲染服务只接收模板内容、参数、模型配置这些输入，输出渲染结果。模板内容从哪里来？从资产管理服务通过API获取，在本地做进程内缓存作为加速。模型配置怎么管理？通过配置中心下发，渲染服务只负责读配置并执行调用。这样任何一个渲染服务实例都可以随时重启、扩容、缩容，不会因为丢失本地状态而造成错误。

渲染逻辑本身也要做优化。早期用正则做变量替换的性能很差，模板一复杂就出现各种转义问题。我们换成了模板预编译方案：模板内容在写入缓存之前先编译成中间表示，渲染时直接执行中间表示，不再重复解析模板字符串。实测下来，模板预编译之后渲染耗时下降了大约70%，因为解析模板这个CPU密集的操作不再出现在请求路径上。

同时我们做了幂等处理。渲染接口的请求里必须带request_id，同一个request_id重试不会产生副作用。模型调用如果超时也要透传request_id，方便后续做链路追踪。幂等这个设计看着不起眼，但在下游重试、消息队列重复消费的场景里非常关键。

3.3 第三步：接入层网关的路由与治理

服务拆分到这一步，看起来已经有模有样了，但如果不解决统一入口的问题，调用方会陷入混乱：有的直接调资产管理接口，有的直连渲染服务，限流逻辑散在各个服务里，完全不可治理。所以第三步是做一层统一的API网关。

网关承担的核心职责是路由和治理。路由方面，网关根据请求里的业务域字段，把流量分发到不同的渲染服务实例组。治理方面，网关集中做鉴权、限流、熔断、灰度。限流不再依赖每个服务自己实现，而是在网关统一配置配额，比如某个测试业务线每秒允许一千次请求，超过则快速失败返回错误码。

灰度能力也是在这一层落地的。模板发布新版本后，通过网关把一小部分流量切到新版本模板对应的渲染实例上，观察延迟和错误率，稳定后再逐步放大比例。灰度如果出现问题，只需在网关上把流量全部切回旧版本实例，不用重新发版。

网关的选型其实不用太纠结，成熟的API网关项目都能满足基本需求。要注意的是网关层的配置管理，路由规则、限流配额、熔断阈值必须支持动态修改并且热生效，最好能跟配置中心打通。我们遇到过最尴尬的情况是线上流量异常需要紧急降级，结果网关配置要改代码发版，最后花了几个小时才恢复，这个教训直接推动我们切换到了动态配置方案。

3.4 第四步：变更事件的异步解耦

模板发布之后，渲染服务怎么感知到最新版本？最直白的方式是渲染服务每次请求都实时查资产管理服务，但这样会把在线流量路由到管理面，一旦管理面出现抖动，在线渲染就会跟着出问题。我们最终采用的是事件驱动的异步解耦方案。

资产管理服务在模板版本发布后会发送一个变更事件到消息队列，渲染服务订阅这个事件，收到后刷新本地缓存的模板内容。这样模板发布的动作和管理面的请求完全解耦，渲染服务不依赖管理面的实时可用性。

事件设计上需要额外注意版本语义。事件消息里必须带上版本号，消费端处理时要以版本号高的为准，不能简单覆盖。因为消息队列不保证严格顺序，两个版本事件先后到达时，后到的可能是旧版本，如果直接覆盖就会导致线上模板错乱。我们的做法是消费端维护一个"当前已应用版本号"字段，只有发现事件中的版本号大于当前版本时才刷新，否则直接丢弃。

消费者还要做到幂等。同一版本事件可能被重复投递，也可能在消息队列里出现副本，消费逻辑需要在重复事件下保持结果一致。我们在业务侧做了一层轻量去重，用版本号加模板ID作为唯一键，确保一个版本只生效一次。

4. 分布式落地中躲不开的细节与坑

4.1 缓存设计：命中率与一致性怎么平衡

分布式之后，缓存成了性能的命脉。我们的缓存分成两层：渲染服务进程内缓存和分布式缓存。进程内缓存用LRU策略，负责挡住单个实例的重复渲染热点；分布式缓存负责集群共享，避免每个实例各自查库。

Key设计上，我们统一采用"业务域:模板标识:版本号"的结构。带上版本号是必须的，因为同一个模板在不同版本下内容完全不同，如果不区分版本，发布后可能出现新旧内容交错的情况。例如某个服务刚刚收到新版本事件但缓存还是旧版本，另一个服务已经拿到新版本内容，流量打到不同实例上就会出现结果不一致。

缓存失效策略我们选择了主动失效，而不是只依赖过期时间。当模板版本发布时，资产管理服务除了发MQ事件，还会主动删除分布式缓存中对应的Key，让下一次请求回源到最新数据。只靠TTL的问题是失效窗口不可控，高峰期缓存过期瞬间容易造成数据库压力骤增。

热Key问题最麻烦。某个大促模板在活动期间的访问量是平时的几十倍，全部打到一个Key上，分布式缓存单分片压力很大。我们最终用本地缓存加singleflight模式解决：进程内缓存兜底一部分流量，同一时刻对同一个Key的并发回源请求合并成一个，避免缓存击穿。这个组合实测扛住了活动峰值，QPS翻了四倍也没有出现明显抖动。

4.2 版本热更新与快速回滚

模板发布后的快速回滚能力，是我们在一次线上事故之后才真正重视起来的。那次事故里，新版本的模板存在一个非常隐蔽的变量默认值问题，导致渲染出来的内容不符合预期，业务方反馈之后我们想把版本回退到上一个稳定版本，结果发现回滚操作要手动跑脚本去改数据库，而且还要等缓存自动过期，整个过程花了将近半小时。

痛定思痛，我们完善了一套版本发布和回滚流程。每个版本保存了完整的渲染上下文快照，包括模板内容、变量定义、模型参数。线上模板始终有一个"当前生效版本号"的指向，发布新版本只是把这个指向改到新版本，回滚只是改回旧版本号。整个操作在管理后台一键完成，同时自动清掉相关缓存Key并发送MQ事件让渲染服务刷新本地缓存。

版本灰度也需要配合回滚机制。我们的灰度策略支持按百分比逐步放开，如果某个阶段错误率超过阈值，系统自动把流量全部切回旧版本，并发出告警。这个自动回滚机制后来救了我们一次，它把一个可能持续几分钟的事故压缩成了十几秒的抖动。

4.3 可观测性：日志、指标与链路追踪

分布式系统最大的痛点之一就是故障排查变得困难，所以可观测性不能等到服务全部拆完再补，应该每一步同步建设。我们从三个维度搭建了完整的可观测体系。

指标层面，我们重点埋了四类指标：渲染服务的QPS和P95延迟、模板缓存命中率、模型调用成功率和耗时、网关层面的限流次数和熔断事件。每个指标都按业务域打标签，方便单独看某条业务线的状态。模板缓存命中率这个指标尤其重要，它直接反映了缓存设计是否合理，也能提前预警热Key问题。

日志层面，全部改成结构化日志，统一用JSON格式输出，并且强制要求包含request_id、业务域、模板版本号、耗时这几个字段。以前用文本日志排查问题要写正则去抠字段，现在直接查结构化日志服务，效率提升明显。

链路追踪层面，我们用标准的trace方案串联起网关、渲染服务、资产管理服务和模型调用。一次请求的完整调用链可以在同一个trace里看到：在哪个环节耗时最长，是模型调用还是模板渲染，是缓存命中还是回源查库。这个能力在排查"一个问题出现在多个环节"的场景里极其好用。

4.4 数据一致性：最终一致与对账

分布式之后，模板版本的一致性是一个绕不开的话题。我们的设计接受的是最终一致：模板发布之后，渲染服务并不是立刻就能拿到最新版本，中间会有一个短暂的窗口期，窗口期内可能还在用旧版本渲染。

这个窗口期能不能接受？对提示系统来说可以，因为模板更新的时效性要求通常不高，几秒甚至十几秒的延迟不会造成严重后果。但我们必须把这个窗口控制在可接受范围内，并且有一个持续检测的机制。

我们的方案是定时对账。一个后台任务定期扫描当前的模板版本列表，查询渲染服务报告上来的当前生效版本号，如果一个模板的线上指向版本与渲染服务实际生效版本不一致，就把差量找出来并且触发一次强制刷新。对账任务也承接了兜底职责：如果MQ事件因为故障没有送达，对账任务也能保证最终一致，只是时间稍微慢一些。

这里特别想说，不要在分布式模板系统里去使用分布式事务。有一次我们尝试用两阶段提交保证模板发布和缓存刷新的原子性，结果复杂度急剧上升，各种协调器超时问题层出不穷。后来我们彻底放弃了强一致思路，转向事件加对账，系统反而稳定了很多。

5. 常见问题与排查实录

5.1 六个高频问题排查速查表

转型过程中遇到的各种问题，不少具备共性，我整理了一份排查速查表，给团队内部作为参考，现在分享出来。

这张表看着简单，实际上每一条背后都是真实的线上问题。它最大的价值是让运维和开发在告警触发后不用从零开始猜，而是能对照着快速定位方向，节省大量排查时间。

5.2 两个真实踩坑记录

第一个是模板发布后的回滚事故。有一次新版本模板上线后，渲染出来的内容出现了严重的格式错误，我们立即在后台执行回滚，把线上版本标记改回旧版本。但当时缓存清理逻辑没有集成进回滚流程，线上各节点还在继续使用新版本的本地缓存，结果就是回滚操作没有真正生效，旧版本内容迟迟没法恢复。后来花了二十多分钟手动清缓存才稳定下来。这个事故之后，我们回滚操作里加了强制的缓存清空和事件广播，并且每次回滚后自动跑一次对账，确保所有节点回到目标版本。

第二个是热点模板导致的冷启动雪崩。大促期间，某个爆款模板的访问量陡增，我们按预案对渲染服务做了扩容。新启动的实例本地缓存是空的，所有请求同一时间回源到分布式缓存，分布式缓存也不够热，继续回源到数据库，数据库连接池被打满。这个问题其实充分体现了"进程内缓存不能省"的道理。后来我们在新实例启动时增加了热点模板预热机制，把当前Top 50的热点模板预加载进本地缓存，同时配合singleflight合并回源请求，才算从根本上解决了冷启动问题。

转型完成一年多之后再回头看，我最深的感受是，架构拆分本身不复杂，难的是让团队和流程跟上。分布式之后，提示词变成了一个真正被管理的资产，它不再依附于某个业务系统，而是一个独立的、有版本、有审批、有灰度、有监控的基础能力。如果让我给正准备转型的团队一个建议，我会说：先不要追求一步到位的完整分布式，先做最小拆分——把提示资产管理独立出来、渲染服务无状态化、加一层统一网关，这三件事做完，单体时期百分之八十的瓶颈就能解决。剩下的，等业务真的需要再说。