Adamant Tools

Adamant Tools › Blog

  • Java
  • Spring AI
  • Spring Boot
  • Ollama

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.

Pubblicato 5 min di letturaGitHubRead in English

Chiamare un LLM da Spring Boot con Spring AI 2.0: risposta, streaming e output strutturato
Foto: Franklsf95, CC BY-SA 3.0, Wikimedia Commons

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:

  1. /ask restituisce tutta la risposta del modello come testo;
  2. /ask/stream invia la risposta un pezzo alla volta, così l'utente la vede comparire;
  3. /advice chiede una risposta strutturata e la converte in un record Java.

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.
bash
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.

xml
<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:

properties
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:

java
@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

java
@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.

bash
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:

java
@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:

bash
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:

java
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:

json
{"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:

properties
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:

xml
<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.

Codice completo su GitHub
L'esempio completo e testato di questo articolo è nel nostro repository pubblico: adamant-solutions/ai-dev-examples/spring-ai-chat

Chi l'ha scritto

Scritto dal team tecnico di Adamant Solutions: ingegneri senior che lavorano su API, identità e integrazione enterprise, certificati WSO2 e Spring. Il codice è testato prima della pubblicazione; se trovi un errore, scrivi a administrata@adamant-solutions.com.