[Spring AI 2025 Renewal #5] Embedding Models & Audio Models & Moderation Models

안녕하세요 dev_writer입니다.

 

이번 시간에는 Spring AI 공식 문서 중 나머지 모델인 Embedding Models, Audio Models, Moderation Models에 대해 번역한 내용을 전달해 드리겠습니다.

 

Embedding Models

임베딩 (Embedding)은 텍스트, 이미지, 비디오와 같은 입력 데이터를 수치화된 벡터 형태로 변환하여, 이들 간의 관계를 포착하는 방식입니다.

 

임베딩은 텍스트, 이미지, 비디오 등을 부동소수점 숫자의 배열 (벡터)로 변환함으로써 작동합니다. 이 벡터는 해당 입력의 의미를 포착하도록 설계되어 있으며, 이 벡터 배열의 길이는 벡터의 차원 (dimensionality)이라고 합니다.

 

두 텍스트의 임베딩 벡터 간 수치적 거리를 계산함으로써, 애플리케이션은 해당 객체 간의 유사도 (similarity)를 판단할 수 있습니다.

 

EmbeddingModel 인터페이스는 AI 및 머신러닝에서 임베딩 모델과의 통합을 간단하게 만들기 위해 설계되었습니다. 이 인터페이스의 주요 목적은 텍스트를 수치 벡터 (임베딩)로 변환하는 것입니다. 이러한 임베딩은 의미 분석 (semantic analysis), 텍스트 분류 (text classification) 등 다양한 작업에 핵심적으로 사용됩니다.

 

EmbeddingModel 인터페이스의 설계는 다음 두 가지 주요 목표를 중심으로 이루어졌습니다.

1. 이식성 (Portability): 이 인터페이스는 다양한 임베딩 모델 간의 손쉬운 전환을 가능하게 하여, 최소한의 코드 변경만으로도 다른 임베딩 기법이나 모델로 교체할 수 있도록 지원합니다. 이는 Spring 프레임워크의 모듈화 및 호환성 철학과도 잘 부합합니다.
2. 단순성 (Simplicity): EmbeddingModel은 텍스트를 임베딩으로 변환하는 과정을 단순화합니다. embed(String text), embed(Document document)와 같은 간단한 메서드를 제공하여, 원시 텍스트 데이터와 임베딩 알고리즘을 직접 다루는 복잡성을 제거합니다. 이러한 설계는 AI에 익숙하지 않은 개발자들도 임베딩 기능을 쉽게 활용할 수 있도록 돕습니다.

API 개요

임베딩 모델 API (Embedding Model API)는 Spring AI 라이브러리의 일부인 범용 Spring AI 모델 API 위에 구축되어 있습니다. 이로 인해 EmbeddingModel 인터페이스는 Model 인터페이스를 확장하며, AI 모델과 상호작용하기 위한 표준 메서드 집합을 제공합니다.

 

EmbeddingRequest와 EmbeddingResponse 클래스는 각각 입력과 출력을 캡슐화하기 위해 사용되며, 이는 ModelRequest와 ModelResponse를 확장하여 설계되었습니다. 이를 통해 임베딩 모델의 요청/응답 처리가 일관된 방식으로 수행됩니다.

 

EmbeddingModel API는 상위 계층 컴포넌트에서 OpenAI, Titan, Azure OpenAI, Ollie 등 다양한 특정 임베딩 모델에 대한 구현을 지원하기 위해 사용됩니다. 이 구조는 추상화 계층을 통해 모델 간의 호환성을 보장하면서, 개발자가 특정 벤더에 종속되지 않고 유연하게 구현할 수 있도록 돕습니다.

 

다음 다이어그램은 Embedding API가 Spring AI Model API 및 구체적인 Embedding Models와 어떻게 연계되어 있는지를 시각적으로 설명합니다.

출처: Spring AI 공식 문서

 

이 섹션에서는 EmbeddingModel 인터페이스 및 관련 클래스에 대한 가이드를 제공합니다.

public interface EmbeddingModel extends Model<EmbeddingRequest, EmbeddingResponse> {

	@Override
	EmbeddingResponse call(EmbeddingRequest request);


	/**
	 * 주어진 문서의 내용을 벡터로 임베딩합니다.
	 * @param document 임베딩할 문서
	 * @return 임베딩된 벡터
	 */
	float[] embed(Document document);

	/**
	 * 주어진 텍스트를 벡터로 임베딩합니다.
	 * @param text 임베딩할 텍스트
	 * @return 임베딩된 벡터
	 */
	default float[] embed(String text) {
		Assert.notNull(text, "Text must not be null");
		return this.embed(List.of(text)).iterator().next();
	}

	/**
	 * 텍스트 목록을 벡터로 일괄 임베딩합니다.
	 * @param texts 임베딩할 텍스트 목록
	 * @return 임베딩된 벡터 목록의 목록
	 */
	default List<float[]> embed(List<String> texts) {
		Assert.notNull(texts, "Texts must not be null");
		return this.call(new EmbeddingRequest(texts, EmbeddingOptions.EMPTY))
			.getResults()
			.stream()
			.map(Embedding::getOutput)
			.toList();
	}

	/**
	 * 텍스트 목록을 벡터로 임베딩하고 {@link EmbeddingResponse}를 반환합니다.
	 * @param texts 임베딩할 텍스트 목록
	 * @return 임베딩 응답
	 */
	default EmbeddingResponse embedForResponse(List<String> texts) {
		Assert.notNull(texts, "Texts must not be null");
		return this.call(new EmbeddingRequest(texts, EmbeddingOptions.EMPTY));
	}

	/**
	 * @return 임베딩된 벡터의 차원 수를 반환합니다. 이는 생성 모델별로 다릅니다.
	 */
	default int dimensions() {
		return embed("Test String").size();
	}
}

 

embed 메서드는 텍스트를 임베딩으로 변환하는 다양한 옵션을 제공합니다. 단일 문자열, 구조화된 Document 객체, 또는 텍스트의 배치 (batch)를 처리할 수 있습니다.

 

텍스트를 임베딩하기 위한 여러 개의 단축 메서드가 제공되며, 그중 embed(String text) 메서드는 단일 문자열을 입력받아 해당하는 임베딩 벡터를 반환합니다. 모든 단축 메서드는 임베딩 모델을 호출하는 기본 메서드인 call 메서드를 중심으로 구현되어 있습니다.

 

임베딩은 일반적으로 부동소수점 숫자 (float)의 리스트로 반환되며, 이는 임베딩을 수치 벡터 형식으로 표현한 것입니다. embedForResponse 메서드는 보다 포괄적인 출력을 제공하며, 임베딩에 대한 추가 정보가 포함될 수 있습니다.

dimensions 메서드는 개발자가 임베딩 벡터의 크기를 빠르게 파악할 수 있도록 도와주는 유용한 도구입니다. 이는 임베딩 공간을 이해하거나 후속 처리 단계에 있어서 중요한 요소입니다.

EmbeddingRequest

EmbeddingRequest는 ModelRequest를 상속한 클래스로, 텍스트 객체의 리스트와 선택적인 임베딩 요청 옵션을 입력으로 받습니다. 아래는 생성자 및 기타 유틸리티 메서드를 제외한 EmbeddingRequest 클래스의 축약 버전입니다.

public class EmbeddingRequest implements ModelRequest<List<String>> {
    private final List<String> inputs;
    private final EmbeddingOptions options;
    // 다른 메서드들은 생략
}

EmbeddingResponse

EmbeddingResponse 클래스의 구조는 아래와 같습니다.

public class EmbeddingResponse implements ModelResponse<Embedding> {

    private List<Embedding> embeddings;
    private EmbeddingResponseMetadata metadata = new EmbeddingResponseMetadata();
    // 다른 메서드들은 생략
}

 

EmbeddingResponse 클래스는 AI 모델의 출력을 보관하며, 각 Embedding 인스턴스는 단일 텍스트 입력에 대한 결과 벡터 데이터를 포함합니다.

 

또한 EmbeddingResponse 클래스는 AI 모델의 응답에 대한 메타데이터인 EmbeddingResponseMetadata 도 함께 포함합니다.

Embedding

Embedding은 단일 임베딩 벡터를 나타냅니다.

public class Embedding implements ModelResult<float[]> {
    private float[] embedding;
    private Integer index;
    private EmbeddingResultMetadata metadata;
    // 다른 메서드들은 생략
}

이용 가능한 구현체

내부적으로 다양한 EmbeddingModel 구현체들은 임베딩 작업을 수행하기 위해 서로 다른 저수준 라이브러리 및 API를 사용합니다. 다음은 사용 가능한 EmbeddingModel 구현체들의 일부입니다.

• Spring AI OpenAI Embeddings
• Spring AI Azure OpenAI Embeddings
• Spring AI Ollamma Embeddings
• Spring AI Transformers (ONNX) Embeddings
• Spring AI PostgresML Embeddings
• Spring AI Bedrock Cohere Embeddings
• Spring AI Bedrock Titan Embeddings
• Spring AI VertexAI Embeddings
• Spring AI Mistral AI Embeddings
• Spring AI Oracle Cloud Infrastructure GenAI Embeddings

---

Audio Models (OpenAI)

음성-텍스트 변환 (Transcription, 전사) API

Spring AI는 OpenAI의 음성-텍스트 변환 API를 지원합니다. 향후 추가적인 제공자가 구현되면, 공통 인터페이스인 AudioTranscriptionModel이 추출되어 적용될 예정입니다.

OpenAI Transcriptions

Spring AI는 OpenAI의 음성-텍스트 변환 모델을 지원합니다.

사전 준비 사항

ChatGPT 모델에 접근하려면 OpenAI API 키를 생성해야 합니다. OpenAI 회원가입 페이지에서 계정을 생성하고, API Keys 페이지에서 토큰 (API Key)을 생성하세요. Spring AI 프로젝트에서는 spring.ai.openai.api-keys라는 구성 속성을 사용하여 이 API 키 값을 설정하도록 정의되어 있습니다. 환경 변수 내보내기는 해당 구성 속성을 설정하는 한 가지 방법입니다.

자동 구성

참고
Spring AI의 자동 구성 및 스타터 모듈 아티팩트 이름이 변경되었습니다. 업그레이드 노트를 참조하세요.

 

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

음성-텍스트 변환 속성

연결 속성

접두어 spring.ai.openai는 OpenAI에 연결하기 위한 구성 속성의 접두어로 사용됩니다.

프로퍼티	설명	기본값
spring.ai.openai.base-url	OpenAI에 연결할 URL	api.openai.com
spring.ai.openai.api-key	OpenAI API 키
spring.ai.openai.organization-id	API 요청 시 사용할 조직 (선택 사항)
spring.ai.openai.project-id	API 요청 시 사용할 프로젝트 (선택 사항)

팁
여러 조직에 소속되어 있거나, 레거시 사용자 API 키를 통해 프로젝트에 접근하는 경우에는 API 요청 시 사용할 조직 ID와 프로젝트 ID를 명시할 수 있습니다. 이렇게 설정하면, 해당 요청은 지정된 조직 및 프로젝트의 사용량으로 집계됩니다.

 

구성 속성

참고
오디오 트랜스크립션 자동 구성의 활성화 및 비활성화는 이제 spring.ai.model.audio.transcription 접두어를 갖는 최상위 속성을 통해 설정됩니다.
활성화하려면: spring.ai.model.audio.transcription=openai (기본값으로 활성화됨)
비활성화하려면: spring.ai.model.audio.transcription=none (또는 openai와 일치하지 않는 임의의 값)
이 변경은 여러 모델을 동시에 구성할 수 있도록 하기 위해 도입되었습니다.

 

spring.ai.openai.audio.transcription 접두어는 OpenAI 음성-텍스트 변환 모델의 재시도 (retry) 메커니즘을 구성할 때 사용하는 설정 접두어입니다.

프로퍼티	설명	기본값
spring.ai.model.audio.transcription	OpenAI 오디오 트랜스크립션 모델 활성화 여부	openai
spring.ai.openai.audio.transcription.base-url	연결할 OpenAI API의 URL	api.openai.com
spring.ai.openai.audio.transcription.api-key	OpenAI API 키
spring.ai.openai.audio.transcription.organization-id	API 요청 시 사용할 조직 (선택 사항)
spring.ai.openai.audio.transcription.project-id	API 요청 시 사용할 프로젝트 (선택 사항)
spring.ai.openai.audio.transcription.options.model	사용할 모델의 ID (현재는 오픈소스 Whisper V2 기반의 whisper-1만 사용 가능)	whisper
spring.ai.openai.audio.transcription.options.response-format	출력 포맷 (선택 가능: json, text, srt, verbose_json, vtt)	json
spring.ai.openai.audio.transcription.options.prompt	모델의 스타일을 유도하거나 이전 오디오 구간을 이어가기 위한 선택적 프롬프트 (오디오 언어와 일치해야 함)
spring.ai.openai.audio.transcription.options.language	입력 오디오의 언어 (ISO-639-1 포맷 권장, 정확도 및 속도 향상에 도움)
spring.ai.openai.audio.transcription.options.temperature	샘플링 온도 (0~1 사이 값. 높을수록 랜덤, 낮을수록 결정적. 0일 경우 자동 조정됨)	0
spring.ai.openai.audio.transcription.options.timestamp_granularities	타임스탬프 세분화 수준 지정 (response_format이 verbose_json일 때만 사용 가능). word, segment 중 하나 또는 둘 다 사용 가능. 참고: segment는 추가 지연 없음, word는 지연 발생 가능	segment

참고
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, api-key, organization-id, project-id로 개별적으로 오버라이드(재정의)할 수 있습니다. 이러한 설정은 서로 다른 모델 또는 엔드포인트에서 OpenAI 계정을 분리하여 사용할 경우 유용합니다.

팁
spring.ai.openai.transcription.options 접두어로 시작하는 모든 속성은 런타임 중에도 재정의할 수 있습니다.

런타임 옵션

OpenAiAudioTranscriptionOptions 클래스는 음성-텍스트 변환 요청 시 사용할 옵션을 제공합니다. 애플리케이션 시작 시에는 spring.ai.openai.audio.transcription에 지정된 설정값이 사용되지만, 이 설정들은 런타임 (runtime)에 재정의할 수 있습니다.

 

다음은 예시입니다.

OpenAiAudioApi.TranscriptResponseFormat responseFormat = OpenAiAudioApi.TranscriptResponseFormat.VTT;

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

수동 구성

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을 빌드 파일에 추가하기 위해서는 Dependency Management 섹션을 참조하세요.

 

다음으로, OpenAiAudioTranscriptionModel을 생성합니다.

var openAiAudioApi = new OpenAiAudioApi(System.getenv("OPENAI_API_KEY"));

var openAiAudioTranscriptionModel = new OpenAiAudioTranscriptionModel(this.openAiAudioApi);

var transcriptionOptions = OpenAiAudioTranscriptionOptions.builder()
    .responseFormat(TranscriptResponseFormat.TEXT)
    .temperature(0f)
    .build();

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

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

예제 코드

OpenAiTranscriptionModelIT.java 테스트 클래스는 라이브러리를 사용하는 일반적인 예시를 제공합니다.

텍스트-음성 변환 (Text-to-Speech) API

Spring AI는 OpenAI의 음성 생성 (Speech) API를 지원합니다. 추가적인 제공자가 구현되면, 공통 인터페이스인 SpeechModel 및 StreamingSpeechModel이 추출되어 적용될 예정입니다.

개요

Audio API는 OpenAI의 TTS(Text-to-Speech) 모델을 기반으로 하는 음성 엔드포인트를 제공하며, 사용자는 다음과 같은 기능을 이용할 수 있습니다:

• 작성된 블로그 게시글을 음성으로 낭독
• 다양한 언어로 음성 오디오 생성
• 스트리밍을 통한 실시간 음성 출력

사전 준비 사항

1. OpenAI 계정을 생성하고 API 키를 발급받으세요. 회원가입은 OpenAI의 회원가입 페이지에서 할 수 있으며, API 키 페이지에서 API 키를 생성할 수 있습니다.
2. 프로젝트의 빌드 파일에 spring-ai-openai 의존성을 추가하세요. 자세한 내용은 Dependency Management 섹션을 참고하시기 바랍니다.

자동 구성

Spring AI의 자동 구성 (auto-configuration) 및 스타터 모듈의 artifact 이름에 중요한 변경 사항이 있습니다. 자세한 내용은 업그레이드 노트를 참고하시기 바랍니다.

 

Spring AI는 OpenAI Text-to-Speech 클라이언트를 위한 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을 빌드 파일에 추가하세요.

 

Speech 속성

연결 속성 (Connection Properties)

spring.ai.openai는 OpenAI에 연결할 수 있도록 해주는 속성 접두어입니다.

속성명	설명	기본값
spring.ai.openai.base-url	연결할 URL	api.openai.com
spring.ai.openai.api-key	API 키	-
spring.ai.openai.organization-id	(선택) API 요청 시 사용할 조직을 지정할 수 있음	-
spring.ai.openai.project-id	(선택) API 요청 시 사용할 프로젝트를 지정할 수 있음

 

팁
여러 조직에 속해 있거나 레거시 사용자 API 키를 통해 프로젝트에 접근하는 사용자라면, organization-id와 project-id를 명시함으로써 어떤 조직 및 프로젝트로 사용량이 집계될지를 지정할 수 있습니다.

 

구성 속성 (Configuration Properties)

주의
오디오 스피치 자동 구성의 활성화/비활성화는 이제 최상위 속성 접두어 spring.ai.model.audio.speech를 통해 설정합니다.

활성화하려면: spring.ai.model.audio.speech=openai (기본값으로 활성화됨)
비활성화하려면: spring.ai.model.audio.speech=none (또는 openai와 일치하지 않는 아무 값)

이 변경은 여러 모델을 구성할 수 있도록 하기 위한 것입니다.

 

spring.ai.openai.audio.speech는 OpenAI Text-to-Speech 클라이언트를 구성할 수 있도록 해주는 속성 접두어입니다.

속성명	설명	기본값
spring.ai.model.audio.speech	Audio Speech 모델 활성화 여부 지정	openai
spring.ai.openai.audio.speech.base-url	연결할 URL	api.openai.com
spring.ai.openai.audio.speech.api-key	OpenAI 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 입니다. OpenAI의 TTS API에서는 사용 가능한 모델 중 하나인 tts-1 또는 tts-1-hd를 지정해야 합니다.	tts-1
spring.ai.openai.audio.speech.options.voice	음성 합성에 사용할 목소리 (voice)를 지정합니다. OpenAI의 TTS API에서는 선택한 모델에 따라 사용할 수 있는 목소리 중 하나를 지정해야 하며, 사용 가능한 값은 다음과 같습니다: alloy, echo, fable, onyx, nova, shimmer	alloy
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.orgnanization-id
- spring.ai.openai.audio.speech.project-id
이 기능은 모델별로 다른 OpenAI 계정이나 엔드포인트를 사용하고자 할 때 유용합니다.

 

팁: spring.ai.openai.image.options 접두어로 시작하는 모든 속성은 런타임에 재정의할 수 있습니다.

 

런타임 옵션

OpenAiAudioSpeechOptions 클래스는 텍스트를 음성으로 변환할 때 사용할 옵션들을 제공합니다. 애플리케이션이 시작될 때는 spring.ai.openai.audio.speech에 정의된 설정이 적용되지만, 런타임에서 해당 옵션을 재정의할 수 있습니다.

 

예를 들어:

OpenAiAudioSpeechOptions speechOptions = OpenAiAudioSpeechOptions.builder()
    .model("tts-1")
    .voice(OpenAiAudioApi.SpeechRequest.Voice.ALLOY)
    .responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
    .speed(1.0f)
    .build();

SpeechPrompt speechPrompt = new SpeechPrompt("Hello, this is a text-to-speech example.", speechOptions);
SpeechResponse response = openAiAudioSpeechModel.call(speechPrompt);

 

수동 구성 (Manual Configuration)

프로젝트에 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을 빌드 파일에 추가하는 방법은 Dependency Management 섹션을 참고하세요.

 

다음 단계로 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.0f)
    .model(OpenAiAudioApi.TtsModel.TTS_1.value)
    .build();

var speechPrompt = new SpeechPrompt("Hello, this is a text-to-speech example.", speechOptions);
SpeechResponse response = openAiAudioSpeechModel.call(speechPrompt);

// 메타데이터 (요청 제한 정보)에 접근하기
OpenAiAudioSpeechResponseMetadata metadata = response.getMetadata();

byte[] responseAsBytes = response.getResult().getOutput();

 

실시간 오디오 스트리밍

Speech API는 청크 전송 인코딩 (chunk transfer encoding)을 사용하여 실시간 오디오 스트리밍을 지원합니다.

이는 전체 오디오 파일이 완전히 생성되어 접근 가능해지기 전에 재생할 수 있음을 의미합니다.

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.0f)
    .responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
    .model(OpenAiAudioApi.TtsModel.TTS_1.value)
    .build();

SpeechPrompt speechPrompt = new SpeechPrompt("Today is a wonderful day to build something people love!", speechOptions);

Flux<SpeechResponse> responseStream = openAiAudioSpeechModel.stream(speechPrompt);

 

예제 코드

OpenAiSpeechModelIT.java 테스트는 해당 라이브러리를 사용하는 방법에 대한 일반적인 예제를 제공합니다.

---

Moderation Models (OpenAI)

Spring AI는 OpenAI의 Moderation 모델을 지원합니다. 이 모델을 통해 텍스트 내의 잠재적으로 유해하거나 민감한 콘텐츠를 감지할 수 있습니다. 자세한 정보는 OpenAI의 Moderation 모델 관련 가이드를 참조하세요.

 

사전 준비 사항

1. OpenAI 계정을 생성하고 API 키를 발급받습니다. OpenAI 회원가입 페이지에서 계정을 생성하고, API Keys 페이지에서 API 키를 생성하세요.
2. 프로젝트의 빌드 파일에 spring-ai-openai 의존성을 추가합니다. 자세한 내용은 의존성 관리 (Dependency Management) 섹션을 참조하세요.

자동 구성

참고
Spring AI의 자동 구성 방식 및 스타터 모듈의 아티팩트 이름에 중요한 변경이 있었습니다. 자세한 내용은 업그레이드 노트를 참조하세요.

 

Spring AI는 OpenAI의 Text-to-Speech 클라이언트에 대해 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을 빌드 파일에 추가하는 방법은 Dependency Management 섹션을 참고하세요.

Moderation 속성

연결 속성

spring.ai.openai는 OpenAI와 연결하기 위한 설정의 프로퍼티 접두어입니다.

프로퍼티	설명	기본값
spring.ai.openai.base-url	연결할 URL	api.openai.com
spring.ai.openai.api-key	API 키
spring.ai.openai.organization-id	API 요청에 사용할 조직 지정 (선택 사항)
spring.ai.openai.project-id	API 요청에 사용할 프로젝트 지정 (선택 사항)

팁
여러 조직에 소속된 사용자이거나 레거시 사용자 API 키를 통해 프로젝트에 접근하는 경우, 요청 시 사용할 조직 및 프로젝트를 명시할 수 있습니다. 이 경우 해당 조직과 프로젝트에 사용량이 기록됩니다.

구성 속성

참고
임베딩 자동 구성의 활성화 여부는 이제 spring.ai.model.embedding 접두어를 가진 최상위 프로퍼티로 설정합니다.
활성화: spring.ai.model.moderation=openai (기본값)
비활성화: spring.ai.model.moderation=none (또는 openai와 일치하지 않는 값)
이 변경은 여러 모델의 구성을 지원하기 위함입니다.

 

OpenAI의 Moderation 모델을 구성할 때는 접두어 spring.ai.openai.moderation을 사용합니다.

프로퍼티	설명	기본값
spring.ai.model.moderation	Moderation 모델 활성화 여부	openai
spring.ai.openai.moderation.base-url	연결할 URL	api.openai.com
spring.ai.openai.moderation.api-key	API 키
spring.ai.openai.moderation.organization-id	조직 ID (선택 사항)
spring.ai.openai.moderation.project-id	프로젝트 ID (선택 사항)
spring.ai.openai.moderation.options.model	사용할 Moderation 모델 ID	text-moderation-latest

참고
공통 속성 (spring.ai.openai.base-url, api-key, organization-id, project-id)보다 Moderation 전용 속성 (spring.ai.openai.moderation.*)이 우선 적용됩니다. 서로 다른 모델 또는 OpenAI 계정을 사용하고자 할 때 유용합니다.

팁
spring.ai.openai.moderation.options.* 접두어로 시작하는 모든 속성은 런타임에 재정의할 수 있습니다.

런타임 옵션

OpenAiModerationOptions 클래스는 Moderation 요청 시 사용할 옵션을 정의합니다. 애플리케이션 시작 시에는 spring.ai.openai.moderation에 정의된 값이 적용되지만, 아래와 같이 런타임에서 재정의할 수도 있습니다.

OpenAiModerationOptions moderationOptions = OpenAiModerationOptions.builder()
    .model("text-moderation-latest")
    .build();

ModerationPrompt moderationPrompt = new ModerationPrompt("Text to be moderated", this.moderationOptions);
ModerationResponse response = openAiModerationModel.call(this.moderationPrompt);

// 결과 접근
Moderation moderation = moderationResponse.getResult().getOutput();

// 일반 정보 출력
System.out.println("Moderation ID: " + moderation.getId());
System.out.println("Model used: " + moderation.getModel());

// 결과 리스트 (보통 하나지만 리스트 형태)
for (ModerationResult result : moderation.getResults()) {
    System.out.println("\nModeration Result:");
    System.out.println("Flagged: " + result.isFlagged());

    // 카테고리 접근
    Categories categories = result.getCategories();
    System.out.println("\nCategories:");
    System.out.println("Sexual: " + categories.isSexual());
    System.out.println("Hate: " + categories.isHate());
    System.out.println("Harassment: " + categories.isHarassment());
    System.out.println("Self-Harm: " + categories.isSelfHarm());
    System.out.println("Sexual/Minors: " + categories.isSexualMinors());
    System.out.println("Hate/Threatening: " + categories.isHateThreatening());
    System.out.println("Violence/Graphic: " + categories.isViolenceGraphic());
    System.out.println("Self-Harm/Intent: " + categories.isSelfHarmIntent());
    System.out.println("Self-Harm/Instructions: " + categories.isSelfHarmInstructions());
    System.out.println("Harassment/Threatening: " + categories.isHarassmentThreatening());
    System.out.println("Violence: " + categories.isViolence());

    // 카테고리 점수 접근
    CategoryScores scores = result.getCategoryScores();
    System.out.println("\nCategory Scores:");
    System.out.println("Sexual: " + scores.getSexual());
    System.out.println("Hate: " + scores.getHate());
    System.out.println("Harassment: " + scores.getHarassment());
    System.out.println("Self-Harm: " + scores.getSelfHarm());
    System.out.println("Sexual/Minors: " + scores.getSexualMinors());
    System.out.println("Hate/Threatening: " + scores.getHateThreatening());
    System.out.println("Violence/Graphic: " + scores.getViolenceGraphic());
    System.out.println("Self-Harm/Intent: " + scores.getSelfHarmIntent());
    System.out.println("Self-Harm/Instructions: " + scores.getSelfHarmInstructions());
    System.out.println("Harassment/Threatening: " + scores.getHarassmentThreatening());
    System.out.println("Violence: " + scores.getViolence());
}

수동 구성

Maven pom.xml 또는 Gradle build.gradle 파일에 sprint-ai-openai 의존성을 추가하세요.

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai</artifactId>
</dependency>

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai'
}

팁
Spring AI BOM을 build 파일에 추가하는 방법은 Dependency Management 섹션을 참조하세요.

 

다음으로 OpenAiModerationModel을 생성합니다.

OpenAiModerationApi openAiModerationApi = new OpenAiModerationApi(System.getenv("OPENAI_API_KEY"));

OpenAiModerationModel openAiModerationModel = new OpenAiModerationModel(this.openAiModerationApi);

OpenAiModerationOptions moderationOptions = OpenAiModerationOptions.builder()
    .model("text-moderation-latest")
    .build();

ModerationPrompt moderationPrompt = new ModerationPrompt("Text to be moderated", this.moderationOptions);
ModerationResponse response = this.openAiModerationModel.call(this.moderationPrompt);

예시 코드

OpenAiModerationModelIT 테스트 클래스는 라이브러리를 사용하는 일반적인 예시를 제공합니다. 더 자세한 사용법은 해당 테스트를 참고할 수 있습니다.

 

Reference

• Spring AI : Embedding Models API
• Spring AI : Audio Models > Transcription API > OpenAI
• Spring AI : Audio Models > Text-To-Speech (TTS) API > OpenAI
• Spring AI : Moderation Models > OpenAI