langchain4j--langchain4j/docs/docs/integrations/embedding-models/open-ai.md

sidebar_position

sidebar_position
15

OpenAI

:::note

This is the documentation for the OpenAI integration, that uses a custom Java implementation of the OpenAI REST API, that works best with Quarkus (as it uses the Quarkus REST client) and Spring (as it uses Spring's RestClient).

LangChain4j provides 3 different integrations with OpenAI for using embedding models, and this is #1 :

• OpenAI uses a custom Java implementation of the OpenAI REST API, that works best with Quarkus (as it uses the Quarkus REST client) and Spring (as it uses Spring's RestClient).
• OpenAI Official SDK uses the official OpenAI Java SDK.
• Azure OpenAI uses the Azure SDK from Microsoft, and works best if you are using the Microsoft Java stack, including advanced Azure authentication mechanisms.

:::

• https://platform.openai.com/docs/guides/embeddings
• https://platform.openai.com/docs/api-reference/embeddings

Maven Dependency

Plain Java

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

Spring Boot

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>
    <version>1.17.2-beta27</version>
</dependency>

Creating OpenAiEmbeddingModel

Plain Java

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

Spring Boot

Add to the 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=...

Setting custom embedding request parameters

When using OpenAiEmbeddingModel, you can configure custom parameters for the embedding request within the HTTP request's JSON body. This is useful for OpenAI-compatible providers that require provider-specific embedding parameters:

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

• Per-call parameters (via EmbeddingRequest): dimensions — reduce output dimensionality on text-embedding-3 models. OpenAI-specific user, encoding_format and arbitrary passthrough parameters are available via OpenAiEmbeddingRequestParameters (used, for example, for NVIDIA's input_type).
• Text-only (no image inputs).
• Listeners: configure via OpenAiEmbeddingModel.builder().listeners(...).

See Embedding Model for the request/response API.

Examples

• OpenAiEmbeddingModelExamples