|
此版本仍在开发中，尚未被视为稳定版。为了获取最新的快照版本，请使用Spring AI 1.1.3！ |
OpenAI 文本转语音（TTS）
前提条件
-
创建一个OpenAI账户并获取API密钥。您可以在OpenAI注册页面上注册，并在API密钥页面上生成API密钥。
-
将
spring-ai-openai依赖项添加到项目的构建文件中。更多信息，请参阅依赖管理部分。
自动配置
|
There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the 升级说明以获取更多信息。 |
Spring AI 为 OpenAI 文本转语音客户端提供了 Spring Boot 自动配置功能。要启用此功能，请在项目的 Maven pom.xml 文件中添加以下依赖项：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>或者添加到你的 Gradle build.gradle 构建文件中：
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}| 参考以下依赖管理部分，添加Spring AI BOM到你的构建文件中。 |
语音属性
连接属性
前缀 spring.ai.openai 用于作为属性前缀，以便您连接到OpenAI。
属性 |
描述 |
默认 |
spring.ai.openai.base-url |
要连接的URL |
|
spring.ai.openai.api-key |
API 密钥 |
- |
spring.ai.openai.organization-id |
您可以选择性地指定用于API请求的组织。 |
- |
spring.ai.openai.project-id |
您可以选择性地指定用于API请求的项目。 |
- |
| 对于属于多个组织（或通过其旧版用户API密钥访问项目）的用户，可选地，您可以指定用于API请求的组织和项目。 来自这些API请求的使用将计为指定组织和项目的使用量。 |
配置属性
|
音频语音自动配置的启用和禁用现在通过带有前缀 要启用，请设置 spring.ai.model.audio.speech=openai （默认情况下已启用） 要禁用，请设置 spring.ai.model.audio.speech=none（或任何不匹配openai的值） 这种修改是为了允许配置多个模型。 |
前缀 spring.ai.openai.audio.speech 用于作为属性前缀，以便您配置OpenAI文本转语音客户端。
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.model.audio.speech |
启用音频语音模型 |
开源人工智能 |
spring.ai.openai.audio.speech.base-url |
要连接的URL |
|
spring.ai.openai.audio.speech.api-key |
API 密钥 |
- |
spring.ai.openai.audio.speech.organization-id |
您可以选择性地指定用于API请求的组织。 |
- |
spring.ai.openai.audio.speech.project-id |
您可以选择性地指定用于API请求的项目。 |
- |
spring.ai.openai.audio.speech.options.model |
用于生成音频的模型ID。可用模型： |
gpt-4o-mini-tts |
spring.ai.openai.audio.speech.options.voice |
用于合成的声音。对于OpenAI的TTS API，所选模型可用的声音之一：alloy、echo、fable、onyx、nova和shimmer。 |
合金 |
spring.ai.openai.audio.speech.options.response-format |
音频输出的格式。支持的格式有：mp3、opus、aac、flac、wav和pcm。 |
mp3 |
spring.ai.openai.audio.speech.options.speed |
语音合成的速度。可接受的范围是从0.25（最慢）到4.0（最快）。 |
1.0 |
您可以覆盖常用的spring.ai.openai.base-url、spring.ai.openai.api-key、spring.ai.openai.organization-id和spring.ai.openai.project-id属性。
如果设置了spring.ai.openai.audio.speech.base-url、spring.ai.openai.audio.speech.api-key、spring.ai.openai.audio.speech.organization-id和spring.ai.openai.audio.speech.project-id属性，它们将优先于常用属性。
这对于希望为不同模型和不同的模型端点使用不同的OpenAI账户非常有用。 |
所有以spring.ai.openai.audio.speech.options为前缀的属性都可以在运行时覆盖。 |
运行时选项
OpenAiAudioSpeechOptions 类提供了在进行文本转语音请求时使用的选项。
启动时，使用由 spring.ai.openai.audio.speech 指定的选项，但您可以在运行时覆盖这些选项。
OpenAiAudioSpeechOptions 类实现了 TextToSpeechOptions 接口，提供了可移植性和OpenAI特定的配置选项。
例如：
OpenAiAudioSpeechOptions speechOptions = OpenAiAudioSpeechOptions.builder()
.model("gpt-4o-mini-tts")
.voice(OpenAiAudioApi.SpeechRequest.Voice.ALLOY)
.responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
.speed(1.0)
.build();
TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.", speechOptions);
TextToSpeechResponse response = openAiAudioSpeechModel.call(speechPrompt);手动配置
将 spring-ai-openai 依赖添加到您项目的 Maven pom.xml 文件中：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai</artifactId>
</dependency>或者添加到你的 Gradle build.gradle 构建文件中：
dependencies {
implementation 'org.springframework.ai:spring-ai-openai'
}| 参考以下依赖管理部分，添加Spring AI BOM到你的构建文件中。 |
接下来，创建一个 OpenAiAudioSpeechModel:
var openAiAudioApi = new OpenAiAudioApi()
.apiKey(System.getenv("OPENAI_API_KEY"))
.build();
var openAiAudioSpeechModel = new OpenAiAudioSpeechModel(openAiAudioApi);
var speechOptions = OpenAiAudioSpeechOptions.builder()
.responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
.speed(1.0)
.model(OpenAiAudioApi.TtsModel.GPT_4_O_MINI_TTS.value)
.build();
var speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.", speechOptions);
TextToSpeechResponse response = openAiAudioSpeechModel.call(speechPrompt);
// Accessing metadata (rate limit info)
OpenAiAudioSpeechResponseMetadata metadata = (OpenAiAudioSpeechResponseMetadata) response.getMetadata();
byte[] responseAsBytes = response.getResult().getOutput();实时流音频
语音API提供了使用分块传输编码的实时音频流支持。这意味着在完整文件生成并可访问之前，音频就能够开始播放。
数字OpenAiAudioSpeechModel实现了StreamingTextToSpeechModel接口，提供了标准和流处理能力。
var openAiAudioApi = new OpenAiAudioApi()
.apiKey(System.getenv("OPENAI_API_KEY"))
.build();
var openAiAudioSpeechModel = new OpenAiAudioSpeechModel(openAiAudioApi);
OpenAiAudioSpeechOptions speechOptions = OpenAiAudioSpeechOptions.builder()
.voice(OpenAiAudioApi.SpeechRequest.Voice.ALLOY)
.speed(1.0)
.responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
.model(OpenAiAudioApi.TtsModel.GPT_4_O_MINI_TTS.value)
.build();
TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Today is a wonderful day to build something people love!", speechOptions);
Flux<TextToSpeechResponse> responseStream = openAiAudioSpeechModel.stream(speechPrompt);
// You can also stream raw audio bytes directly
Flux<byte[]> audioByteStream = openAiAudioSpeechModel.stream("Hello, world!");迁移指南
如果您正在从已弃用的SpeechModel和SpeechPrompt类升级，本指南提供了迁移到新共享接口的详细说明。
重大变更摘要
此迁移包含以下重大更改：
-
已移除的类: 六个已弃用的类已从
org.springframework.ai.openai.audio.speech包中移除 -
包更改: 核心TTS类已移至
org.springframework.ai.audio.tts包 -
类型变更:
speed参数在所有 OpenAI TTS 组件中已从Float更改为Double -
接口层次结构:
TextToSpeechModel现在扩展自StreamingTextToSpeechModel
类映射参考
| 已废弃（已移除） | 新接口 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
逐步迁移指南
步骤 1：更新导入
将来自旧org.springframework.ai.openai.audio.speech包的所有导入替换为新的共享接口:
Find: import org.springframework.ai.openai.audio.speech.SpeechModel;
Replace: import org.springframework.ai.audio.tts.TextToSpeechModel;
Find: import org.springframework.ai.openai.audio.speech.StreamingSpeechModel;
Replace: import org.springframework.ai.audio.tts.StreamingTextToSpeechModel;
Find: import org.springframework.ai.openai.audio.speech.SpeechPrompt;
Replace: import org.springframework.ai.audio.tts.TextToSpeechPrompt;
Find: import org.springframework.ai.openai.audio.speech.SpeechResponse;
Replace: import org.springframework.ai.audio.tts.TextToSpeechResponse;
Find: import org.springframework.ai.openai.audio.speech.SpeechMessage;
Replace: import org.springframework.ai.audio.tts.TextToSpeechMessage;
Find: import org.springframework.ai.openai.audio.speech.Speech;
Replace: import org.springframework.ai.audio.tts.Speech;步骤 2：更新类型引用
将代码中的所有类型引用替换为：
Find: SpeechModel
Replace: TextToSpeechModel
Find: StreamingSpeechModel
Replace: StreamingTextToSpeechModel
Find: SpeechPrompt
Replace: TextToSpeechPrompt
Find: SpeechResponse
Replace: TextToSpeechResponse
Find: SpeechMessage
Replace: TextToSpeechMessage步骤 3：更新速度参数（Float → Double）
参数 speed 已从 Float 更改为 Double。更新所有出现的地方:
Find: .speed(1.0f)
Replace: .speed(1.0)
Find: .speed(0.5f)
Replace: .speed(0.5)
Find: Float speed
Replace: Double speed如果您的应用程序中包含了序列化的数据或配置文件，并且这些文件中使用了Float类型的值，您也需要对这些文件进行相应的更新。
// Before
{
"speed": 1.0
}
// After (no code change needed for JSON, but be aware of type change in Java)
{
"speed": 1.0
}步骤 4：更新 Bean 声明
如果您使用了Spring Boot的自动配置或手动的Bean定义：
// Before
@Bean
public SpeechModel speechModel(OpenAiAudioApi audioApi) {
return new OpenAiAudioSpeechModel(audioApi);
}
// After
@Bean
public TextToSpeechModel textToSpeechModel(OpenAiAudioApi audioApi) {
return new OpenAiAudioSpeechModel(audioApi);
}代码迁移示例
示例 1：基本的文本转语音转换
之前（已废弃）:
import org.springframework.ai.openai.audio.speech.*;
@Service
public class OldNarrationService {
private final SpeechModel speechModel;
public OldNarrationService(SpeechModel speechModel) {
this.speechModel = speechModel;
}
public byte[] createNarration(String text) {
SpeechPrompt prompt = new SpeechPrompt(text);
SpeechResponse response = speechModel.call(prompt);
return response.getResult().getOutput();
}
}在（使用共享接口后）：
import org.springframework.ai.audio.tts.*;
import org.springframework.ai.openai.OpenAiAudioSpeechModel;
@Service
public class NarrationService {
private final TextToSpeechModel textToSpeechModel;
public NarrationService(TextToSpeechModel textToSpeechModel) {
this.textToSpeechModel = textToSpeechModel;
}
public byte[] createNarration(String text) {
TextToSpeechPrompt prompt = new TextToSpeechPrompt(text);
TextToSpeechResponse response = textToSpeechModel.call(prompt);
return response.getResult().getOutput();
}
}示例 2：使用自定义选项的文本转语音
之前（已废弃）:
import org.springframework.ai.openai.audio.speech.*;
import org.springframework.ai.openai.api.OpenAiAudioApi;
SpeechModel model = new OpenAiAudioSpeechModel(audioApi);
OpenAiAudioSpeechOptions options = OpenAiAudioSpeechOptions.builder()
.model("tts-1")
.voice(OpenAiAudioApi.SpeechRequest.Voice.NOVA)
.speed(1.0f) // Float value
.responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
.build();
SpeechPrompt prompt = new SpeechPrompt("Hello, world!", options);
SpeechResponse response = model.call(prompt);
byte[] audio = response.getResult().getOutput();在（使用共享接口后）：
import org.springframework.ai.audio.tts.*;
import org.springframework.ai.openai.OpenAiAudioSpeechModel;
import org.springframework.ai.openai.OpenAiAudioSpeechOptions;
import org.springframework.ai.openai.api.OpenAiAudioApi;
TextToSpeechModel model = new OpenAiAudioSpeechModel(audioApi);
OpenAiAudioSpeechOptions options = OpenAiAudioSpeechOptions.builder()
.model("tts-1")
.voice(OpenAiAudioApi.SpeechRequest.Voice.NOVA)
.speed(1.0) // Double value
.responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
.build();
TextToSpeechPrompt prompt = new TextToSpeechPrompt("Hello, world!", options);
TextToSpeechResponse response = model.call(prompt);
byte[] audio = response.getResult().getOutput();示例 3：流式文本转语音
之前（已废弃）:
import org.springframework.ai.openai.audio.speech.*;
import reactor.core.publisher.Flux;
StreamingSpeechModel model = new OpenAiAudioSpeechModel(audioApi);
SpeechPrompt prompt = new SpeechPrompt("Stream this text");
Flux<SpeechResponse> stream = model.stream(prompt);
stream.subscribe(response -> {
byte[] audioChunk = response.getResult().getOutput();
// Process audio chunk
});在（使用共享接口后）：
import org.springframework.ai.audio.tts.*;
import org.springframework.ai.openai.OpenAiAudioSpeechModel;
import reactor.core.publisher.Flux;
TextToSpeechModel model = new OpenAiAudioSpeechModel(audioApi);
TextToSpeechPrompt prompt = new TextToSpeechPrompt("Stream this text");
Flux<TextToSpeechResponse> stream = model.stream(prompt);
stream.subscribe(response -> {
byte[] audioChunk = response.getResult().getOutput();
// Process audio chunk
});示例 4：使用 Spring Boot 的依赖注入
之前（已废弃）:
@RestController
public class OldSpeechController {
private final SpeechModel speechModel;
@Autowired
public OldSpeechController(SpeechModel speechModel) {
this.speechModel = speechModel;
}
@PostMapping("/narrate")
public ResponseEntity<byte[]> narrate(@RequestBody String text) {
SpeechPrompt prompt = new SpeechPrompt(text);
SpeechResponse response = speechModel.call(prompt);
return ResponseEntity.ok()
.contentType(MediaType.parseMediaType("audio/mpeg"))
.body(response.getResult().getOutput());
}
}在（使用共享接口后）：
@RestController
public class SpeechController {
private final TextToSpeechModel textToSpeechModel;
@Autowired
public SpeechController(TextToSpeechModel textToSpeechModel) {
this.textToSpeechModel = textToSpeechModel;
}
@PostMapping("/narrate")
public ResponseEntity<byte[]> narrate(@RequestBody String text) {
TextToSpeechPrompt prompt = new TextToSpeechPrompt(text);
TextToSpeechResponse response = textToSpeechModel.call(prompt);
return ResponseEntity.ok()
.contentType(MediaType.parseMediaType("audio/mpeg"))
.body(response.getResult().getOutput());
}
}Spring Boot配置更改
Spring Boot的自动配置属性保持不变。无需对您的application.properties或application.yml文件进行任何更改。
但是，如果您有明确的bean引用或限定符，请更新它们：
// Before
@Qualifier("speechModel")
// After
@Qualifier("textToSpeechModel")迁移的好处
-
可移植性: 代码一次编写，轻松在OpenAI、ElevenLabs或其他TTS提供商之间切换
-
一致性: 与ChatModel和其他Spring AI抽象相同的模式
-
类型安全: 增强的类型层次结构，采用适当的接口实现
-
面向未来: 新的TTS提供商将自动与您现有的代码协同工作
-
标准化: 所有TTS提供商间速度参数的一致
Double类型
常见迁移问题及解决方案
问题1：编译错误 - 找不到符号 SpeechModel
Error:
error: cannot find symbol SpeechModel解决方案： 根据步骤1中的说明更新您的导入，将SpeechModel改为TextToSpeechModel。
示例代码
-
OpenAiSpeechModelIT.java 测试提供了一些关于如何使用该库的通用示例。