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

2401_87660168

621人浏览 · 2026-04-02 13:18:01

2401_87660168 · 2026-04-02 13:18:01 发布

系列栏目：Spring AI

Spring AI 实战教程（一）入门示例

Spring AI 实战系列（二）：ChatClient封装，告别大模型开发样板代码

Spring AI 实战系列（三）：多模型共存+双版本流式输出

Spring AI 实战系列（四）：Prompt工程深度实战

Spring AI 实战系列（五）：结构化输出，让大模型严格适配你的业务数据模型

Spring AI 实战系列（六）：Tool Calling深度实战，让大模型自动调用你的业务接口

Spring AI实战系列（七）：Chat Memory实战，基于Redis实现持久化多轮对话

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

Spring AI 实战系列（九）：RAG检索实战 —— 私有知识库

Spring AI 实战系列（十）：MCP深度集成 —— 工具暴露与跨服务调用

一、系列回顾与本篇定位

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 顶层接口	阿里云百炼实现	核心作用
文本对话	`ChatModel`	`DashScopeChatModel`	文本生成与多轮对话
文生图	`ImageModel`	`DashScopeImageModel`	文本生成图像
语音合成	`SpeechSynthesisModel`	`DashScopeSpeechSynthesisModel`	文本转换为语音
向量嵌入	`EmbeddingModel`	`DashScopeEmbeddingModel`	文本转换为数值向量

这种统一抽象的设计，让我们能用完全一致的开发范式，调用不同模态的 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() {
        // 准备示例文档
        List<Document> 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 List<Document> searchDocuments(@RequestParam(name = "msg") String msg) {
        // 构建检索请求：查询文本、返回TopK
        SearchRequest searchRequest = SearchRequest.builder()
                .query(msg)
                .topK(10) // 返回最相关的10条文档
                .build();

        // 执行相似度检索
        List<Document> 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）。