企业官网建设流程全解析

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 官方不完全同步。对于企业级项目，它的成熟度和文档完善度依然是首选。

3.3 模型适配层：把“换模型”变成改一行配置

模型适配层的核心接口我简化成这样：

public interface ModelAdapter { String provider(); ChatResponse chat(ChatRequest request); Flux<ChatChunk> 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 微服务接入 QuickBlue

4.1 环境准备与依赖引入

假设你有一个现成的 Spring Cloud Alibaba 项目，用的是 Nacos 做注册配置。接入 QuickBlue 的第一步是引入客户端依赖。我一般会封装一个 starter，业务方只需要加一个依赖、写几行配置。

<dependency> <groupId>com.quickblue</groupId> <artifactId>quickblue-spring-boot-starter</artifactId> <version>1.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 会自动注入一个QuickBlueClient：

@Autowired 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 测试可以按模板维度做，提示词版本可以回溯。我见过太多团队把提示词写死在代码里，改一个标点都要走一次发布流程，效率极低。

流式调用也很简单，返回一个Flux：

@GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> 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里，结果异步切换后丢了。正确做法是用ScopedValue（JDK 21 预览特性）或者显式传递上下文，别依赖ThreadLocal。如果非要用，记得用InheritableThreadLocal并测试清楚。

5.3 向量检索的“看起来对但实际错”

RAG 最迷惑人的地方是：检索出来的片段看起来相关，但模型回答还是错的。原因通常是召回片段和问题不在同一个语义空间。比如用户问“退款政策”，文档里写的是“退货规则”，纯向量检索可能召不回。解决办法是混合检索加同义词扩展，把“退款”“退货”“退单”这类词做成同义词表，检索时扩展查询。另外，重排序模型（Rerank）对最终效果提升非常明显，值得加。

5.4 常见问题速查表

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 底座的价值不在于它接了多少个模型，而在于它让业务团队不用关心接了多少个模型。当业务方写代码时脑子里想的是“我要一个摘要能力”，而不是“我要调哪个模型的哪个接口”，这个底座就算成功了。技术选型、架构分层、治理策略，最终都是为这个目标服务的。