企业官网建设流程全解析

做了一年多的AI应用集成，我越来越觉得 Spring AI Alibaba 这套东西的价值被低估了。上篇聊完基础接入和 Prompt 工程的坑之后，这篇我打算把真正决定项目能不能从 Demo 走向生产的那些事一次性交代清楚：模型调用的细节参数、AIService 的封装、RAG 落地的向量检索、以及生产环境里那些日志和异常处理的门道。这些都是我用真金白银的线上故障换回来的经验，希望能帮你少走点弯路。

1. 上篇聊完接入和 Prompt，这篇聊聊真正决定生产可用性的东西

先对齐一下上篇的内容范围。上一篇我们把 Spring AI Alibaba 的起步动作做完了：Spring Boot 项目引入spring-ai-alibaba-starter、配好通义千问的 API Key、用ChatClient跑通了第一个对话、还把 Prompt 模板和多轮会话的基础概念过了一遍。如果你是从零开始，那上篇的内容足够让你把对话框转起来。

这篇就不再重复那些入门内容了，我默认你已经具备以下基础：

• Spring Boot 项目能正常引入依赖并启动
• ChatClient能发起单轮对话，知道call()和stream()的区别
• 对Prompt、Message这些核心对象有基本的认识
• 知道通义千问的模型名称（如qwen-plus、qwen-turbo）和基本参数

这篇文章，我围绕四个核心主题来写：

1. 从硬编码到可配置的工程化改造—— 把模型参数、超时、重试这些细节管起来，别让 AI 调用成为线上事故的隐患
2. 用@AIService把 AI 能力变成业务方法—— 这才是 Spring AI 最优雅的用法，比到处调ChatClient高级得多
3. RAG 落地过程中的真实经验—— 文档解析、向量化、检索排序这些环节，我踩过的坑比你想象的多
4. 生产环境的观测与排查—— 日志、Token 统计、异常分类，让你的 AI 功能真的敢上线

话不多说，进入正题。

2. 模型调用细节：把超时、重试和参数控制从默认值里捞出来

很多初学者拿到 Spring AI Alibaba 就默认用ChatClient的默认配置，结果一上生产就出事。默认配置只能保证"能跑通"，不能保证"跑得稳"。这一章节，我们聚焦模型调用层面的工程化改造。

2.1 先从模型的参数调优说起

通义千问在 Spring AI Alibaba 里常用的几个参数，我用一张表整理出来，这些都是我在实际项目中反复调过的：

这里必须多说两句temperature。很多人把它理解为"创造力"，其实不对。temperature控制的是采样概率分布的平滑程度，值越高，模型越倾向于从概率较低的候选词中做选择，所以看起来"更有想象力"；值越低，模型就越只选择最高概率的那个词，输出更确定。

我做过一次真实对比：用同一个问题"查一下订单表中金额最大的三笔订单，并生成 SQL"，temperature=0时，模型稳定输出ORDER BY amount DESC LIMIT 3；当我把temperature调到 0.9 之后，结果里开始出现WHERE amount IS NOT NULL ORDER BY amount DESC这类"看似更严谨但其实无关紧要"的 SQL。对于代码生成、SQL 生成、信息抽取这类确定性要求极高的场景，temperature请直接压到 0.2 以下。

2.2 超时和重试：不加这两个配置，模型接口分分钟压垮你的链路

Spring AI Alibaba 底层调用的是通义千问的 HTTP 接口，网络抖动、模型推理排队都在所难免。默认的超时时间偏乐观，生产环境必须显式配置。

spring: ai: alibaba: qwen: chat: options: model: qwen-plus temperature: 0.4 http-client: read-timeout: 60s connect-timeout: 10s

注意，这里的read-timeout我给了 60 秒。通义千问在生成长文本时（比如总结一份 2000 字的文档），推理时间超过 30 秒是很正常的。如果你把read-timeout设成 10 秒，你会发现"偶发超时"特别多，而且大多数不是模型出了问题，是客户端等得不耐烦先放弃了。

重试方面，我的经验是两个原则：

• 幂等请求才重试。如果用户的请求是查询类的，重试没问题；如果是下单、支付回调这类写操作，重试可能会导致重复执行，必须配合幂等键。
• 重试要有退避。别用固定间隔。Spring 的@Retryable直接支持指数退避，我调过一轮参数之后觉得maxAttempts=3, multiplier=2是比较稳的组合：第一次失败 1 秒后重试，第二次失败 2 秒后重试。再往后就不重试了，直接走降级逻辑。

2.3 用ChatOptions实现按场景切换配置

前面说的参数，如果你写死在application.yml里，你会发现不同业务场景很难平衡。比如客服问答场景希望temperature=0.3，文案润色场景希望temperature=0.8，这两者没法共用一套全局配置。

Spring AI Alibaba 针对这个场景提供了ChatOptions对象，你可以在每次请求时覆盖默认配置：

var options = ChatOptions.builder() .model("qwen-plus") .temperature(0.3) .maxTokens(512) .build(); var response = chatClient.call( Prompt.builder() .messages(List.of(SystemMessage.builder() .text("你是一名严谨的客服助手，回答必须基于给定知识库内容，不得自行编造。") .build())) .options(options) .build() );

这样，全局application.yml里只保留兜底配置，业务侧的差异通过代码动态控制。你想按用户等级给不同模型也行：免费用户用qwen-turbo（便宜），付费用户用qwen-max（更强）。

提示：动态切换模型的逻辑封装成一个ModelRouter组件，能省掉很多重复代码。后面我在第 4 节会提到完整的服务封装方案。

3.@AIService：当你不再满足于"调接口"的时候，用它把 AI 变成方法

我觉得 Spring AI 全家桶里最被低估的就是@AIService。它相当于把"模型调用"这一层彻底屏蔽掉，让你像写普通方法一样写 AI 能力。

3.1 从ChatClient到@AIService，到底改了什么

ChatClient你每次都要手动拼Prompt、拼Message、处理ChatResponse，这套流程确实灵活，但也啰嗦。更麻烦的是，业务代码里到处是chatClient.call(...)的痕迹，你在代码评审的时候一眼就能看出"这里调了 AI"，时间长了代码里全是这种碎片化的调用，职责边界很模糊。

@AIService从根本上改变了这个局面：你定义一个接口方法，框架帮你完成 AI 调用、参数绑定、结果解析，你拿到的就是干净的 Java 对象。

@AIService public interface CustomerAssistant { @SystemMessage("你是一名资深的电商客服，回答需要专业、简洁，并基于给定上下文。") String reply(@UserMessage(""" 用户的问题是: {question} 请先判断问题是否在以下知识范围内: {knowledge} 如果不在，请直接回复"这个问题我暂时无法回答"。 """)); }

关键在于方法参数上的@UserMessage模板：用{question}这种占位符把方法参数映射进 Prompt，模型根据这个结构化的 Prompt 输出结果。

3.2 返回结构化对象的正确姿势

String reply(...)这种形式是最简单的。真正提效的场景是让 AI 返回结构化对象——比如做意图识别。传统做法是让模型输出 JSON，你再解析 JSON，Handle 各种格式错误。@AIService直接支持把输出映射成对象：

@AIService public interface IntentRecognizer { @SystemMessage("分析用户意图，并按给定的JSON结构返回。") IntentResult analyze(@UserMessage("用户输入: {input}")); record IntentResult(String action, String category, int confidence) {} }

你没看错，方法返回类型直接就是IntentResult。Spring AI Alibaba 在底层会让模型先输出 JSON，再用 Jackson 反序列化。这里有个小细节：record类型也能正常映射，不用额外写 DTO。

这里有个性能上的注意事项：让模型输出结构化 JSON 意味着maxTokens要留足余量，另外temperature必须调低（0.2 或更低），否则模型可能会输出合法但不满足字段约束的 JSON。

3.3@AIService的鉴权与复杂 Prompt 场景

@AIService上的方法也能灵活变通。有些业务需要带鉴权信息——比如查询用户私有数据。

@AIService public interface PersonalAssistant { @SystemMessage("你是个人助理，必须根据提供的用户信息回答。") String chat( @UserMessage(""" 用户姓名: {name} 用户标签: {tags} 用户历史问题: {history} 当前问题: {question} """), @MemoryId String userId); }

注意这个@MemoryId String userId，它用来区分不同用户的会话记忆。这样同一个 Assistant 服务可以为多个用户服务，各自的对话记忆互相隔离。这个能力在多租户系统里非常有用，否则你就要自己手动管理不同用户的会话上下文，复杂度立马翻倍。

实际业务中还有一个高频需求：给 AI 指定"能做什么、不能做什么"。

@AIService public interface OrderAssistant { @SystemMessage(""" 你是订单助手。你可以查询订单信息。 当用户试图修改或删除订单时，必须礼貌拒绝。 所有回复必须在 50 字以内。 """) String handle(@UserMessage("用户消息: {message}")); }

这类"行为约束型" Prompt 在纯ChatClient时代你要么写在代码常量里，要么通过SystemMessage.builder()传入。用了@AIService之后，约束直接写在注解里，业务方法面和 Prompt 绑得更紧，队友看代码直接理解意图，维护成本直线下降。

4. RAG 落地：从"能跑通"到"回答靠谱"，中间隔着一堆细节

RAG 是 Spring AI Alibaba 里最实用但也最容易"看起来会了、实际效果很差"的功能。我见过太多人跑通了官方 Demo，觉得"我有了一个问答机器人"，结果换了自己的文档之后，回答开始驴唇不对马嘴。这一节我把 RAG 的几个关键环节逐个拆开。

4.1 文档解析：你的 PDF 真的被正确读了吗

RAG 的第一步是把知识库文档变成向量存起来。而向量化的质量，直接取决于你的文档解析效果。

Spring AI Alibaba 提供了DocumentReader接口，针对 PDF、Word、HTML 都有实现。但一个很现实的坑是：如果你的 PDF 是扫描件（纯图片），内置 Reader 读出来全是空字符串或者乱码。text/plain都不是，是图像。

这种情况你需要配合 OCR。我用过的组合是：

• 常规数字型 PDF（合同、报告、论文）—— 阿里云的文档智能或本地 PDF 解析库都行
• 扫描件 PDF —— 必须先走 OCR，推荐对接现成的 OCR 服务，识别准确率能到 95% 以上
• Excel 表格 —— 推荐转成 Markdown 表格再去向量化，保留结构信息有利于检索

一个非常关键但经常被忽略的点：对文档做分块（chunking）时，块的大小和重叠度直接决定检索命中率。我的经验参考：

分块太小，语义被切碎；分块太大，混入无关信息导致检索不精准。这个没有绝对标准，但你可以先用我的推荐值起步，再根据实际效果微调。

4.2 向量化和检索：别迷信单模型，混合检索才是王道

Spring AI Alibaba 内置的向量存储抽象做的很干净，你可以无缝对接本地向量库、也可以对接云上的向量检索服务。但选型只是第一步，真正决定检索质量的是 embedding 模型和检索策略。

我自己在项目里踩过最大的坑就是：只用向量检索，召回率看起来不错，但精确率一塌糊涂。

比如用户在问"订单超时怎么退款"，向量检索可能找到一堆和"超时""退款"语义相近的文档，但其中一半其实是售后政策里讲"超时未支付订单自动关闭"的内容。这时如果结合关键词检索（BM25）做一个混合召回：

• 向量检索负责召回语义相近的文档
• 关键词检索负责兜底命中的精确词条
• 两者结果取并集再按相关度排融合

Spring AI Alibaba 的VectorStore是抽象层，你要实现混合检索需要自己写一点编排代码。我的做法是把向量检索结果和关键词检索结果都拿回来，手动设置权重做加权求和：

public List<Document> hybridSearch(String query, int topK) { var vectorHits = vectorStore.similaritySearch( SearchRequest.builder() .query(query) .topK(topK * 2) .build()); var keywordHits = keywordSearch(query, topK * 2); // 用 BM25 实现的检索 // 合并去重，按权重汇排 return mergeByRrf(vectorHits, keywordHits, topK); }

关于 RRF（Reciprocal Rank Fusion）权重，我的经验值是 60（向量）比 40（关键词），对中文文档来说，语义相关性比词汇重合更重要些，但也不能完全丢掉关键词。

4.3 检索之后的"重排"：检索对了不等于回答对了

很多人做 ADD / RAG 做到「检索文档 + 拼接进 Prompt」就结束了。实际上，真正提升回答准确率的，是检索之后的重排（Re-rank）环节。

原因很简单：Top K（比如 5）的文档里，可能只有 2 条真正有用，其他 3 条是"干扰项"。如果直接把 5 条全塞进 Prompt，模型会被噪音干扰，出现答非所问。

Spring AI Alibaba 目前没有内置重排器，但你可以通过它的DocumentSelector或者自定义逻辑来做。我的做法是：

1. Top K 扩大到 10
2. 用一个精排模型按用户问题计算相关性分
3. 只取分数最高的 3~4 条，拼接进 Prompt

这看起来多了一步"多余计算"，但实际效果差距极大。我做过对比：不加重排时回答正确率约 62%，加完后能到 85% 以上。

注意：重排会消耗额外的模型调用（或 API 配额），对高并发场景有成本压力。我们的线上策略是：普通问题不做重排，复杂问题（由意图识别判断为推理类）才触发重排。

5. 生产环境里那些磨人的问题：日志、Token 统计与链路追踪

AI 功能和传统接口一样，上了生产之后你面临的问题就完全变了——不再是"怎么让它跑通"，而是"出了问题怎么快速定位"。

5.1 让日志记录"人话"：把 Prompt 和响应都打印出来

AI 应用的排障难在不确定性。同样的输入，模型可能给出不同输出。一旦用户反馈"AI 回复很奇怪"，你如果没有记录当时的 Prompt 和响应，排查基本靠猜。

我的做法是在关键调用点埋结构化日志：

log.info("[AI_REQUEST] user_id={}, scene={}, model={}, temperature={}, prompt={}", userId, scene, modelUsed, temperature, promptText); log.info("[AI_RESPONSE] user_id={}, scene={}, finish_reason={}, output_tokens={}, response={}", userId, scene, finishReason, outputTokens, responseText);

这样做的好处是：用户投诉时，你能直接按user_id + 时间范围检索出模型当时看到的完整上下文，迅速判断是 Prompt 写的有问题、知识库没召回对、还是模型本身抽风。

日志切不可把敏感信息（手机号、身份证、地址）原样打印。生产环境我们做了脱敏过滤，统一替换成***再输出。

5.2 Token 统计：别让 API 成本悄悄吃掉利润

模型调用的计费是基于 Token 的，如果你不统计，月底账单会让你肉疼。Spring AI Alibaba 的ChatResponse里有 Token 使用情况，我在统一封装层里做了拦截统计：

public ChatResponse callWithStats(Prompt prompt) { var response = chatClient.call(prompt); var usage = response.getMetadata().getUsage(); statsCollector.record( prompt.getModel(), usage.getPromptTokens(), usage.getCompletionTokens() ); return response; }

这个统计结果落到监控看板上，每日观察三个指标：

1. 不同业务线的日均 Token 消耗
2. 单次请求的平均响应 Token 数（如果明显升高，可能 Prompt 或模型配置被改过）
3. 缓存命中率（下面单独说）

成本优化层面最实用的招是响应缓存。对于 FAQ 类场景，相同问题在一天内会被问很多遍。我引入了一层 Redis 缓存：以「Prompt + temperature」作为 key，缓存响应结果，TTL 设为 15 分钟。实测缓存命中率约 30%，意味着省掉了近三成的模型调用费用。由于temperature低（0.2 左右）时输出本身就接近确定性，缓存适用性很高；高temperature的场景不建议缓存，会破坏随机性。

5.3 异常分类与降级策略：模型也有拉胯的时候

模型接口的异常，不能统统抛给上层。我把它们分成了三类分别处理：

降级策略我分两层：线上（非核心场景）—— 直接返回预设的兜底回复"我暂时无法处理，请稍后再试"。核心场景（如交易类）—— 转为人工客服处理队列。

提示：Spring AI Alibaba 里的模型调用都有对应的异常类，你可以在@ControllerAdvice里全局拦截，集中做异常到降级策略的映射。

6. 我踩过的坑和最后推荐的项目结构

最后，把项目里AI相关的代码结构分享出来，这是我在两个生产项目里落地并验证过的组织方式，按这个结构来，你的代码在增长之后不会乱成一锅粥。

com.example.ai ├── controller/ # 暴露 HTTP 接口，只做参数接收 ├── service/ # 业务编排，如意图识别 + RAG + 重排 ├── assistant/ # @AIService 接口，Prompt 集中在注解里 ├── vector/ # 向量检索、混合检索的封装 ├── stats/ # Token 统计、成本报表 └── config/ # 模型配置、超时、缓存、重试策略

这种分层的核心思想是：

• Controller 层不出现任何ChatClient或@AIService的影子，它只管 HTTP 参数
• Service 层是唯一允许"编排 AI 能力"的地方，比如先意图识别、再查知识库、再决定是否追问
• Assistant 层是纯声明式接口，Prompt 全部内聚在注解里，方便统一 review 也方便替换
• Vector 层单独独立，因为后续大概率要换不同的向量库或加重排逻辑

最后说几个我在实际运行中总结的经验：

第一，别在一个方法里同时用ChatClient和@AIService。混用会让代码风格极其混乱。选一个主力风格，另一种只是应对灵活场景的补充。

第二，AI 能力一定要做开关。通过配置中心动态控制某个功能是否走 AI 还是走兜底逻辑。有一次模型服务商那边出了故障，我们临时切了降级开关，业务完全无感。你要是没做开关，就只能紧急发版。

第三，所有 Prompt 的修改必须有版本记录。我们用配置中心管理 Prompt 模板，每次改动都在变更记录里留痕。当某个 Prompt 改动导致线上回答质量明显下降时，可以快速回滚到上一个版本。很多团队出了问题只能"懵"，就是因为 Prompt 散落在代码里，根本追溯不了改动历史。

说实话，Spring AI Alibaba 起步很快，但真正把它用明白，靠的还是工程化思维：参数管起来、异常分好类、日志打全、Prompt 可追溯、结构保持干净。这些经验不是从文档里能直接学到的，都是线上一点点磨出来的。希望对你有用。