企业官网建设流程全解析

Spring AI 多模态这块，我真正跑通第一个“看图说话”Demo的时候，说实话有点小激动。倒不是因为它多高深，而是我作为常年跟 Spring Boot 打交道的后端开发，第一次觉得“AI 接入”这件事不再需要绕道 Python，能在自己熟悉的依赖注入、配置项、Service 层里把图像理解功能串起来，那种顺手感是别的方案给不了的。

这篇文章我会把自己从零构建图像理解应用的过程完整拆开讲，包括为什么选 Spring AI、依赖怎么引、消息结构怎么理解、代码怎么写、实测踩了哪些坑，以及最后怎么往产品化方向扩展。各位 Spring 开发者，尤其是想在自己项目里快速接入多模态能力但不想换技术栈的朋友，这篇应该能帮你省不少弯路。

1. Spring AI 多模态到底解决了 Java 开发者的什么问题

先说个背景，我之前做某个内部工具时，需要一个“根据用户上传的图片自动生成标签和摘要”的能力。按老思路，要么单独写一个 Python 服务，通过 HTTP 和主项目对接，要么直接在 Java 里用 HTTP Client 硬调 AI 服务的 REST 接口。两条路都挺别扭的，Python 服务要维护两套部署、监控、日志体系；硬调接口更麻烦，请求构造、鉴权、JSON 解析、重试策略、异常处理全得自己造轮子。

Spring AI 的出现相当于把这一层脏活包了。它给 Java 生态带来了一套统一的接口抽象，让开发者操作的是“ChatModel”“Message”“Prompt”这些东西，而不是某个厂商 SDK 独有的数据结构。也就是说，你可以用近乎相同的一套代码，对接不同的模型服务商，切换的时候只需改动配置。

多模态方面，Spring AI 的切入点也很实在：既然大模型本身已经能理解图片，那 Java 侧要解决的本质问题就是——怎么把一张图片（或者图片 URL）以模型能接受的消息格式传进去，并且让模型返回文本描述。

实际上你深入用就会发现，Spring AI 的图像理解并没有做什么黑魔法，它做的事情就是：

• 把用户输入的文本和图片引用组装成多模态 Message
• 通过标准 ChatModel 接口发给模型服务
• 把返回的文本结果解包成你方便使用的对象

但这件事的意义在于“标准化的体验”。一旦你理解了这套抽象，后续无论是接不同的模型、调整模型参数，还是增加多轮对话能力，改动成本都被压得很低。这才是它作为“Spring 家族一员”最大的价值。

1.1 为什么说它比 Python 方案更适合 Java 团队

我见过不少团队，因为某个 AI 功能就强行走 Python，结果后期维护越来越痛苦。不是说 Python 不好，而是对一支 Java 背景的团队来说，无谓地引入第二种技术栈，知识分散、部署复杂、排障链路变长，很多时候是不划算的。

Spring AI 让 Java 团队可以继续待在熟悉的环境里。依赖注入帮你管理各个客户端实例，配置项统一放在application.yml，业务代码里通过 Service 封装一下，整个图像理解能力看起来就像调用自家普通接口一样。这对项目长期迭代、人员交接、代码审查都有实打实的好处。

1.2 它不擅长什么：提前说清楚边界

Spring AI 毕竟还是一套“接入层”框架，它不负责模型训练，也不提供图形界面，更不可能帮你把图片识别准确率提升多少。如果你要的是那种像素级分割、目标检测框这种传统 CV 能力，Spring AI 目前并不是干这个的。它擅长的场景是“让多模态模型理解图片内容、生成自然语言描述”，也就是理解层面，而不是视觉算法层面。

搞清楚了这条边界，至少你不会拿着它去做工业质检，然后在项目里撞得头破血流。

2. 环境准备：依赖版本、API Key 与基础配置的一次性说明

开始写代码之前，先把环境理清楚。很多人在 Spring AI 上卡住，其实不是代码问题，而是版本没对上，或者配置缺胳膊少腿。

我用的环境是：

• JDK 17
• Spring Boot 3.2.x
• Spring AI 1.0.0-M6 系列（当时最新的里程碑版本）

这里特别提醒一点，Spring AI 的版本迭代比较快，API 在不同版本之间可能有微调。如果跟我用的版本不一样，个别类名或方法签名对不上，别慌，以官方文档对应版本的 javadoc 为准即可。

2.1 Maven 依赖怎么引才干净

图像理解功能，核心依赖就两个：

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.0.0-M6</version> <type>pom</type> <scope>import</scope> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> </dependency>

这段配置看起来简单，但有个细节容易被忽略：spring-ai-bom要以import方式放进dependencyManagement，不然子依赖版本会乱。另外，如果你用的是 Spring Boot 3.2，对应的 Spring Cloud 版本也得匹配，否则启动时可能因为上下文刷新失败报错。

我踩过的一个版本坑是：Spring Boot 3.1 + Spring AI 早期版本时，自动装配偶尔会出现冲突，换成 3.2 之后就稳定多了。所以如果你是新项目，建议直接上 Spring Boot 3.2+，别在旧版本上纠结。

2.2 application.yml 配置的艺术

Spring AI 的配置遵循 Spring Boot 的“约定优于配置”哲学，大部分东西都能塞进application.yml：

spring: ai: openai: api-key: ${AI_API_KEY} base-url: ${AI_BASE_URL:https://api.example.com} chat: options: model: gpt-4o-mini temperature: 0.2 max-tokens: 2048

这里我刻意把api-key和base-url都做成了环境变量占位符。原因很简单：密钥绝对不能硬编码提交到仓库，哪怕是你自己的私有项目，养成用环境变量或配置中心注入的习惯，将来才不会出事故。

base-url这个东西我是强烈建议显式配置出来的。因为不少国内团队访问服务商接口可能遇到网络延迟问题，需要通过合规的网络通道或代理转发，这时候一个显式的base-url就是你的救命稻草——直接在配置层切换网关地址，代码一行不用改。

2.3 校验服务可用性的三个步骤

依赖引完、配置填好之后，别急着写业务代码，先花一分钟验证链路是否通：

1. 启动 Spring Boot 应用，观察日志里有没有OpenAiChatModel相关的 Bean 创建成功。
2. 在配置类里注入ChatModel，写一个临时的ApplicationRunner，跑一句最简单的“你好”。
3. 确认拿到响应之后，再删掉测试代码。

这样分三步走，能让你把“环境问题”和“代码问题”彻底切开。很多人一上来就做完整业务页面，结果出了错也分不清是配置的锅还是逻辑的锅，排查效率极低。

3. 核心机制拆解：图片是怎么被“塞”进对话的

图像理解最关键的一环，是理解 Spring AI 的消息（Message）结构。进入多模态之后，你面对的不再是单纯的“字符串进，字符串出”，而是一套内容类型更丰富的消息体系。

简化理解：聊天模型接收的不是一个 String，而是一个Message列表。Message又分为不同的角色（系统、用户、助手），其中用户消息可以包含多个Media对象，每个Media就是一张图片或一段音频。

3.1 从 Prompt 到 ChatModel 的完整调用链

搞清楚调用链，代码怎么写你心里就有底了：

1. 构造Media对象，传入图片 URL 或二进制数据、MIME 类型。
2. 构造UserMessage，把文本指令和Media列表塞进去。
3. 把UserMessage放进Prompt，还可以带ChatOptions设置采样参数。
4. 调用ChatModel.call(prompt)，拿到ChatResponse。
5. 从ChatResponse里提取Generation，也就是模型的文本回复。

这套链路本质上跟文本对话是一致的，区别只在于第 1 步——图片内容作为Media打进了用户消息里。这一点想通了，后面所有花样都是在这个骨架上做文章。

3.2 ImageUrl 与字节流：两种图片传入方式及应用场景

Spring AI 的多模态消息里，图片通常是作为Media对象出现的。而Media的数据来源有两种：

• URL 方式：适用图片已经托管在公网/内网可访问地址上。比如电商商品图、用户头像、内容平台图片链接。这种方式请求体积最小，AI 服务端会自行拉取图片。
• Base64 方式：适用本地文件、前端上传的字节流、带鉴权的私有图片。先把图片字节编码成 Base64，塞进Media的 data 字段。

我实际用下来，二者的选择逻辑很简单：如果图片已经是一个可访问的 URL，用 URL 方式最省事；如果是用户刚从手机上传的新鲜图片，强烈建议转 Base64，让服务端直接解析。

为什么？因为“用户上传的临时图片”往往没有公网地址，或者图片服务有防盗链，如果你把 URL 传给 AI 服务端去拉，可能会遇到 403 或者拉取超时。Base64 方式则没有这个烦恼，唯一的代价是请求体变大、Token 计算略高一些。

3.3 Token 消耗概念：一张图到底吃掉多少预算

很多人不重视 Token 概念，到了账单结算的时候才傻眼。图像理解请求除了文本 Prompt 要占 Token，图片本身也要按视觉 Token 计费。

以当前主流多模态模型为例，一张 1024x1024 的图片大概会折算成 1000+ 视觉 Token，这跟模型的具体视觉编码器有关，不同模型差异很大。如果是更高的分辨率，Token 消耗会成倍上涨。

所以我在实际项目里总结了一条铁律：能传低分辨率图就别传高分辨率图，能传局部就别传全图，能一次传一张就别传十张。很多时候，识别“这是什么东西”只需要一张 512x512 的缩略图就够了，没必要拿原图去烧 Token。

4. 实战编码：一个“看图识物+属性描述”的完整示例

理论聊了一堆，现在进入大家最关心的环节：代码到底怎么写。

我这里写一个相对贴近真实场景的示例：接收前端上传的美食图片，返回菜名、主要食材、口味特点三段结构化描述。

4.1 服务层：封装图像理解组件

先定义一个 Service，把与 AI 交互的逻辑藏起来，业务代码不直接碰 Spring AI 的消息结构。这样将来哪怕底层换了模型服务，业务层纹丝不动。

@Service public class ImageAnalysisService { private final ChatModel chatModel; public ImageAnalysisService(ChatModel chatModel) { this.chatModel = chatModel; } public String analyzeFoodImage(byte[] imageBytes) { Media imageMedia = Media.builder() .mimeType(MediaType.IMAGE_JPEG) .data(imageBytes) .build(); String instruction = """ 请仔细观察这张美食图片，用中文回答。 回答格式必须严格按照以下三行输出： 菜名:（不超过15个字） 主要食材:（用顿号分隔） 口味特点:（用一句话描述） """; UserMessage userMessage = new UserMessage(instruction, List.of(imageMedia)); Prompt prompt = new Prompt(userMessage); ChatResponse response = chatModel.call(prompt); return response.getResult().getOutput().getText(); } }

这里有三个值得说道的细节：

• MIME 类型必须和实际图片格式一致。如果前端传的是 PNG，你却写 IMAGE_JPEG，服务端可能解码失败。所以最好根据图片魔数判断格式，或者让前端在表单里带上类型，而不是写死。
• 指令文本写得越结构化，返回越可控。上面这段指令明确规定了“三行输出”“格式必须严格”，实际测试下来的回答规范性远超“帮我看看这张图是什么”这种开放式提问。
• ChatResponse的数据结构里，getResult()拿到的是第一个生成结果。如果你设置了 n=2 之类采样多个回答的参数，那就要自行选择取哪个，默认情况下一个就够。

4.2 控制器：接收上传并返回分析结果

Controller 层没什么花活，就是一个文件接收：

@RestController @RequestMapping("/api/image") public class ImageController { private final ImageAnalysisService imageAnalysisService; public ImageController(ImageAnalysisService imageAnalysisService) { this.imageAnalysisService = imageAnalysisService; } @PostMapping(value = "/analyze-food", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) public ResponseEntity<String> analyzeFood( @RequestPart("file") MultipartFile file) throws IOException { if (file.isEmpty()) { return ResponseEntity.badRequest().body("文件不能为空"); } String result = imageAnalysisService.analyzeFoodImage(file.getBytes()); return ResponseEntity.ok(result); } }

实测下来，调用这个接口的完整请求链路是：前端选择图片 → MultipartFile 收到字节 → 转成 Media → 发给模型 → 返回文本。整个过程对前端来说就是一个普通的 POST 上传接口，完全感知不到 AI 的存在。这种“把 AI 藏在 Service 层后面”的做法，我认为是最适合现有 Java 项目的集成方式。

4.3 一个容易翻车的位置：图片格式判定与异常兜底

刚才提到 MIME 类型不能写死，我补一个能自己判断格式的工具方法：

private String detectImageType(byte[] bytes) { if (bytes.length < 12) { throw new IllegalArgumentException("无效的图片数据"); } if (bytes[0] == (byte) 0xFF && bytes[1] == (byte) 0xD8) { return MediaType.IMAGE_JPEG; } if (bytes[0] == (byte) 0x89 && bytes[1] == (byte) 0x50) { return MediaType.IMAGE_PNG; } if (bytes[0] == (byte) 0x47 && bytes[1] == (byte) 0x49) { return MediaType.IMAGE_GIF; } throw new IllegalArgumentException("仅支持 JPEG/PNG/GIF 格式"); }

这个方法的原理就是读取文件头两个字节的“魔数”。JPEG 开头固定是FF D8，PNG 开头是89 50，GIF 开头是47 49。用这个比前端传的contentType可靠得多，因为前端那个值是可以被伪造或者漏传的。

另外在实际代码里，我还会给chatModel.call包一层 try-catch，捕获超时和限流异常，返回一个可读的错误提示。虽然 Spring AI 自带重试机制，但对于“用户上传图片并等待结果”这种场景，我更倾向于快速失败，而不是让用户一直转圈。

5. 实测中的三类高频问题：排查链路复盘

代码写出来了，但这篇文章如果不把踩过的坑写出来，价值就要打对折。我整理了三类我在实际测试过程中遇到最多的问题，每个都附带排查思路，希望能帮你节省时间。

5.1 图片传了，模型却说“我看不到图片”

这是新手最容易遇到的错误，表现是：接口返回正常，但模型的回答接近“我没有收到图片，请重新上传”之类的内容。

排查链路是这样的：

第一步，检查自己发送的消息结构。把UserMessage.getMedia()打印出来，确认 Media 数量是 1 而不是 0，确认 data 字段不是 null。很多时候问题出在你构造 Media 的时候，图片数据本身是空的，但序列化时没有报错，导致模型服务端收到一个空壳。

第二步，确认 MIME 类型与真实格式匹配。如果图片是 PNG，但你声明成 JPEG，部分模型服务会解析失败或忽略这张图。这个我在前面已经强调过，务必用魔数判断。

第三步，如果是 URL 方式传图，确认图片地址对模型服务端“可见”。你用本地浏览器访问 URL 没问题，不代表模型服务端能在它的网络环境里访问到。内网图片、带鉴权的图片、防盗链的图片，都会导致拉取失败。遇到这种情况，换 Base64 方式传字节是最稳的。

5.2 响应超时：视觉模型吃的时间比想象中多

文本对话通常 1-2 秒就回来了，但图像理解的响应时间明显更长。我第一次测试时，前端设置的超时时间是 5 秒，结果频繁抛超时异常。

根因有两层：图片传输需要时间，图片视觉编码需要时间，两者叠加导致整体响应变慢。如果传的是 Base64 大图，比如一张 5MB 的照片，请求体就有七八兆，光上传就要好几秒。

我的解决办法是两个：

1. 在后端收到图片后，先做一个降采样，把图片尺寸缩到最长边 1024 像素以内，再编码 Base64。这样请求体大幅缩小，模型服务端处理速度也快。
2. 前端请求超时时间放宽到 15-30 秒，并在界面上做 loading 状态提示。毕竟用户体验这件事，你不能既想要 AI 识别，又苛求它像普通接口一样秒回。

5.3 同样的图，每次返回结果不一样？那是温度参数在作怪

还有一个让我当时有点崩溃的现象：连续两次调用同一个接口、传同一张图片，返回的描述竟然有差异。一开始我以为是缓存问题，排查了半天发现是温度（temperature）参数在起作用。

温度参数控制模型生成的随机性，值越低，回答越保守、稳定；值越高，越发散、有创意。默认值可能是 0.7 左右，这个值对文本聊天挺合适，但对“图像描述”这种有标准答案倾向的任务就偏高了。

我的做法是把temperature调低到 0.1-0.2，甚至直接设 0。效果立竿见影，多次返回的结果一致性明显提高。如果你要做的是商品信息识别、光学字符识别这类需要稳定输出的场景，这个参数务必调低。

6. 从 Demo 到产品：图像理解能力的三个进阶方向

跑通 Demo 只是漫漫长路的第一步。真正要把图像理解能力变成产品里一个可靠的功能，我建议从下面三个维度扩展。

6.1 多轮对话：让用户和图片“聊起来”

静态分析一次只能返回一个结果，但用户的需求往往是交互式的。比如上传一张户型图，先问“这是几室几厅”，再追问“厨房在哪里”“承重墙在哪”。

Spring AI 跟做多轮文本对话的方式是相通的。核心思想是维护一个消息历史列表，每次把用户的新提问、之前的对话记录、图片 Media 一起发给模型。

public ChatResponse chatWithImage(String userInput, ImageMedia imageMedia, List<Message> history) { UserMessage newMessage = new UserMessage(userInput, List.of(imageMedia)); List<Message> messages = new ArrayList<>(history); messages.add(newMessage); Prompt prompt = new Prompt(messages); return chatModel.call(prompt); }

这里要注意的是：多轮对话的消息历史会在每次请求时重复传给模型，Token 消耗会线性增长。一个实际项目如果场景是长对话，就要考虑是否只保留最近几轮，或者把历史图片做模糊/裁剪处理降低 Token 消耗。

6.2 结构化输出：别再靠提示词硬抠 JSON

我最初的美食识别示例返回的是纯文本三行描述，但如果要做成结构化数据，比如直接返回 JSON 给前端渲染，更优雅的方式是让模型直接输出 JSON，并利用 Spring AI 的实体解析能力做类型转换。

我常用的做法是加上输出格式约束，把指令改成“只输出 JSON，不要包含任何其他文字”，然后通过StructuredOutputConverter把文本转成 POJO。这比在业务代码里自己解析字符串要稳得多，因为模型输出的格式可控性再强，也难免偶尔多打一个逗号或者加一句解释，纯手写解析就很容易炸。

6.3 结合向量检索：让图片分析拥有“长期记忆”

如果你做的不是一次性分析，而是希望系统在面对新图片时能参考之前分析过的类似图片，那就值得引入向量数据库。

思路是这样：每次分析完一张图片，除了返回文本描述，还把这段描述向量化存入数据库；下次来了新图片，先在向量库里找到最相似的若干历史描述，作为上下文拼进 Prompt，再让模型基于“历史类似样本 + 当前图片”做分析。这能让识别结果更贴合你自己的业务领域，等于给通用模型加了一层领域经验。

我之前在某公司做商品识别类功能时，就是用这个思路让模型对一批特殊品类产品的敏感属性识别率有了明显提升。当然，这块的前提是你确实有大量符合业务特征的图片样本可以沉淀。

6.4 成本控制：流式输出、缓存与降级策略

产品上线之后，成本控制是绕不开的话题。流式输出是第一个推荐做法——模型边生成边返回，用户等待的感知时间会大幅缩短，虽然总体 Token 消耗不变，但用户体验完全不同。Spring AI 里相应的ChatModel.stream能直接拿到Flux流。

另一个方向是做结果缓存。同一张图片可能被不同用户反复发送分析，比如商品主图，这时候完全可以在图片哈希维度和文本结果上做一层 Redis 缓存。实际业务中命中率相当可观，能省下不少调用量。

最后是降级策略。如果 AI 服务发生故障或超时，至少要有一个兜底提示，而不是让用户看到满屏报错。我之前在项目里就直接用搜索引擎的图片描述兜底的方案，虽然效果粗糙，但至少不会让用户拿到一个白页面。

最后再分享两个关于 Spring AI 实践的小技巧

第一个技巧是关于测试的。写图像理解代码的时候，不要每次测试都用真实图片调模型接口，一方面费 Token，另一方面网络抖动会干扰你的调试。我的习惯是先在本地准备一张固定的测试图，再 mock 掉ChatModel，返回一段预设文本，先把 Controller 到 Service 的逻辑跑通，最后再连真模型做集成测试。这样能把“链路问题”和“模型问题”分开排查，效率翻倍。

第二个技巧是关于升级的。Spring AI 这个项目本身爬坡速度极快，每次版本升级都要留出半天到一天时间做回归验证。重点检查两个位置：自动装配类有没有改名，ChatResponse和Generation的 API 有没有变化。我遇到过只升了一个小版本，结果new UserMessage(instruction, List.of(media))这个构造函数就废弃的情况，连编译都过不去。所以升级前先看看官方 changelog，心里有个底。

图像理解应用是最容易让产品“看起来变聪明”的能力之一。对一个 Java 开发者来说，Spring AI 把进入门槛降到了“会写 Service 就能接”的程度。你真正需要考虑的，反而是业务上怎么定义图片分析的目标、怎么设计指令文本、怎么控制成本和稳定输出。很多项目最终没做好，不是因为技术不够，而是因为对这些“AI 之外的事情”想得不够多。花点时间在这上面，比换一个更贵的模型实在得多。