1. 从一堆零散服务到统一底座QuickBlue 到底想解决什么问题第一次听到“QuickBlue”这个名字很多人会以为是某个新出的前端框架或者低代码工具。实际上它瞄准的是一个更底层、也更让企业技术团队头疼的问题当公司内部同时跑着十几个甚至几十个 AI 应用时这些应用背后的模型调用、向量检索、提示词管理、权限控制、日志追踪、计费统计到底该由谁来统一管。我见过太多团队在 AI 项目上的真实状态算法组用 Python 写了一套 RAG 服务工程组用 Spring Cloud 搭了一套业务中台前端组又单独维护一个 Node 层的 BFF。每个团队都能把自己的部分跑通但一旦要把这些能力串成一条完整的业务链路问题就全冒出来了。模型密钥散落在各个配置文件里调用量统计口径不一致某个服务挂了要排查半天才发现是向量库连接池被打满。QuickBlue 要做的就是把这些重复建设、重复踩坑的部分抽出来形成一个“AI 应用底座”。所谓“AI 应用底座”你可以把它理解成盖楼时的地基和承重结构。上面每一层住户可以按自己的喜好装修但水电、燃气、消防、电梯这些公共设施必须统一规划。QuickBlue 提供的正是这类公共设施统一的模型接入层、统一的向量存储抽象、统一的提示词版本管理、统一的调用链追踪、统一的配额与计费。业务团队只需要关心自己的业务逻辑不用再为“怎么安全地存 API Key”或者“怎么统计每个部门的 Token 消耗”这种问题反复造轮子。这个底座特别适合三类团队参考。第一类是正在从单点 AI 试验走向多应用矩阵的中型公司他们已经有了一些跑通的原型但缺乏统一治理。第二类是传统行业的技术部门想引入 AI 能力但又不想把原有 Spring Cloud 体系推倒重来。第三类是平台型团队需要给内部多个业务线提供 AI 能力输出同时要能算清楚账。如果你正好处在这些场景里QuickBlue 的设计思路值得仔细拆一拆。2. 为什么不是直接堆框架AI 应用底座的选型逻辑2.1 微服务架构在 AI 场景下的特殊挑战传统微服务架构解决的是业务逻辑的拆分与治理问题比如订单服务、用户服务、库存服务之间的调用。但 AI 应用引入了一类全新的依赖模型推理。模型推理有几个很麻烦的特性。第一是延迟波动大同样一个请求可能 200 毫秒返回也可能因为排队跑到 10 秒以上。第二是成本不透明一次调用消耗多少 Token、折合多少钱如果不做专门统计月底账单出来就是一笔糊涂账。第三是版本迭代快今天用这个模型明天可能就要切到另一个提示词更是三天两头在改。如果直接把模型调用塞进现有的业务微服务里会出现什么情况订单服务里混着模型调用的重试逻辑用户服务里存着模型密钥每个服务都要自己实现一套限流和降级。这显然不可持续。QuickBlue 的思路是把 AI 能力单独抽成一层用独立的微服务集群来承载业务服务通过标准接口来调用。这样一来模型切换、提示词调整、配额变更都不会影响业务服务的稳定性。2.2 为什么选择 Spring Cloud 而不是其他方案热词里有人问“spring cloud alibaba 停更了”也有人搜“python 应用融入 spring cloud alibaba 微服务体系”。这说明很多团队正面临一个现实问题已有的 Java 微服务体系怎么和 Python 的 AI 生态对接。QuickBlue 选择 Spring Cloud 作为底座我认为核心原因有三个。第一是存量系统的兼容性。国内大量企业的核心业务系统跑在 Java 技术栈上Spring Cloud 的注册中心、配置中心、网关、熔断组件已经非常成熟。如果 AI 底座另起炉灶用一套完全不同的服务发现机制运维成本会成倍增加。第二是 JDK 21 带来的新可能。虚拟线程在 JDK 21 里正式转正这对 AI 场景下大量阻塞式 IO 调用非常友好。以前一个模型调用占一个平台线程并发一高线程池就爆了现在用虚拟线程可以用更少的资源扛住更高的并发。第三是生态整合的便利性。Spring Cloud Gateway 做统一入口Spring Cloud LoadBalancer 做模型服务的负载均衡Micrometer 做指标采集这些组件和现有监控体系是无缝衔接的。2.3 底座与业务应用的边界怎么划这是实际落地时最容易扯皮的地方。我的经验是底座只做“所有 AI 应用都会用到且必须统一”的事情业务特有的逻辑一律不下沉。具体来说模型接入、密钥管理、调用审计、配额控制、向量库连接、提示词模板存储这些放到底座。而具体的业务 Prompt 内容、业务侧的 RAG 策略、业务数据的预处理这些留在业务应用里。注意边界划不清的典型症状是底座越来越臃肿最后变成一个什么都管但什么都管不好的“大泥球”。判断标准很简单如果某个功能只有一两个应用会用那它就不该进底座。3. 核心模块拆解QuickBlue 底座里到底装了什么3.1 统一模型网关让模型切换不再改代码模型网关是整个底座最核心的模块。它的职责是屏蔽不同模型提供方的接口差异对上提供统一的调用协议。比如业务侧统一用/v1/chat/completions这样的接口网关内部根据配置路由到不同的模型后端。这样做的好处是当你要从 A 模型切换到 B 模型时业务代码一行都不用改只需要在配置中心调整路由规则。网关内部需要处理几个关键问题。第一是协议转换不同模型的请求体和响应体格式有差异网关要做归一化。第二是流式输出的统一处理SSE 格式在各家实现里细节不同网关要保证业务侧拿到一致的流式体验。第三是失败重试与降级当主模型超时或返回错误时网关可以按策略切换到备用模型。这里有个实操细节重试不能无脑重试对于已经产生部分输出的流式请求重试会导致内容重复需要根据请求类型做区分。# 模型路由配置示例 routes: - id: default-chat uri: lb://model-provider-a predicates: - Path/v1/chat/completions filters: - name: ModelRouting args: primary: provider-a fallback: provider-b timeout: 300003.2 向量存储抽象层一次接入多种后端可选RAG 应用离不开向量数据库。但向量数据库的选型变化很快今天用这个明天可能因为性能或成本原因要换。如果业务代码直接依赖某个特定向量库的 SDK迁移成本会非常高。QuickBlue 在底座里做了一层向量存储抽象定义统一的 Collection 管理、向量写入、相似度查询接口底层可以适配多种向量库实现。这层的设计难点在于不同向量库的能力差异很大。有的支持元数据过滤有的不支持有的支持混合检索有的只支持纯向量检索。抽象层不能只做最小公约数否则会丢失高级特性。我的做法是定义一套基础接口保证通用性同时允许业务侧通过“能力探测”接口查询当前后端支持哪些高级特性再决定是否使用。这样既保证了可移植性又不牺牲性能。3.3 提示词版本管理把 Prompt 当代码来管提示词管理是很多团队早期最容易忽视的部分。一开始大家把 Prompt 硬编码在代码里改一次就要发一次版。后来有人把它抽到配置文件但很快配置文件也失控了没人知道线上跑的是哪个版本。QuickBlue 把提示词当作一种特殊的“配置资产”来管理支持版本记录、灰度发布、回滚、变量注入。具体来说每个提示词模板有唯一的标识和版本号业务侧调用时指定模板 ID 和变量值底座负责渲染出最终 Prompt。灰度发布时可以按流量比例或用户标签把请求路由到不同版本的模板。这样做的好处是当新版本 Prompt 效果变差时可以快速回滚到上一个稳定版本而不需要重新部署应用。3.4 调用审计与配额算清楚每一笔账AI 应用的调用成本如果不做精细化管理很容易失控。QuickBlue 在底座层面记录每一次模型调用的详细信息调用方、模型、输入输出 Token 数、耗时、是否命中缓存、预估费用。这些数据一方面用于计费分摊另一方面也是容量规划和性能优化的依据。配额控制需要支持多个维度按应用、按部门、按用户、按时间窗口。实现上可以用令牌桶算法做限流同时结合 Redis 做分布式计数。这里有个坑要注意Token 计数不能只依赖模型返回的 usage 字段有些模型在流式模式下不返回准确的 usage需要在网关侧做估算。估算算法要尽量贴近实际计费口径否则会出现配额和账单对不上的情况。4. 实操落地从零搭建一个最小可用的 AI 应用底座4.1 环境准备与基础依赖先明确技术栈版本。JDK 21 是必须的虚拟线程和新的 GC 特性对 AI 场景帮助很大。Spring Boot 用 3.2 以上版本Spring Cloud 用 2023.0.x 系列。注册中心可以用 Nacos 或 Consul配置中心建议和注册中心统一减少运维组件。网关用 Spring Cloud Gateway注意要基于 WebFlux 而不是 Servlet 栈否则流式转发会有问题。数据库方面元数据存储用 PostgreSQL 或 MySQL 都可以向量存储根据实际需求选型。如果只是做原型验证PgVector 是个不错的选择省去了单独维护向量库的麻烦。缓存和分布式计数用 Redis建议用 Redis 7 以上版本对 Stream 和 Function 的支持更完善。# 基础环境检查 java -version # 应输出 openjdk version 21.x.x docker run -d --name quickblue-redis -p 6379:6379 redis:7-alpine docker run -d --name quickblue-pg -p 5432:5432 -e POSTGRES_PASSWORDquickblue postgres:16-alpine4.2 模型网关服务的搭建步骤第一步创建 Spring Boot 项目引入 Spring Cloud Gateway、Spring Cloud LoadBalancer、Nacos Discovery 依赖。第二步配置路由规则把/v1/**的请求转发到模型服务集群。第三步实现自定义的 GlobalFilter在请求转发前做鉴权、配额检查、请求日志记录在响应返回后做 Token 统计和费用计算。这里重点说一下流式响应的处理。Spring Cloud Gateway 默认会把响应体缓存起来再转发这对 SSE 是致命的。需要配置spring.cloud.gateway.httpclient.response-timeout并确保使用FluxDataBuffer做零拷贝转发。我踩过的坑是如果中间加了自定义的响应包装 Filter很容易破坏流式语义导致客户端收到的是完整响应而不是逐字输出。// 流式转发关键配置 Bean public RouteLocator customRouteLocator(RouteLocatorBuilder builder) { return builder.routes() .route(model-stream, r - r .path(/v1/chat/stream) .filters(f - f .filter(new QuotaCheckFilter()) .filter(new TokenCountFilter())) .uri(lb://model-provider)) .build(); }4.3 向量存储抽象层的实现要点定义VectorStore接口包含createCollection、upsert、search、delete等方法。然后为每种向量库写适配器实现。以 PgVector 为例需要处理向量维度的动态配置因为不同 Embedding 模型输出的维度不同。建表时用vector(dim)类型查询时用操作符计算余弦距离。一个容易被忽视的点是索引策略。PgVector 支持 IVFFlat 和 HNSW 两种索引IVFFlat 建索引快但查询精度略低HNSW 查询快但建索引慢且内存占用高。实际选型时如果数据量在百万级以下HNSW 的综合表现更好。另外要注意向量检索的limit参数不要设得太大一般取 TopK 的 3 到 5 倍即可后面再用重排序模型做精排。4.4 提示词管理与灰度发布配置提示词模板用 JSON 或 YAML 存储包含模板内容、变量定义、版本号、创建时间、状态等字段。渲染引擎可以用 Handlebars 或 Mustache注意做好变量转义防止 Prompt 注入。灰度发布通过配置中心下发规则比如templateId: order-assistant, grayRatio: 0.1, grayVersion: v2网关在渲染时根据规则决定用哪个版本。提示提示词版本回滚一定要做成一键操作并且回滚后要能立即生效。我见过因为回滚流程太复杂导致线上问题持续了半小时才恢复的案例。5. 踩坑记录与常见问题排查5.1 模型调用超时与重试的坑最常见的问题是超时设置不合理。模型推理的延迟分布是长尾的P99 可能是 P50 的十倍以上。如果超时设得太短大量正常请求会被误杀设得太长故障时资源会被长时间占用。我的经验是先跑一周的监控数据看 P99 和 P999 的分布超时时间设在 P999 的 1.5 倍左右。重试策略要区分错误类型连接超时可以重试但模型已经返回部分内容后的超时不应该重试。5.2 向量检索结果不稳定的排查思路有时候同样的查询两次返回的结果差异很大。排查顺序是这样的先确认 Embedding 模型是否一致不同模型或不同版本的 Embedding 结果不可比。再检查向量归一化是否统一有的库要求输入向量必须归一化有的会自动处理。然后看索引是否在写入后及时刷新PgVector 的 HNSW 索引在大量写入后可能需要手动 REINDEX。最后检查查询时的距离度量方式是否和建索引时一致余弦距离和欧氏距离混用会导致结果完全错乱。5.3 配额统计与实际账单对不上的原因这个问题通常有三个来源。第一是流式请求的 Token 估算偏差特别是输出 Token 的估算不同模型的分词方式不同估算误差可能到 10% 以上。第二是缓存命中的请求是否计入配额如果计入了但实际没有产生模型调用就会虚高。第三是并发场景下的计数丢失用 Redis 的 INCR 做计数时如果网络抖动导致命令失败需要有补偿机制。建议每天做一次对账任务把底座统计数据和模型提供方的账单做比对偏差超过 5% 就要排查。问题现象可能原因排查方法解决措施流式输出中断网关缓冲区配置不当检查 response-timeout 和缓冲区大小关闭响应缓存增大超时向量检索结果漂移索引未刷新或度量不一致对比建索引和查询的距离参数统一度量方式定期 REINDEX配额消耗异常快缓存未生效或重试过多查看缓存命中率和重试次数优化缓存策略限制重试次数模型切换后效果下降提示词未适配新模型对比新旧模型的输出差异针对新模型调整提示词模板5.4 微服务拆分粒度的经验之谈底座内部的微服务拆分不要照搬业务微服务的拆法。模型网关、向量服务、提示词服务、审计服务这四个是核心边界。不要再往下拆了比如把鉴权单独拆一个服务只会增加调用链长度和故障点。我试过把 Token 计数拆成独立服务结果每次调用都要多一次网络往返延迟增加了 15 毫秒得不偿失。底座的拆分原则是能合并的尽量合并除非有独立的扩缩容需求或技术栈差异。6. 这套底座后续还能怎么扩展QuickBlue 目前覆盖的是模型接入、向量存储、提示词管理、审计配额这几个核心能力。但 AI 应用底座的外延还可以继续扩展。比如加入 Agent 编排能力让业务侧可以通过配置的方式定义多步推理流程而不是硬编码在代码里。再比如加入评测模块对提示词版本和模型切换做 A/B 测试用数据驱动决策而不是凭感觉。另一个方向是和现有的 DevOps 体系打通。把提示词变更纳入 CI/CD 流程每次修改都走代码评审和自动化测试。模型切换也做成发布单记录变更原因和影响范围。这样做的好处是AI 应用的变更和传统应用的变更一样可追溯、可回滚减少“谁改了 Prompt 导致线上效果变差”这类扯皮。我个人在实际操作中的体会是底座的价值不在于功能多全而在于边界清晰、接口稳定。只要业务侧调用底座的方式足够简单一致底座内部怎么迭代都不会影响上层。反过来如果底座接口三天两头变业务团队就会绕过底座自己搞一套底座也就名存实亡了。所以前期设计时宁可少做几个功能也要把核心接口的稳定性放在第一位。