Java SpringAI

Spring AI 1.0 Complete API Reference — Every Interface, Builder, and Option

Comments

Spring AI 1.0 Complete API Reference — Every Interface, Builder, and Option

A quick-reference guide to the complete Spring AI 1.0 public API — every important interface, builder method, configuration property, and annotation. Bookmark this post to find what you need without searching the docs.

BOM and Core Dependencies

<!-- pom.xml -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- Starters -->
spring-ai-openai-spring-boot-starter
spring-ai-anthropic-spring-boot-starter
spring-ai-vertex-ai-gemini-spring-boot-starter
spring-ai-azure-openai-spring-boot-starter
spring-ai-ollama-spring-boot-starter
spring-ai-pgvector-store-spring-boot-starter
spring-ai-chroma-store-spring-boot-starter
spring-ai-pinecone-store-spring-boot-starter
spring-ai-redis-store-spring-boot-starter
spring-ai-pdf-document-reader
spring-ai-tika-document-reader
spring-ai-mcp-server-spring-boot-starter
spring-ai-mcp-client-spring-boot-starter

ChatClient — Full Builder API

// Build
ChatClient chatClient = ChatClient.builder(chatModel)
        .defaultSystem("System prompt")
        .defaultUser("Default user template")
        .defaultOptions(OpenAiChatOptions.builder()
                .withModel("gpt-4o-mini")
                .withTemperature(0.7f)
                .withMaxTokens(4096)
                .withTopP(1.0f)
                .withPresencePenalty(0.0f)
                .withFrequencyPenalty(0.0f)
                .withStop(List.of("STOP"))
                .build())
        .defaultAdvisors(
                new SimpleLoggerAdvisor(),
                new MessageChatMemoryAdvisor(chatMemory),
                new QuestionAnswerAdvisor(vectorStore)
        )
        .build();

// Prompt building
chatClient.prompt()
        .system("Override system")
        .user("User message")
        .messages(List.of(new UserMessage("msg"), new AssistantMessage("reply")))
        .options(OpenAiChatOptions.builder().withModel("gpt-4o").build())
        .advisors(a -> a.param("key", "value"))

// Response formats
.call().content()              // String
.call().chatResponse()         // ChatResponse (includes metadata)
.call().entity(MyClass.class)  // structured output via BeanOutputConverter
.call().entity(new ParameterizedTypeReference<List<MyClass>>(){})
.stream().content()            // Flux<String>
.stream().chatResponse()       // Flux<ChatResponse>

VectorStore — Full API

VectorStore vectorStore = /* injected */;

// Store documents
vectorStore.add(List.of(new Document("content", Map.of("key", "value"))));
vectorStore.delete(List.of("id1", "id2"));

// Search
List<Document> results = vectorStore.similaritySearch("query");

// Advanced search
List<Document> results = vectorStore.similaritySearch(
        SearchRequest.query("query text")
                .withTopK(5)
                .withSimilarityThreshold(0.7)  // 0.0 - 1.0
                .withFilterExpression("category == 'java'")
);

// Filter expressions
"category == 'java'"
"year > 2024"
"category == 'java' && year > 2024"
"category in ['java', 'spring']"
"NOT category == 'deprecated'"

EmbeddingModel — Full API

EmbeddingModel embeddingModel = /* injected */;

// Single text
float[] vector = embeddingModel.embed("text to embed");

// Batch
EmbeddingResponse response = embeddingModel.embedForResponse(List.of("text1", "text2"));
List<Embedding> embeddings = response.getResults();
float[] firstVector = embeddings.get(0).getOutput();

// With options
EmbeddingRequest request = new EmbeddingRequest(
        List.of("text1"),
        OpenAiEmbeddingOptions.builder()
                .withModel("text-embedding-3-small")
                .build());
EmbeddingResponse response = embeddingModel.call(request);

Document ETL — Full API

// Readers
PagePdfDocumentReader pdfReader = new PagePdfDocumentReader(resource,
        PdfDocumentReaderConfig.builder()
                .withPagesPerDocument(1)
                .withPageTopMargin(0)
                .build());

TikaDocumentReader tikaReader = new TikaDocumentReader(resource);
TextReader textReader = new TextReader(resource);
JsonReader jsonReader = new JsonReader(resource, "$.field.path");

// Transformers
TokenTextSplitter splitter = TokenTextSplitter.builder()
        .withChunkSize(800)
        .withMinChunkSizeChars(350)
        .withMinChunkLengthToEmbed(5)
        .withMaxNumChunks(1000)
        .withKeepSeparator(true)
        .build();

KeywordMetadataEnricher keywordEnricher = new KeywordMetadataEnricher(chatModel, 5);
SummaryMetadataEnricher summaryEnricher = new SummaryMetadataEnricher(chatModel,
        List.of(MetadataMode.ALL));

// Pipeline
new TokenTextSplitter()
        .apply(reader.get())          // split documents
        .stream()
        .map(keywordEnricher)          // enrich
        .forEach(vectorStore::add);    // store

Advisors — Full API

// Built-in
SimpleLoggerAdvisor()               // debug logging
MessageChatMemoryAdvisor(memory)    // multi-turn chat
QuestionAnswerAdvisor(vectorStore)  // RAG
ReActAdvisor.maxIterations(10)      // agentic loop

// Custom
public class MyAdvisor implements CallAroundAdvisor {
    @Override
    public AdvisedResponse aroundCall(AdvisedRequest request, CallAroundAdvisorChain chain) {
        // Modify request
        AdvisedRequest modified = AdvisedRequest.from(request)
                .withUserText(request.userText() + " extra instruction")
                .build();

        // Call next in chain
        AdvisedResponse response = chain.nextAroundCall(modified);

        // Inspect/modify response
        return response;
    }
    @Override public int getOrder()    { return 0; }
    @Override public String getName()  { return "MyAdvisor"; }
}

// Context parameters
chatClient.prompt().advisors(a -> a
        .param(MessageChatMemoryAdvisor.CHAT_MEMORY_CONVERSATION_ID_KEY, "session-1")
        .param(QuestionAnswerAdvisor.FILTER_EXPRESSION, "category == 'java'")
        .param("myCustomParam", "value"));

Tool Calling — Full API

// Declare tools
public class WeatherTools {
    @Tool(description = "Get current weather for a city")
    public WeatherData getWeather(String city) { ... }

    @Tool(description = "Get 7-day forecast")
    public List<ForecastDay> getForecast(String city, int days) { ... }
}

// Register in ChatClient
chatClient.prompt()
        .user("What's the weather in Paris?")
        .tools(new WeatherTools())           // instance — all @Tool methods auto-registered
        .call().content();

application.properties — All Common Properties

# OpenAI
spring.ai.openai.api-key=
spring.ai.openai.base-url=https://api.openai.com
spring.ai.openai.chat.options.model=gpt-4o-mini
spring.ai.openai.chat.options.temperature=0.7
spring.ai.openai.chat.options.max-tokens=4096
spring.ai.openai.embedding.options.model=text-embedding-3-small

# Anthropic
spring.ai.anthropic.api-key=
spring.ai.anthropic.chat.options.model=claude-sonnet-4-6
spring.ai.anthropic.chat.options.max-tokens=8096

# Ollama
spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.options.model=llama3.2
spring.ai.ollama.embedding.options.model=nomic-embed-text

# PGVector
spring.ai.vectorstore.pgvector.initialize-schema=true
spring.ai.vectorstore.pgvector.dimensions=1536
spring.ai.vectorstore.pgvector.distance-type=cosine_distance
spring.ai.vectorstore.pgvector.index-type=hnsw

# Retry
spring.ai.retry.max-attempts=3
spring.ai.retry.on-http-codes=429,503
spring.ai.retry.backoff.initial-interval=1000ms
spring.ai.retry.backoff.multiplier=2
spring.ai.retry.backoff.max-interval=30000ms

Key Points

  • All provider starters auto-configure ChatClient.Builder, ChatModel, and EmbeddingModel — just inject ChatClient.Builder and call .build()
  • The VectorStore interface is the same regardless of provider — only the starter dependency and spring.ai.vectorstore.* properties change
  • Use .call().entity(MyClass.class) for structured output — Spring AI automatically adds JSON format instructions and parses the response
  • Advisor execution order: lowest getOrder() value runs first on request, last on response — HIGHEST_PRECEDENCE for safety, LOWEST_PRECEDENCE for logging
  • The BOM manages all Spring AI artifact versions consistently — never specify individual Spring AI artifact versions in your dependencies
Topics: Java SpringAI
← Newer Post Older Post →

Comments