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

OpenAI models support for Spring AI, providing comprehensive integration for chat completion, embeddings, image generation, audio transcription, text-to-speech, and content moderation capabilities within Spring Boot applications.

Overview

Eval results

Files

Quick Start Guide

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

Get started with Spring AI OpenAI in 5 minutes.

Prerequisites

Java 17 or later
Maven or Gradle
OpenAI API key (Get one here)

Installation

Maven

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

Gradle

implementation 'org.springframework.ai:spring-ai-openai:1.1.2'

Basic Usage

1. Chat Completion

import org.springframework.ai.openai.OpenAiChatModel;
import org.springframework.ai.openai.api.OpenAiApi;
import org.springframework.ai.chat.prompt.Prompt;

public class ChatExample {
    public static void main(String[] args) {
        // Create API client
        var openAiApi = OpenAiApi.builder()
            .apiKey(System.getenv("OPENAI_API_KEY"))
            .build();

        // Create chat model
        var chatModel = OpenAiChatModel.builder()
            .openAiApi(openAiApi)
            .build();

        // Generate response
        var response = chatModel.call(
            new Prompt("Explain quantum computing in simple terms")
        );

        System.out.println(response.getResult().getOutput().getContent());
    }
}

2. Embeddings

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

// Create embedding model
var embeddingModel = new OpenAiEmbeddingModel(
    openAiApi,
    MetadataMode.EMBED,
    OpenAiEmbeddingOptions.builder()
        .model(OpenAiApi.EmbeddingModel.TEXT_EMBEDDING_3_SMALL.getValue())
        .build()
);

// Generate embedding
var document = new Document("The quick brown fox jumps over the lazy dog");
float[] embedding = embeddingModel.embed(document);
System.out.println("Embedding dimensions: " + embedding.length);

3. Image Generation

import org.springframework.ai.openai.OpenAiImageModel;
import org.springframework.ai.openai.OpenAiImageOptions;
import org.springframework.ai.openai.api.OpenAiImageApi;
import org.springframework.ai.image.ImagePrompt;

// Create image API client
var imageApi = OpenAiImageApi.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

// Create image model
var imageModel = new OpenAiImageModel(
    imageApi,
    OpenAiImageOptions.builder()
        .model(OpenAiImageApi.ImageModel.DALL_E_3.getValue())
        .build(),
    null
);

// Generate image
var response = imageModel.call(
    new ImagePrompt("A serene mountain landscape at sunset")
);

System.out.println("Image URL: " + response.getResult().getOutput().getUrl());

4. Audio Transcription

import org.springframework.ai.openai.OpenAiAudioTranscriptionModel;
import org.springframework.ai.openai.api.OpenAiAudioApi;
import org.springframework.core.io.FileSystemResource;

// Create audio API client
var audioApi = OpenAiAudioApi.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

// Create transcription model
var transcriptionModel = new OpenAiAudioTranscriptionModel(audioApi);

// Transcribe audio
var audioFile = new FileSystemResource("recording.mp3");
String transcript = transcriptionModel.call(audioFile);
System.out.println("Transcript: " + transcript);

5. Text-to-Speech

import org.springframework.ai.openai.OpenAiAudioSpeechModel;
import org.springframework.ai.openai.OpenAiAudioSpeechOptions;
import java.nio.file.Files;
import java.nio.file.Paths;

// Create speech model
var speechModel = new OpenAiAudioSpeechModel(
    audioApi,
    OpenAiAudioSpeechOptions.builder()
        .model(OpenAiAudioApi.TtsModel.TTS_1_HD.getValue())
        .voice("nova")
        .build()
);

// Generate speech
byte[] audioBytes = speechModel.call("Hello, how can I help you today?");
Files.write(Paths.get("speech.mp3"), audioBytes);

6. Content Moderation

import org.springframework.ai.openai.OpenAiModerationModel;
import org.springframework.ai.openai.api.OpenAiModerationApi;
import org.springframework.ai.moderation.ModerationPrompt;

// Create moderation API client
var moderationApi = OpenAiModerationApi.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

// Create moderation model
var moderationModel = new OpenAiModerationModel(moderationApi);

// Moderate content
var response = moderationModel.call(new ModerationPrompt("Some text to moderate"));
var result = response.getResult();

if (result.isFlagged()) {
    System.out.println("Content flagged!");
    result.getCategories().forEach((category, flagged) -> {
        if (flagged) {
            System.out.println("  - " + category);
        }
    });
}

Spring Boot Integration

1. Add Spring Boot Starter

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>1.1.2</version>
</dependency>

2. Configure Properties

# application.properties
spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.options.model=gpt-4o
spring.ai.openai.chat.options.temperature=0.7
spring.ai.openai.chat.options.max-tokens=1000

3. Use Auto-Configured Beans

import org.springframework.ai.openai.OpenAiChatModel;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/chat")
public class ChatController {
    private final OpenAiChatModel chatModel;

    // Auto-injected by Spring Boot
    public ChatController(OpenAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @PostMapping
    public String chat(@RequestBody String message) {
        return chatModel.call(new Prompt(message))
            .getResult()
            .getOutput()
            .getContent();
    }
}

Advanced Configuration

Custom Options

import org.springframework.ai.openai.OpenAiChatOptions;

var options = OpenAiChatOptions.builder()
    .model(OpenAiApi.ChatModel.GPT_4_O.getValue())
    .temperature(0.7)
    .maxTokens(1000)
    .topP(0.9)
    .frequencyPenalty(0.0)
    .presencePenalty(0.0)
    .build();

var chatModel = OpenAiChatModel.builder()
    .openAiApi(openAiApi)
    .defaultOptions(options)
    .build();

Retry Configuration

import org.springframework.retry.support.RetryTemplate;

var retryTemplate = RetryTemplate.builder()
    .maxAttempts(3)
    .exponentialBackoff(1000, 2.0, 10000)
    .build();

var chatModel = OpenAiChatModel.builder()
    .openAiApi(openAiApi)
    .retryTemplate(retryTemplate)
    .build();

Observability

import io.micrometer.observation.ObservationRegistry;

var chatModel = OpenAiChatModel.builder()
    .openAiApi(openAiApi)
    .observationRegistry(observationRegistry)
    .build();

Streaming Responses

import reactor.core.publisher.Flux;

// Streaming chat
Flux<ChatResponse> stream = chatModel.stream(
    new Prompt("Write a short story")
);

stream.subscribe(response -> {
    String content = response.getResult().getOutput().getContent();
    if (content != null) {
        System.out.print(content);
    }
});

Tool/Function Calling

import org.springframework.ai.model.function.FunctionCallback;

// Define function callback
FunctionCallback weatherCallback = FunctionCallback.builder()
    .function("get_weather", "Get weather for a location")
    .inputType(WeatherRequest.class)
    .apply(request -> {
        return new WeatherResponse(request.location(), "72°F", "Sunny");
    })
    .build();

// Configure with tools
var options = OpenAiChatOptions.builder()
    .tools(List.of(weatherTool))
    .toolCallbacks(Map.of("get_weather", weatherCallback))
    .build();

var response = chatModel.call(
    new Prompt("What's the weather in San Francisco?", options)
);

Error Handling

import org.springframework.ai.openai.api.common.OpenAiApiClientErrorException;

try {
    var response = chatModel.call(new Prompt("Hello"));
} catch (OpenAiApiClientErrorException e) {
    switch (e.getStatusCode()) {
        case 401 -> System.err.println("Invalid API key");
        case 429 -> System.err.println("Rate limit exceeded");
        case 400 -> System.err.println("Invalid request: " + e.getMessage());
        default -> System.err.println("API error: " + e.getMessage());
    }
} catch (Exception e) {
    System.err.println("Unexpected error: " + e.getMessage());
}

Next Steps

Real-World Scenarios - Production patterns and use cases
Chat Models Reference - Complete chat API documentation
Embedding Models Reference - Vector embeddings API
Image Models Reference - DALL-E image generation
Audio Models Reference - TTS and transcription
API Clients Reference - Low-level REST clients

Common Issues

API Key Not Found

Error: API key not set
Solution: Set OPENAI_API_KEY environment variable

Rate Limit Exceeded

Error: 429 Too Many Requests
Solution: Implement retry with exponential backoff

Connection Timeout

Error: Read timeout
Solution: Increase timeout or check network connectivity

Resources

Install with Tessl CLI

npx tessl i tessl/maven-org-springframework-ai--spring-ai-openai

docs

examples

guides

quick-start.md

reference

index.md

tile.json