CtrlK

Community Documentation Log in Get started

tessl/maven-org-springframework-ai--spring-ai-starter-model-openai

Spring Boot Starter for OpenAI integration providing auto-configuration for chat completion, embeddings, image generation, audio speech synthesis, audio transcription, and content moderation models. Includes high-level ChatClient API and conversation memory support.

Overview

Eval results

Files

Embedding Model

Name: tessl/maven-org-springframework-ai--spring-ai-starter-model-openai
Author: tessl

The OpenAiEmbeddingModel generates vector embeddings for text and documents, enabling semantic search, similarity comparisons, and other vector-based operations.

Import

import org.springframework.ai.openai.OpenAiEmbeddingModel;
import org.springframework.ai.openai.OpenAiEmbeddingOptions;
import org.springframework.ai.embedding.EmbeddingRequest;
import org.springframework.ai.embedding.EmbeddingResponse;
import org.springframework.ai.embedding.Embedding;
import org.springframework.ai.document.Document;

API

OpenAiEmbeddingModel

package org.springframework.ai.openai;

public class OpenAiEmbeddingModel extends AbstractEmbeddingModel {
    // Embed single text string
    public float[] embed(String text);

    // Embed single document
    public float[] embed(Document document);

    // Embed multiple texts (returns list of float arrays)
    public List<float[]> embed(List<String> texts);

    // Embed multiple documents with options and batching strategy
    public List<List<Double>> embed(List<Document> documents, EmbeddingOptions options, BatchingStrategy batchingStrategy);

    // Embed multiple texts with response metadata
    public EmbeddingResponse embedForResponse(List<String> texts);

    // Embed with custom options
    public EmbeddingResponse call(EmbeddingRequest request);

    // Set observation convention
    public void setObservationConvention(EmbeddingModelObservationConvention observationConvention);
}

OpenAiEmbeddingOptions

package org.springframework.ai.openai;

public class OpenAiEmbeddingOptions implements EmbeddingOptions {
    // Builder methods
    public static OpenAiEmbeddingOptions.Builder builder();

    // Configuration - Getters
    public String getModel();
    public String getEncodingFormat();
    public Integer getDimensions();
    public String getUser();

    // Configuration - Setters
    public void setModel(String model);
    public void setEncodingFormat(String encodingFormat);
    public void setDimensions(Integer dimensions);
    public void setUser(String user);

    // Utility methods
    public Integer dimensions();
}

Usage Examples

Basic Text Embedding

import org.springframework.ai.openai.OpenAiEmbeddingModel;
import org.springframework.stereotype.Service;

@Service
public class EmbeddingService {

    private final OpenAiEmbeddingModel embeddingModel;

    public EmbeddingService(OpenAiEmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }

    public float[] embedText(String text) {
        return embeddingModel.embed(text);
    }
}

Document Embedding

import org.springframework.ai.document.Document;
import java.util.Map;

public float[] embedDocument(String content) {
    Document doc = new Document(content, Map.of("source", "user-input"));
    return embeddingModel.embed(doc);
}

Batch Embedding

import org.springframework.ai.embedding.EmbeddingResponse;
import org.springframework.ai.embedding.Embedding;
import java.util.List;

public List<float[]> embedMultipleTexts(List<String> texts) {
    EmbeddingResponse response = embeddingModel.embedForResponse(texts);

    return response.getResults().stream()
        .map(Embedding::getOutput)
        .toList();
}

Embedding with Options

import org.springframework.ai.openai.OpenAiEmbeddingOptions;
import org.springframework.ai.embedding.EmbeddingRequest;

public float[] embedWithOptions(String text) {
    OpenAiEmbeddingOptions options = OpenAiEmbeddingOptions.builder()
        .model("text-embedding-3-large")
        .dimensions(1024)
        .build();

    EmbeddingRequest request = new EmbeddingRequest(List.of(text), options);
    EmbeddingResponse response = embeddingModel.call(request);

    return response.getResults().get(0).getOutput();
}

Semantic Similarity

public double cosineSimilarity(float[] vec1, float[] vec2) {
    double dotProduct = 0.0;
    double norm1 = 0.0;
    double norm2 = 0.0;

    for (int i = 0; i < vec1.length; i++) {
        dotProduct += vec1[i] * vec2[i];
        norm1 += vec1[i] * vec1[i];
        norm2 += vec2[i] * vec2[i];
    }

    return dotProduct / (Math.sqrt(norm1) * Math.sqrt(norm2));
}

public double calculateSimilarity(String text1, String text2) {
    float[] embedding1 = embeddingModel.embed(text1);
    float[] embedding2 = embeddingModel.embed(text2);
    return cosineSimilarity(embedding1, embedding2);
}

Document Search

import org.springframework.ai.document.Document;
import java.util.List;
import java.util.Map;

public List<Document> searchDocuments(String query, List<Document> documents) {
    // Embed the query
    float[] queryEmbedding = embeddingModel.embed(query);

    // Embed all documents and calculate similarity
    return documents.stream()
        .map(doc -> {
            float[] docEmbedding = embeddingModel.embed(doc);
            double similarity = cosineSimilarity(queryEmbedding, docEmbedding);
            return Map.entry(doc, similarity);
        })
        .sorted((e1, e2) -> Double.compare(e2.getValue(), e1.getValue()))
        .map(Map.Entry::getKey)
        .limit(5)
        .toList();
}

Embedding with Document Metadata

import org.springframework.ai.document.Document;
import org.springframework.ai.document.MetadataMode;
import org.springframework.ai.openai.OpenAiEmbeddingOptions;

public float[] embedWithMetadata(String content, Map<String, Object> metadata) {
    Document doc = new Document(content, metadata);

    // Include metadata in embedding
    OpenAiEmbeddingOptions options = OpenAiEmbeddingOptions.builder()
        .model("text-embedding-ada-002")
        .build();

    // Metadata handling controlled by application property:
    // spring.ai.openai.embedding.metadata-mode=EMBED (default)
    return embeddingModel.embed(doc);
}

Configuration

Configure via application.properties:

# API Connection
spring.ai.openai.embedding.api-key=sk-...
spring.ai.openai.embedding.base-url=https://api.openai.com
spring.ai.openai.embedding.project-id=proj_...
spring.ai.openai.embedding.organization-id=org-...
spring.ai.openai.embedding.embeddings-path=/v1/embeddings

# Model Configuration
spring.ai.openai.embedding.options.model=text-embedding-ada-002
spring.ai.openai.embedding.options.encoding-format=float
spring.ai.openai.embedding.options.dimensions=1536

# Document Metadata Handling
spring.ai.openai.embedding.metadata-mode=EMBED

Response Metadata

Access metadata from embedding responses:

EmbeddingResponse response = embeddingModel.embedForResponse(List.of("text"));

// Token usage
EmbeddingResponseMetadata metadata = response.getMetadata();
Integer totalTokens = metadata.getUsage().getTotalTokens();

// Model information
String model = metadata.getModel();

Model Options

Available Models

text-embedding-ada-002 - Cost-effective, 1536 dimensions (default)
text-embedding-3-small - Improved performance, configurable dimensions
text-embedding-3-large - Highest quality, configurable dimensions

Dimensions

For text-embedding-3-small and text-embedding-3-large, you can configure output dimensions:

Smaller dimensions = faster processing, lower cost
Larger dimensions = better accuracy
Default: 1536 for ada-002, 1536 for -3-small, 3072 for -3-large

Encoding Format

float - Standard floating point (default)
base64 - Base64-encoded binary format (more compact)

Metadata Mode

Controls how document metadata is included in embeddings:

EMBED - Include metadata in text to be embedded (default)
NONE - Exclude all metadata
ALL - Include all metadata fields

Document Handling

Document Structure

package org.springframework.ai.document;

public class Document {
    public Document(String content);
    public Document(String content, Map<String, Object> metadata);
    public Document(String id, String content, Map<String, Object> metadata);

    public String getId();
    public String getContent();
    public Map<String, Object> getMetadata();
    public float[] getEmbedding();
    public void setEmbedding(float[] embedding);
}

Document Metadata Mode

package org.springframework.ai.document;

public enum MetadataMode {
    ALL,    // Include all metadata
    EMBED,  // Include metadata in embedding (default)
    NONE    // Exclude metadata
}

Error Handling

import org.springframework.ai.openai.api.OpenAiApiException;

public float[] safeEmbed(String text) {
    try {
        return embeddingModel.embed(text);
    } catch (OpenAiApiException e) {
        // Handle API errors (rate limits, invalid API key, etc.)
        throw new RuntimeException("Embedding failed: " + e.getMessage(), e);
    }
}

Types

Builder

package org.springframework.ai.openai;

public static class Builder {
    public Builder model(String model);
    public Builder encodingFormat(String encodingFormat);
    public Builder dimensions(Integer dimensions);
    public Builder user(String user);
    public OpenAiEmbeddingOptions build();
}

EmbeddingRequest

package org.springframework.ai.embedding;

public class EmbeddingRequest {
    public EmbeddingRequest(List<String> inputs);
    public EmbeddingRequest(List<String> inputs, EmbeddingOptions options);

    public List<String> getInstructions();
    public EmbeddingOptions getOptions();
}

EmbeddingResponse

package org.springframework.ai.embedding;

public class EmbeddingResponse {
    public List<Embedding> getResults();
    public EmbeddingResponseMetadata getMetadata();
}

Embedding

package org.springframework.ai.embedding;

public class Embedding {
    public float[] getOutput();
    public Integer getIndex();
    public EmbeddingMetadata getMetadata();
}

tessl i tessl/maven-org-springframework-ai--spring-ai-starter-model-openai@1.1.1

docs

examples

guides

reference

audio-speech-model.md

audio-transcription-model.md