Spring AI Cheat Sheet

The Spring AI APIs, annotations and application.yml properties you reach for daily — ChatClient, advisors, tool calling, structured output and vector stores.

ChatClient basics

Simple call

Send a user message, get the text back.

chatClient.prompt().user("Explain records").call().content();

System message

Set role and constraints with higher priority than user input.

chatClient.prompt().system("You are a terse Java expert.").user(q).call().content();

Streaming

Return a Flux of chunks; pair with SSE for interactive UIs.

Flux<String> stream = chatClient.prompt().user(q).stream().content();

Prompt template
Interpolate variables instead of concatenating strings.
```
.user(u -> u.text("Summarise {doc}").param("doc", doc))
```
Per-call options
Override model, temperature or max tokens for one request.
```
.options(ChatOptions.builder().temperature(0.2).build())
```
Defaults on the builder
Apply a system prompt or advisors to every call from this client.
```
builder.defaultSystem(PROMPT).defaultAdvisors(advisor).build();
```

Structured output

Into a record
Schema is derived from the type; the response is parsed and validated.
```
Recipe r = chatClient.prompt().user(q).call().entity(Recipe.class);
```
Into a generic list
Use ParameterizedTypeReference to keep the element type.
```
.entity(new ParameterizedTypeReference<List<Recipe>>() {});
```

Converter directly

When you need the format instructions inside a custom prompt.

var converter = new BeanOutputConverter<>(Recipe.class); converter.getFormat();

Tool calling

@Tool method
Any bean method becomes callable; the description is what the model reads.
```
@Tool(description = "Get current weather for a city") String weather(String city)
```
Typed parameters
Document each argument so the model fills it correctly.
```
@ToolParam(description = "ISO-8601 date") LocalDate date
```
Register per call
Expose only the tools this request should be allowed to use.
```
.tools(new WeatherTools())
```
Register globally
Every call from this client can use the tool.
```
builder.defaultTools(new WeatherTools()).build();
```

RAG & vector stores

Add documents

Embeds and persists in one call.

vectorStore.add(new TokenTextSplitter().apply(documents));

Similarity search

Top-k with a similarity floor to drop weak matches.

vectorStore.similaritySearch(SearchRequest.builder().query(q).topK(5).similarityThreshold(0.7).build());

Metadata filter
Restrict retrieval to a tenant, source or version.
```
.filterExpression("tenant == 'acme' && year >= 2024")
```
RAG advisor
Injects retrieved context into the prompt automatically.
```
.advisors(QuestionAnswerAdvisor.builder(vectorStore).build())
```

application.yml

spring.ai.openai.api-key
Prefer ${OPENAI_API_KEY} over a literal.
spring.ai.openai.chat.options.model
Model id for chat completions.
spring.ai.openai.chat.options.temperature
0.0-0.2 for extraction and tools.
spring.ai.openai.embedding.options.model
Embedding model; must match the store dimensions.
spring.ai.vectorstore.pgvector.dimensions
Must equal the embedding model output size.
spring.ai.vectorstore.pgvector.index-type
HNSW for production, IVFFLAT for smaller sets.
spring.ai.chat.observations.log-prompt
Off by default — prompts may contain personal data.