版本：2.0.1

本站内所有文档均为中英对照文档，点击中文可以显示英文。此提醒连续关闭5次后，将不再显示。

文档内容来源于 spring.io，由 springdoc.tech 翻译，版权归属于 SPRING.IO (Broadcom. Inc)。可供个人学习、研究，未经许可，不得进行转载或用于商业行为。

OpenAI Transcriptions :: Spring AI 参考

OpenAI Transcriptions

备注

从 2.0.0-M5 版本开始，Spring AI 在底层使用官方的 openai-java SDK 来处理所有 OpenAI 模型。这次迁移预计是无缝的，对于现有使用 OpenAI API 属性和构建器的用户来说没有破坏性变更。如果您发现任何问题，请通过 Spring AI GitHub Issues 向我们报告。

先决条件

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

自动配置

备注

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

Spring AI 为 OpenAI Transcription Client 提供了 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'
}

提示

参考 Dependency Management 部分，将 Spring AI BOM 添加到构建文件中。

转录属性

连接属性

前缀 spring.ai.openai 用作属性前缀，用于连接到 OpenAI。

Property	Description	Default
spring.ai.openai.base-url	连接地址	api.openai.com
spring.ai.openai.api-key	API Key	-
spring.ai.openai.organization-id	可选，用于指定 API 请求使用的组织 ID。	-
spring.ai.openai.project-id	可选，用于指定 API 请求使用的项目 ID。	-
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

提示

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

配置属性

备注

音频转录自动配置的启用和禁用现已通过带有前缀 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	api.openai.com
spring.ai.openai.audio.transcription.api-key	API 密钥	-
spring.ai.openai.audio.transcription.organization-id	可选，您可以指定用于 API 请求的组织。	-
spring.ai.openai.audio.transcription.project-id	可选，您可以指定用于 API 请求的项目。	-
spring.ai.openai.audio.transcription.model	用于转录的模型 ID。可用模型：`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`）。	text
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
spring.ai.openai.audio.transcription.known-speaker-names	说话人姓名（最多 4 个），按位置与 `known-speaker-references` 匹配。仅用于 `gpt-4o-transcribe-diarize`。
spring.ai.openai.audio.transcription.known-speaker-references	已知说话人的音频样本（作为数据 URL，例如 `data:audio/wav;base64,…`），按位置与 `known-speaker-names` 匹配。仅用于 `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` 响应。请参阅 diarized_json SDK 变通方案。	true

备注

你可以覆盖通用的 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 账户，这非常有用。

提示

所有以 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 禁用此 workaround。

手动配置

在项目的 Maven pom.xml 文件中添加 spring-ai-openai 依赖：

<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。

接下来，创建一个 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 创建之前拦截该构建器。每个 customizer 都会接收到所有 OpenAI 模型（聊天、嵌入、图像、音频、内容审核）共用的同一个构建器，因此自定义配置将统一生效。

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

典型的使用场景包括：

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

当存在多个定制器（customizers）时，它们会在 Spring AI 自身的默认设置之后，按照 @Order / Ordered 的顺序应用，因此用户代码优先。

通过 OpenAi*Model.Builder 手动配置模型时，也可以使用相同的钩子：

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

示例代码

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

先决条件​

自动配置​

转录属性​

连接属性​

配置属性​

运行时选项​

响应元数据​

diarized_json SDK 解决方案​

手动配置​

自定义 HTTP 客户端​

示例代码​