Spring AI 生产级实战：多模态

一、为什么需要多模态？

过去我们使用大模型时，大多数场景都是"文本进、文本出"。

比如：

text 复制代码

请总结这段文字。
请分析这份报告。
请根据用户问题生成回答。

这种方式已经可以解决很多问题，但在真实业务系统中，信息往往并不只存在于文本里。

例如：

在医学影像场景中，医生不仅要看报告文本，还要看 CT、MR、DR 等影像图像；

在质检场景中，系统不仅要读取检测说明，还要识别图片中的缺陷；

在教育场景中，学生上传的是试卷照片、手写作业、图表和文字混合内容；

在工业巡检场景中，现场数据可能包括图片、视频、传感器说明和文字记录。

这类场景的共同特点是：

text 复制代码

业务判断不能只依赖文本，还需要结合图像、音频、视频等多种信息。

这就是多模态技术的价值。

多模态不是简单地"上传一张图让模型看一下"，而是让模型能够同时理解多种输入信息，并把它们综合起来完成推理、分析和生成。

对于 Spring AI 来说，多模态能力的意义在于：

text 复制代码

让 Java / Spring 应用可以用统一的方式调用支持多模态的大模型，
把文本、图片、音频等信息一起交给模型处理。

这使得 AI 应用不再局限于聊天机器人，而是可以进入更多真实业务场景。

二、什么是多模态？

多模态，英文是 Multimodality。

简单理解，就是模型可以同时处理多种类型的数据输入，例如：

文本；
图片；
音频；
视频；
其他结构化或非结构化数据。

传统 AI 模型往往是单一模态的。

比如：

text 复制代码

语音识别模型：音频 → 文本
图像分类模型：图片 → 分类结果
文本大模型：文本 → 文本

而多模态大模型可以把多种信息放在一起理解。

例如：

text 复制代码

输入：一段文字 + 一张图片
输出：对图片内容的解释、判断、总结或建议

在生产系统中，多模态特别适合以下任务：

text 复制代码

图片理解
图文问答
报告与图像一致性检查
票据识别
医学图像辅助分析
设备巡检图片分析
教学作业批改
质检缺陷识别

所以，多模态可以理解为大模型从"读文字"走向"看图、听音、理解场景"的关键能力。

三、Spring AI 如何支持多模态？

Spring AI 并不是自己训练多模态模型，而是提供统一的 Java API 抽象，让开发者可以方便地调用底层支持多模态的大模型。

从官方文档来看，Spring AI 的多模态支持主要建立在 Message API 之上。

一个用户消息 UserMessage 中有两个关键部分：

text 复制代码

content：主要用于文本内容
media：用于附加图片、音频、视频等媒体内容

也就是说，Spring AI 把一次多模态请求抽象成：

text 复制代码

文本提示词 + 一个或多个媒体资源

例如：

text 复制代码

请解释这张图片中有什么内容。
+
图片文件 multimodal.test.png

模型收到后，会结合文本和图片进行理解，然后返回文本结果。

四、核心对象：UserMessage、Media、MimeType

Spring AI 多模态调用中，最重要的是三个概念。

1. UserMessage

UserMessage 表示用户发给模型的消息。

在普通文本场景下，我们只需要传入文本。

在多模态场景下，除了文本，还可以附带媒体内容。

示例：

java 复制代码

var userMessage = UserMessage.builder()
        .text("Explain what do you see in this picture?")
        .media(new Media(MimeTypeUtils.IMAGE_PNG, imageResource))
        .build();

这里的 .text() 是文本提示词。

.media() 是附加的图片资源。

2. Media

Media 用来描述一份媒体内容。

它通常包含两部分：

text 复制代码

媒体类型
媒体数据

例如：

java 复制代码

new Media(MimeTypeUtils.IMAGE_PNG, imageResource)

表示传入的是一张 PNG 图片。

媒体数据可以是：

text 复制代码

本地 Resource 对象
远程 URI 地址

具体支持哪种方式，要看底层模型供应商的能力。

3. MimeType

MimeType 用于告诉模型当前媒体是什么类型。

常见类型包括：

java 复制代码

MimeTypeUtils.IMAGE_PNG
MimeTypeUtils.IMAGE_JPEG

为什么必须指定类型？

因为模型需要知道传入的数据到底是图片、音频还是其他格式。

这和 Web 开发中的 Content-Type 很类似。

例如：

text 复制代码

image/png
image/jpeg
audio/mpeg
video/mp4

在生产环境中，媒体类型一定要准确，否则容易导致模型无法识别或请求失败。

五、基础代码示例：让模型理解一张图片

下面是官方文档中类似的基础用法。

方式一：使用 ChatModel

java 复制代码

var imageResource = new ClassPathResource("/multimodal.test.png");

var userMessage = UserMessage.builder()
        .text("Explain what do you see in this picture?")
        .media(new Media(MimeTypeUtils.IMAGE_PNG, imageResource))
        .build();

ChatResponse response = chatModel.call(new Prompt(userMessage));

这个例子表达的流程很清楚：

text 复制代码

读取图片资源
  ↓
构造 UserMessage
  ↓
文本 + 图片一起发送给模型
  ↓
模型返回文本解释

这种方式比较接近底层 API，适合需要自己控制 Prompt、Message、Response 的场景。

方式二：使用 ChatClient Fluent API

Spring AI 更推荐在应用开发中使用 ChatClient。

代码可以写得更简洁：

java 复制代码

String response = ChatClient.create(chatModel)
        .prompt()
        .user(u -> u.text("Explain what do you see on this picture?")
                .media(MimeTypeUtils.IMAGE_PNG,
                        new ClassPathResource("/multimodal.test.png")))
        .call()
        .content();

这种方式更适合业务代码中直接调用。

例如：

text 复制代码

Controller
Service
Agent
Workflow

都可以通过 ChatClient 来封装多模态能力。

六、多模态在生产系统中的典型流程

多模态调用在 Demo 中很简单，但在生产系统中不能只关注"能不能调用成功"。

一个更完整的生产流程应该是：

text 复制代码

用户上传文件
  ↓
文件类型校验
  ↓
文件大小校验
  ↓
病毒或安全扫描
  ↓
存储到对象存储或本地文件系统
  ↓
构造 Resource 或 URI
  ↓
组合 Prompt + Media
  ↓
调用多模态模型
  ↓
解析模型返回结果
  ↓
结构化处理或人工审核
  ↓
记录日志与审计信息

如果应用场景比较严肃，例如医学、质检、金融票据审核，就不能简单地把图片丢给模型，然后直接相信模型结果。

更合理的方式是：

text 复制代码

模型负责识别和辅助判断；
系统负责校验、留痕、审核和流程控制。

七、结合医学影像报告质控的实战思路

以医学影像报告质控为例，单纯分析报告文本是不够的。

因为报告中的结论是否合理，往往需要结合图像本身。

例如：

text 复制代码

报告写"右肺上叶结节"，但关键图像可能显示病灶在左肺；
报告写"未见骨折"，但图像中肋骨存在可疑断裂；
报告写"女性盆腔结构"，但患者性别为男性；
报告诊断与图像描述不一致。

这类问题，只靠文本大模型很难判断。

这时可以使用多模态模型，把报告文本和关键图像一起传入。

示例 Prompt：

text 复制代码

你是一名医学影像报告质控助手。

请结合影像关键图像和报告文本，判断报告中是否存在：
1. 图像与报告描述不一致；
2. 病灶位置描述错误；
3. 诊断结论与图像表现不匹配；
4. 建议医生重点复核的风险点。

请输出：
- 是否存在明显不一致；
- 风险等级；
- 问题描述；
- 复核建议。

代码示例：

java 复制代码

String result = chatClient.prompt()
        .user(u -> u.text("""
                你是一名医学影像报告质控助手。
                请结合影像关键图像和报告文本进行分析。

                报告内容：
                {reportText}

                请判断报告和图像是否存在明显不一致，并给出复核建议。
                """)
                .param("reportText", reportText)
                .media(MimeTypeUtils.IMAGE_PNG, imageResource))
        .call()
        .content();

这个示例适合以下应用：

text 复制代码

报告质控
影像图文一致性检查
AI 辅助审核
疑似漏诊提示
报告风险分级

不过需要特别强调：

text 复制代码

医学影像多模态分析不能直接替代医生诊断。

它更适合做"辅助质控"和"风险提醒"，最终仍应由医生复核确认。

八、多张图片如何处理？

在医学影像、工业质检、试卷批改等场景中，往往不是一张图片，而是多张图片。

例如：

text 复制代码

一份 CT 检查可能有多张关键图像；
一份作业可能有多页照片；
一个设备缺陷可能有多个角度图片。

Spring AI 的 media 字段可以添加一个或多个不同模态的内容。

概念上可以理解为：

text 复制代码

UserMessage
  ├── text：任务说明
  ├── media：图片1
  ├── media：图片2
  └── media：图片3

示例代码可以这样组织：

java 复制代码

String result = chatClient.prompt()
        .user(u -> u.text("""
                请分析以下多张图片，并结合文本说明给出判断。
                文本说明：{description}
                """)
                .param("description", description)
                .media(MimeTypeUtils.IMAGE_PNG, image1)
                .media(MimeTypeUtils.IMAGE_PNG, image2)
                .media(MimeTypeUtils.IMAGE_PNG, image3))
        .call()
        .content();

不过在生产环境中，要注意以下问题：

text 复制代码

图片数量不要无限制增加；
图片分辨率要适当压缩；
关键图像应优先筛选；
不同模型对图片数量和大小有不同限制；
多图分析成本通常高于纯文本分析。

对于医学影像系统来说，不建议把完整 DICOM 序列全部传给多模态模型。

更合理的方式是：

text 复制代码

先由系统或医生筛选关键图像；
再把关键图像和报告文本一起交给模型分析。

九、多模态与结构化输出结合

多模态模型返回的结果默认仍然是文本。

但在业务系统中，我们通常希望得到结构化结果。

例如：

json 复制代码

{
  "consistent": false,
  "riskLevel": "HIGH",
  "findings": [
    {
      "type": "LOCATION_MISMATCH",
      "description": "报告描述为右侧病灶，但图像疑似位于左侧",
      "suggestion": "建议医生复核病灶侧别"
    }
  ]
}

所以，多模态在生产系统中经常和结构化输出一起使用。

示例对象：

java 复制代码

public record ImageReportQcResult(
        Boolean consistent,
        String riskLevel,
        List<ImageReportFinding> findings,
        String summary
) {
}

public record ImageReportFinding(
        String type,
        String description,
        String suggestion
) {
}

调用方式：

java 复制代码

ImageReportQcResult result = chatClient.prompt()
        .user(u -> u.text("""
                请结合报告文本和图像进行质控分析。

                报告内容：
                {reportText}

                riskLevel 只能取 LOW、MEDIUM、HIGH。
                findings 中列出发现的问题。
                """)
                .param("reportText", reportText)
                .media(MimeTypeUtils.IMAGE_PNG, imageResource))
        .call()
        .entity(ImageReportQcResult.class);

这样，多模态能力就可以真正进入业务流程。

例如：

text 复制代码

模型分析图片和文本
  ↓
返回结构化质控结果
  ↓
系统判断风险等级
  ↓
高风险进入人工复核
  ↓
质控结果写入数据库
  ↓
进入审计和统计

这才是生产级 AI 应用应该具备的能力。

十、多模态与 RAG、Tool Calling 的关系

多模态不是孤立能力。

在生产级 Spring AI 应用中，它经常和 RAG、Tool Calling、结构化输出一起使用。

1. 多模态 + RAG

适合需要结合知识库的场景。

例如医学影像质控中，可以先从知识库检索相关规则：

text 复制代码

肺结节报告规范
肋骨骨折报告规范
性别相关解剖结构规则
检查部位描述规范

然后把规则、报告文本、关键图像一起交给模型。

流程如下：

text 复制代码

用户提交报告和图像
  ↓
RAG 检索质控规则
  ↓
多模态模型结合图像、报告、规则分析
  ↓
输出质控建议

这样可以减少模型胡乱发挥，让结果更贴合业务规范。

2. 多模态 + Tool Calling

适合需要调用外部系统的场景。

例如：

text 复制代码

读取患者基本信息；
查询历史检查；
获取 DICOM 元数据；
调用肺结节 AI；
调用肋骨骨折 AI；
查询报告模板规则。

多模态模型并不一定负责所有事情。

更合理的方式是：

text 复制代码

工具负责获取可靠数据；
模型负责综合分析和语言理解。

3. 多模态 + 结构化输出

适合需要进入业务流程的场景。

例如：

text 复制代码

返回风险等级；
返回问题列表；
返回建议动作；
返回是否需要人工审核；
返回对应业务分类。

也就是说：

text 复制代码

多模态解决"看得懂"的问题；
结构化输出解决"系统能处理"的问题；
RAG 解决"依据从哪里来"的问题；
Tool Calling 解决"外部数据怎么获取"的问题。

十一、生产级落地建议

1. 不要直接把原始大文件全部交给模型

多模态模型通常对输入大小、图片数量、视频长度都有约束。

生产环境应先做预处理：

text 复制代码

图片压缩；
格式转换；
关键帧抽取；
关键图像筛选；
去除无关背景；
脱敏处理；
文件大小限制。

例如医学影像场景中，可以从 DICOM 中提取关键 PNG/JPEG 图像，再交给模型，而不是直接上传完整序列。

2. Prompt 要明确模型看图的任务边界

不要只写：

text 复制代码

请分析这张图。

这种提示太宽泛。

更推荐写成：

text 复制代码

请根据图片判断是否存在与报告描述不一致的地方。
重点关注病灶位置、侧别、数量、大小和明显异常。
不要给出最终诊断，只给出需要医生复核的风险点。

这样可以减少模型输出偏离业务目标。

3. 严肃场景要保留人工复核

多模态模型会犯错。

尤其在医学、法律、金融、工业安全等场景中，不能把模型结果作为最终结论。

建议系统设计为：

text 复制代码

低风险：自动通过或抽检；
中风险：进入医生/审核员复核；
高风险：强制人工复核；
模型异常：转人工处理。

4. 必须记录审计日志

建议保存：

text 复制代码

输入文本；
图片文件 ID；
图片版本；
模型名称；
Prompt 版本；
模型原始输出；
结构化解析结果；
人工复核结果；
最终处理状态。

这对后续问题追溯非常重要。

尤其是当用户质疑 AI 结果时，系统必须能回答：

text 复制代码

当时模型看了哪些图？
用了哪个 Prompt？
返回了什么内容？
是谁复核的？
最终如何处理？

5. 注意数据安全和隐私保护

多模态输入往往包含更敏感的信息。

例如：

text 复制代码

患者影像；
身份证照片；
票据图片；
设备现场图片；
学生作业照片；
合同扫描件。

所以在上传给模型前，需要考虑：

text 复制代码

是否需要脱敏；
是否允许传到外部模型；
是否需要本地化部署；
是否需要用户授权；
是否符合行业监管要求。

对于医疗影像场景，建议至少进行：

text 复制代码

患者姓名脱敏；
检查号脱敏；
身份证号脱敏；
机构信息脱敏；
图像角标脱敏。

十二、一个推荐的多模态系统架构

可以将生产级多模态系统设计为以下结构：

text 复制代码

前端上传层
  ↓
文件接收服务
  ↓
文件安全校验
  ↓
媒体预处理服务
  ↓
对象存储
  ↓
业务编排服务
  ↓
Spring AI ChatClient
  ↓
多模态模型
  ↓
结构化输出解析
  ↓
业务规则校验
  ↓
人工审核 / 自动流转
  ↓
审计日志与反馈闭环

在这个架构中，Spring AI 主要承担的是：

text 复制代码

统一封装模型调用；
构造文本 + 媒体输入；
调用多模态大模型；
获取模型响应；
结合结构化输出进入业务流程。

它不是替代业务系统，而是把大模型能力嵌入到 Spring 应用中。

十三、适合多模态的业务场景

多模态能力非常适合以下业务方向。

1. 医学影像报告质控

text 复制代码

输入：报告文本 + 关键影像图像
输出：图文一致性分析、风险点、复核建议

2. 教育作业批改

text 复制代码

输入：学生试卷照片 + 题目要求
输出：答案识别、错误分析、批改建议

3. 工业缺陷检测

text 复制代码

输入：设备图片 + 巡检记录
输出：疑似缺陷、风险等级、维修建议

4. 票据和合同审核

text 复制代码

输入：票据扫描件 + 审核规则
输出：字段提取、异常提示、合规检查

5. 产品质检

text 复制代码

输入：产品外观图片 + 质检标准
输出：缺陷描述、是否合格、复检建议

这些场景的共同点是：

text 复制代码

需要模型同时理解图片和文字，并给出面向业务的判断。

十四、常见误区

误区一：多模态就是 OCR

不是。

OCR 主要是从图片中识别文字。

多模态模型不仅可以识别文字，还可以理解图像内容、空间关系、上下文语义和用户问题。

例如：

text 复制代码

OCR：识别图片里写了什么字。
多模态：理解图片表达了什么、是否与文本描述一致。

误区二：多模态模型可以直接替代专业系统

不能。

例如医学影像中，专业 AI 模型可能专门用于肺结节检测、骨折检测、脑卒中识别。

多模态大模型更适合做综合理解、解释、质控和辅助判断。

在严肃场景中，更推荐：

text 复制代码

专业模型负责精确检测；
多模态大模型负责综合分析；
业务系统负责流程控制；
专业人员负责最终确认。

误区三：图片越多越好

不一定。

图片越多，模型上下文负担越重，成本越高，也更容易引入无关信息。

更好的方式是：

text 复制代码

少量关键图片 + 明确任务说明 + 必要业务上下文。

误区四：模型返回内容可以直接入库使用

不建议。

多模态模型返回的内容仍然需要：

text 复制代码

格式校验；
业务校验；
风险分级；
人工复核；
日志留痕。

特别是用于质控、审核、诊断建议时，更不能直接作为最终结论。

十五、总结

Spring AI 的多模态能力，让 Java 开发者可以用熟悉的 Spring 编程方式，把文本、图片、音频等多种输入交给大模型处理。

它的核心价值不在于"让模型看图"，而在于：

text 复制代码

让多模态大模型能够被工程化地集成到业务系统中。

在生产级实践中，多模态通常不会单独存在，而是会和以下能力组合使用：

text 复制代码

结构化输出；
RAG；
Tool Calling；
审计日志；
人工复核；
业务规则校验。

只有这样，多模态能力才能从 Demo 走向真正可用的业务系统。