1. 从一堆“散装 AI 项目”说起QuickBlue 到底想解决什么问题过去一年半我陆陆续续帮三家公司做过 AI 功能的落地场景各不相同一家做跨境电商客服一家做工业质检报告生成还有一家做企业内部知识问答。有意思的是这三家踩的坑几乎一模一样——模型调用代码散落在各个业务模块里提示词硬编码在 Java 类里换个模型要改十几个文件密钥管理靠配置文件明文谁调用了多少次、花了多少钱完全说不清。这就是 QuickBlue 这类“AI 应用底座”出现的真实背景。它不是又一个模型也不是又一个聊天界面而是一层夹在业务系统和各种 AI 能力之间的中间层。你可以把它理解成 AI 时代的“中台”或者“网关”所有跟大模型、向量库、提示词、会话、计费、限流相关的事情都收敛到这一层统一处理业务侧只调用几个稳定的接口。QuickBlue 这个标题里有两个关键词值得拆开看。Quick强调的是接入速度——让一个原本没有 AI 能力的 Spring Cloud 微服务系统能在半天内接上对话、检索、Agent 这些能力Blue我理解成“蓝图”或者“底座”的意思它要提供的是可复用的基础设施而不是一次性脚本。合起来它想回答的问题就是企业已经有了一套成熟的微服务架构怎么把 AI 能力“长”进去而不是“贴”上去。适合读这篇的人有三类。第一类是正在做 AI 功能落地的后端工程师尤其是 Java 技术栈、用 Spring Cloud 或 Spring Cloud Alibaba 的团队第二类是技术负责人需要评估“自研一套 AI 网关”还是“用现成底座”第三类是对微服务架构感兴趣、想看看 AI 场景下微服务怎么演进的开发者。下面我会把 QuickBlue 的设计思路、核心模块、实操接入步骤、以及我踩过的坑尽量讲透。2. 为什么企业真的需要一个“AI 应用底座”2.1 没有底座时AI 功能会烂成什么样我先描述一个非常典型的“无底座”现场。某公司的订单服务里为了做智能客服摘要直接引入了某云厂商的 SDK在 Service 层写了一段调用代码提示词用字符串拼接模型名写在application.yml里。三个月后产品要求换一个更便宜的模型同时运营要求能看到每个租户的调用量。结果就是改模型要重新发版统计调用量得去翻云厂商控制台提示词版本无法回溯A/B 测试根本做不了。这种模式的问题可以归纳成四条。耦合AI 调用逻辑和业务逻辑混在一起业务代码里到处是if (model.equals(...))。不可观测没有统一的埋点token 消耗、响应延迟、失败率都是黑盒。不可治理限流、降级、熔断这些微服务里早就玩熟的东西在 AI 调用上完全缺失。不可复用A 团队写的提示词B 团队要重新写一遍知识无法沉淀。QuickBlue 这类底座的价值就是把这四个问题一次性收口。它把 AI 能力抽象成独立的服务业务侧通过 Feign 或者网关调用模型切换、提示词管理、计量计费都在底座内部完成。这跟当年微服务拆分把“用户”“订单”“支付”拆出来是同一个逻辑——关注点分离。2.2 底座和“直接调 API”的本质区别很多人会问我直接调大模型 API 不就行了为什么要多一层这个问题我在项目评审会上被问过至少五次。我的回答通常是直接调 API 相当于每个业务模块自己连数据库短期没问题长期一定失控。底座提供的是横切能力。举个具体例子限流。大模型 API 通常有 QPS 和 token 双重限制如果十个业务模块各自调用你根本没法做全局配额。底座可以在入口处做统一令牌桶按租户、按应用、按模型维度分配额度。再比如缓存相同的问题在短时间内被问多次底座可以做语义缓存直接返回省下的 token 是实打实的成本。还有审计哪些提示词、哪些用户、什么时候调的、返回了什么这些在合规场景下是刚需。提示判断要不要上底座有个简单的标准——如果你的系统里 AI 调用点超过 3 个或者模型供应商可能更换或者需要对调用做计量那就该考虑底座了。少于这个规模直接调 API 反而更省事。2.3 微服务架构下AI 底座应该放在哪一层这是架构设计里最容易吵起来的地方。我的实践结论是AI 底座应该是一个独立的微服务集群位于业务服务和外部模型之间而不是塞进网关也不是做成一个 SDK 库。塞进网关的问题是网关通常只做路由和鉴权把提示词渲染、向量检索、Agent 编排这些重逻辑放进去会让网关变得极其臃肿而且网关一般是无状态的AI 会话是有状态的模型不匹配。做成 SDK 库的问题是版本升级要所有业务方跟着升级Java 生态里这种“公共 jar 地狱”大家都懂。独立微服务的好处是可以独立扩缩容AI 调用是 IO 密集型和业务服务的 CPU 密集型特征不同可以独立选型用 JDK 21 的虚拟线程扛高并发可以独立发布提示词改了不用动业务。QuickBlue 的整体架构基本就是这个思路下面细说。3. QuickBlue 的核心模块拆解与技术选型3.1 整体架构网关、编排、模型适配、向量、治理五件套QuickBlue 的架构我画过好几版最终稳定下来的形态大致分五层。最外层是接入网关负责鉴权、限流、协议转换对外暴露 REST 和 SSE流式输出用。第二层是编排引擎处理提示词模板渲染、多轮会话管理、Agent 的工具调用链路。第三层是模型适配层把不同厂商的 API 差异抹平统一成内部协议。第四层是向量与检索层对接向量数据库做 RAG。第五层是治理与观测层埋点、计量、日志、链路追踪。这五层里模型适配层是最需要“设计感”的。因为各家模型的请求体、响应体、流式协议都不一样有的用messages数组有的用prompt字符串有的流式返回是 SSE有的是 WebSocket。适配层的做法是定义一个内部统一的ChatRequest和ChatResponse每个厂商写一个 Adapter 实现新增模型只需要加一个 Adapter不动上层代码。这就是典型的策略模式 适配器模式。3.2 为什么选 JDK 21 和 Spring Cloud Alibaba技术选型这块QuickBlue 用了 JDK 21 加 Spring Cloud Alibaba 的组合我觉得是有讲究的。JDK 21 最大的价值是虚拟线程Virtual Threads。AI 调用是典型的阻塞式 IO 场景——发一个请求出去等模型返回可能等几秒甚至几十秒。传统线程池模式下每个请求占一个平台线程并发一高线程池就爆了。虚拟线程让每个请求的“等待”几乎不占系统资源同样的硬件能扛的并发数提升一个数量级。我实测过一个对比在 4 核 8G 的机器上用传统线程池处理模型调用稳定并发大概在 200 左右就开始排队换成虚拟线程后同样的响应时间下并发能到 1500 以上。这个差距对于 AI 场景是决定性的因为 AI 请求的等待时间远长于普通接口。Spring Cloud Alibaba 这边Nacos 做注册中心和配置中心Sentinel 做限流熔断Seata 处理分布式事务比如扣费和调用要一致。有人会问 Spring Cloud Alibaba 是不是停更了这个说法不准确——核心组件一直在维护只是版本节奏和 Spring 官方不完全同步。对于企业级项目它的成熟度和文档完善度依然是首选。组件选型在 QuickBlue 中的职责注册/配置Nacos服务发现、动态配置提示词和模型参数限流熔断Sentinel按租户/模型维度限流模型故障时降级网关Spring Cloud Gateway统一入口、鉴权、SSE 透传服务调用OpenFeign业务侧调用 AI 服务的声明式客户端链路追踪Micrometer OTel追踪一次 AI 调用的完整链路3.3 模型适配层把“换模型”变成改一行配置模型适配层的核心接口我简化成这样public interface ModelAdapter { String provider(); ChatResponse chat(ChatRequest request); FluxChatChunk stream(ChatRequest request); }每个厂商实现这个接口注册到 Spring 容器里。上层通过provider名字路由。这样业务侧要换模型只需要在 Nacos 配置里把ai.default-provider从qwen改成deepseek重启都不用配置热更新直接生效。这里有个细节值得说流式输出的统一。不同厂商的流式格式差异很大有的按 token 返回有的按句子返回有的会在最后带一个 usage 统计。适配层要做的是把这些差异归一化成统一的ChatChunk包含delta内容、finishReason、usage。业务侧拿到的永远是同一种格式前端 SSE 解析逻辑只写一遍。注意适配层一定要做超时和重试的差异化配置。不同模型的响应时间差异巨大有的 2 秒返回有的要 30 秒。统一超时会导致快的模型被误杀慢的模型还没返回就断了。我的做法是按 provider 配置独立的超时时间重试只对幂等的非流式请求开启。3.4 向量检索与 RAG企业知识库的落地关键企业用 AI很大一部分需求是“基于自己的文档回答问题”也就是 RAG检索增强生成。QuickBlue 的向量层要解决三个问题文档怎么切、向量存哪里、检索怎么召回。文档切分这块我的经验是不要用固定长度硬切。中文文档按 500 字硬切经常把一句话、一个表格切断检索出来的片段语义不完整。更好的做法是按语义边界切——按段落、按标题层级、按 Markdown 结构切再对超长段落做二次切分。切分粒度建议在 300 到 800 字之间太小召回噪声多太大检索精度下降。向量库选型上QuickBlue 支持多种后端常见的是 Milvus、PgVector、Redis Stack。我的建议是数据量在百万级以下直接用 PgVector省一个中间件上了千万级再考虑 Milvus 这类专用向量库。检索策略上纯向量检索在专业术语场景下召回率一般混合检索向量 关键词 BM25效果明显更好再叠加一个重排序模型准确率能再提一截。4. 实操把一个 Spring Cloud 微服务接入 QuickBlue4.1 环境准备与依赖引入假设你有一个现成的 Spring Cloud Alibaba 项目用的是 Nacos 做注册配置。接入 QuickBlue 的第一步是引入客户端依赖。我一般会封装一个 starter业务方只需要加一个依赖、写几行配置。dependency groupIdcom.quickblue/groupId artifactIdquickblue-spring-boot-starter/artifactId version1.0.0/version /dependency配置项放在 Nacos 的quickblue-client.yaml里quickblue: endpoint: http://quickblue-gateway:8080 app-id: order-service tenant: retail-biz default-provider: qwen timeout: 30s stream-timeout: 120s这里app-id和tenant很关键它们是限流和计费的维度。app-id标识调用方tenant标识租户底座按这两个维度做配额分配和用量统计。stream-timeout单独配置是因为流式请求的总时长可能很长不能和普通请求用同一个超时。4.2 业务侧调用三行代码接上对话能力接入之后业务代码里调用 AI 就变得非常简单。starter 会自动注入一个QuickBlueClientAutowired private QuickBlueClient aiClient; public String summarizeOrder(String orderJson) { ChatRequest request ChatRequest.builder() .templateId(order-summary) .variable(order, orderJson) .build(); return aiClient.chat(request).getContent(); }注意这里用的是templateId而不是直接写提示词。提示词模板统一在底座管理业务侧只传变量。这样做的好处是运营改提示词不用发版A/B 测试可以按模板维度做提示词版本可以回溯。我见过太多团队把提示词写死在代码里改一个标点都要走一次发布流程效率极低。流式调用也很简单返回一个FluxGetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString streamChat(RequestParam String question) { return aiClient.stream(ChatRequest.builder() .templateId(qa) .variable(question, question) .build()) .map(ChatChunk::getDelta); }4.3 提示词模板管理让运营也能改 AI 行为提示词模板是底座里我最看重的模块之一。它的数据结构大概是模板 ID、模板内容带占位符、变量定义、默认模型、温度等参数、版本号。模板内容用类似{{variable}}的占位符语法渲染时替换。一个订单摘要的模板长这样你是一个电商订单分析助手。请根据以下订单信息用不超过 100 字总结订单的核心内容 包括商品、金额、用户诉求。订单信息{{order}}运营在管理后台改这段文字保存后 Nacos 配置推送底座热更新业务侧无感知。版本管理上每次保存生成一个新版本可以一键回滚。这个功能在真实项目里救过我好几次——有一次运营把提示词改坏了导致摘要全是乱码回滚到上一版本 30 秒解决。提示模板变量一定要做类型校验和转义。用户输入的内容如果直接拼进提示词可能造成提示词注入。我的做法是对变量做长度限制和特殊字符过滤敏感场景下用结构化格式如 JSON传参而不是纯文本拼接。4.4 计量与限流把成本管起来AI 调用是要花钱的而且花得很快。没有计量月底账单出来你会吓一跳。QuickBlue 的计量模块在每次调用后记录租户、应用、模型、输入 token 数、输出 token 数、耗时、是否命中缓存。这些数据落到时序库可以按天、按租户、按模型出报表。限流用 Sentinel 实现规则可以动态配置。我通常配三层全局层限制整个底座的总 QPS防止打爆下游模型租户层限制单个租户的配额防止一个租户影响其他人模型层限制单个模型的并发因为不同模型的承载能力不同。降级策略上模型不可用时返回缓存结果或者兜底话术而不是直接报错。// Sentinel 资源定义按租户维度限流 SentinelResource(value ai-chat, blockHandler handleBlock) public ChatResponse chat(ChatRequest request) { // ... } public ChatResponse handleBlock(ChatRequest request, BlockException ex) { return ChatResponse.fallback(当前请求较多请稍后再试); }5. 踩坑实录那些文档里不会写的问题5.1 流式输出在网关被缓冲这个问题我卡了整整一天。前端明明用的是 SSE但内容总是一次性出来没有逐字效果。排查后发现是 Spring Cloud Gateway 默认会对响应做缓冲。解决办法是在网关配置里对 SSE 路径关闭缓冲并且设置Cache-Control: no-cache。如果你用的是 Nginx 做前置还要在 Nginx 里关掉proxy_buffering。这个坑几乎每个做流式的团队都会踩一次。5.2 虚拟线程下的 ThreadLocal 陷阱JDK 21 虚拟线程很好用但有个坑虚拟线程会频繁创建销毁ThreadLocal里的数据可能不会按你预期的方式传递。我在做链路追踪时把 traceId 放在ThreadLocal里结果异步切换后丢了。正确做法是用ScopedValueJDK 21 预览特性或者显式传递上下文别依赖ThreadLocal。如果非要用记得用InheritableThreadLocal并测试清楚。5.3 向量检索的“看起来对但实际错”RAG 最迷惑人的地方是检索出来的片段看起来相关但模型回答还是错的。原因通常是召回片段和问题不在同一个语义空间。比如用户问“退款政策”文档里写的是“退货规则”纯向量检索可能召不回。解决办法是混合检索加同义词扩展把“退款”“退货”“退单”这类词做成同义词表检索时扩展查询。另外重排序模型Rerank对最终效果提升非常明显值得加。5.4 常见问题速查表现象可能原因排查方向流式无逐字效果网关/Nginx 缓冲关闭 proxy_buffering检查 SSE 配置调用超时频繁超时配置过短按 provider 分别配置超时token 消耗异常高提示词过长或缓存未命中检查模板长度开启语义缓存限流误伤配额维度不合理检查租户/应用维度配置检索结果不相关切分粒度或检索策略问题调整切分启用混合检索重排配置改了不生效Nacos 监听未刷新检查 RefreshScope 和监听配置5.5 几个我总结的实操心得第一先做计量再做优化。没有数据支撑的优化都是瞎猜先把每次调用的 token、耗时、命中率记下来你才知道瓶颈在哪。第二提示词要像代码一样管理有版本、有评审、有回滚别让运营在后台随便改生产环境的提示词。第三缓存是省钱利器语义缓存对客服、问答这类重复率高的场景命中率能到 30% 以上直接省下三成成本。第四别一上来就上 Agent很多需求用一次 RAG 加一次模型调用就能解决Agent 的复杂度和不确定性高得多等基础能力跑顺了再考虑。6. 底座之后AI 能力和微服务体系的融合走向把 AI 底座跑起来之后我观察到一些有意思的演进。最开始业务侧只是把底座当成一个“模型调用代理”后来慢慢开始把 AI 能力当成一种普通的微服务能力来编排。比如订单服务在创建订单后异步调用 AI 服务生成摘要再通过消息队列通知下游这跟调用一个普通的库存服务没有本质区别。再往后一些团队开始做AI 能力的服务化拆分。把“摘要”“分类”“抽取”“问答”拆成独立的 AI 微服务各自有独立的模型、提示词、扩缩容策略。这其实就是微服务拆分思路在 AI 领域的自然延伸——按业务能力拆分而不是按技术分层拆分。QuickBlue 这类底座提供的统一协议和治理能力让这种拆分变得可行否则每个 AI 服务都要自己处理模型适配和限流重复劳动太多。Python 生态的融入也是个现实问题。很多 AI 相关的库和框架是 Python 的但企业主系统是 Java。我的做法是让 Python 服务也注册到 Nacos通过统一的 HTTP 协议和 Java 服务互通底座对两边一视同仁。这样既用上了 Python 的生态又不破坏现有的微服务体系。关键是协议要统一别让 Java 调 Python 用一套协议Python 调 Java 又用另一套。最后分享一个我在实际项目里的体会AI 底座的价值不在于它接了多少个模型而在于它让业务团队不用关心接了多少个模型。当业务方写代码时脑子里想的是“我要一个摘要能力”而不是“我要调哪个模型的哪个接口”这个底座就算成功了。技术选型、架构分层、治理策略最终都是为这个目标服务的。