OpenAI 전사

OpenAI 전사 (Transcriptions)

Spring AI는 OpenAI의 Transcription 모델을 지원해요. 음성(오디오)을 텍스트로 변환하는 작업에 유용하죠. 이 글에서는 의존성 추가와 자동 설정, 전사 관련 프로퍼티, 런타임 옵션, 수동 구성, 그리고 diarized_json SDK 워크어라운드까지 다뤄볼게요.

출처: 문서

본문

Spring AI는 OpenAI’s Transcription model을 지원해요.

Prerequisites

ChatGPT 모델에 접근하려면 OpenAI로 API 키를 만들어야 해요. OpenAI signup page에서 계정을 만들고 API Keys page에서 토큰을 생성하세요. Spring AI 프로젝트는 spring.ai.openai.api-key라는 구성 프로퍼티를 정의하는데, 여기에 openai.com에서 얻은 API Key 값을 설정해야 해요. 환경 변수를 내보내는 것도 이 구성 프로퍼티를 설정하는 한 가지 방법이에요:

Auto-configuration

Spring AI는 OpenAI Transcription 클라이언트에 대한 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'
}

Transcription Properties

Connection Properties

프리픽스 spring.ai.openai는 OpenAI에 연결할 수 있게 해주는 프로퍼티 프리픽스예요.

Configuration Properties

프리픽스 spring.ai.openai.audio.transcription은 OpenAI 전사 모델의 재시도 메커니즘을 구성할 수 있게 해주는 프로퍼티 프리픽스예요.

Runtime Options

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);

Response Metadata

verbose_json과 diarized_json의 경우, response.getMetadata()는 전사된 텍스트에 더해 getDuration(), getLanguage(), getUsage(), getSegments(), getWords()를 노출하는 OpenAiAudioTranscriptionResponseMetadata예요. 다른 응답 형식에서는 이 값들이 null/empty예요.

diarized_json SDK Workaround

OpenAI Java SDK(4.42.0 기준)는 diarized_json 응답을 잘못 분류해서, 그대로 두면 원시 JSON 페이로드가 전사 텍스트로 드러나요(openai-java#802). Spring AI는 이를 감지해 깨끗한 텍스트, 화자 세그먼트, 사용량을 자동으로 복구해요. 이 형식에서는 API가 duration을 반환하지 않으므로 duration은 계속 사용할 수 없어요. 워크어라운드를 비활성화하려면 OpenAiAudioTranscriptionOptions.Builder#diarizedJsonWorkaroundEnabled(false) 또는 spring.ai.openai.audio.transcription.diarized-json-workaround-enabled=false를 사용하세요.

Manual Configuration

프로젝트의 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'
}

다음으로 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);

Customizing the HTTP Client

Spring AI는 내부적으로 공식 openai-java SDK를 사용하며, SpringAiOpenAiHttpClient.Builder가 만든 커스텀 OkHttp 클라이언트로 HTTP 전송을 구성해요. 기저 OkHttpClient가 생성되기 전에 하나 이상의 OpenAiHttpClientBuilderCustomizer 빈을 노출해서 그 빌더를 가로챌 수 있어요. 각 커스터마이저는 모든 OpenAI 모델(chat, embedding, image, audio, moderation)이 사용하는 동일한 빌더를 받으므로, 커스터마이징이 균일하게 적용돼요.

@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();

Example Code

• OpenAiAudioTranscriptionModelIT.java 테스트는 라이브러리 사용법에 대한 일반적인 예제를 제공해요.

더 알아보기 (Learn more)