OpenAI 임베딩 모델 통합

OpenAI 임베딩 모델을 LangChain4j에서 쓰는 방법을 다룰게요. 문서 텍스트를 벡터로 바꿔서 검색(RAG)에 쓰려면 OpenAiEmbeddingModel을 만들면 돼요. 이 통합은 OpenAI REST API를 자바로 직접 구현한 방식이라 Quarkus(Quarkus REST client)와 Spring(Spring의 RestClient)에서 가장 잘 동작해요.

LangChain4j는 임베딩 모델을 위한 OpenAI 통합을 세 가지 제공하는데, 이 페이지가 그중 1번이에요.

OpenAI — OpenAI REST API의 자바 사용자 구현으로, Quarkus·Spring에 잘 맞아요.
OpenAI Official SDK — 공식 OpenAI 자바 SDK를 사용해요.
Azure OpenAI — 마이크로소프트의 Azure SDK를 쓰고, 고급 Azure 인증을 포함한 MS 자바 스택에서 가장 잘 동작해요.

출처: 공식문서

Maven 의존성

Plain Java

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>1.20.0</version>
</dependency>

Spring Boot

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai-spring-boot4-starter</artifactId>
    <version>1.20.0-beta30</version>
</dependency>

:::note 이 starter는 Spring Boot 4가 필요해요. Spring Boot 3에서는 langchain4j-open-ai-spring-boot-starter를 쓰면 되고, 자세한 건 Spring Boot Integration 문서를 참고하세요. :::

`OpenAiEmbeddingModel` 만들기

Plain Java

EmbeddingModel model = OpenAiEmbeddingModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("text-embedding-3-small")
        .build();

Spring Boot

application.properties에 추가해요:

# Mandatory properties:
langchain4j.open-ai.embedding-model.api-key=${OPENAI_API_KEY}
langchain4j.open-ai.embedding-model.model-name=text-embedding-3-small

# Optional properties:
langchain4j.open-ai.embedding-model.base-url=...
langchain4j.open-ai.embedding-model.custom-headers=...
langchain4j.open-ai.embedding-model.dimensions=...
langchain4j.open-ai.embedding-model.log-requests=...
langchain4j.open-ai.embedding-model.log-responses=...
langchain4j.open-ai.embedding-model.max-retries=...
langchain4j.open-ai.embedding-model.organization-id=...
langchain4j.open-ai.embedding-model.project-id=...
langchain4j.open-ai.embedding-model.timeout=...
langchain4j.open-ai.embedding-model.user=...

커스텀 임베딩 요청 파라미터 설정

OpenAiEmbeddingModel을 쓸 때 HTTP 요청 JSON 본문 안에 임베딩 요청용 커스텀 파라미터를 넣을 수 있어요. provider 특화 임베딩 파라미터를 요구하는 OpenAI 호환 제공자에서 유용한데, NVIDIA의 input_type 같은 게 대표적이에요:

EmbeddingModel model = OpenAiEmbeddingModel.builder()
        .baseUrl("https://integrate.api.nvidia.com/v1")
        .apiKey(System.getenv("NVIDIA_API_KEY"))
        .modelName("nvidia/nv-embedqa-e5-v5")
        .customParameters(Map.of("input_type", "passage"))
        .build();

기능 (Capabilities)

호출별 파라미터(EmbeddingRequest 경유): dimensions — text-embedding-3 모델에서 출력 차원을 줄여줘요. OpenAI 전용 user, encoding_format과 임의의 passthrough 파라미터는 OpenAiEmbeddingRequestParameters로 사용할 수 있어요(예: NVIDIA의 input_type).
텍스트 전용(이미지 입력 없음).
Listeners: OpenAiEmbeddingModel.builder().listeners(...)로 구성해요.

요청/응답 API는 Embedding Model을 참고하세요.

예시

OpenAiEmbeddingModelExamples

OpenAI 임베딩 모델 통합