Spring AI 实战：集成阿里百炼TTS打造有声应用

1. 从零开始为什么选择Spring AI与阿里百炼TTS大家好我是老陈一个在AI和智能硬件领域摸爬滚打了十多年的老码农。这些年我见过太多开发者一提到集成AI能力尤其是语音合成TTS就觉得头大API调用复杂、网络延迟、音频流处理麻烦更别提不同服务商之间五花八门的SDK了。每次新项目都要重新造轮子调试成本高得吓人。直到我遇见了Spring AI这个框架再结合阿里百炼的TTS服务感觉就像找到了“开箱即用”的瑞士军刀。今天我就手把手带你用一顿饭的功夫把一个能说会道的“有声应用”原型给搭起来。这不仅仅是跑通一个入门示例而是真正理解如何将两者深度集成做出一个结构清晰、易于扩展的实战项目。你可能要问市面上TTS服务那么多为啥偏偏是阿里百炼我实测下来原因有三点。第一是声音质量百炼的语音合成模型在中文场景下的表现非常自然特别是对古诗词、专业术语的韵律处理比不少通用模型要强。第二是成本与易得性新用户有充足的免费额度API Key申请流程简单对于学习和原型开发非常友好。第三也是最重要的一点就是它与Spring AI框架的“原生”集成。Spring AI的目标就是统一AI模型调用的抽象层你不需要直接面对百炼复杂的HTTP API细节而是通过一套标准的、声明式的Java接口来操作这让代码变得异常简洁和优雅。所以我们这个实战项目的目标很明确利用Spring AI的抽象能力将阿里百炼TTS服务无缝嵌入到一个标准的Spring Boot应用中打造一个具备同步生成和流式生成两种模式的可运行、可测试的语音服务后端。无论你是想给博客加个“听文章”功能还是为智能硬件项目添加语音反馈这个原型都能成为你坚实的起点。接下来我们就从环境准备开始一步步拆解。2. 环境搭建与项目初始化避开我踩过的那些坑万事开头难但把环境理顺了后面就是一马平川。这里我会把版本选择、依赖配置这些容易出错的细节讲透保证你一次成功。2.1 JDK与Spring Boot版本锁定首先看基础环境。Spring AI对版本有明确要求这是第一个容易踩坑的地方。官方要求JDK最低17但我强烈推荐直接使用JDK 21。为什么因为JDK 21是目前的长期支持LTS版本性能更好而且虚拟线程等新特性在未来处理AI请求的并发场景时潜力巨大。我用的就是OpenJDK 21实测非常稳定。Spring Boot版本我选择3.3.3。这里有个小经验Spring AI的版本迭代很快最好选择Spring Boot官方当前推荐的稳定版本。3.3.x系列是目前的主力兼容性最好。别用太老的2.x系列也不建议盲目追最新的3.4.x避免遇到一些未预见的兼容性问题。2.2 创建工程与核心依赖配置打开你的IDE我用的是IntelliJ IDEA创建一个新的Spring Boot项目。GroupId和ArtifactId按你的习惯来比如com.yourname和spring-ai-tts-demo。重点在于pom.xml的配置这里我把我优化过的版本分享给你并解释每个依赖的作用。?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdcom.yourname/groupId artifactIdspring-ai-tts-demo/artifactId version1.0-SNAPSHOT/version parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.3.3/version relativePath/ /parent properties maven.compiler.source21/maven.compiler.source maven.compiler.target21/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding java.version21/java.version /properties dependencies !-- Web基础 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring AI 阿里百炼 Starter核心 -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter/artifactId version1.0.0-M3.3/version /dependency !-- 文件操作工具 -- dependency groupIdcommons-io/groupId artifactIdcommons-io/artifactId version2.18.0/version /dependency !-- 测试 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies repositories !-- 关键Spring AI依赖尚未全部进入中央仓库 -- repository idspring-milestones/id nameSpring Milestones/name urlhttps://repo.spring.io/milestone/url snapshots enabledfalse/enabled /snapshots /repository /repositories /project这里要敲黑板了spring-ai-alibaba-starter这个依赖的版本1.0.0-M3.3是专门为Spring Boot 3.3.x适配的。如果你用的Boot版本不同可能需要调整。最稳妥的办法是去Spring官方或阿里云的Maven仓库查看最新适配版本。另外那个repositories配置必须加上否则Maven会找不到spring-ai-core等基础库导致项目一片红。2.3 申请阿里百炼API Key并配置依赖搞定后我们需要让应用知道去哪里调用服务。首先打开阿里云官网找到“百炼”模型服务平台。完成实名认证后个人开发者就行在控制台创建一个API Key。这个过程是免费的新用户会赠送相当可观的调用额度足够我们折腾了。拿到那一串以sk-开头的Key之后我们来配置application.yml。我习惯使用多环境配置这里我们在resources目录下创建application.yml作为主配置再创建一个application-dev.yml作为开发环境配置。application.ymlspring: profiles: active: dev # 默认激活dev环境 application: name: spring-ai-tts-demo server: port: 8080application-dev.ymlspring: ai: dashscope: api-key: sk-你的真实API Key在这里 # 务必替换 # 其他可选配置如连接超时等后续可以按需添加 logging: level: com.alibaba.cloud.ai: DEBUG # 开启调试日志方便排查问题重要提示千万不要把真实的API Key提交到Git等版本控制系统我通常会用spring.ai.dashscope.api-key${DASHSCOPE_API_KEY:}这种形式从环境变量中读取。为了教程直观这里直接写在配置里你练习时用完后记得及时在百炼控制台重置或禁用这个Key。3. 核心代码实战两种语音生成模式详解环境配好了钥匙API Key也拿到了现在我们来盖房子的主体部分。Spring AI Alibaba Starter已经为我们自动配置好了SpeechSynthesisModel这个Bean我们直接注入使用就行。这部分我会带你写一个功能完整的Controller并深入讲解同步和流式两种生成模式的区别与应用场景。3.1 理解核心模型与选项类在写代码前先花两分钟理解两个核心类这能让你后面的代码写得心里有底。SpeechSynthesisModel这是Spring AI抽象出来的语音合成模型接口。无论底层是阿里百炼、OpenAI还是其他家我们操作的都是这个接口。它主要提供了两个方法call()用于同步合成stream()用于流式合成。这种设计的好处是未来如果你想换一家TTS服务商业务代码几乎不用动只需换一个依赖和配置。DashScopeSpeechSynthesisOptions这是阿里百炼TTS服务的具体配置类。通过它我们可以精细地控制生成的语音。我把它比作汽车的“驾驶模式”旋钮withSpeed(1.0)语速1.0是正常大于1变快小于1变慢。withPitch(0.9)音调影响声音的高低。withVolume(60)音量范围一般是0-100。你还可以设置withVoice()来选择不同的发音人如男声、女声、童声等百炼提供了多个音色可选。3.2 实现同步TTS简单直接的“一键生成”同步模式是最常用、最直观的方式。你发送一段文本服务端处理完成后一次性把整个音频文件比如MP3返回给你。这就像你下单点一份外卖然后等骑手全部送到你手上。下面是我们TTSController中同步生成接口的完整实现和讲解package com.yourname.controller; 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 org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import java.io.File; import java.io.FileOutputStream; import java.io.IOException; import java.nio.ByteBuffer; RestController RequestMapping(/ai/tts) public class TTSController { Autowired private SpeechSynthesisModel speechSynthesisModel; // 指定一个目录存放生成的音频避免污染项目结构 private static final String AUDIO_OUTPUT_DIR audio-output; GetMapping(/sync) public String generateSpeechSync(RequestParam(defaultValue 欢迎使用Spring AI与阿里百炼打造的语音合成服务。) String text) throws IOException { // 1. 创建输出目录如果不存在 File outputDir new File(AUDIO_OUTPUT_DIR); if (!outputDir.exists()) { outputDir.mkdirs(); } // 2. 构建语音合成选项这里我调成了一个听起来更沉稳、语速稍慢的男声效果 DashScopeSpeechSynthesisOptions options DashScopeSpeechSynthesisOptions.builder() .withSpeed(0.9) // 语速稍慢更清晰 .withPitch(0.85) // 音调偏低显得沉稳 .withVolume(70) // 音量适中 // .withVoice(zhitian_emo) // 可以指定特定音色如“知天-情感”版 .build(); // 3. 创建合成请求Prompt将文本和选项绑定 SpeechSynthesisPrompt prompt new SpeechSynthesisPrompt(text, options); // 4. 调用模型同步等待结果 SpeechSynthesisResponse response speechSynthesisModel.call(prompt); // 5. 处理响应将音频二进制数据写入文件 String fileName synced_speech_ System.currentTimeMillis() .mp3; File audioFile new File(outputDir, fileName); try (FileOutputStream fos new FileOutputStream(audioFile)) { ByteBuffer audioBuffer response.getResult().getOutput().getAudio(); // 将ByteBuffer转换为byte数组并写入文件 byte[] audioBytes new byte[audioBuffer.remaining()]; audioBuffer.get(audioBytes); fos.write(audioBytes); fos.flush(); } return String.format(同步语音生成成功文件已保存至%s 文件大小%d 字节, audioFile.getAbsolutePath(), audioFile.length()); } }我来解释几个关键点。第一我用了RequestParam来接收前端传来的文本这样测试更灵活默认值是一句欢迎语。第二文件命名加上了时间戳System.currentTimeMillis()这样可以避免多次生成的文件互相覆盖。第三音频数据在response.getResult().getOutput().getAudio()中它是一个ByteBuffer对象我们需要把它转成byte[]再写入文件流。这个流程是固定的你完全可以封装成一个通用的音频文件写入工具方法。3.3 实现流式TTS应对长文本的“边下边播”同步模式在处理很长的文本比如一整章电子书时有个问题用户需要等待全部合成完成后才能听到声音体验不好。这时就需要流式StreamingTTS。它的原理是服务端一边合成一边将音频数据分成多个小块chunk实时推送给客户端。客户端可以收到一块就播放一块实现“边生成边听”的效果。Spring AI的SpeechSynthesisModel提供了stream()方法来支持这种模式。虽然我们这里演示的是在服务端将流数据拼接成完整文件但思想是和推送给前端播放器一致的。import reactor.core.publisher.Flux; import java.util.concurrent.CountDownLatch; GetMapping(/stream) public String generateSpeechStream(RequestParam(defaultValue 这是一个测试流式语音合成的文本内容。流式处理适合很长的文章可以边生成边播放用户体验更佳。) String text) { File outputDir new File(AUDIO_OUTPUT_DIR); if (!outputDir.exists()) { outputDir.mkdirs(); } String fileName streamed_speech_ System.currentTimeMillis() .mp3; File audioFile new File(outputDir, fileName); // 1. 调用stream方法返回一个Flux流响应式编程核心类 FluxSpeechSynthesisResponse responseFlux speechSynthesisModel.stream( new SpeechSynthesisPrompt(text) // 流式模式下也可以传Options ); // 2. 使用CountDownLatch等待流处理完成生产环境会用更优雅的方式 CountDownLatch latch new CountDownLatch(1); final String[] resultMessage new String[1]; try (FileOutputStream fos new FileOutputStream(audioFile)) { // 3. 订阅这个流每收到一个数据块chunk就执行一次 responseFlux.doOnComplete(() - { // 流处理完成时 resultMessage[0] String.format(流式语音生成成功文件已保存至%s, audioFile.getAbsolutePath()); latch.countDown(); // 通知主线程完成 }) .doOnError(error - { // 流处理出错时 resultMessage[0] 流式语音生成失败: error.getMessage(); latch.countDown(); }) .subscribe(chunkResponse - { // 4. 处理每一个音频数据块 try { ByteBuffer audioBuffer chunkResponse.getResult().getOutput().getAudio(); if (audioBuffer ! null audioBuffer.hasRemaining()) { byte[] chunkBytes new byte[audioBuffer.remaining()]; audioBuffer.get(chunkBytes); fos.write(chunkBytes); // 将每个块依次写入文件 fos.flush(); } } catch (IOException e) { throw new RuntimeException(写入音频块失败, e); } }); // 5. 等待流处理完成这里为了演示简单用了阻塞方式WebFlux非阻塞项目中不会这么用 latch.await(); } catch (IOException | InterruptedException e) { throw new RuntimeException(文件操作或线程等待异常, e); } return resultMessage[0]; }这段代码比同步模式复杂一些核心在于理解响应式编程的Flux。你可以把它想象成一根水管数据像水一样一块一块地流过来。我们通过subscribe方法“接上”这根水管每流过来一块数据chunkResponse我们就把它写入文件。doOnComplete和doOnError相当于水管的“开关关闭”和“水管破裂”的监听器。CountDownLatch在这里是一个简单的同步工具确保文件流关闭前所有数据都写完了。在真正的WebFlux或前端SSEServer-Sent Events场景中我们会直接将这个Flux返回给客户端实现真正的实时流式推送。4. 功能验证、优化与扩展思路代码写完了是骡子是马得拉出来溜溜。我们启动应用然后进行测试和优化。4.1 启动应用与接口测试首先找到你的Application启动类运行main方法。看到控制台打印出“启动成功”和端口号默认8080后就可以开始测试了。测试同步接口打开浏览器或者用你喜欢的API测试工具如Postman、curl访问GET http://localhost:8080/ai/tts/sync?text今天天气真好适合用SpringAI集成TTS功能。稍等片刻取决于文本长度和网络你会收到一个成功消息告诉你文件保存的路径。去项目根目录下的audio-output文件夹里就能找到生成的synced_speech_xxxxxx.mp3文件双击播放听听效果。测试流式接口访问GET http://localhost:8080/ai/tts/stream?text这是一个稍长一点的文本用于测试流式处理的效果。流式合成技术可以让音频数据像流水一样逐步生成和传输。同样检查audio-output文件夹里的streamed_speech_xxxxxx.mp3文件。你可以对比一下对于长文本流式接口的“首包响应时间”是否感觉更快虽然我们最终是等全部完成才生成文件。4.2 配置优化与生产级考量demo跑通了但想用到实际项目还得做几点优化配置外部化与安全绝对不要将API Key硬编码在代码或配置文件中提交到Git。应该使用环境变量或配置中心如Nacos, Apollo。修改application-dev.ymlspring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY:} # 从环境变量读取冒号后为空则报错然后在启动应用前设置环境变量DASHSCOPE_API_KEYsk-xxx。超时与重试配置网络请求总有波动。在生产环境你需要为TTS客户端配置合理的超时和重试策略。虽然Spring AI Alibaba Starter可能还未暴露所有底层HTTP客户端配置但你可以通过自定义RestTemplate或WebClientBean来注入更精细的控制。异常处理上面的示例为了简洁异常处理比较粗糙。在生产代码中你需要定义全局异常处理器ControllerAdvice对SpeechSynthesisException、网络超时、额度不足等不同异常进行捕获并返回结构化的错误信息给前端。性能与资源管理频繁生成音频文件会占用磁盘空间。示例中我们简单放在本地目录实际项目中需要考虑将文件上传到对象存储如OSS、S3返回URL给前端。设置定时任务清理过期的临时音频文件。对于热门内容可以考虑加入缓存机制避免相同文本重复合成。4.3 扩展思路你的有声应用可以做什么有了这个核心的TTS服务能力你已经可以玩出很多花样了有声内容生产写一个定时任务将你的博客网站最新的RSS文章抓取过来自动转换成语音生成“AI播客”。智能硬件语音反馈在你的树莓派或智能家居项目中集成这个服务。当传感器触发事件时调用接口生成语音提示通过本地音箱播放出来。语音助手后端结合语音识别ASR服务打造一个简单的语音问答系统。用户提问ASR转文本大模型生成回答再用TTS把回答念出来。多音色与情感化播报深入探索DashScopeSpeechSynthesisOptions调用百炼提供的不同音色如亲切女声、活泼童声、专业男声甚至尝试情感化语音让播报不再单调。我自己的一个智能闹钟项目就用了这套方案。每天早上它会用温和的女声播报天气和日程体验比冰冷的机械音好太多了。集成过程中最大的体会就是Spring AI这套抽象确实省心把不同AI服务的技术细节差异给屏蔽掉了让我能更专注于业务逻辑本身。