OpenAI 转录

Spring AI 支持 OpenAI 的转录模型。

NOTE

从 2.0.0-M5 版本起，Spring AI 在所有 OpenAI 模型底层使用官方的 openai-java SDK。此次迁移预期是无缝的，OpenAI API 属性与构建器的现有用户不会遇到破坏性变更。如发现任何问题，请在 Spring AI GitHub Issues 向我们报告。

前置条件

你需要在 OpenAI 创建一个 API 密钥才能访问 ChatGPT 模型。 在 OpenAI 注册页 创建账户，并在 API Keys 页 生成令牌。 Spring AI 项目定义了一个名为 spring.ai.openai.api-key 的配置属性，你应把它设为从 openai.com 获取的 API Key 的值。 导出一个环境变量是设置该配置属性的一种方式：

自动配置

NOTE

Spring AI 的自动配置、starter 模块的制品名称发生了重大变更。 更多信息请参阅 升级说明。

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'
}

TIP

参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。

转录属性

连接属性

前缀 spring.ai.openai 用作连接 OpenAI 的属性前缀。

属性	描述	默认值
spring.ai.openai.base-url	要连接到的 URL	https://api.openai.com
spring.ai.openai.api-key	API 密钥	-
spring.ai.openai.organization-id	可选地，你可以指定某组织用于 API 请求。	-
spring.ai.openai.project-id	可选地，你可以指定某项目用于 API 请求。	-
spring.ai.openai.timeout	OpenAI 客户端的请求超时。	60 sec.
spring.ai.openai.max-retries	OpenAI 客户端的最大重试次数。	3
spring.ai.openai.proxy	OpenAI 客户端的代理设置。	-
spring.ai.openai.custom-headers	要添加到 OpenAI 客户端请求的自定义 HTTP 头。	empty
spring.ai.openai.connection-pool-metrics-enabled	是否为底层 OkHttp 客户端启用连接池指标。	false

TIP

对于属于多个组织（或通过旧版用户 API 密钥访问其项目）的用户，可选地，你可以指定哪个组织和项目用于 API 请求。

这些 API 请求的用量将计入所指定组织和项目的用量。

配置属性

NOTE

音频转录自动配置的启用与禁用，现通过以 spring.ai.model.audio.transcription 为前缀的顶层属性来配置。

要启用，spring.ai.model.audio.transcription=openai（默认启用）

要禁用，spring.ai.model.audio.transcription=none（或任何不匹配 openai 的值）

做出此变更是为了支持配置多个模型。

前缀 spring.ai.openai.audio.transcription 用作配置 OpenAI 转录模型重试机制的属性前缀。

配置项	说明	默认值
spring.ai.model.audio.transcription	启用 OpenAI 音频转写模型	openai
spring.ai.openai.audio.transcription.base-url	连接用的 URL	https://api.openai.com
spring.ai.openai.audio.transcription.api-key	API Key	-
spring.ai.openai.audio.transcription.organization-id	可选：指定某次 API 请求使用哪个 organization。	-
spring.ai.openai.audio.transcription.project-id	可选：指定某次 API 请求使用哪个 project。	-
spring.ai.openai.audio.transcription.model	用于转写的模型 ID。 Available models: gpt-4o-transcribe (由 GPT-4o 驱动语音转文本), gpt-4o-mini-transcribe (由 GPT-4o mini 驱动语音转文本), gpt-4o-transcribe-diarize (说话人分离), 或 whisper-1 (通用语音识别模型，默认).	whisper-1
spring.ai.openai.audio.transcription.response-format	转写输出的格式： json, text, srt, verbose_json, vtt, 或 diarized_json (带说话人标签的分段，需配合 gpt-4o-transcribe-diarize).	文本
spring.ai.openai.audio.transcription.prompt	可选文本，用于引导模型风格或接续上一段音频。 提示词应与音频语言一致。	spring.ai.openai.audio.transcription.language
输入音频的语言。 以 ISO-639-1 格式提供输入语言可提升准确度与延迟。	spring.ai.openai.audio.transcription.temperature	采样温度，取值 0 到 1。像 0.8 这样较高的值会使输出更随机，像 0.2 这样较低的值则更聚焦、更确定。若设为 0，模型会利用对数概率自动上调温度直到达到某些阈值。
0	spring.ai.openai.audio.transcription.timestamp-granularities	本次转写要填充的时间戳粒度。 要使用时间戳粒度必须把 response_format 设为 verbose_json。支持 word 与 segment 中任一个或两个。注意：segment 时间戳不额外增加延迟，但生成 word 时间戳会带来额外延迟。
segment	spring.ai.openai.audio.transcription.known-speaker-names	说话人姓名（最多 4 个），与 known-speaker-references 按位置一一对应。 Only used with gpt-4o-transcribe-diarize.
spring.ai.openai.audio.transcription.known-speaker-references	已知说话人的音频样本（data URL，如 data:audio/wav;base64,...），与 known-speaker-names 按位置一一对应。 Only used with gpt-4o-transcribe-diarize.	spring.ai.openai.audio.transcription.chunking-strategy
控制音频如何分块。 该配置项仅支持 auto；语音活动检测的细分调优请用代码方式 OpenAiAudioTranscriptionOptions.Builder。whisper-1 不支持。	spring.ai.openai.audio.transcription.diarized-json-workaround-enabled	是否绕过已知的 OpenAI Java SDK 缺陷 (openai-java#802) （该缺陷会误分类 diarized_json 响应）。 See diarized-json-workaround.
true

NOTE

你可以覆盖通用的 spring.ai.openai.base-url、spring.ai.openai.api-key、spring.ai.openai.organization-id 和 spring.ai.openai.project-id 属性。

若设置了 spring.ai.openai.audio.transcription.base-url、spring.ai.openai.audio.transcription.api-key、spring.ai.openai.audio.transcription.organization-id 和 spring.ai.openai.audio.transcription.project-id 属性，它们优先于通用属性。 当你想为不同模型、不同模型端点使用不同的 OpenAI 账户时，这很有用。

TIP

所有以 spring.ai.openai.audio.transcription 为前缀的属性都可在运行时被覆盖。

运行时选项

OpenAiAudioTranscriptionOptions 类提供进行转录时使用的选项。 在启动时，使用由 spring.ai.openai.audio.transcription 指定的选项，但你可以在运行时覆盖它们。

例如：

OpenAiAudioTranscriptionOptions transcriptionOptions = OpenAiAudioTranscriptionOptions.builder()
    .language("en")
    .prompt("Ask not this, but ask that")
    .temperature(0f)
    .responseFormat(AudioResponseFormat.VTT)
    .build();
AudioTranscriptionPrompt transcriptionRequest = new AudioTranscriptionPrompt(audioFile, transcriptionOptions);
AudioTranscriptionResponse response = openAiTranscriptionModel.call(transcriptionRequest);

响应元数据

对于 verbose_json 和 diarized_json，response.getMetadata() 是一个 OpenAiAudioTranscriptionResponseMetadata，除转录文本外还暴露 getDuration()、getLanguage()、getUsage()、getSegments() 和 getWords()。对于其他响应格式，这些为 null/空。

diarized_json SDK 变通方案

OpenAI Java SDK（截至 4.42.0）会误分类 diarized_json 响应，否则会把原始 JSON 负载作为转录文本呈现（openai-java#802）。Spring AI 会检测此情况并自动恢复干净的文本、说话人分段和用量。由于 API 不返回 duration，对该格式它仍不可用。可用 OpenAiAudioTranscriptionOptions.Builder#diarizedJsonWorkaroundEnabled(false) 或 spring.ai.openai.audio.transcription.diarized-json-workaround-enabled=false 禁用该变通方案。

手动配置

把 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'
}

TIP

参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。

接下来，创建一个 OpenAiAudioTranscriptionModel

var transcriptionOptions = OpenAiAudioTranscriptionOptions.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .responseFormat(AudioResponseFormat.TEXT)
    .temperature(0f)
    .build();

var openAiAudioTranscriptionModel = OpenAiAudioTranscriptionModel.builder()
    .options(transcriptionOptions)
    .build();

var audioFile = new FileSystemResource("/path/to/your/resource/speech/jfk.flac");

AudioTranscriptionPrompt transcriptionRequest = new AudioTranscriptionPrompt(audioFile, transcriptionOptions);
AudioTranscriptionResponse response = openAiAudioTranscriptionModel.call(transcriptionRequest);

定制 HTTP 客户端

Spring AI 在底层使用官方的 openai-java SDK，并通过由 SpringAiOpenAiHttpClient.Builder 构建的自定义 OkHttp 客户端来配置其 HTTP 传输。 你可以通过暴露一个或多个 OpenAiHttpClientBuilderCustomizer bean，在底层 OkHttpClient 创建之前拦截那个构建器。 每个定制器接收的都是每个 OpenAI 模型（聊天、嵌入、图像、音频、审核）所使用的同一个构建器，因此该定制会统一生效。

@FunctionalInterface
public interface OpenAiHttpClientBuilderCustomizer {
    void customize(SpringAiOpenAiHttpClient.Builder builder);
}

典型用例包括：

• 注册 OkHttp 的 Interceptor 实例（身份认证、传播头、自定义日志）；
• 更换调度器的 ExecutorService（例如，把异步 I/O 路由到虚拟线程）；
• 配置代理、SSL、主机名验证，或构建器暴露的连接池大小。

当存在多个定制器时，它们会按 @Order / Ordered 顺序、在 Spring AI 自身默认值之后应用，因此用户代码胜出。

当通过 OpenAi*Model.Builder 手动装配模型时，同样的钩子也可用：

var chatModel = OpenAiChatModel.builder()
    .options(OpenAiChatOptions.builder().model("gpt-4o").build())
    .httpClientBuilderCustomizer(myCustomizer)
    .build();

示例代码

• OpenAiAudioTranscriptionModelIT.java 测试提供了一些关于如何使用该库的通用示例。