1. 从一堆重复造轮子的项目说起如果你带过几个企业级 AI 项目大概率见过这样的场景第一个项目用 Flask 搭了个问答接口第二个项目换成 FastAPI 重写一遍鉴权第三个项目又用 Spring Boot 把知识库检索逻辑重新实现一次。每个项目单看都能跑但把三个放在一起你会发现登录模块写了三套、日志格式三种、模型调用封装三种、权限校验逻辑三种。团队里每个人都在做 AI 应用但没有人真正在做 AI 应用的公共部分。QuickBlue 要解决的就是这个问题。它本质上是一个AI 应用底座——你可以把它理解成专门为 AI 类应用定制的一层地基把模型接入、会话管理、知识库检索、权限体系、前端交互这些每个 AI 项目都要做一遍的事情收敛成一套可复用的基础能力。业务团队只需要在这层地基上写自己的业务逻辑不用再关心怎么把大模型接进来怎么管理多轮对话上下文怎么做流式输出这些重复劳动。这篇文章适合三类人看正在做企业级 AI 应用、被重复建设折磨的架构师想了解 AI 应用底座到底包含哪些能力的技术负责人以及准备选型或自建类似平台的开发者。我会从设计思路、核心模块、实操落地、踩坑经验几个角度把 QuickBlue 这类底座的价值和实现细节讲透涉及 JDK 21、Spring Cloud 2025、Vite 8 这些技术选型的地方也会说明为什么这么选。2. AI 应用底座到底解决什么问题2.1 企业做 AI 应用的三个典型困境先说清楚为什么需要底座这件事不然很容易被当成又一个中台概念。困境一模型接入的碎片化。一家中型企业往往同时对接多个模型服务——有的场景用通用大模型做对话有的场景用嵌入模型做向量检索有的场景用专门的 OCR 或语音模型。每个模型服务的 SDK、鉴权方式、超时策略、重试逻辑都不一样。如果没有统一封装业务代码里会散落大量if model A else ...的判断换一个模型就要改一片代码。困境二AI 应用的非功能性需求高度相似。会话上下文怎么存、流式响应怎么推、Token 怎么计费统计、敏感词怎么过滤、并发怎么限流、失败怎么降级——这些和具体业务无关但每个 AI 应用都躲不掉。重复实现不仅浪费人力更麻烦的是质量参差不齐A 项目做了限流 B 项目没做线上就出问题。困境三前后端协作模式变了。传统 CRUD 应用是请求-响应一次完成AI 应用大量使用 SSE 流式输出、长连接、异步任务。前端要处理打字机效果、中断重试、多轮上下文展示后端要处理流式分片、背压、连接保活。这套协作模式如果没有统一约定前后端联调会非常痛苦。QuickBlue 这类底座的价值就是把上面三件事标准化。它不是业务框架而是能力框架——提供的是做 AI 应用必需但不属于业务的那部分。2.2 底座和应用的分界线在哪这里有个容易混淆的点底座该做多少业务该做多少我的经验是划三条线。第一条线与具体业务语义无关的能力放底座。比如调用大模型并返回流式结果是底座能力根据用户问题检索订单数据是业务能力。第二条线跨项目复用的放底座。如果三个项目都要做会话管理那它就该进底座如果只有一个项目需要发票识别那它留在业务层。第三条线变化频率低的放底座。模型接入协议、鉴权规范这些相对稳定而具体的 Prompt 模板、业务规则变化频繁应该留在业务层可配置。提示底座设计最容易犯的错是什么都想收进来结果底座变成一个大泥球业务想改点东西要动底座底座一改所有业务都要回归测试。克制是底座设计的第一原则。2.3 为什么是底座而不是平台有人会问这和 AI 中台、AI 平台有什么区别我的理解是平台通常带管控属性强调统一入口、统一治理、统一运营底座更偏技术属性强调提供能力、屏蔽复杂度、支撑上层自由发挥。QuickBlue 定位在底座意味着它不强制所有 AI 应用走同一个入口而是提供一套 SDK 和运行时让各业务团队按自己的节奏接入。这个定位差异直接决定了它的技术选型要偏向轻量、可嵌入、低侵入。3. QuickBlue 的核心模块拆解3.1 模型接入层统一抽象与多路适配模型接入层是整个底座的地基。QuickBlue 的做法是定义一套统一的模型调用抽象把不同模型服务的差异屏蔽在适配器里。核心抽象大概是这样几个概念ModelProvider表示一个模型提供方ChatModel、EmbeddingModel、RerankModel表示不同能力类型的模型ModelRequest和ModelResponse是统一的请求响应结构。业务代码只依赖这些抽象不直接依赖任何具体厂商的 SDK。public interface ChatModel { ChatResponse call(ChatRequest request); FluxChatChunk stream(ChatRequest request); }为什么用Flux而不是普通的Stream因为流式场景下需要处理背压、取消、超时Reactor 的响应式模型天然支持这些。这也是选 JDK 21 的原因之一——虚拟线程配合响应式编程在高并发流式场景下资源利用率明显更好。适配器层要处理几个关键差异不同厂商的流式分片格式不同有的按字符、有的按 token、有的按句子结束标志不同有的发[DONE]有的发特定事件错误码体系不同。这些都在适配器里归一化业务层拿到的永远是统一的ChatChunk流。3.2 会话与上下文管理不只是存个历史会话管理看起来简单实际是 AI 应用里最容易出问题的地方。QuickBlue 的会话模块要解决四件事。上下文窗口管理。大模型有 Token 上限多轮对话累积到一定程度必须裁剪。裁剪策略有几种按轮次保留最近 N 轮、按 Token 数动态裁剪、对早期对话做摘要压缩。QuickBlue 把这几种策略做成可插拔的ContextTrimmer业务可以按场景选。会话状态持久化。会话不能只放内存否则服务重启就丢。QuickBlue 默认用 Redis 存热会话用关系库存冷会话通过一个SessionStore接口统一访问。这里有个细节流式响应过程中会话状态是不断变化的如果每来一个分片就写一次库压力会很大。实际做法是流式过程中只在内存维护流结束后一次性落库。多会话隔离。同一个用户可能同时开多个会话会话之间上下文不能串。这要求会话 ID 的生成和传递有严格规范QuickBlue 用userId sessionId做二级隔离。会话生命周期。会话要有过期策略不然存储会无限膨胀。默认配置是热会话 2 小时过期冷会话 30 天归档。3.3 知识库与检索增强RAG 的工程化封装RAG检索增强生成是当前企业 AI 应用最主流的形态QuickBlue 把它封装成一条标准流水线文档解析 → 分块 → 向量化 → 存储 → 检索 → 重排 → 拼装 Prompt。这条流水线里分块策略是最影响效果的环节。固定长度分块简单但会切断语义按段落分块保留语义但长度不均。QuickBlue 默认用语义分块 重叠窗口先按段落和标题切再对超长段落按句子边界切相邻块之间保留 10% 到 20% 的重叠避免关键信息正好落在切分点上。检索环节支持向量检索和关键词检索的混合模式。纯向量检索对语义相似但字面不同的查询效果好但对精确匹配比如产品型号、专有名词容易漏。混合检索用加权融合两路结果实测召回率比单路高不少。重排环节是可选的但对精度要求高的场景很关键。向量检索返回的 Top-K 里真正相关的可能排在第 5 到第 10 位重排模型能把这些提上来。QuickBlue 把重排做成独立阶段业务可以按需开启。3.4 权限与多租户企业场景的硬需求个人项目可以不管权限企业项目不行。QuickBlue 的权限模块要处理几个层次。租户隔离是最高层。不同租户的数据、模型配置、知识库完全隔离一个租户的会话不能查到另一个租户的。实现上通过租户 ID 贯穿所有数据访问在数据层做强制过滤。用户权限是中间层。同一个租户内不同用户能访问的知识库、能调用的模型可能不同。这层用 RBAC 模型角色绑定权限用户绑定角色。数据权限是最细层。同一条知识不同用户可见范围可能不同。这层用标签过滤检索时带上用户的可见标签做过滤。注意权限过滤一定要在检索阶段做不能等检索完再过滤。否则用户可能通过检索结果条数变化推断出自己无权访问的内容存在这是信息泄露。3.5 前端交互层Vite 8 带来的开发体验QuickBlue 的前端部分基于 Vite 8 构建。选 Vite 8 主要看中两点一是构建速度大型 AI 应用前端模块多传统打包工具冷启动要几十秒Vite 的按需编译能压到秒级二是对现代浏览器特性的支持更激进比如原生 ESM、Top-level await写流式交互代码更顺手。前端层封装了几个 AI 应用特有的组件流式消息展示组件处理打字机效果、Markdown 渲染、代码高亮、会话列表组件、知识库引用展示组件把 RAG 检索到的原文片段以引用形式展示。这些组件在多个项目里复用省去重复开发。4. 技术选型背后的取舍逻辑4.1 为什么是 JDK 21JDK 21 是 LTS 版本虚拟线程正式转正。对 AI 应用来说虚拟线程的价值在于大量阻塞式 IO 场景。AI 应用经常要同时调用多个外部服务——模型服务、向量库、关系库、缓存每个调用都是 IO 等待。传统线程池模式下线程数受限于池大小高并发时请求排队。虚拟线程让每个请求可以独占一个轻量线程阻塞时自动让出载体线程吞吐量提升明显。实测数据在 500 并发流式请求场景下传统线程池配置 200 线程时平均响应延迟 800ms虚拟线程模式下延迟降到 300ms 左右。当然这个数据依赖具体场景但趋势是明确的。另一个原因是 JDK 21 的模式匹配、记录类、密封类这些特性让模型抽象层的代码更简洁。比如用密封接口定义模型响应类型编译器能帮你检查所有分支是否处理完整。4.2 Spring Cloud 2025 的定位Spring Cloud 2025 对应 Spring Boot 3.5 和 Spring Framework 6.2是当前企业 Java 生态最稳的组合。QuickBlue 用它主要做三件事服务注册发现、配置中心、网关路由。有人会问AI 应用需要微服务吗我的看法是看规模。小团队单体足够但企业级底座往往要支撑多个业务团队服务化能带来独立部署、独立扩缩容的好处。比如模型接入服务压力大可以单独扩容知识库服务内存占用高可以单独调优。Spring Cloud 2025 相比早期版本对响应式编程的支持更成熟和 Reactor 配合处理流式场景更顺。网关层支持 SSE 长连接透传这是 AI 应用的关键需求。4.3 Vite 8 与前端工程化Vite 8 的核心变化是更彻底的 ESM 优先和更快的 HMR。对 AI 应用前端来说流式交互的调试很频繁改一行代码要等几秒编译会严重影响效率。Vite 8 的 HMR 基本做到毫秒级改完即见。另一个考虑是构建产物体积。AI 应用前端往往要引入 Markdown 渲染、代码高亮、图表等重依赖Vite 的 tree-shaking 和代码分割能有效控制首屏体积。配合动态 import把知识库管理、模型配置这些低频页面拆成独立 chunk首屏只加载对话界面。4.4 选型对比表维度传统方案QuickBlue 方案取舍理由运行时JDK 8/11 线程池JDK 21 虚拟线程高并发流式场景吞吐更好框架Spring Boot 2.xSpring Cloud 2025响应式支持成熟生态稳定前端构建WebpackVite 8冷启动和 HMR 快一个量级模型接入各项目自行封装统一抽象 适配器换模型不改业务代码会话存储内存或单库Redis 关系库分层兼顾性能和持久化5. 从零搭建一个最小可用底座5.1 环境准备与依赖清单先把环境列清楚避免版本踩坑。JDK 21推荐 Temurin 或 Oracle 官方版注意要 21.0.2 以上早期版本虚拟线程有 bugMaven 3.9 或 Gradle 8.5Spring Boot 3.5.x、Spring Cloud 2025.0.xRedis 7.x会话存储PostgreSQL 16 或 MySQL 8持久化Node.js 20、pnpm 9前端Vite 8依赖管理上Spring Cloud 2025 有对应的 BOM直接 import 避免版本冲突。模型 SDK 建议用官方提供的不要用第三方封装出问题不好排查。5.2 模型接入层的实现步骤第一步定义统一抽象。前面提过的ChatModel、EmbeddingModel接口先定下来这是所有适配器的契约。第二步实现至少一个适配器。建议先接一个通用大模型服务把call和stream两个方法跑通。流式方法要注意处理分片边界——有的服务会把一个 token 拆成多个分片发过来适配器要做缓冲合并。第三步加一层ModelRouter。业务调用时不直接依赖具体模型而是通过路由根据场景选择模型。路由规则可以配置化比如对话场景用模型 A摘要场景用模型 B。第四步加熔断和降级。模型服务不稳定是常态用 Resilience4j 做熔断失败时降级到备用模型或返回缓存结果。Service public class DefaultModelRouter implements ModelRouter { private final MapString, ChatModel models; private final CircuitBreaker circuitBreaker; Override public FluxChatChunk stream(String scene, ChatRequest request) { ChatModel model selectModel(scene); return circuitBreaker.executeFluxSupplier( () - model.stream(request), throwable - fallbackStream(request) ); } }5.3 会话管理的落地细节会话表设计建议包含这些字段session_id、user_id、tenant_id、title、created_at、updated_at、status、metadata。metadata用 JSON 存扩展信息比如关联的知识库 ID、使用的模型等。上下文裁剪的实现我推荐用滑动窗口 摘要组合。最近 N 轮完整保留更早的对话用一个小模型做摘要把摘要作为系统消息拼在 Prompt 前面。这样既控制了 Token 数又不完全丢失早期信息。流式落库的时机很关键。我的做法是流式过程中每收到一个分片更新内存中的会话对象流结束时把完整回复一次性写入。如果流中途断开把已生成的部分标记为未完成也落库避免用户刷新后内容丢失。5.4 知识库流水线的配置文档解析阶段要支持 PDF、Word、Markdown、HTML 等常见格式。PDF 解析是难点扫描版 PDF 需要 OCR文本版 PDF 要注意表格和分栏的处理。建议用成熟的开源库不要自己写解析器。分块参数建议块大小 500 到 800 字符重叠 100 到 150 字符。这个范围是实测下来对中文文档比较友好的区间。太小会丢上下文太大检索精度下降。向量化阶段嵌入模型的选择直接影响检索效果。中文场景建议用针对中文优化的模型通用模型在中文语义相似度上表现一般。向量维度常见的是 768、1024、1536维度越高精度越好但存储和计算成本越高。检索阶段Top-K 建议设 10 到 20配合重排后取前 3 到 5 条拼进 Prompt。K 太小容易漏太大引入噪声。5.5 前端流式交互的实现前端处理 SSE 流核心是用fetch配合ReadableStream读取而不是用EventSource。因为EventSource只支持 GET 请求而 AI 对话通常要 POST 传参。async function streamChat(payload, onChunk) { const response await fetch(/api/chat/stream, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(payload) }); const reader response.body.getReader(); const decoder new TextDecoder(); let buffer ; while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const lines buffer.split(\n\n); buffer lines.pop(); for (const line of lines) { if (line.startsWith(data: )) { onChunk(JSON.parse(line.slice(6))); } } } }打字机效果不要用setTimeout逐字追加那样在长文本下会卡。正确做法是收到分片就追加用 CSS 的transition或requestAnimationFrame做平滑渲染。6. 实操中踩过的坑与排查技巧6.1 流式响应的常见故障问题一流式响应中途卡住不结束。排查思路先看后端日志有没有发结束标志再看网关有没有缓冲。很多网关默认会缓冲响应体导致流式变成攒完一次性发。解决方法是网关配置里关闭响应缓冲或者对 SSE 路径单独设置。问题二中文乱码。流式分片可能把一个多字节字符从中间切断前端TextDecoder要用{ stream: true }参数让它保留不完整字节等下一个分片。问题三连接被中间层超时断开。长连接要定期发心跳通常是发一个空注释行: heartbeat\n\n。心跳间隔要小于中间层的最短超时时间一般设 15 到 30 秒。6.2 上下文丢失的排查用户反馈AI 忘了前面说的话排查顺序先确认会话 ID 有没有正确传递再看上下文裁剪是不是裁太狠最后看 Prompt 拼装顺序对不对。有个隐蔽的坑多实例部署时如果会话存在本地内存用户请求被负载均衡打到不同实例上下文就丢了。这就是为什么会话必须存 Redis 这类共享存储。6.3 检索效果差的调优RAG 效果差先定位是检索问题还是生成问题。方法很简单把检索到的原文片段直接打印出来看如果片段本身就不相关那是检索问题如果片段相关但回答不对那是 Prompt 或生成问题。检索问题的调优顺序先调分块策略再调嵌入模型最后加混合检索和重排。不要一上来就换模型很多时候是分块把语义切碎了。6.4 常见问题速查表现象可能原因排查方向解决手段流式卡住网关缓冲抓包看响应是否分片到达关闭网关响应缓冲中文乱码分片切断多字节字符检查 TextDecoder 参数加 stream: true上下文丢失会话未共享存储检查多实例部署会话存 Redis检索不准分块过碎打印检索片段调整块大小和重叠响应慢模型服务排队看模型服务监控加熔断和降级Token 超限上下文未裁剪统计 Prompt Token 数启用滑动窗口裁剪6.5 几个独家避坑经验经验一模型调用一定要设超时。默认不设超时的话模型服务卡住会拖垮整个线程池。建议连接超时 5 秒读超时按场景设 30 到 120 秒流式场景要设分片间隔超时而不是总超时。经验二Prompt 里不要塞太多检索片段。我见过有人把 Top-20 全塞进去结果模型被噪声干扰回答质量反而下降。3 到 5 条精排后的片段通常最优。经验三会话标题让模型生成但要有兜底。用模型根据首轮对话生成标题体验好但模型可能失败或超时。兜底方案是截取用户第一句话的前 20 个字。经验四日志要记录完整的 Prompt 和响应。排查问题时没有完整上下文会非常痛苦。但要注意脱敏用户隐私信息不能明文落日志。经验五灰度发布模型切换。换模型不要一刀切先切 5% 流量对比效果确认没问题再全量。不同模型对同一个 Prompt 的响应差异可能很大。7. 底座之上还能怎么扩展QuickBlue 这类底座搭好之后上层能做的事情就多了。我分享几个实际项目里验证过的扩展方向。方向一Agent 编排。底座提供了模型调用和工具调用的基础能力后上层可以做多步骤 Agent。比如一个数据分析 Agent先调用模型理解问题再调用 SQL 工具查数据再调用模型生成结论。底座负责每次模型调用的统一管理Agent 层负责流程编排。方向二多模态扩展。底座如果一开始就把模型抽象设计好扩展图像、语音模型只是加适配器的事。业务层拿到的还是统一的调用接口不用关心底层是文本模型还是多模态模型。方向三效果评估体系。底座可以内置一套评估框架对每次对话记录质量打分定期跑回归测试集。这样换模型、改 Prompt 之后能快速知道效果是变好还是变差而不是靠感觉。方向四成本管控。底座统一记录每次调用的 Token 消耗按租户、按场景统计成本。可以设置配额超了自动降级到更便宜的模型。这在企业场景里是刚需不然月底账单会吓人。我个人在实际项目里的体会是底座的价值不在于技术多先进而在于把重复的事情做一次、做对、做扎实。很多团队一开始觉得我们自己也能封装但真做起来会发现模型适配的边界情况、流式处理的坑、权限隔离的细节每一样都要花时间踩。有一个经过验证的底座打底业务团队能把精力真正放在业务价值上这才是它最大的意义。最后分享一个小技巧底座的能力边界要用文档写清楚明确哪些是底座保证的、哪些是业务自己负责的。我见过太多项目因为边界模糊最后底座和业务代码互相渗透改一处动全身。边界清晰比功能丰富更重要。