Spring AI 实战系列（八）：多模态能力全解锁 —— 文生图、语音合成与向量嵌入实战

一、系列回顾与本篇定位1.1 系列回顾第一篇完成 Spring AI 与阿里云百炼的基础集成基于ChatModel实现同步对话。第二篇解锁ChatClient高层级 API告别样板代码。第三篇实现 DeepSeek/Qwen 双模型共存与流式输出。第四篇深度拆解 Prompt 工程掌握与大模型高效沟通的方法论。第五篇掌握结构化输出实现大模型与业务系统的无缝对接。第六篇掌握 Tool Calling让大模型自动调用业务接口。第七篇掌握 Chat Memory基于 Redis 实现持久化多轮对话。1.2 本篇定位前面我们已经完整掌握了 Spring AI 的文本对话核心能力但企业级 AI 应用往往需要多模态能力—— 不仅能 “对话”还能 “画图”、“说话”、“理解语义”。本篇是系列多模态核心篇我们将一次性解锁 Spring AI 的三大多模态能力文生图Text-to-Image基于通义万相大模型一句话生成高质量图像。语音合成Text-to-Speech基于 CosyVoice 大模型将文本转换为自然流畅的语音。向量嵌入与 RAG 基础将文本向量化并存入向量数据库实现语义相似度检索为下一篇完整 RAG 实战打下基础。这三大能力与前面的文本对话能力结合就能构建出完整的 “多模态 AI 应用”—— 既能对话、又能画图、还能语音播报同时基于私有知识库回答问题。二、核心概念Spring AI 多模态统一抽象和ChatModel一样Spring AI 对多模态能力也做了统一的顶层抽象屏蔽了不同厂商 API 的差异切换模型仅需修改配置无需改动业务代码。能力类型Spring AI 顶层接口阿里云百炼实现核心作用文本对话ChatModelDashScopeChatModel文本生成与多轮对话文生图ImageModelDashScopeImageModel文本生成图像语音合成SpeechSynthesisModelDashScopeSpeechSynthesisModel文本转换为语音向量嵌入EmbeddingModelDashScopeEmbeddingModel文本转换为数值向量这种统一抽象的设计让我们能用完全一致的开发范式调用不同模态的 AI 能力 —— 都是 “创建 Prompt → 调用 Model → 处理 Response”学习成本极低。三、实战落地三大多模态能力全实现3.1 环境前提已完成 JDK 17、Spring Boot 3.2.x 环境搭建已配置阿里云百炼API Key环境变量DASHSCOPE_API_KEY已在pom.xml中引入spring-ai-alibaba-starter-dashscope依赖包含所有多模态能力3.2 能力一文生图Text-to-Image—— 一句话生成高质量图像文生图是 AI 应用中最常用的多模态能力之一Spring AI 基于通义万相大模型提供了极简的文生图 API。代码实现import com.alibaba.cloud.ai.dashscope.image.DashScopeImageOptions; import jakarta.annotation.Resource; import org.springframework.ai.image.ImageModel; import org.springframework.ai.image.ImagePrompt; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; /** * 文生图实战接口 */ RestController public class Text2ImageController { // wanx2.1-t2i-turbo 模型 public static final String IMAGE_MODEL wanx2.1-t2i-turbo; Resource private ImageModel imageModel; /** * 文生图接口 */ GetMapping(value /t2i/image) public String image(RequestParam(name prompt, defaultValue 一只可爱的猫) String prompt) { // 1. 构建ImagePrompt包含提示词和模型配置 ImagePrompt imagePrompt new ImagePrompt( prompt, DashScopeImageOptions.builder() .withModel(IMAGE_MODEL) .build() ); // 2. 调用ImageModel生成图像 // 3. 从响应中提取图像URL并返回 return imageModel.call(imagePrompt) .getResult() .getOutput() .getUrl(); } }关键说明Prompt 技巧提示词越详细生成的图像质量越高。建议包含主体描述、风格、光线、构图等元素例如 “一只可爱的刺猬在草地上打滚阳光明媚高清摄影浅景深自然光线”。返回值处理ImageModel返回的是图像的公网 URL有效期30天生产环境建议下载到本地存储或OSS中。高级参数通义万相V2版支持任意分辨率、智能改写、水印等功能可通过DashScopeImageOptions配置DashScopeImageOptions.builder() .withModel(IMAGE_MODEL) .withSize(1024*768) // 自定义分辨率 .withN(1) // 生成图像数量 .build();3.3 能力二语音合成Text-to-Speech—— 文本转自然语音语音合成是智能客服、有声书、语音助手等场景的核心能力Spring AI 基于 CosyVoice 大模型提供了流畅的语音合成 API。代码实现import com.alibaba.cloud.ai.dashscope.audio.DashScopeSpeechSynthesisOptions; import com.alibaba.cloud.ai.dashscope.audio.synthesis.SpeechSynthesisModel; import com.alibaba.cloud.ai.dashscope.audio.synthesis.SpeechSynthesisPrompt; import com.alibaba.cloud.ai.dashscope.audio.synthesis.SpeechSynthesisResponse; import jakarta.annotation.Resource; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import java.io.FileOutputStream; import java.nio.ByteBuffer; import java.util.UUID; /** * 语音合成实战接口 */ RestController public class Text2VoiceController { Resource private SpeechSynthesisModel speechSynthesisModel; // 语音模型选择平衡版 cosyvoice-v3 public static final String VOICE_MODEL cosyvoice-v3; // 音色选择标准女声 longxiaochun_v3 public static final String VOICE_TIMBER longxiaochun_v3; /** * 语音合成接口 */ GetMapping(/t2v/voice) public String voice( RequestParam(name msg, defaultValue 温馨提醒支付宝到账请注意查收) String msg) { // 生成保存路径用户主目录/Downloads/随机UUID.mp3 String filePath System.getProperty(user.home) /Downloads/ UUID.randomUUID() .mp3; // 1. 构建语音合成参数模型、音色 DashScopeSpeechSynthesisOptions options DashScopeSpeechSynthesisOptions.builder() .model(VOICE_MODEL) .voice(VOICE_TIMBER) .build(); // 2. 构建SpeechSynthesisPrompt包含文本和参数 SpeechSynthesisPrompt prompt new SpeechSynthesisPrompt(msg, options); // 3. 调用SpeechSynthesisModel生成语音 SpeechSynthesisResponse response speechSynthesisModel.call(prompt); // 4. 提取二进制音频数据 ByteBuffer byteBuffer response.getResult().getOutput().getAudio(); // 5. 保存到本地文件 try (FileOutputStream fos new FileOutputStream(filePath)) { fos.write(byteBuffer.array()); } catch (Exception e) { throw new RuntimeException(语音保存失败 e.getMessage(), e); } // 返回文件保存路径 return 语音已保存至 filePath; } }关键说明字符计费规则1 个汉字算 2 个字符英文、标点、空格算 1 个字符生产环境注意成本控制。高级参数配置可通过DashScopeSpeechSynthesisOptions调整语速、语调、音量DashScopeSpeechSynthesisOptions.builder() .model(VOICE_MODEL) .voice(VOICE_TIMBER) .speechRate(1.0f) // 语速0.5-2.0默认1.0 .pitchRate(1.0f) // 语调0.5-2.0默认1.0 .volume(50) // 音量0-100默认50 .build();流式合成对于长文本如小说、文章建议使用流式合成边生成边播放提升用户体验。3.4 能力三向量嵌入与 RAG 基础 —— 文本向量化与语义检索向量嵌入是 RAG检索增强生成的核心基础它能将文本转换为多维数值向量通过相似度计算找到语义最相关的内容。核心概念EmbeddingModel将文本转换为向量的模型。VectorStore向量数据库用于存储和检索向量。相似度检索通过计算向量之间的余弦相似度找到语义最相关的文档。代码实现import com.alibaba.cloud.ai.dashscope.embedding.DashScopeEmbeddingOptions; import jakarta.annotation.Resource; import lombok.extern.slf4j.Slf4j; import org.springframework.ai.document.Document; import org.springframework.ai.embedding.EmbeddingModel; import org.springframework.ai.embedding.EmbeddingRequest; import org.springframework.ai.embedding.EmbeddingResponse; import org.springframework.ai.vectorstore.SearchRequest; import org.springframework.ai.vectorstore.VectorStore; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import java.util.List; /** * 向量嵌入与RAG基础实战接口 */ RestController Slf4j public class Embed2VectorController { Resource private EmbeddingModel embeddingModel; Resource private VectorStore vectorStore; /** * 文本向量化将文本转换为多维数值向量 */ GetMapping(/text2embed) public EmbeddingResponse text2Embed(RequestParam(name msg) String msg) { // 构建EmbeddingRequest包含文本和模型配置 EmbeddingRequest request new EmbeddingRequest( List.of(msg), DashScopeEmbeddingOptions.builder() .withModel(text-embedding-v3) // 选择text-embedding-v3模型 .build() ); // 调用EmbeddingModel生成向量 EmbeddingResponse response embeddingModel.call(request); // 打印向量生产环境不要打印向量维度很高 log.info(文本向量{}, response.getResult().getOutput()); return response; } /** * 向量存储将文档向量化后存入向量数据库 */ GetMapping(/embed2vector/add) public String addDocuments() { // 准备示例文档 ListDocument documents List.of( new Document(i study LLM), new Document(i love java), new Document(海绵宝宝住在菠萝屋里), new Document(章鱼哥住在石头屋里) ); // 将文档存入向量数据库自动向量化 vectorStore.add(documents); return 文档已存入向量数据库; } /** * 语义检索从向量数据库中查找最相关的文档 */ GetMapping(/embed2vector/get) public ListDocument searchDocuments(RequestParam(name msg) String msg) { // 构建检索请求查询文本、返回TopK SearchRequest searchRequest SearchRequest.builder() .query(msg) .topK(10) // 返回最相关的10条文档 .build(); // 执行相似度检索 ListDocument results vectorStore.similaritySearch(searchRequest); // 打印检索结果 log.info(语义检索结果{}, results); return results; } }关键说明向量模型选择推荐使用text-embedding-v3维度高、语义理解能力强。VectorStore 配置Spring AI 支持多种向量数据库RedisStack、Milvus、PGVector 等只需引入对应的依赖并配置即可。RAG 基础本篇只是 RAG 的基础下一篇我们将完整实现 “文档加载 → 分块 → 向量化 → 存储 → 检索 → 大模型生成回答” 的全流程 RAG。四、生产环境最佳实践4.1 文生图最佳实践Prompt 工程提示词越详细生成质量越高。建议包含主体、风格、光线、构图、画质等元素。成本控制根据场景选择合适的模型日常创作用wanx2.1-t2i-turbo高质量需求用wanx2.1-t2i-plus人像生成用wanx2.0-t2i-turbo。图像存储生成的图像 URL 有效期仅 30 天生产环境建议下载到本地存储或 OSS 中避免链接失效。4.2 语音合成最佳实践音色选择根据场景选择合适的音色客服用longxiaochun_v3龙小淳有声书用longxiu_v2龙修方言用longlaotie_v2龙老铁。成本控制注意字符计费规则长文本建议分段合成避免一次性生成过长文本。流式播放对于长文本使用流式合成边生成边播放提升用户体验。4.3 向量嵌入与 RAG 最佳实践向量模型选择优先使用text-embedding-v3语义理解能力强检索准确率高。文档分块长文档需要分块后再向量化分块大小建议 256-1024 Token根据文档类型调整。向量数据库选型小规模数据用 RedisStack大规模数据用 Milvus 或 PGVector根据数据量和性能需求选择。五、踩坑避坑指南5.1 文生图常见问题坑点 1生成的图像不符合预期原因Prompt 太简单信息不足。解决方案优化 Prompt增加细节描述例如 “一只可爱的刺猬在草地上打滚阳光明媚高清摄影浅景深自然光线4K 画质”。坑点 2图像 URL 失效原因生成的图像 URL 有效期仅 30 天。解决方案生产环境下载到本地存储或 OSS 中永久保存。5.2 语音合成常见问题坑点 1音色与模型不匹配原因v3 模型必须使用 v3 音色v2 模型必须使用 v2 音色。解决方案确保模型和音色版本一致例如cosyvoice-v3配longxiaochun_v3。坑点 2音频无法播放原因文件后缀与音频格式不一致。解决方案确保文件后缀与请求参数中的格式一致例如 MP3 格式用.mp3后缀。5.3 向量嵌入常见问题坑点 1向量数据库连接失败原因向量数据库未启动或配置错误。解决方案检查向量数据库是否正常启动核对配置文件中的连接信息。坑点 2检索结果不准确原因文档分块不合理或向量模型选择不当。解决方案优化文档分块大小更换语义理解能力更强的向量模型如text-embedding-v3。六、本篇总结本篇我们一次性解锁了 Spring AI 的三大多模态核心能力文生图基于通义万相大模型一句话生成高质量图像支持任意分辨率、智能改写等高级功能。语音合成基于 CosyVoice 大模型将文本转换为自然流畅的语音支持多种音色和个性化参数调整。向量嵌入与 RAG 基础将文本向量化并存入向量数据库实现语义相似度检索为下一篇完整 RAG 实战打下基础。这三大能力与前面的文本对话能力结合就能构建出功能完整的多模态 AI 应用。七、下篇预告本篇我们掌握了向量嵌入与语义检索的基础能力。在本系列的下一篇中我们将进入Spring AI 企业级高级能力的最后一块拼图 —— 完整 RAG 检索增强生成实战深度拆解 RAG 的全流程文档加载 → 分块 → 向量化 → 存储 → 检索 → 大模型生成回答。从零实现基于私有知识库的智能问答系统。覆盖文档加载器、分块策略、相似度阈值调整、检索结果重排序等企业级高频场景。补充生产环境 RAG 的最佳实践与性能优化指南。如果本文对你有帮助欢迎点赞、收藏、评论跟着系列教程一步步完成 Spring AI 企业级应用的全流程落地。