先说结论Spring AI Alibaba 1.x 系列在接入多模态模型时整体思路和 OpenAI 协议的兼容性做得很到位但细节坑非常多尤其是1.0.0-M6.1这个版本如果你照着官方文档敲大概率会在图像消息结构、模型名称映射、结构化输出这三个地方卡住。这篇文章不是官方文档的复述是我自己在一个真实项目中从零接入通义千问 VL、在 Spring AI Alibaba 框架里跑通图生文、图文对话、以及结构化抽取的完整记录。我会把项目背景、依赖选型、核心代码、配置参数、以及我实际踩过的每一个坑都写清楚文章偏实战适合正在用 Spring Boot 3.x JDK 17/21 做 AI 应用集成的开发者尤其是那些想用 Java 统一对接多模态模型、又不想被各家 SDK 绑死的团队。如果你目前还在用 LangChain4j 或者裸调 HTTP 接口这篇文章也能给你一个对比视角。1. 项目整体设计与技术选型思路1.1 为什么选 Spring AI Alibaba 而不是直接调 HTTP我们这个项目要做的不是一个 demo而是一个生产级的文档智能审核系统。核心场景是用户上传图片合同、发票、产品截图系统需要自动识别图片中的关键信息提取结构化字段并且支持多轮追问。最开始我确实考虑过直接用 OkHttp 调通义千问的 HTTP 接口毕竟官方文档写得很清楚但很快发现几个问题第一多模态对话不是一次请求就能搞定的。真实场景里用户会追问“这张发票的税率是多少”“那这张呢”你需要维护会话上下文。如果裸调 HTTP上下文管理、消息历史裁剪、token 计数全得自己写工作量不小。第二项目里其他 AI 能力文本生成、向量化、RAG已经用了 Spring AI 的 API如果再为多模态单独搞一套 HTTP 调用代码结构会很割裂团队成员的学习成本也高。Spring AI Alibaba 这个框架的价值在于它把 OpenAI、通义千问、DeepSeek 等模型的接入方式统一成了 Spring 风格的ChatModel、ChatClient接口你可以像配置一个数据库连接池一样配置模型然后在业务代码里面向接口编程。换模型厂商时只需要改依赖和配置业务代码基本不动。对于多模态场景它提供了UserMessage、MediaData这样的抽象图像可以通过MediaData对象传进去框架负责把它转成对应厂商的 API 请求格式。1.2 多模态模型接入的核心链路拆解Spring AI Alibaba 1.x 系列的多模态支持本质上是把多模态请求抽象成了标准的 Spring AI Message 结构。一条完整的图文消息链路是这样的用户上传图片 - 业务层把图片转成 URL 或 Base64 - 构造UserMessage内部包含MediaData列表 - 把UserMessage传给ChatClient.prompt().messages(...)- 框架通过ChatModel的适配器把 Spring AI 的 Message 结构映射成通义千问 API 的messages数组 - 请求发出 - 响应经适配器转回 Spring AI 的AssistantMessage。这里最关键的一点是通义千问 VL 系列模型在 API 层面对图像内容的表达方式和你平时调文本模型完全不一样但 Spring AI Alibaba 帮你屏蔽了这层差异。你需要做的只是正确构造MediaData告诉框架“这是图片、图片在哪”剩下的交给框架处理。我画了一张包结构图方便你理解主要类之间的关系这个项目我用了 1.0.0-M6.1包路径以com.alibaba.cloud.ai开头com.alibaba.cloud.ai ├── model │ ├── chat │ │ ├── ChatModel // 统一入口图/文都走这里 │ │ ├── ChatClient // 流式/非流式调用的门面 │ │ └── message │ │ ├── UserMessage // 包含 MediaData 列表 │ │ └── MediaData // 图像的载体URL/Base64 都行 │ ├── embedding │ └── audio └── dashscope ├── DashScopeChatModel └── ...1.3 项目基础环境与版本矩阵这块是踩坑高发区我先把我这边验证通过的组合贴出来你在建项目时可以直接参考组件版本说明JDK17建议 21Spring AI 官方要求 JDK 17我用 17 跑通21 也没问题Spring Boot3.3.x / 3.4.x3.2.x 以下直接出兼容问题建议别试spring-ai-alibaba1.0.0-M6.1这是目前 1.x 系列我用得最稳的版本spring-ai-core1.0.0-M6.1需要和上面严格保持一致否则类冲突通义千问模型qwen-vl-plus / qwen-vl-max视觉语言模型plus 性价比高max 精度高连接方式DashScope 兼容模式走 DashScope 的 OpenAI 兼容接口注意Spring AI Alibaba 1.x 系列目前还在快速迭代M6.1并不是最终的 Release 版本。如果你在生产环境使用建议锁定1.0.0-M6.1这个精确版本号不要用1.0.0-M6或1.0.0-SNAPSHOT这两个版本我都试过存在 API 不兼容问题。2. 环境准备与依赖引入的坑2.1 Maven 依赖坐标与版本冲突我们先说依赖。很多人直接在pom.xml里加spring-ai-alibaba-starter结果启动时直接报NoClassDefFoundError原因多半是版本号没对齐。Spring AI Alibaba 1.x 系列对依赖的管控比较严格spring-ai-core和spring-ai-alibaba必须同版本而且你还需要额外引入spring-ai-alibaba-dashscope这个包才是真正实现 DashScope 协议的地方。我最终用的依赖配置如下Maven 风格dependencyManagement dependencies dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-dependencies/artifactId version1.0.0-M6.1/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies !-- Spring AI Alibaba 核心 -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter/artifactId version1.0.0-M6.1/version /dependency !-- DashScope 实现 -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-dashscope/artifactId version1.0.0-M6.1/version /dependency !-- 如果你要用通义千问的 OpenAI 兼容模式还需要这个 -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-openai/artifactId version1.0.0-M6.1/version /dependency /dependencies这里有一个细节容易忽略如果你在项目里同时用了spring-ai-alibaba-starter和spring-ai-alibaba-dashscope注意启动时有没有重复 Bean 定义的警告。我遇到过一次原因是starter里边已经包含了 DashScope 的自动配置我又手动加了一遍DashScopeChatModel导致容器里出现两个ChatModelBean。解决方式是去掉对DashScopeChatModel的显式Bean定义只保留 starter 的自动配置。2.2 application.yml 配置参数详解配置这块的坑也不少尤其是模型名称的映射关系。Spring AI Alibaba 默认会读取spring.ai.dashscope.*前缀的配置但很多网上教程用的是spring.ai.model.*或spring.ai.openai.*这在新版里已经变了。我实际可用的配置如下spring: application: name: ai-doc-review ai: dashscope: api-key: ${DASHSCOPE_API_KEY} base-url: https://dashscope.aliyuncs.com/api/v2 chat: options: model: qwen-vl-plus temperature: 0.2 max-tokens: 4096 top-p: 0.9 client: chat: api-key: ${DASHSCOPE_API_KEY}几个关键配置项的说明spring.ai.dashscope.api-key这个是从环境变量读取千万别把 key 硬编码进 yml不然代码提交到仓库就泄露了。spring.ai.dashscope.chat.options.model多模态场景必须指定为qwen-vl-plus或qwen-vl-max如果你用默认的qwen-plus请求能发出去但模型根本不看图片只会把图片 URL 当成普通文本处理返回结果完全不可用。这个坑我栽了一次下面会详说。spring.ai.dashscope.chat.options.temperature多模态场景我建议设置低一点0.1~0.3 之间。图像识别这种任务需要确定性输出温度太高模型会“脑补”不存在的字段值。base-url通义千问 DashScope 的 API 地址有个/api/v2后缀新版的兼容接口要求带 v2不加的话部分模型尤其是 VL 系列会报 404。重要spring.ai.dashscope.chat.options.model和spring.ai.client.chat.options.model是有区别的。前者是DashScopeChatModel的核心模型名后者是ChatClient的默认模型名。如果你用ChatClient调多模态建议两处都显式指定为qwen-vl-plus避免走到默认模型上。3. 多模态代码实现与核心细节3.1 用 ChatClient 实现图片内容识别框架跑通后实现多模态识别其实很直观。Spring AI Alibaba 的ChatClient接口接受一个UserMessage而UserMessage里可以携带图片媒体对象。我这里给一个最精简可用的示例代码识别合同印章图片中的公司名称import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.chat.messages.UserMessage; import org.springframework.ai.media.MediaData; import org.springframework.ai.media.MediaType; import org.springframework.stereotype.Service; import java.net.URI; import java.util.List; Service public class SealRecognizeService { private final ChatClient chatClient; public SealRecognizeService(ChatClient chatClient) { this.chatClient chatClient; } public String recognizeSeal(String imageUrl) { UserMessage userMessage UserMessage.builder() .text(请识别这张图片中的公司印章内容返回公司全称。如果印章模糊无法识别请返回无法识别。) .media(List.of( MediaData.builder() .url(URI.create(imageUrl)) .mediaType(MediaType.IMAGE_PNG) // 根据实际图片类型调整 .build() )) .build(); return chatClient.prompt() .messages(userMessage) .call() .content(); } }这段代码里三个关键点MediaData.builder().url(...)传图片 URL。这里支持 http/https 地址也支持 base64 数据串用data方法下面会讲。mediaType建议显式指定比如IMAGE_PNG、IMAGE_JPEG如果你传的图片格式和声明不一致模型可能解析失败。我遇到过 PNG 图片却声明成 JPEG导致返回 400。chatClient.prompt().messages(userMessage)UserMessage是一个特殊的 Message 实现里边的文本和媒体会被框架包装成一个数组序列化成 DashScope API 需要的结构。你不要试图自己构造system/user/assistant角色数组ChatClient会处理。3.2 本地图片 Base64 传参的正确姿势很多场景下图片并不是先传到对象存储、再拿 URL 给模型而是客户端直接上传到你的服务器这时候你就需要把图片转成 Base64 再传给模型。Spring AI Alibaba 对 Base64 的支持也封装好了但有一些细节你必须注意。我封装了一个工具方法public UserMessage buildImageMessage(String base64Image, String prompt) { // 去掉 Data URL 前缀如果客户端传入的是完整的 data:image/png;base64,xxx 格式 String pureBase64 base64Image; if (base64Image.startsWith(data:image)) { pureBase64 base64Image.substring(base64Image.indexOf(,) 1); } return UserMessage.builder() .text(prompt) .media(List.of( MediaData.builder() .data(pureBase64.getBytes(StandardCharsets.UTF_8)) .mediaType(MediaType.IMAGE_PNG) .build() )) .build(); }这段代码有个小妙招把 Data URL 前缀去掉只保留纯 Base64 字符串。Spring AI Alibaba 底层在序列化时会自动加上data:image/png;base64,前缀如果你没去掉就会变成data:image/png;base64,data:image/png;base64,...模型直接报格式错误或解析出空图片。另外有一个性能相关实测数据值得分享Base64 传图比 URL 传图多消耗约 33% 的 token因为 Base64 本身有 4/3 的编码膨胀。对于大图比如 4MB 的扫描件我建议先压缩到 2MB 以内再转 Base64否则单次请求的 token 消耗很容易超过模型上下文上限。通义千问 VL 的图片 token 计算规则大概是一张 1024x1024 的图片约等于 1024 token分辨率越高消耗越大这个在你的成本预估里要考虑进去。3.3 图文多轮对话的实现方式多模态的另一个高频场景是“一边看图一边聊”。你要让用户上传一张图然后围绕这张图不断追问。Spring AI Alibaba 里实现多轮对话需要把历史消息保存下来在下一轮请求时连同新消息一起传给模型。这块比较容易踩坑的是图片消息在历史消息中应该保留原始形式还是只保留文本我的经验是如果图片已经在第一轮传给模型了后续轮次只需要传文本历史不需要重复传图片否则 token 消耗翻倍而且模型的注意力会被重复图片干扰。完整实现如下Service public class ImageChatService { private final ChatClient chatClient; private final MapString, ListMessage sessionHistory new ConcurrentHashMap(); public ImageChatService(ChatClient chatClient) { this.chatClient chatClient; } public String chat(String sessionId, String userText, String imageUrl) { ListMessage history sessionHistory.computeIfAbsent(sessionId, k - new ArrayList()); // 构造当前用户消息 Message currentUserMessage; if (imageUrl ! null !imageUrl.isBlank()) { currentUserMessage UserMessage.builder() .text(userText) .media(List.of(MediaData.builder() .url(URI.create(imageUrl)) .mediaType(MediaType.IMAGE_JPEG) .build())) .build(); } else { currentUserMessage new UserMessage(userText); } history.add(currentUserMessage); // 调用模型 String response chatClient.prompt() .messages(history) .call() .content(); // 保存模型回复 history.add(new AssistantMessage(response)); // 控制历史长度防止超上下文窗口 if (history.size() 20) { // 保留系统提示词最近20条剔除第一条包含图片的如果第一轮有图 ListMessage trimmed new ArrayList(history.subList(history.size() - 20, history.size())); sessionHistory.put(sessionId, trimmed); } return response; } }这里比较关键的是会话历史的裁剪策略。我实际测试发现当历史消息超过 20 条时qwen-vl-plus 偶尔会返回不完整的 JSON 或开始“遗忘”第一张图的内容。保守起见我会在保留最近 20 条的同时确保第一条消息通常包含图片不被裁剪掉除非对话已经进入完全不同的主题。4. 结构化输出与实体类映射的坑4.1 Structured Output 实现方式多模态模型最常见的生产场景就是“从图片中提取字段”比如扫描的发票、合同、身份证。如果只是让模型返回一段无序文本下游系统没法直接消费。Spring AI 1.x 提供了结构化输出能力核心思路是你定义一个 Java 实体类框架用 Json Schema 约束模型输出然后自动反序列化成你的对象。我在做发票信息提取时踩了不少坑最有价值的是一个结论Spring AI 的 Structured Output 在 1.0.0-M6.1 版本中对多模态模型有一些兼容性问题你必须手动指定响应格式。实现方式有两种我直接给代码方式一使用ChatClient的.entity()方法推荐public record InvoiceInfo( String invoiceCode, String invoiceNumber, String amount, String taxRate, String sellerName, String buyerName ) {} public InvoiceInfo extractInvoice(String imageUrl) { return chatClient.prompt() .messages(UserMessage.builder() .text(请从这张发票图片中抽取以下字段发票代码、发票号码、金额、税率、销售方名称、购买方名称。只返回 JSON。) .media(List.of(MediaData.builder() .url(URI.create(imageUrl)) .mediaType(MediaType.IMAGE_JPEG) .build())) .build()) .call() .entity(InvoiceInfo.class); }这种方式最省心框架会自动生成 JSON Schema、约束模型输出、解析实体。但有一个坑你必须在文本提示词里明确说“只返回 JSON”或“不要返回其他内容”因为多模态模型的指令遵循能力比纯文本模型弱一些如果不提醒它可能会在 JSON 前后追加解释文字导致反序列化失败。方式二手动指定StructuredOutputConverter更可控Configuration public class AiConfig { Bean public StructuredOutputConverterInvoiceInfo invoiceConverter() { return StructuredOutputConverter.builder() .targetType(InvoiceInfo.class) .build(); } } // 使用 public InvoiceInfo extractInvoice(String imageUrl) { return chatClient.prompt() .messages(...) .call() .entity(invoiceConverter); }方式二适合需要复用同一个实体类的场景比如你有多种票据类型每种都定义对应的 converter代码更干净。4.2 实体类字段命名与 JSON 映射的注意点这里有几个实战经验直接说结论字段不要用 Java 驼峰命名建议直接用 JSON 字段名。比如invoice_code对应发票代码字段实体类字段就叫invoiceCode没问题但我测试下来直接给实体类字段加JsonProperty(发票代码)注解能显著提高抽取准确率因为模型的注意力会被中文标签直接引导到正确位置。所有字段用 String 类型不要用 BigDecimal 或 LocalDate。模型输出时会 99% 的情况给你标准 JSON 数字格式但有时候它会输出金额123.45这样的带标签字符串导致BigDecimal解析直接崩。String 字段 业务层转换是最稳的方案。必须显式声明record或class的构造方式。如果你用record框架通过 Jackson 反序列化没问题但如果你用class且没有无参构造器Jackson 会报错。我建议新代码统一用record。我还遇到过一个比较隐蔽的问题当实体类字段过多超过 15 个时多模态模型经常漏字段或输出错误类型。这时候不要指望模型自己“变聪明”要对实体类做精简一次性只提取核心字段或者拆分成两次调用来提取不同维度。比如发票提取我拆成了“票面信息”和“商品明细”两次调用准确率从 82% 提到了 94%。4.3 输出格式校验与重试策略模型即使用了 Structured Output也不能保证 100% 输出合法 JSON。多模态场景尤其如此因为图片中的文字、排版、遮挡都会影响模型的理解。真实生产环境必须有兜底策略。我的实现是在服务层加一个简单的重试机制public InvoiceInfo extractWithRetry(String imageUrl, int maxRetries) { for (int i 0; i maxRetries; i) { try { InvoiceInfo info extractInvoice(imageUrl); if (info.invoiceNumber() null || info.invoiceNumber().isBlank()) { // 关键字段为空说明抽取失败重试 continue; } return info; } catch (JsonProcessingException e) { log.warn(第{}次抽取发票信息失败原因{}, i 1, e.getMessage()); // 第二次重试时改变策略用更简单的实体类 if (i 1) { InvoiceSimpleInfo simpleInfo extractSimpleInvoice(imageUrl); return convert(simpleInfo); } } } throw new InvoiceExtractException(发票信息抽取失败重试次); }这里有一个经验第一次抽取失败后第二次重试建议换一个更简单的实体类只提取关键字段或者改一下提示词成功率会高很多。同一套提示词原样重试失败概率接近 100%因为模型对同一张图的注意力分布是稳定的它不觉得自己错了。5. 流式输出与异步任务的实现5.1 多模态流式响应的坑我原以为多模态场景用不到流式输出——毕竟图片识别一般是一次性返回结果。但实际业务有一个需求用户在聊天界面发了一张图问“这个合同有没有问题”模型需要一边分析一边输出结论用户体验要求打字机效果。Spring AI Alibaba 支持流式输出ChatClient有.stream()方法。但多模态流式有一个巨坑qwen-vl-plus 的流式返回可能是分片乱序的文本可能不是一个完整的句子顺序到达。这是模型服务端的特性不是框架的问题。如果你把流式片段直接渲染给用户可能会看到文字先跳出一个结论再慢慢补上原因的现象。我的解决方案是不直接渲染流式片段而是先累积片段、在客户端做一个 200ms 的防抖缓冲最后一次性渲染。这样虽然牺牲了一点“打字机”效果但用户体验更好文字也不会有跳变感。5.2 结合 Spring Boot 异步机制多模态图片识别通常耗时较长我实测下来 1MB 左右的图片qwen-vl-plus 单次识别大约 2~4 秒如果图片内容复杂比如多页表格可能要 8 秒以上。这种情况下同步接口绝对不行必须用异步。我给出一个简单的CompletableFutureAsync方案Service public class AsyncImageAnalysisService { private final ChatClient chatClient; private final ExecutorService executor Executors.newFixedThreadPool(8); Async(aiTaskExecutor) public CompletableFutureString analyzeAsync(String imageUrl, String prompt) { return CompletableFuture.supplyAsync(() - { UserMessage message UserMessage.builder() .text(prompt) .media(List.of(MediaData.builder() .url(URI.create(imageUrl)) .mediaType(MediaType.IMAGE_PNG) .build())) .build(); return chatClient.prompt() .messages(message) .call() .content(); }, executor); } }注意线程池的配置。AI 请求是 IO 密集型的线程数可以比 CPU 核数多很多但也别无线增加。我实测 DashScope 的 API 并发限制大约在 100 QPS具体看账号等级线程池设置 16 个线程每个线程处理一个图片识别请求已经够用。压到 32 个线程时有部分请求会出现超时或 429 限流。6. 常见问题与排查技巧实录6.1 问题速查表我在开发过程中把遇到的所有问题整理成了一张表方便你对照排查。这些问题我全都实际遇见过不是网上抄的。现象可能原因解决方案返回 404提示model not found模型名称不匹配用了文本模型名调 VL检查spring.ai.dashscope.chat.options.model改成qwen-vl-plus或qwen-vl-max请求成功但返回内容完全忽略图片用了不支持视觉的模型同上确认模型名以-vl-开头图片 Base64 报格式错误Data URL 前缀重复去掉data:image/...;base64,前缀再传返回 JSON 解析失败模型在 JSON 前后加了说明文字提示词中强约束“只返回 JSON”或用.entity()方法流式返回文字乱序模型服务端分片特性客户端做缓冲累积 200ms 再渲染偶尔返回空字符串图片格式不支持或图片 URL 过期统一转 Base64 或使用对象存储的永久链接请求耗时过长超过 10 秒图片分辨率太高先压缩图片到 2MB 内或降采样到 2048px 以下NoSuchBeanDefinitionException: ChatModel依赖缺失或版本不对确认spring-ai-alibaba-starter和dashscope依赖都在且版本一致UnsupportedMediaTypeExceptionmediaType声明与实际图片格式不一致校验图片 MIME 类型动态设置MediaType6.2 典型错误日志与修复过程我挑一个最典型的错误日志展开讲因为它出现的几率太高了。com.alibaba.cloud.ai.exception.DashScopeException: HTTP 400 Bad Request {message:Invalid parameter: messages. The content field of message must be a string or an array of content objects. Content array contains an invalid media type.}这个错误的根因是用户上传的是 GIF 动图或 WebP 格式但代码里写死MediaType.IMAGE_PNGSpring AI Alibaba 序列化时把图片作为 PNG 格式传给 DashScopeDashScope 不认这个格式。修复方式很简单在上传时动态判断图片格式public MediaType resolveMediaType(String contentType) { return switch (contentType) { case image/png - MediaType.IMAGE_PNG; case image/jpeg, image/jpg - MediaType.IMAGE_JPEG; case image/webp - MediaType.IMAGE_WEBP; case image/gif - MediaType.IMAGE_GIF; default - MediaType.IMAGE_PNG; // 默认 }; }但这里要说明一个更深层的问题qwen-vl 系列官方文档说支持 PNG、JPG、WEBP 格式我实测 GIF 虽然能传但识别效果不稳定建议转成 PNG 再传。WebP 格式能解析但效果也不如 PNG最好后端统一做格式转换。6.3 图片 URL 访问限制的坑另一个高频问题图片明明能打开但传给模型后返回结果不佳或报错“image download failed”。这通常是因为你的图片 URL 有访问控制比如在本地环境用localhost:8080的自然访问不了但生产环境图片藏在某个内网地址里DashScope 的服务器根本访问不到你的内网资源。所以生产环境的多模态应用图片一定要走公网可访问的 URL或者直接转 Base64。我这边的一个判断规则是如果图片文件小于 2MB直接转 Base64 传给模型如果大于 2MB先压缩再转 Base64。这样最省心不会遇到 URL 访问限制的问题。public MediaData buildMediaData(byte[] imageBytes, String contentType) { // 压缩到合适大小这里用 Java 原生 ImageIO 简单处理 if (imageBytes.length 2 * 1024 * 1024) { imageBytes compressImage(imageBytes, 2048, 0.85f); } String base64 Base64.getEncoder().encodeToString(imageBytes); return MediaData.builder() .data(base64.getBytes(StandardCharsets.UTF_8)) .mediaType(resolveMediaType(contentType)) .build(); }6.4 Token 消耗与成本控制多模态模型的成本不可忽视尤其是生产环境。我简单估算过一张 1024x1024 的图片约等于 1024 token加上提示词和系统消息一次识别请求大约消耗 1500~2500 token。qwen-vl-plus 的价格大约是 ¥0.003/千 token输入整体成本可控但如果你每天处理几万张图这就是一笔不小的开销。我从项目里总结的几个省钱策略图片上传时先做预处理去掉多余背景、裁剪主要区域能显著降低 token 消耗。比如发票扫描件先识别出票据区域再裁剪图片面积减少 60%token 消耗大概也降了一半。用低分辨率模型先做预筛。如果业务允许先用qwen-vl-plus快速跑一遍识别置信度低再升级到qwen-vl-max。价格差异大概是 10 倍但大多数场景 plus 已经够用。缓存相同图片的识别结果。用图片的 MD5 作为 key多次识别同一张图时直接走缓存省掉重复请求。7. 避坑清单5 个最容易让人崩溃的细节7.1 模型名称不是“越新越好”在 Spring AI Alibaba 的配置里model字段可以直接指定qwen-vl-max但不建议在开发阶段就用 max。原因一是贵二是 max 返回结果更长有时候反而容易在结构化输出时溢出。我的建议是开发环境用qwen-vl-plus联调验证逻辑生产环境再根据业务需求决定是否升到 max。7.2 不要手动拼 DashScope 的 messages 数组Spring AI Alibaba 既然封装了 Message 结构就不要试图自己拼 DashScope 的messagesJSON 然后走chatClient.call()这样两条路很容易打架。有一个真实的报错场景自己拼了messages数组传进去又用了MediaData结果内部序列化逻辑直接抛ClassCastException。正确的做法是始终使用框架的UserMessage、AssistantMessage、SystemMessage不要混用。7.3 图片格式转换要趁早我在项目里定了一个规矩所有上传的图片后端统一转成 PNG 或 JPEG 格式再进入 AI 识别链路。这样处理有几个好处第一个是避免 WebP 的兼容性问题第二个是统一图片转向可以顺手清理 EXIF 信息避免隐私问题第三个是压缩统一处理控制 token 消耗。用 Java 的ImageIO就够用不需要引入额外依赖。public static byte[] convertToPng(byte[] sourceBytes) throws IOException { BufferedImage image ImageIO.read(new ByteArrayInputStream(sourceBytes)); if (image null) { throw new IOException(无法解析图片); } ByteArrayOutputStream baos new ByteArrayOutputStream(); ImageIO.write(image, png, baos); return baos.toByteArray(); }有一点要特别提醒ImageIO对某些格式比如 HEIC 格式是不支持的如果业务上有苹果设备上传 HEIC 的需求需要引入额外的解码库比如twelvemonkeys否则图片会解析失败。7.4 图片压缩比和质量要平衡图片压缩会影响识别精度。我实测下来的经验对于 300 DPI 的扫描件压缩到 1600px 以内、质量 0.85 左右识别准确率几乎不降但压缩到 800px 以下发票上的小字号金额数字开始频繁识别错误。所以压缩策略要根据业务场景调整不要为了省钱过度压缩。7.5 日志打印要脱敏多模态请求的日志里会包含图片 URL 或 Base64 数据这些数据可能包含敏感信息发票代码、姓名、地址。建议在日志配置里把图片相关字段去掉或者只打 MD5 摘要。另外图片 Base64 数据如果原样打在日志里日志文件会急速膨胀一张 2MB 的图转成 Base64 大约是 2.7MB如果每次请求打一条日志系统扛不住。8. 结尾聊聊我踩坑之后的一些体会多模态模型接入这件事从代码量上看并不复杂真正的复杂度不在功能实现而在你对模型能力和框架封装的边界理解。Spring AI Alibaba 1.x 系列给我的感觉是它把多模态接入的门槛降得很低但对使用者的要求反而更高了——你得更清楚地知道自己传入的数据最终会变成什么格式、会被哪个模型处理、处理结果可能有哪些偏差。我个人在实际项目里最深刻的体会是生产级的多模态应用不能只考虑“怎么调通接口”还要想清楚容错策略。模型一定会犯错图片一定会五花八门网络一定会偶发超时——这些不是“万一”的问题而是“必然”的问题。你写的代码里有没有重试机制、有没有降级方案、有没有超时控制比你能不能把一张图的内容识别出来更重要。如果你正准备在你的项目里接入 Spring AI Alibaba 的多模态能力我最后再给你两个具体的建议第一个请一定先把版本锁死不要用latest这个框架迭代太快隔一个月 API 可能就变了第二个从项目的第一天就引入结构化输出和重试机制不要等模型调通了再补因为后期补容错逻辑的成本远高于一开始就设计好。这篇文章里涉及的所有代码片段都是我从实际项目中抽取出来的核心逻辑。你照着跑大概率能一次通过。如果遇到我没有列出的坑欢迎你在评论区补充我会持续更新这个踩坑清单。
