OpenAI 転写
Spring AI は OpenAI の転写モデル (英語) をサポートしています。
バージョン |
前提条件
ChatGPT モデルにアクセスするには、OpenAI で API キーを作成する必要があります。OpenAI サインアップページ (英語) でアカウントを作成し、API キーページ (英語) でトークンを生成してください。Spring AI プロジェクトでは、openai.com から取得した API Key の値を設定する必要がある spring.ai.openai.api-key という名前の設定プロパティが定義されています。環境変数をエクスポートすることは、この設定プロパティを設定する 1 つの方法です。
自動構成
Spring AI の自動構成およびスターターモジュールのアーティファクト名に大幅な変更がありました。詳細については、アップグレードノートを参照してください。 |
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 の部品表をビルドファイルに追加してください。 |
転写プロパティ
接続プロパティ
接頭辞 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 リクエストに使用するプロジェクトを指定できます。 | - |
spring.ai.openai.timeout | OpenAI クライアントのリクエストがタイムアウトしました。 | 60 秒 |
spring.ai.openai.max-retries | OpenAI クライアントの最大再試行回数。 | 3 |
spring.ai.openai.proxy | OpenAI クライアントのプロキシ設定。 | - |
spring.ai.openai.custom-headers | OpenAI クライアントのリクエストに追加するカスタム HTTP ヘッダー。 | 空 |
spring.ai.openai.connection-pool-metrics-enabled | 基盤となる OkHttp クライアントの接続プールメトリクスを有効にするかどうか。 | false |
| 複数の組織に属しているユーザー（または従来のユーザー API キーを使用してプロジェクトにアクセスしているユーザー）の場合は、オプションで、API リクエストに使用する組織とプロジェクトを指定できます。これらの API リクエストからの使用量は、指定された組織とプロジェクトの使用量としてカウントされます。 |
プロパティの構成
オーディオ文字起こしの自動構成の有効化と無効化は、プレフィックス 有効にするには、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 オーディオ転写モデルを有効にする | 開く |
spring.ai.openai.audio.transcription.base-url | 接続先の URL | |
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。利用可能なモデル: | ささやき -1 |
spring.ai.openai.audio.transcription.response-format | 文字起こし出力の形式: | テキスト |
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 を | セグメント |
spring.ai.openai.audio.transcription.known-speaker-names | 話者名（最大 4 名）、 | |
spring.ai.openai.audio.transcription.known-speaker-references | 既知の話者の音声サンプル（データ URL、例: | |
spring.ai.openai.audio.transcription.chunking-strategy | 音声のチャンク分割方法を制御します。このプロパティでは | |
spring.ai.openai.audio.transcription.diarized-json-workaround-enabled |
| 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/empty となります。
diarized_json SDK の回避策
OpenAI Java SDK (4.42.0 時点) は、diarized_json レスポンスを誤って分類し、本来であれば生の JSON ペイロードをトランスクリプトテキストとして表示してしまうという課題があります ( openai-java#802 [GitHub] (英語) )。Spring AI はこの課題を検出し、クリーンテキスト、話者セグメント、使用状況を自動的に復元します。この形式では、API が duration を返さないため、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'
}| 依存関係管理のセクションを参照して、Spring AI の部品表をビルドファイルに追加してください。 |
次に 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 トランスポートを構成します。1 つ以上の OpenAiHttpClientBuilderCustomizer Bean を公開することで、基盤となる OkHttpClient が作成される前にそのビルダーをインターセプトできます。各カスタマイザーは、すべての OpenAI モデル (チャット、埋め込み、イメージ、音声、モデレーション) で使用される同じビルダーを受け取るため、カスタマイズが一律に適用されます。
@FunctionalInterface
public interface OpenAiHttpClientBuilderCustomizer {
void customize(SpringAiOpenAiHttpClient.Builder builder);
}典型的な使用例としては、以下のようなものがあります。
OkHttp および
Interceptorインスタンスの登録（認証、伝播ヘッダー、カスタムログ記録）ディスパッチャー
ExecutorServiceを交換します（たとえば、非同期 I/O を仮想スレッド経由でルーティングするため）。プロキシ、SSL、ホスト名の検証、ビルダーによって公開される接続プールのサイズ設定。
複数のカスタマイザーが存在する場合、Spring AI のデフォルト設定の後に @Order / Ordered の順序で適用されるため、ユーザーコードが優先されます。
OpenAi*Model.Builder を介してモデルを手動で接続する場合にも、同じフックが使用できます。
var chatModel = OpenAiChatModel.builder()
.options(OpenAiChatOptions.builder().model("gpt-4o").build())
.httpClientBuilderCustomizer(myCustomizer)
.build();サンプルコード
OpenAiAudioTranscriptionModelIT.java [GitHub] (英語) テストでは、ライブラリの使用方法に関する一般的な例がいくつか提供されます。
