Chiamare un LLM da Spring Boot con Spring AI 2.0: risposta, streaming e output strutturato
Un esempio testato con Spring Boot 4.1 e Spring AI 2.0 e un modello locale Ollama: risposta semplice, risposta in streaming e risposta mappata su un record Java, più le modifiche di configurazione che rompono i tutorial più vecchi.

Spring AI offre alle applicazioni Spring Boot un'unica API, il ChatClient, per dialogare con i modelli linguistici di OpenAI, Anthropic, Google, Mistral, Ollama e altri. In questa guida costruiamo un piccolo servizio REST con tre endpoint:
/askrestituisce tutta la risposta del modello come testo;/ask/streaminvia la risposta un pezzo alla volta, così l'utente la vede comparire;/advicechiede una risposta strutturata e la converte in unrecordJava.
Usiamo Ollama, che esegue modelli open sul tuo computer: nessuna chiave API, nessun costo a richiesta, e nessun dato esce dal portatile. Passare poi a un fornitore in cloud richiede una dipendenza e qualche proprietà, come mostrato alla fine.
Versioni usate (verificate su Maven Central il 30 ottobre 2026): Spring Boot 4.1.2, Spring AI 2.0.2, Java 21. A quella data Spring AI 2.1 e Spring Boot 4.2 erano ancora release candidate. Il progetto completo è su GitHub e viene compilato a ogni modifica.
Prerequisiti
- Java 21 e Maven.
- Ollama installato e avviato (risponde su
http://localhost:11434). - Un modello. Noi abbiamo provato con
llama3.2:1b(circa 1,3 GB) perché è veloce su un portatile;llama3.2(3B) dà risposte migliori.
ollama pull llama3.2
La configurazione Maven
Importa il BOM di Spring AI, così tutti i moduli Spring AI hanno la stessa versione, poi aggiungi lo starter del tuo fornitore. Lo starter Ollama porta l'auto-configurazione e il ChatClient.
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.1.2</version>
</parent>
<properties>
<java.version>21</java.version>
<spring-ai.version>2.0.2</spring-ai.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>${spring-ai.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>
</dependencies>
Configurazione: in 2.0 il nome della proprietà è cambiato
Qui molti tutorial più vecchi smettono di funzionare. In Spring AI 2.0 il modello e la temperatura sono saliti di un livello:
| Spring AI 1.x (ancora accettata, deprecata) | Spring AI 2.0 |
|---|---|
spring.ai.ollama.chat.options.model |
spring.ai.ollama.chat.model |
spring.ai.ollama.chat.options.temperature |
spring.ai.ollama.chat.temperature |
L'abbiamo verificato nei metadati di configurazione contenuti in spring-ai-autoconfigure-model-ollama-2.0.2.jar: i vecchi nomi sono segnati come deprecati e indicano i nuovi come sostituti. Usa i nomi nuovi:
spring.application.name=spring-ai-chat
spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.model=llama3.2
spring.ai.ollama.chat.temperature=0.2
# Download the model on first start if it is missing (default: never)
spring.ai.ollama.init.pull-model-strategy=when_missing
Una temperatura bassa (0.2) rende le risposte più ripetibili, che è quello che serve nella maggior parte delle funzioni applicative. Il valore predefinito di pull-model-strategy è never: senza l'ultima riga, l'applicazione fallisce alla prima richiesta se il modello non è stato scaricato.
Creare il ChatClient
Spring Boot configura in automatico un ChatClient.Builder per il fornitore presente nel classpath. Inietta il builder, imposta i valori predefiniti per ogni richiesta (qui un prompt di sistema) e crea il client una volta sola:
@RestController
public class ChatController {
private final ChatClient chatClient;
public ChatController(ChatClient.Builder builder) {
this.chatClient = builder
.defaultSystem("You are a concise assistant for Java developers. Answer in plain text.")
.build();
}
}
Il prompt di sistema viene inviato a ogni richiesta. Tienilo breve: lo paghi, in tempo o in denaro, a ogni chiamata.
1. Una risposta semplice
@GetMapping("/ask")
public String ask(@RequestParam String q) {
return chatClient.prompt()
.user(q)
.call()
.content();
}
call() attende la risposta completa; content() la restituisce come String.
curl "localhost:8080/ask?q=What%20is%20a%20Java%20record%3F%20One%20sentence."
2. La risposta in streaming
I modelli linguistici producono il testo un token alla volta. Aspettare la risposta intera può richiedere diversi secondi, quindi per tutto ciò che legge una persona conviene lo streaming:
@GetMapping(value = "/ask/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> askStream(@RequestParam String q) {
return chatClient.prompt()
.user(q)
.stream()
.content();
}
stream() restituisce un Flux<String> di Reactor. Anche in un'applicazione Spring MVC classica (usiamo spring-boot-starter-web, non WebFlux), restituire un Flux con text/event-stream invia ogni pezzo al browser come Server-Sent Event:
curl -N "localhost:8080/ask/stream?q=Name%20three%20Java%20build%20tools."
# data:Here
# data: are
# data: three
# ...
Nel browser si legge con EventSource oppure con fetch e un lettore di stream.
3. Output strutturato in un record Java
Spesso non serve un testo, servono dati. entity() chiede al modello un JSON conforme al tuo tipo e lo converte:
public record LibraryAdvice(String library, String reason, List<String> alternatives) {}
@GetMapping("/advice")
public LibraryAdvice advice(@RequestParam String task) {
return chatClient.prompt()
.user(u -> u.text("Suggest one Java library for this task: {task}").param("task", task))
.call()
.entity(LibraryAdvice.class);
}
Spring AI aggiunge al prompt le istruzioni di formato, con uno schema JSON ricavato dal record, poi interpreta la risposta. Il segnaposto {task} viene riempito da param(), che tiene separato l'input dell'utente dal testo del tuo modello di prompt.
Valida quello che torna indietro
È la lezione più importante della nostra prova. Con il modello piccolo llama3.2:1b, l'endpoint /advice ha restituito un JSON perfettamente valido:
{"library":"org.apache.commons.csv","reason":"CSV file parser",
"alternatives":["org.apache.commons.csv.CSVParser","org.json.simple.CSVParser"]}
La struttura è giusta, ma org.json.simple.CSVParser non esiste. Nella stessa sessione il modello ha anche detto che i record sono arrivati con Java 14 (lì erano in anteprima; sono diventati definitivi con Java 16). Un formato corretto non garantisce un contenuto corretto. Prima di usare una risposta strutturata:
- valida i campi con Bean Validation o con controlli tuoi (la libreria è nella lista consentita? questo ID esiste nel database?);
- tieni bassa la temperatura e preferisci un modello più grande per i compiti che richiedono fatti precisi;
- quando un errore costa caro, tratta il risultato come un suggerimento per una persona, oppure basalo sui tuoi dati (retrieval).
Retry: controlla i valori predefiniti
Spring AI ripete le chiamate fallite al modello tramite spring-ai-retry. I valori predefiniti nella 2.0.2 (dai metadati di configurazione) sono spring.ai.retry.max-attempts=10, spring.ai.retry.backoff.initial-interval=2000ms e spring.ai.retry.backoff.multiplier=5. Vanno bene per un'elaborazione in background, ma per un utente in attesa di una risposta HTTP possono trasformare un errore in un'attesa lunghissima. Per gli endpoint interattivi abbassali:
spring.ai.retry.max-attempts=3
spring.ai.retry.backoff.initial-interval=500ms
spring.ai.retry.backoff.multiplier=2
spring.ai.retry.backoff.max-interval=5s
Se chiami direttamente un'API in cloud, la nostra guida su come gestire l'HTTP 429 con Retry-After spiega cosa ripetere e quanto aspettare, e il simulatore di backoff mostra come impostazioni diverse distribuiscono i tentativi nel tempo.
Passare a un modello in cloud
Il codice del controller non cambia. Sostituisci lo starter e le proprietà, per esempio per Anthropic:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-anthropic</artifactId>
</dependency>
Lo stesso schema vale per spring-ai-starter-model-openai e per gli altri starter di modelli (tutti pubblicati per la 2.0.2). Ogni fornitore ha le sue proprietà spring.ai.<fornitore>.* per la chiave API e il nome del modello: prendi i nomi esatti dalla pagina del fornitore nella documentazione di riferimento di Spring AI, e tieni la chiave API in una variabile d'ambiente, mai in un application.properties salvato su Git.
Prima della produzione
- Timeout: un modello può impiegare decine di secondi. Imposta i timeout sul client HTTP e sul tuo endpoint.
- Costi e limiti: le API in cloud si pagano a token e hanno limiti di frequenza. Registra l'uso dei token e limita la dimensione dell'input dell'utente.
- Log: prompt e risposte possono contenere dati personali. Prima di condividere i log togli segreti e dati personali (il nostro redattore di log e HAR funziona nel browser).
- Errori: traduci i fallimenti del modello in codici HTTP chiari per i tuoi client; vedi quale codice restituire.
L'esempio completo, con i tre endpoint e la configurazione qui sopra, è nel nostro repository GitHub. Il capitolo su ChatClient della documentazione di Spring AI tratta advisor, memoria e tool calling, i passi successivi a questa guida.
L'esempio completo e testato di questo articolo è nel nostro repository pubblico: adamant-solutions/ai-dev-examples/spring-ai-chat