尧图网页设计 
1. 从一堆“重复造轮子”的痛说起QuickBlue 到底想解决什么如果你带过三五个企业级项目大概率经历过这样的场景新项目立项架构组拍板用 Spring Cloud 全家桶然后团队开始干一件极其枯燥的事——把注册中心、配置中心、网关、鉴权、日志、链路追踪、限流熔断、代码生成、权限模型这些模块从上一个项目里“抠”出来改改包名再拼到新项目里。抠的过程中还会发现上个项目里那套鉴权逻辑跟当前业务对不上网关的限流规则要重写配置中心的命名空间要重新规划。折腾两三周业务代码一行没写人已经累得够呛。QuickBlue 就是冲着这个痛点来的。它本质上是一个AI 应用底座你可以把它理解成一套“开箱即用的企业级微服务脚手架 AI 能力接入层”。它把 Spring Cloud 生态里那些绕不开的基础设施——服务注册发现、配置管理、网关路由、统一鉴权、限流熔断、分布式缓存、日志链路——全部预置好同时在上面叠了一层面向 AI 应用的通用能力比如大模型调用编排、向量检索接入、会话上下文管理、Prompt 模板管理等。换句话说它想让你在启动一个新项目时不用再从零搭地基而是直接在地基上盖楼。为什么现在企业需要一个“AI 应用底座”因为过去一年我接触到的团队几乎都在做同一件事把大模型能力塞进已有的业务系统里。但塞的方式五花八门有的在 Controller 里直接写 HTTP 调用有的把 API Key 硬编码在配置文件里有的连会话状态都不存每次请求都是无状态的。这种“游击队”式的接入方式在 demo 阶段没问题一旦要上生产、要过安全审计、要做多租户隔离问题就全暴露出来了。QuickBlue 这类底座的价值就是把这些散落的实践收敛成一套标准化的、可复用的工程结构。这篇文章适合谁看如果你是中高级后端工程师、架构师或者正在负责企业 AI 应用落地的技术负责人那接下来的内容会对你有直接参考价值。我会从架构设计思路、核心模块拆解、实操搭建步骤、常见坑位排查几个维度把 QuickBlue 这类 AI 应用底座的完整面貌讲清楚。即使你最终不用 QuickBlue这套思路也可以直接迁移到你自己的项目里。2. 架构设计思路拆解为什么是微服务 AI 能力层2.1 单体还是微服务这个老问题在 AI 场景下有了新答案传统业务系统选单体还是微服务争论了快十年结论通常是“看团队规模和业务复杂度”。但在 AI 应用场景下我的判断会更倾向于微服务原因有三个而且都跟 AI 本身的特性有关。第一AI 调用的资源特征跟普通业务接口完全不同。一次大模型推理请求耗时可能是几百毫秒到几十秒占用的连接资源、内存资源跟一个普通的 CRUD 接口不是一个量级。如果把它和业务接口混在同一个单体应用里一个慢速的 AI 请求就可能把整个线程池拖垮。拆成独立服务后你可以针对 AI 服务单独做线程池隔离、超时配置、熔断策略互不影响。第二AI 能力的迭代速度远快于业务代码。今天用这个模型明天可能换另一个今天用同步调用明天可能要改成流式输出。如果 AI 逻辑和业务逻辑耦合在一起每次调整都要全量发布风险大、效率低。独立成服务后AI 能力层可以独立部署、独立灰度业务侧只需要通过稳定的接口契约调用即可。第三多租户和权限隔离的需求。企业级 AI 应用往往要服务多个部门或客户不同租户能访问的模型、能用的 Token 额度、能看到的会话数据都不一样。这种隔离在微服务架构下可以通过网关层 服务层的双重拦截来实现比单体应用里靠 if-else 判断要清晰得多。QuickBlue 的架构选择正是基于这三点。它没有把 AI 能力做成一个巨大的单体模块而是拆成了几个职责清晰的微服务AI 编排服务负责模型调用和 Prompt 管理向量服务负责嵌入和检索会话服务负责上下文存储再通过 API 网关统一暴露给上层业务。这种拆分方式跟热词里提到的“微服务拆分”原则是一致的——按业务能力边界拆而不是按技术分层拆。2.2 Spring Cloud 生态选型为什么不是别的热词里出现了大量 Spring Cloud 相关词汇这不是偶然。QuickBlue 选择 Spring Cloud 作为微服务底座背后有几个很实际的考量。首先是团队学习成本。国内绝大多数 Java 团队对 Spring Cloud 的组件体系是熟悉的——Nacos 做注册配置、Gateway 做网关、Sentinel 做限流熔断、OpenFeign 做服务调用。你招一个三年经验的 Java 工程师他大概率已经用过这套东西。如果换成一个自研的或者小众的微服务框架光是培训成本就够呛。其次是生态成熟度。Spring Cloud Alibaba 这套组合在国内经过大量生产验证Nacos 的注册配置能力、Sentinel 的流量治理能力、Seata 的分布式事务能力都有大量现成的文档和社区案例。遇到问题能搜到答案这对企业项目来说太重要了。再就是 JDK 21 的加持。QuickBlue 基于 JDK 21 构建这意味着它可以用上虚拟线程Virtual Threads。虚拟线程对 AI 应用来说是个大利好——AI 调用大量时间是花在等待网络 IO 上的虚拟线程可以让你在不增加太多硬件成本的情况下支撑更高的并发请求。传统平台线程模型下一个线程对应一个 OS 线程创建成本高、数量有限虚拟线程由 JVM 调度可以轻松创建几十万个特别适合 IO 密集型的 AI 调用场景。注意虚拟线程虽好但不要滥用。如果你的 AI 服务里有大量 CPU 密集型操作比如本地向量计算虚拟线程并不会带来收益反而可能因为调度开销导致性能下降。判断标准很简单任务是不是大部分时间在等 IO。是就用虚拟线程不是就用传统线程池。2.3 AI 能力层的设计把“调用大模型”这件事工程化QuickBlue 最核心的差异化在于它在微服务底座之上叠了一层 AI 能力层。这层能力不是简单封装一个 HTTP 客户端而是把 AI 应用开发中反复出现的几个问题做了抽象。第一个抽象是模型路由。企业里往往同时接入了多个模型来源——可能有公有云的大模型 API也可能有私有化部署的开源模型。不同模型的能力、成本、延迟都不一样。QuickBlue 的做法是定义一个统一的模型调用接口上层业务只面向接口编程具体走哪个模型由路由策略决定。路由策略可以基于租户、基于任务类型、基于成本预算来配置。这样业务代码不需要关心底层用的是哪个模型切换模型时也不用改业务逻辑。第二个抽象是Prompt 模板管理。Prompt 写死在代码里是 AI 应用开发的大忌。一旦要调整措辞、增加少样本示例、适配不同模型就得改代码重新发布。QuickBlue 把 Prompt 模板抽出来支持版本管理、变量替换、A/B 测试。你可以把 Prompt 当成配置来管理改 Prompt 不需要重新编译部署。第三个抽象是会话上下文管理。多轮对话场景下每次请求都要带上历史消息。如果让业务代码自己维护这个上下文很快就会乱套。QuickBlue 的会话服务统一管理会话状态支持上下文窗口裁剪、敏感信息过滤、会话过期清理。业务侧只需要传一个会话 ID剩下的交给底座处理。这三个抽象看起来简单但真正落地时涉及大量细节。比如模型路由要考虑故障转移——主模型超时了怎么自动切到备用模型Prompt 模板要考虑变量注入的安全性——防止用户输入的内容被当成模板指令执行会话上下文要考虑存储选型——用 Redis 还是数据库过期策略怎么定。这些细节才是 AI 应用底座真正的价值所在。3. 核心模块拆解与实操要点3.1 服务注册与配置中心Nacos 的落地细节QuickBlue 用 Nacos 做服务注册和配置中心这是 Spring Cloud Alibaba 体系里的标准选择。但标准选择不代表没有坑我结合实际配置说一下关键点。服务注册这块核心配置在bootstrap.yml里。注意是bootstrap.yml不是application.yml因为注册中心地址需要在应用启动的最早阶段加载。配置大概长这样spring: application: name: quickblue-ai-orchestrator cloud: nacos: discovery: server-addr: ${NACOS_ADDR:127.0.0.1:8848} namespace: ${NACOS_NAMESPACE:quickblue-dev} group: QUICKBLUE_GROUP ephemeral: true这里有几个参数值得展开说。namespace用来做环境隔离开发、测试、生产各用一个 namespace避免服务互相串门。group用来做业务分组比如 AI 编排服务和向量服务可以放在同一个 group 里。ephemeral设为 true 表示临时实例服务下线后 Nacos 会自动摘除如果设为 false 则是持久化实例适合那种需要人工确认下线的场景。配置中心这块我建议按“共享配置 应用配置”两层来组织。共享配置放数据库连接、Redis 连接、日志级别这些所有服务都要用的东西应用配置放各服务特有的参数比如 AI 编排服务的模型 API 地址、向量服务的索引名称。Nacos 支持配置继承通过shared-configs和extension-configs来引用。实操心得Nacos 配置的dataId命名一定要有规范。我见过团队用application-dev.yml这种通用名字结果多个项目共用同一个 Nacos 时配置互相覆盖。推荐格式是${spring.application.name}-${profile}.${file-extension}比如quickblue-ai-orchestrator-prod.yml一眼就能看出是哪个服务的哪个环境。还有一个容易忽略的点是配置的灰度发布。Nacos 支持配置的 Beta 发布可以先把新配置推给指定的 IP 列表验证没问题再全量。这个功能在调整 AI 模型参数时特别有用——你可以先让一台机器用新参数跑一段时间观察效果和成本再决定是否全量。3.2 API 网关不只是路由转发QuickBlue 的网关基于 Spring Cloud Gateway 构建但它的职责远不止路由转发。在企业 AI 应用场景下网关承担了鉴权、限流、日志、请求改写等多重职责。鉴权这块QuickBlue 采用的是 JWT 网关过滤器的方式。所有外部请求先到网关网关校验 JWT 的有效性解析出用户身份和租户信息然后把身份信息通过请求头透传给下游服务。下游服务不需要再解析 JWT直接从请求头里取用户信息即可。这样做的好处是鉴权逻辑集中在一处下游服务专注业务。限流这块QuickBlue 集成了 Sentinel。Sentinel 的限流规则可以基于 QPS、线程数、响应时间等多个维度。对 AI 服务来说我建议重点配置两个规则一是基于 QPS 的限流防止突发流量打垮模型服务二是基于响应时间的熔断当模型调用平均耗时超过阈值时自动熔断避免线程堆积。// Sentinel 资源定义示例 SentinelResource(value aiModelInvoke, blockHandler handleBlock, fallback handleFallback) public ModelResponse invokeModel(ModelRequest request) { // 模型调用逻辑 }这里blockHandler处理限流降级fallback处理异常降级。两个方法的签名要和原方法一致只是参数列表最后多一个BlockException或Throwable。请求改写这块网关可以在转发前对请求做统一处理。比如给所有请求加上租户 ID 请求头、统一做请求体大小限制、统一做敏感词过滤。这些操作放在网关层做一次比在每个服务里做要高效得多。注意网关层的过滤器顺序很重要。鉴权过滤器要排在限流过滤器之前否则未认证的请求也会消耗限流配额。日志过滤器要排在最后确保能记录到完整的请求处理链路。Spring Cloud Gateway 通过Order注解或实现Ordered接口来控制顺序数字越小优先级越高。3.3 AI 编排服务模型调用的统一入口AI 编排服务是 QuickBlue 里最核心的模块它把模型调用这件事做了完整的工程化封装。我把它拆成几个关键能力来讲。模型适配层。不同模型提供商的 API 格式不一样有的用 OpenAI 兼容格式有的用自家私有格式。QuickBlue 定义了一个统一的ModelClient接口每个模型提供商实现一个适配器。上层业务只依赖ModelClient接口不关心底层是哪个提供商。public interface ModelClient { ModelResponse chat(ChatRequest request); StreamModelResponse chatStream(ChatRequest request); EmbeddingResponse embed(EmbeddingRequest request); }chat是同步调用chatStream是流式调用embed是向量化调用。三个方法覆盖了绝大多数 AI 应用场景。Prompt 模板引擎。QuickBlue 用模板引擎来管理 Prompt支持变量替换和条件渲染。模板存在配置中心或数据库里改模板不需要重新部署。模板变量用{{variable}}语法渲染时做转义处理防止注入攻击。PromptTemplate template promptTemplateService.get(customer-service-reply); MapString, Object variables Map.of( userName, 张三, question, 如何申请退款, context, retrievedContext ); String prompt template.render(variables);上下文管理。多轮对话的上下文存在 Redis 里key 是会话 IDvalue 是消息列表。每次请求时编排服务从 Redis 取出历史消息拼接到当前请求前面再发给模型。上下文有窗口限制超过最大 Token 数时按策略裁剪——可以保留最近 N 条也可以保留系统消息 最近 N 条。实操心得上下文裁剪策略要结合业务场景来定。客服场景下系统提示词和最近几轮对话最重要早期的对话可以丢弃而合同审查场景下早期的关键条款可能比最近的闲聊更重要。QuickBlue 支持自定义裁剪策略你可以根据业务特点实现自己的裁剪逻辑。3.4 向量服务与 RAG 能力接入RAG检索增强生成是企业 AI 应用里最常见的模式QuickBlue 的向量服务就是为 RAG 场景准备的。它的核心职责是把文档切片、向量化、存入向量库查询时根据问题向量检索最相关的片段。文档切片这块QuickBlue 支持按固定长度切、按段落切、按语义切三种策略。固定长度切最简单但可能把一句话切断按段落切保留了语义完整性但段落长度不均匀按语义切效果最好但需要额外的模型调用成本更高。我的建议是对结构化文档如产品手册用按段落切对非结构化文本如聊天记录用固定长度切对质量要求极高的场景再用语义切。向量化这块QuickBlue 支持多种嵌入模型。选择嵌入模型时重点看三个指标向量维度、检索准确率、推理速度。维度越高表达能力越强但存储和计算成本也越高。常见的嵌入模型维度在 768 到 1536 之间检索准确率差异不大但推理速度可能差好几倍。向量存储这块QuickBlue 默认集成了 Redis 的向量检索能力。Redis 从 7.0 版本开始支持向量相似度搜索对于中小规模的向量数据百万级以下完全够用。如果数据量更大可以切换到 Milvus 或 Qdrant 这类专业向量数据库。QuickBlue 做了存储层的抽象切换存储只需要改配置。quickblue: vector: store-type: redis # 可选 redis, milvus, qdrant index-name: quickblue-docs dimension: 1536 metric: COSINE检索这块QuickBlue 支持相似度阈值过滤和 Top-K 返回。相似度阈值用来过滤掉不相关的结果Top-K 控制返回条数。这两个参数需要根据实际数据调优——阈值太高会漏掉相关内容太低会引入噪声K 值太大浪费 Token太小可能遗漏关键信息。4. 从零搭建 QuickBlue 底座的完整实操4.1 环境准备与依赖安装搭建 QuickBlue 底座第一步是把基础环境准备好。我按实际操作的顺序来说。JDK 21 是必须的因为 QuickBlue 用到了虚拟线程和部分新语法特性。安装完 JDK 后确认java -version输出是 21 以上。Maven 用 3.9 以上版本Gradle 用 8.5 以上版本两者选其一即可。Nacos 需要单独部署。开发环境可以用单机模式生产环境建议用集群模式。单机模式启动命令很简单# Nacos 单机启动 sh startup.sh -m standalone启动后访问http://localhost:8848/nacos默认账号密码都是nacos。进去后先创建命名空间开发、测试、生产各一个。Redis 需要 7.0 以上版本因为要用到向量检索功能。安装完确认redis-cli --version输出是 7.0 以上。如果需要持久化向量数据建议开启 AOF。MySQL 用 8.0 以上版本用来存储 Prompt 模板、会话元数据、租户配置等结构化数据。建库时字符集用utf8mb4排序规则用utf8mb4_general_ci。4.2 服务模块划分与工程结构QuickBlue 的工程结构按微服务模块来组织我列一下核心模块和它们的职责。模块名称职责依赖quickblue-gatewayAPI 网关鉴权限流路由Nacos, Redis, Sentinelquickblue-ai-orchestratorAI 编排模型调用 Prompt 管理Nacos, Redis, MySQLquickblue-vector-service向量化与检索Nacos, Redisquickblue-session-service会话上下文管理Nacos, Redisquickblue-common公共依赖工具类常量无quickblue-api接口定义DTO 对象无模块之间的依赖关系要清晰quickblue-api被所有服务依赖quickblue-common被所有服务依赖业务服务之间不直接依赖通过 API 接口调用。这样做的目的是降低耦合任何一个服务的内部实现变更不会影响其他服务。工程结构上我建议用 Maven 多模块或者 Gradle 多项目来组织。父 POM 里统一管理依赖版本子模块只声明自己需要的依赖。版本管理用dependencyManagement避免版本冲突。dependencyManagement dependencies dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-alibaba-dependencies/artifactId version2023.0.1.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement注意Spring Cloud Alibaba 的版本要和 Spring Boot 版本匹配。2023.0.1.0 对应 Spring Boot 3.2.x如果你用的是 Spring Boot 3.3.x需要选更新的 Alibaba 版本。版本不匹配会导致启动时报各种奇怪的类找不到错误。4.3 关键配置与参数调优配置这块我把几个关键参数单独拎出来说这些都是实际调优时踩过坑的地方。虚拟线程配置。JDK 21 的虚拟线程在 Spring Boot 3.2 以上版本可以一键开启spring: threads: virtual: enabled: true开启后Tomcat 的请求处理线程会自动切换为虚拟线程。但要注意如果你用了synchronized块或者ThreadLocal虚拟线程的行为可能和平台线程不同。synchronized会导致虚拟线程被固定pinning失去虚拟线程的优势。建议用ReentrantLock替代synchronized。连接池配置。AI 服务调用模型 API 时HTTP 连接池的大小直接影响并发能力。默认的 20 个连接在高并发下会成为瓶颈。建议根据实际 QPS 调整spring: cloud: openfeign: httpclient: max-connections: 200 max-connections-per-route: 50max-connections是总连接数max-connections-per-route是单个目标地址的最大连接数。如果模型 API 有多个地址总连接数要按地址数乘以单地址连接数来估算。Redis 向量检索配置。Redis 向量检索需要创建索引索引的配置直接影响检索性能FT.CREATE quickblue-docs ON HASH PREFIX 1 doc: SCHEMA content TEXT embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 1536 DISTANCE_METRIC COSINEHNSW是近似最近邻算法检索速度快但有一定精度损失。如果对精度要求极高可以用FLAT算法但检索速度会慢很多。DIM要和嵌入模型的维度一致DISTANCE_METRIC常用COSINE或L2。Sentinel 规则配置。限流规则建议持久化到 Nacos避免重启后丢失[ { resource: aiModelInvoke, limitApp: default, grade: 1, count: 100, strategy: 0, controlBehavior: 0 } ]grade为 1 表示 QPS 限流count为 100 表示每秒最多 100 次调用。controlBehavior为 0 表示快速失败为 1 表示 Warm Up为 2 表示排队等待。AI 场景建议用快速失败避免请求堆积。4.4 启动验证与联调测试所有服务启动后按这个顺序验证。先看 Nacos 控制台的服务列表确认所有服务都注册上来了。服务名、IP、端口、健康状态都要对。如果有服务没注册上来检查bootstrap.yml里的 Nacos 地址和命名空间配置。然后测网关路由。用 curl 直接访问网关地址看能不能路由到下游服务curl -X POST http://localhost:8080/api/ai/chat \ -H Content-Type: application/json \ -H Authorization: Bearer token \ -d {sessionId:test-001,message:你好}如果返回 401说明鉴权过滤器生效了需要先获取 Token。如果返回 404说明路由配置有问题检查网关的路由规则。如果返回 503说明下游服务不可用检查服务是否正常启动。再测 AI 编排服务的模型调用。可以直接调用编排服务的接口绕过网关curl -X POST http://localhost:8081/ai/chat \ -H Content-Type: application/json \ -d {sessionId:test-001,message:你好,model:default}如果返回模型响应说明模型适配层工作正常。如果报超时检查模型 API 地址和网络连通性。如果报鉴权失败检查模型 API Key 配置。最后测向量检索。先插入一条测试数据再查询# 插入 curl -X POST http://localhost:8082/vector/upsert \ -d {id:doc-001,content:QuickBlue 是一个 AI 应用底座,embedding:[0.1,0.2,...]} # 查询 curl -X POST http://localhost:8082/vector/search \ -d {query:什么是 QuickBlue,topK:3}如果查询能返回刚插入的文档说明向量服务正常。如果返回空检查索引是否创建、维度是否匹配。5. 常见问题与排查技巧实录5.1 服务注册与发现类问题问题一服务注册不上 Nacos。最常见的原因是网络不通或命名空间配置错误。排查步骤先在服务器上telnet nacos-addr 8848确认端口通不通再检查bootstrap.yml里的namespace值是不是 Nacos 控制台上看到的命名空间 ID注意是 ID 不是名称最后看应用启动日志里有没有nacos registry相关的报错。问题二服务注册上了但调用不通。这种情况通常是网络策略或防火墙问题。Nacos 注册的是服务的内网 IP如果调用方和服务不在同一个网络环境就会调不通。解决办法是配置 Nacos 的ip参数显式指定服务注册的 IP。或者检查是否有安全组规则拦截了服务端口。问题三服务实例列表更新不及时。Nacos 默认的心跳间隔是 5 秒超过 15 秒没心跳会标记为不健康超过 30 秒会摘除。如果服务频繁上下线可能出现调用到已下线实例的情况。可以通过调整心跳间隔和超时时间来缓解但根本解决办法是保证服务稳定避免频繁重启。5.2 AI 调用类问题问题一模型调用超时。AI 模型调用耗时波动很大同样的请求可能这次 2 秒下次 20 秒。默认的超时配置往往不够用。建议把 AI 调用的超时时间单独配置比普通接口长一些spring: cloud: openfeign: client: config: model-client: connectTimeout: 5000 readTimeout: 60000connectTimeout是建立连接的超时readTimeout是读取响应的超时。AI 调用主要关注readTimeout建议设 60 秒以上。问题二流式输出中断。流式调用时如果网关或代理有缓冲会导致流式输出变成一次性输出。解决办法是在网关层关闭响应缓冲并设置正确的Content-Typespring: cloud: gateway: httpclient: response-timeout: 120s同时确保Content-Type是text/event-stream这样网关才知道这是流式响应不会做缓冲。问题三Token 消耗过快。这是成本问题也是技术问题。排查方向一是看上下文是不是太长了历史消息没有做裁剪二是看 Prompt 模板里是不是有冗余内容三是看有没有重复调用比如同一个请求调了两次模型。QuickBlue 提供了 Token 消耗统计可以按租户、按模型、按时间段查看消耗情况方便定位问题。5.3 向量检索类问题问题一检索结果不相关。原因可能是嵌入模型不适合当前语种或领域也可能是切片策略不合理。排查方法先拿几个典型问题手动测试看检索出来的片段是不是真的相关。如果不相关换一个嵌入模型试试如果切片太碎调整切片长度如果切片太长检索精度会下降。问题二检索速度慢。向量检索的速度跟数据量、索引类型、硬件配置都有关。百万级数据用 HNSW 索引单次检索应该在几十毫秒内。如果超过几百毫秒检查是不是用了 FLAT 索引或者 Redis 内存不足导致频繁换页。问题三向量维度不匹配。插入时用的嵌入模型维度和索引定义的维度不一致会导致插入失败或检索异常。解决办法是统一嵌入模型或者在索引定义时留出维度余量。QuickBlue 在启动时会校验嵌入模型维度和索引维度是否一致不一致会直接报错避免运行时才发现问题。5.4 高频问题速查表问题现象可能原因排查方向解决措施服务注册不上网络不通/命名空间错误telnet 端口、检查 namespace修复网络、修正配置调用超时超时配置过短查看 Feign 超时配置增大 readTimeout流式输出中断网关缓冲检查 Content-Type关闭缓冲、设 event-streamToken 消耗快上下文过长查看会话消息数裁剪上下文、精简 Prompt检索不相关嵌入模型不适配手动测试检索结果换模型、调切片策略检索速度慢索引类型不当检查索引定义改用 HNSW 索引向量维度不匹配模型与索引不一致检查维度配置统一维度或重建索引限流误伤规则太严查看 Sentinel 规则调整 QPS 阈值配置不生效配置未刷新检查 Nacos 配置手动刷新或重启虚拟线程无效果被 synchronized 固定检查代码中的锁改用 ReentrantLock实操心得排查 AI 应用问题时日志是第一手资料。QuickBlue 默认会记录每次模型调用的请求 ID、模型名称、Token 消耗、耗时。遇到问题时先根据请求 ID 把整条链路的日志串起来从网关到编排服务到模型调用看是哪一环出了问题。这个习惯能帮你省下大量猜测时间。6. 这套底座还能怎么扩展QuickBlue 作为 AI 应用底座基础能力已经覆盖了大多数企业场景。但每个企业的业务特点不同总有一些个性化需求。我分享几个常见的扩展方向都是实际项目中遇到过的。多模型 A/B 测试。同一个业务场景下想对比两个模型的效果和成本。可以在模型路由层加一个分流策略按用户 ID 哈希取模一部分走模型 A一部分走模型 B。QuickBlue 的模型路由接口支持自定义策略实现一个ModelRouter接口即可。Prompt 版本管理。Prompt 调整频繁时需要版本管理来追踪每次变更的效果。可以在 Prompt 模板表里加版本字段每次修改生成新版本旧版本保留。调用时可以指定版本号也可以默认用最新版本。配合 A/B 测试可以量化每个版本的效果差异。成本配额管理。企业里多个团队共用 AI 能力时需要按团队分配 Token 配额。可以在网关层加一个配额检查过滤器每次请求前检查该租户的剩余配额超了就拒绝。配额数据存在 Redis 里按天或按月重置。敏感信息过滤。AI 应用涉及用户输入和模型输出两头都可能包含敏感信息。可以在网关层做输入过滤在编排服务层做输出过滤。过滤规则可以配置化支持正则表达式和关键词列表。离线批量推理。有些场景不需要实时响应比如批量文档摘要、批量数据分类。可以加一个离线任务模块从消息队列消费任务批量调用模型结果写回数据库。这样可以把实时请求和离线任务分开互不影响。这些扩展方向不需要一次性全做按业务优先级逐步迭代即可。QuickBlue 的模块化设计让每个扩展都可以独立开发和部署不会影响现有功能。我在实际项目中的体会是先把核心链路跑通再根据实际需求做扩展比一开始就设计一个大而全的架构要务实得多。 QuickBlue AI应用底座：微服务架构与工程化实践指南
1. 从一堆“重复造轮子”的痛说起QuickBlue 到底想解决什么如果你带过三五个企业级项目大概率经历过这样的场景新项目立项架构组拍板用 Spring Cloud 全家桶然后团队开始干一件极其枯燥的事——把注册中心、配置中心、网关、鉴权、日志、链路追踪、限流熔断、代码生成、权限模型这些模块从上一个项目里“抠”出来改改包名再拼到新项目里。抠的过程中还会发现上个项目里那套鉴权逻辑跟当前业务对不上网关的限流规则要重写配置中心的命名空间要重新规划。折腾两三周业务代码一行没写人已经累得够呛。QuickBlue 就是冲着这个痛点来的。它本质上是一个AI 应用底座你可以把它理解成一套“开箱即用的企业级微服务脚手架 AI 能力接入层”。它把 Spring Cloud 生态里那些绕不开的基础设施——服务注册发现、配置管理、网关路由、统一鉴权、限流熔断、分布式缓存、日志链路——全部预置好同时在上面叠了一层面向 AI 应用的通用能力比如大模型调用编排、向量检索接入、会话上下文管理、Prompt 模板管理等。换句话说它想让你在启动一个新项目时不用再从零搭地基而是直接在地基上盖楼。为什么现在企业需要一个“AI 应用底座”因为过去一年我接触到的团队几乎都在做同一件事把大模型能力塞进已有的业务系统里。但塞的方式五花八门有的在 Controller 里直接写 HTTP 调用有的把 API Key 硬编码在配置文件里有的连会话状态都不存每次请求都是无状态的。这种“游击队”式的接入方式在 demo 阶段没问题一旦要上生产、要过安全审计、要做多租户隔离问题就全暴露出来了。QuickBlue 这类底座的价值就是把这些散落的实践收敛成一套标准化的、可复用的工程结构。这篇文章适合谁看如果你是中高级后端工程师、架构师或者正在负责企业 AI 应用落地的技术负责人那接下来的内容会对你有直接参考价值。我会从架构设计思路、核心模块拆解、实操搭建步骤、常见坑位排查几个维度把 QuickBlue 这类 AI 应用底座的完整面貌讲清楚。即使你最终不用 QuickBlue这套思路也可以直接迁移到你自己的项目里。2. 架构设计思路拆解为什么是微服务 AI 能力层2.1 单体还是微服务这个老问题在 AI 场景下有了新答案传统业务系统选单体还是微服务争论了快十年结论通常是“看团队规模和业务复杂度”。但在 AI 应用场景下我的判断会更倾向于微服务原因有三个而且都跟 AI 本身的特性有关。第一AI 调用的资源特征跟普通业务接口完全不同。一次大模型推理请求耗时可能是几百毫秒到几十秒占用的连接资源、内存资源跟一个普通的 CRUD 接口不是一个量级。如果把它和业务接口混在同一个单体应用里一个慢速的 AI 请求就可能把整个线程池拖垮。拆成独立服务后你可以针对 AI 服务单独做线程池隔离、超时配置、熔断策略互不影响。第二AI 能力的迭代速度远快于业务代码。今天用这个模型明天可能换另一个今天用同步调用明天可能要改成流式输出。如果 AI 逻辑和业务逻辑耦合在一起每次调整都要全量发布风险大、效率低。独立成服务后AI 能力层可以独立部署、独立灰度业务侧只需要通过稳定的接口契约调用即可。第三多租户和权限隔离的需求。企业级 AI 应用往往要服务多个部门或客户不同租户能访问的模型、能用的 Token 额度、能看到的会话数据都不一样。这种隔离在微服务架构下可以通过网关层 服务层的双重拦截来实现比单体应用里靠 if-else 判断要清晰得多。QuickBlue 的架构选择正是基于这三点。它没有把 AI 能力做成一个巨大的单体模块而是拆成了几个职责清晰的微服务AI 编排服务负责模型调用和 Prompt 管理向量服务负责嵌入和检索会话服务负责上下文存储再通过 API 网关统一暴露给上层业务。这种拆分方式跟热词里提到的“微服务拆分”原则是一致的——按业务能力边界拆而不是按技术分层拆。2.2 Spring Cloud 生态选型为什么不是别的热词里出现了大量 Spring Cloud 相关词汇这不是偶然。QuickBlue 选择 Spring Cloud 作为微服务底座背后有几个很实际的考量。首先是团队学习成本。国内绝大多数 Java 团队对 Spring Cloud 的组件体系是熟悉的——Nacos 做注册配置、Gateway 做网关、Sentinel 做限流熔断、OpenFeign 做服务调用。你招一个三年经验的 Java 工程师他大概率已经用过这套东西。如果换成一个自研的或者小众的微服务框架光是培训成本就够呛。其次是生态成熟度。Spring Cloud Alibaba 这套组合在国内经过大量生产验证Nacos 的注册配置能力、Sentinel 的流量治理能力、Seata 的分布式事务能力都有大量现成的文档和社区案例。遇到问题能搜到答案这对企业项目来说太重要了。再就是 JDK 21 的加持。QuickBlue 基于 JDK 21 构建这意味着它可以用上虚拟线程Virtual Threads。虚拟线程对 AI 应用来说是个大利好——AI 调用大量时间是花在等待网络 IO 上的虚拟线程可以让你在不增加太多硬件成本的情况下支撑更高的并发请求。传统平台线程模型下一个线程对应一个 OS 线程创建成本高、数量有限虚拟线程由 JVM 调度可以轻松创建几十万个特别适合 IO 密集型的 AI 调用场景。注意虚拟线程虽好但不要滥用。如果你的 AI 服务里有大量 CPU 密集型操作比如本地向量计算虚拟线程并不会带来收益反而可能因为调度开销导致性能下降。判断标准很简单任务是不是大部分时间在等 IO。是就用虚拟线程不是就用传统线程池。2.3 AI 能力层的设计把“调用大模型”这件事工程化QuickBlue 最核心的差异化在于它在微服务底座之上叠了一层 AI 能力层。这层能力不是简单封装一个 HTTP 客户端而是把 AI 应用开发中反复出现的几个问题做了抽象。第一个抽象是模型路由。企业里往往同时接入了多个模型来源——可能有公有云的大模型 API也可能有私有化部署的开源模型。不同模型的能力、成本、延迟都不一样。QuickBlue 的做法是定义一个统一的模型调用接口上层业务只面向接口编程具体走哪个模型由路由策略决定。路由策略可以基于租户、基于任务类型、基于成本预算来配置。这样业务代码不需要关心底层用的是哪个模型切换模型时也不用改业务逻辑。第二个抽象是Prompt 模板管理。Prompt 写死在代码里是 AI 应用开发的大忌。一旦要调整措辞、增加少样本示例、适配不同模型就得改代码重新发布。QuickBlue 把 Prompt 模板抽出来支持版本管理、变量替换、A/B 测试。你可以把 Prompt 当成配置来管理改 Prompt 不需要重新编译部署。第三个抽象是会话上下文管理。多轮对话场景下每次请求都要带上历史消息。如果让业务代码自己维护这个上下文很快就会乱套。QuickBlue 的会话服务统一管理会话状态支持上下文窗口裁剪、敏感信息过滤、会话过期清理。业务侧只需要传一个会话 ID剩下的交给底座处理。这三个抽象看起来简单但真正落地时涉及大量细节。比如模型路由要考虑故障转移——主模型超时了怎么自动切到备用模型Prompt 模板要考虑变量注入的安全性——防止用户输入的内容被当成模板指令执行会话上下文要考虑存储选型——用 Redis 还是数据库过期策略怎么定。这些细节才是 AI 应用底座真正的价值所在。3. 核心模块拆解与实操要点3.1 服务注册与配置中心Nacos 的落地细节QuickBlue 用 Nacos 做服务注册和配置中心这是 Spring Cloud Alibaba 体系里的标准选择。但标准选择不代表没有坑我结合实际配置说一下关键点。服务注册这块核心配置在bootstrap.yml里。注意是bootstrap.yml不是application.yml因为注册中心地址需要在应用启动的最早阶段加载。配置大概长这样spring: application: name: quickblue-ai-orchestrator cloud: nacos: discovery: server-addr: ${NACOS_ADDR:127.0.0.1:8848} namespace: ${NACOS_NAMESPACE:quickblue-dev} group: QUICKBLUE_GROUP ephemeral: true这里有几个参数值得展开说。namespace用来做环境隔离开发、测试、生产各用一个 namespace避免服务互相串门。group用来做业务分组比如 AI 编排服务和向量服务可以放在同一个 group 里。ephemeral设为 true 表示临时实例服务下线后 Nacos 会自动摘除如果设为 false 则是持久化实例适合那种需要人工确认下线的场景。配置中心这块我建议按“共享配置 应用配置”两层来组织。共享配置放数据库连接、Redis 连接、日志级别这些所有服务都要用的东西应用配置放各服务特有的参数比如 AI 编排服务的模型 API 地址、向量服务的索引名称。Nacos 支持配置继承通过shared-configs和extension-configs来引用。实操心得Nacos 配置的dataId命名一定要有规范。我见过团队用application-dev.yml这种通用名字结果多个项目共用同一个 Nacos 时配置互相覆盖。推荐格式是${spring.application.name}-${profile}.${file-extension}比如quickblue-ai-orchestrator-prod.yml一眼就能看出是哪个服务的哪个环境。还有一个容易忽略的点是配置的灰度发布。Nacos 支持配置的 Beta 发布可以先把新配置推给指定的 IP 列表验证没问题再全量。这个功能在调整 AI 模型参数时特别有用——你可以先让一台机器用新参数跑一段时间观察效果和成本再决定是否全量。3.2 API 网关不只是路由转发QuickBlue 的网关基于 Spring Cloud Gateway 构建但它的职责远不止路由转发。在企业 AI 应用场景下网关承担了鉴权、限流、日志、请求改写等多重职责。鉴权这块QuickBlue 采用的是 JWT 网关过滤器的方式。所有外部请求先到网关网关校验 JWT 的有效性解析出用户身份和租户信息然后把身份信息通过请求头透传给下游服务。下游服务不需要再解析 JWT直接从请求头里取用户信息即可。这样做的好处是鉴权逻辑集中在一处下游服务专注业务。限流这块QuickBlue 集成了 Sentinel。Sentinel 的限流规则可以基于 QPS、线程数、响应时间等多个维度。对 AI 服务来说我建议重点配置两个规则一是基于 QPS 的限流防止突发流量打垮模型服务二是基于响应时间的熔断当模型调用平均耗时超过阈值时自动熔断避免线程堆积。// Sentinel 资源定义示例 SentinelResource(value aiModelInvoke, blockHandler handleBlock, fallback handleFallback) public ModelResponse invokeModel(ModelRequest request) { // 模型调用逻辑 }这里blockHandler处理限流降级fallback处理异常降级。两个方法的签名要和原方法一致只是参数列表最后多一个BlockException或Throwable。请求改写这块网关可以在转发前对请求做统一处理。比如给所有请求加上租户 ID 请求头、统一做请求体大小限制、统一做敏感词过滤。这些操作放在网关层做一次比在每个服务里做要高效得多。注意网关层的过滤器顺序很重要。鉴权过滤器要排在限流过滤器之前否则未认证的请求也会消耗限流配额。日志过滤器要排在最后确保能记录到完整的请求处理链路。Spring Cloud Gateway 通过Order注解或实现Ordered接口来控制顺序数字越小优先级越高。3.3 AI 编排服务模型调用的统一入口AI 编排服务是 QuickBlue 里最核心的模块它把模型调用这件事做了完整的工程化封装。我把它拆成几个关键能力来讲。模型适配层。不同模型提供商的 API 格式不一样有的用 OpenAI 兼容格式有的用自家私有格式。QuickBlue 定义了一个统一的ModelClient接口每个模型提供商实现一个适配器。上层业务只依赖ModelClient接口不关心底层是哪个提供商。public interface ModelClient { ModelResponse chat(ChatRequest request); StreamModelResponse chatStream(ChatRequest request); EmbeddingResponse embed(EmbeddingRequest request); }chat是同步调用chatStream是流式调用embed是向量化调用。三个方法覆盖了绝大多数 AI 应用场景。Prompt 模板引擎。QuickBlue 用模板引擎来管理 Prompt支持变量替换和条件渲染。模板存在配置中心或数据库里改模板不需要重新部署。模板变量用{{variable}}语法渲染时做转义处理防止注入攻击。PromptTemplate template promptTemplateService.get(customer-service-reply); MapString, Object variables Map.of( userName, 张三, question, 如何申请退款, context, retrievedContext ); String prompt template.render(variables);上下文管理。多轮对话的上下文存在 Redis 里key 是会话 IDvalue 是消息列表。每次请求时编排服务从 Redis 取出历史消息拼接到当前请求前面再发给模型。上下文有窗口限制超过最大 Token 数时按策略裁剪——可以保留最近 N 条也可以保留系统消息 最近 N 条。实操心得上下文裁剪策略要结合业务场景来定。客服场景下系统提示词和最近几轮对话最重要早期的对话可以丢弃而合同审查场景下早期的关键条款可能比最近的闲聊更重要。QuickBlue 支持自定义裁剪策略你可以根据业务特点实现自己的裁剪逻辑。3.4 向量服务与 RAG 能力接入RAG检索增强生成是企业 AI 应用里最常见的模式QuickBlue 的向量服务就是为 RAG 场景准备的。它的核心职责是把文档切片、向量化、存入向量库查询时根据问题向量检索最相关的片段。文档切片这块QuickBlue 支持按固定长度切、按段落切、按语义切三种策略。固定长度切最简单但可能把一句话切断按段落切保留了语义完整性但段落长度不均匀按语义切效果最好但需要额外的模型调用成本更高。我的建议是对结构化文档如产品手册用按段落切对非结构化文本如聊天记录用固定长度切对质量要求极高的场景再用语义切。向量化这块QuickBlue 支持多种嵌入模型。选择嵌入模型时重点看三个指标向量维度、检索准确率、推理速度。维度越高表达能力越强但存储和计算成本也越高。常见的嵌入模型维度在 768 到 1536 之间检索准确率差异不大但推理速度可能差好几倍。向量存储这块QuickBlue 默认集成了 Redis 的向量检索能力。Redis 从 7.0 版本开始支持向量相似度搜索对于中小规模的向量数据百万级以下完全够用。如果数据量更大可以切换到 Milvus 或 Qdrant 这类专业向量数据库。QuickBlue 做了存储层的抽象切换存储只需要改配置。quickblue: vector: store-type: redis # 可选 redis, milvus, qdrant index-name: quickblue-docs dimension: 1536 metric: COSINE检索这块QuickBlue 支持相似度阈值过滤和 Top-K 返回。相似度阈值用来过滤掉不相关的结果Top-K 控制返回条数。这两个参数需要根据实际数据调优——阈值太高会漏掉相关内容太低会引入噪声K 值太大浪费 Token太小可能遗漏关键信息。4. 从零搭建 QuickBlue 底座的完整实操4.1 环境准备与依赖安装搭建 QuickBlue 底座第一步是把基础环境准备好。我按实际操作的顺序来说。JDK 21 是必须的因为 QuickBlue 用到了虚拟线程和部分新语法特性。安装完 JDK 后确认java -version输出是 21 以上。Maven 用 3.9 以上版本Gradle 用 8.5 以上版本两者选其一即可。Nacos 需要单独部署。开发环境可以用单机模式生产环境建议用集群模式。单机模式启动命令很简单# Nacos 单机启动 sh startup.sh -m standalone启动后访问http://localhost:8848/nacos默认账号密码都是nacos。进去后先创建命名空间开发、测试、生产各一个。Redis 需要 7.0 以上版本因为要用到向量检索功能。安装完确认redis-cli --version输出是 7.0 以上。如果需要持久化向量数据建议开启 AOF。MySQL 用 8.0 以上版本用来存储 Prompt 模板、会话元数据、租户配置等结构化数据。建库时字符集用utf8mb4排序规则用utf8mb4_general_ci。4.2 服务模块划分与工程结构QuickBlue 的工程结构按微服务模块来组织我列一下核心模块和它们的职责。模块名称职责依赖quickblue-gatewayAPI 网关鉴权限流路由Nacos, Redis, Sentinelquickblue-ai-orchestratorAI 编排模型调用 Prompt 管理Nacos, Redis, MySQLquickblue-vector-service向量化与检索Nacos, Redisquickblue-session-service会话上下文管理Nacos, Redisquickblue-common公共依赖工具类常量无quickblue-api接口定义DTO 对象无模块之间的依赖关系要清晰quickblue-api被所有服务依赖quickblue-common被所有服务依赖业务服务之间不直接依赖通过 API 接口调用。这样做的目的是降低耦合任何一个服务的内部实现变更不会影响其他服务。工程结构上我建议用 Maven 多模块或者 Gradle 多项目来组织。父 POM 里统一管理依赖版本子模块只声明自己需要的依赖。版本管理用dependencyManagement避免版本冲突。dependencyManagement dependencies dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-alibaba-dependencies/artifactId version2023.0.1.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement注意Spring Cloud Alibaba 的版本要和 Spring Boot 版本匹配。2023.0.1.0 对应 Spring Boot 3.2.x如果你用的是 Spring Boot 3.3.x需要选更新的 Alibaba 版本。版本不匹配会导致启动时报各种奇怪的类找不到错误。4.3 关键配置与参数调优配置这块我把几个关键参数单独拎出来说这些都是实际调优时踩过坑的地方。虚拟线程配置。JDK 21 的虚拟线程在 Spring Boot 3.2 以上版本可以一键开启spring: threads: virtual: enabled: true开启后Tomcat 的请求处理线程会自动切换为虚拟线程。但要注意如果你用了synchronized块或者ThreadLocal虚拟线程的行为可能和平台线程不同。synchronized会导致虚拟线程被固定pinning失去虚拟线程的优势。建议用ReentrantLock替代synchronized。连接池配置。AI 服务调用模型 API 时HTTP 连接池的大小直接影响并发能力。默认的 20 个连接在高并发下会成为瓶颈。建议根据实际 QPS 调整spring: cloud: openfeign: httpclient: max-connections: 200 max-connections-per-route: 50max-connections是总连接数max-connections-per-route是单个目标地址的最大连接数。如果模型 API 有多个地址总连接数要按地址数乘以单地址连接数来估算。Redis 向量检索配置。Redis 向量检索需要创建索引索引的配置直接影响检索性能FT.CREATE quickblue-docs ON HASH PREFIX 1 doc: SCHEMA content TEXT embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 1536 DISTANCE_METRIC COSINEHNSW是近似最近邻算法检索速度快但有一定精度损失。如果对精度要求极高可以用FLAT算法但检索速度会慢很多。DIM要和嵌入模型的维度一致DISTANCE_METRIC常用COSINE或L2。Sentinel 规则配置。限流规则建议持久化到 Nacos避免重启后丢失[ { resource: aiModelInvoke, limitApp: default, grade: 1, count: 100, strategy: 0, controlBehavior: 0 } ]grade为 1 表示 QPS 限流count为 100 表示每秒最多 100 次调用。controlBehavior为 0 表示快速失败为 1 表示 Warm Up为 2 表示排队等待。AI 场景建议用快速失败避免请求堆积。4.4 启动验证与联调测试所有服务启动后按这个顺序验证。先看 Nacos 控制台的服务列表确认所有服务都注册上来了。服务名、IP、端口、健康状态都要对。如果有服务没注册上来检查bootstrap.yml里的 Nacos 地址和命名空间配置。然后测网关路由。用 curl 直接访问网关地址看能不能路由到下游服务curl -X POST http://localhost:8080/api/ai/chat \ -H Content-Type: application/json \ -H Authorization: Bearer token \ -d {sessionId:test-001,message:你好}如果返回 401说明鉴权过滤器生效了需要先获取 Token。如果返回 404说明路由配置有问题检查网关的路由规则。如果返回 503说明下游服务不可用检查服务是否正常启动。再测 AI 编排服务的模型调用。可以直接调用编排服务的接口绕过网关curl -X POST http://localhost:8081/ai/chat \ -H Content-Type: application/json \ -d {sessionId:test-001,message:你好,model:default}如果返回模型响应说明模型适配层工作正常。如果报超时检查模型 API 地址和网络连通性。如果报鉴权失败检查模型 API Key 配置。最后测向量检索。先插入一条测试数据再查询# 插入 curl -X POST http://localhost:8082/vector/upsert \ -d {id:doc-001,content:QuickBlue 是一个 AI 应用底座,embedding:[0.1,0.2,...]} # 查询 curl -X POST http://localhost:8082/vector/search \ -d {query:什么是 QuickBlue,topK:3}如果查询能返回刚插入的文档说明向量服务正常。如果返回空检查索引是否创建、维度是否匹配。5. 常见问题与排查技巧实录5.1 服务注册与发现类问题问题一服务注册不上 Nacos。最常见的原因是网络不通或命名空间配置错误。排查步骤先在服务器上telnet nacos-addr 8848确认端口通不通再检查bootstrap.yml里的namespace值是不是 Nacos 控制台上看到的命名空间 ID注意是 ID 不是名称最后看应用启动日志里有没有nacos registry相关的报错。问题二服务注册上了但调用不通。这种情况通常是网络策略或防火墙问题。Nacos 注册的是服务的内网 IP如果调用方和服务不在同一个网络环境就会调不通。解决办法是配置 Nacos 的ip参数显式指定服务注册的 IP。或者检查是否有安全组规则拦截了服务端口。问题三服务实例列表更新不及时。Nacos 默认的心跳间隔是 5 秒超过 15 秒没心跳会标记为不健康超过 30 秒会摘除。如果服务频繁上下线可能出现调用到已下线实例的情况。可以通过调整心跳间隔和超时时间来缓解但根本解决办法是保证服务稳定避免频繁重启。5.2 AI 调用类问题问题一模型调用超时。AI 模型调用耗时波动很大同样的请求可能这次 2 秒下次 20 秒。默认的超时配置往往不够用。建议把 AI 调用的超时时间单独配置比普通接口长一些spring: cloud: openfeign: client: config: model-client: connectTimeout: 5000 readTimeout: 60000connectTimeout是建立连接的超时readTimeout是读取响应的超时。AI 调用主要关注readTimeout建议设 60 秒以上。问题二流式输出中断。流式调用时如果网关或代理有缓冲会导致流式输出变成一次性输出。解决办法是在网关层关闭响应缓冲并设置正确的Content-Typespring: cloud: gateway: httpclient: response-timeout: 120s同时确保Content-Type是text/event-stream这样网关才知道这是流式响应不会做缓冲。问题三Token 消耗过快。这是成本问题也是技术问题。排查方向一是看上下文是不是太长了历史消息没有做裁剪二是看 Prompt 模板里是不是有冗余内容三是看有没有重复调用比如同一个请求调了两次模型。QuickBlue 提供了 Token 消耗统计可以按租户、按模型、按时间段查看消耗情况方便定位问题。5.3 向量检索类问题问题一检索结果不相关。原因可能是嵌入模型不适合当前语种或领域也可能是切片策略不合理。排查方法先拿几个典型问题手动测试看检索出来的片段是不是真的相关。如果不相关换一个嵌入模型试试如果切片太碎调整切片长度如果切片太长检索精度会下降。问题二检索速度慢。向量检索的速度跟数据量、索引类型、硬件配置都有关。百万级数据用 HNSW 索引单次检索应该在几十毫秒内。如果超过几百毫秒检查是不是用了 FLAT 索引或者 Redis 内存不足导致频繁换页。问题三向量维度不匹配。插入时用的嵌入模型维度和索引定义的维度不一致会导致插入失败或检索异常。解决办法是统一嵌入模型或者在索引定义时留出维度余量。QuickBlue 在启动时会校验嵌入模型维度和索引维度是否一致不一致会直接报错避免运行时才发现问题。5.4 高频问题速查表问题现象可能原因排查方向解决措施服务注册不上网络不通/命名空间错误telnet 端口、检查 namespace修复网络、修正配置调用超时超时配置过短查看 Feign 超时配置增大 readTimeout流式输出中断网关缓冲检查 Content-Type关闭缓冲、设 event-streamToken 消耗快上下文过长查看会话消息数裁剪上下文、精简 Prompt检索不相关嵌入模型不适配手动测试检索结果换模型、调切片策略检索速度慢索引类型不当检查索引定义改用 HNSW 索引向量维度不匹配模型与索引不一致检查维度配置统一维度或重建索引限流误伤规则太严查看 Sentinel 规则调整 QPS 阈值配置不生效配置未刷新检查 Nacos 配置手动刷新或重启虚拟线程无效果被 synchronized 固定检查代码中的锁改用 ReentrantLock实操心得排查 AI 应用问题时日志是第一手资料。QuickBlue 默认会记录每次模型调用的请求 ID、模型名称、Token 消耗、耗时。遇到问题时先根据请求 ID 把整条链路的日志串起来从网关到编排服务到模型调用看是哪一环出了问题。这个习惯能帮你省下大量猜测时间。6. 这套底座还能怎么扩展QuickBlue 作为 AI 应用底座基础能力已经覆盖了大多数企业场景。但每个企业的业务特点不同总有一些个性化需求。我分享几个常见的扩展方向都是实际项目中遇到过的。多模型 A/B 测试。同一个业务场景下想对比两个模型的效果和成本。可以在模型路由层加一个分流策略按用户 ID 哈希取模一部分走模型 A一部分走模型 B。QuickBlue 的模型路由接口支持自定义策略实现一个ModelRouter接口即可。Prompt 版本管理。Prompt 调整频繁时需要版本管理来追踪每次变更的效果。可以在 Prompt 模板表里加版本字段每次修改生成新版本旧版本保留。调用时可以指定版本号也可以默认用最新版本。配合 A/B 测试可以量化每个版本的效果差异。成本配额管理。企业里多个团队共用 AI 能力时需要按团队分配 Token 配额。可以在网关层加一个配额检查过滤器每次请求前检查该租户的剩余配额超了就拒绝。配额数据存在 Redis 里按天或按月重置。敏感信息过滤。AI 应用涉及用户输入和模型输出两头都可能包含敏感信息。可以在网关层做输入过滤在编排服务层做输出过滤。过滤规则可以配置化支持正则表达式和关键词列表。离线批量推理。有些场景不需要实时响应比如批量文档摘要、批量数据分类。可以加一个离线任务模块从消息队列消费任务批量调用模型结果写回数据库。这样可以把实时请求和离线任务分开互不影响。这些扩展方向不需要一次性全做按业务优先级逐步迭代即可。QuickBlue 的模块化设计让每个扩展都可以独立开发和部署不会影响现有功能。我在实际项目中的体会是先把核心链路跑通再根据实际需求做扩展比一开始就设计一个大而全的架构要务实得多。