Guida Spring AI

Guida Spring AI

Indice dei contenuti Guida Spring AI

1. Introduzione: cos’è Spring AI e perché usarlo nel 2026
2. Architettura e componenti principali
3. Installazione e configurazione rapida
4. ChatClient API: il primo esempio pratico
5. RAG e Vector Store: AI che conosce i tuoi dati
6. Tool Calling e Advisors API
7. MCP (Model Context Protocol): Spring AI 1.1 e 2.0
8. Best practice: pro e contro di Spring AI
9. Conclusioni e formazione professionale

1. Introduzione: cos’è Spring AI e perché usarlo nel 2026

Il mercato dello sviluppo software è cambiato radicalmente negli ultimi due anni. Integrare modelli di linguaggio di grandi dimensioni (LLM) nelle applicazioni aziendali è passato dall’essere un esperimento da laboratorio a una necessità competitiva. La domanda per i team Java è: come farlo senza abbandonare l’ecosistema Spring che già conoscono?

Spring AI è la risposta ufficiale del team di Broadcom/VMware. Nato come progetto sperimentale nel 2023, ha raggiunto la versione 1.0 GA il 20 maggio 2025, seguita dalla 1.1 GA a novembre 2025 e dai milestone di Spring AI 2.0 (basato su Spring Boot 4) a partire da dicembre 2025. La versione stabile attuale, ad aprile 2026, è la 1.1.x, mentre la 2.0 è in milestone avanzato.

L’obiettivo di Spring AI è portare nel dominio AI gli stessi principi del framework Spring: portabilità, modularità e facilità d’uso tramite POJO e dependency injection. Come Spring Data astrae il layer di persistenza e Spring Security quello della sicurezza, Spring AI astrae la comunicazione con qualsiasi provider LLM.

2. Architettura e componenti principali – Guida Spring AI

Spring AI si struttura attorno a un insieme di astrazioni portabili che si mappano sui principali provider AI. I componenti fondamentali sono:

• ChatModel / ChatClient — l’API principale per dialogare con i modelli linguistici (OpenAI, Anthropic Claude, Google Gemini, Ollama e altri)
• EmbeddingModel — genera vettori numerici dal testo, usati per la ricerca semantica
• VectorStore — integrazione con oltre 15 database vettoriali: PGVector, Redis, Chroma, Milvus, MongoDB Atlas, Weaviate, Pinecone e altri
• ImageModel / AudioModel — generazione di immagini e trascrizione/sintesi audio
• ETL Pipeline — framework per l’ingestione e trasformazione di documenti (fondamentale per RAG)
• Advisors API — layer di interceptor che incapsula pattern ricorrenti come la memoria conversazionale e il RAG
• Tool/Function Calling — permette al modello di richiamare metodi Java annotati per accedere a dati in tempo reale

Tutti questi componenti si integrano con Spring Boot Auto-Configuration: basta aggiungere la dipendenza desiderata e configurare la chiave API nel file application.properties.

3. Installazione e configurazione rapida

Il punto di partenza è Spring Initializr, dove è possibile selezionare il provider AI desiderato. Per aggiungere Spring AI OpenAI a un progetto Maven esistente:

<!-- pom.xml: BOM per gestire tutte le versioni Spring AI -->

<dependencyManagement>

  <dependencies>

    <dependency>

      <groupId>org.springframework.ai</groupId>

      <artifactId>spring-ai-bom</artifactId>

      <version>1.1.0</version>

      <type>pom</type>

      <scope>import</scope>

    </dependency>

  </dependencies>

</dependencyManagement>

<!-- Dipendenza per OpenAI -->

<dependency>

  <groupId>org.springframework.ai</groupId>

  <artifactId>spring-ai-openai-spring-boot-starter</artifactId>

</dependency>

Nel file application.properties aggiungere la chiave API:

spring.ai.openai.api-key=${OPENAI_API_KEY}

spring.ai.openai.chat.options.model=gpt-4o

Per usare un modello locale con Ollama invece di OpenAI, basta sostituire lo starter con spring-ai-ollama-spring-boot-starter e aggiornare la proprietà del modello. Nessun’altra modifica al codice applicativo è necessaria.

4. ChatClient API: il primo esempio pratico

La ChatClient API è l’interfaccia fluente principale di Spring AI. La sua sintassi è volutamente simile a quella di WebClient e RestClient, risultando familiare a qualsiasi sviluppatore Spring.

@Service

public class AiService {

    private final ChatClient chatClient;

    public AiService(ChatClient.Builder builder) {

        this.chatClient = builder

            .defaultSystem("Sei un assistente tecnico esperto di Spring Framework.")

            .build();

    }

    public String risposta(String domanda) {

        return chatClient.prompt()

            .user(domanda)

            .call()

            .content();

    }

    // Output strutturato: risposta mappata su un POJO

    public record Analisi(String sintesi, List<String> suggerimenti) {}

    public Analisi analizza(String testo) {

        return chatClient.prompt()

            .user("Analizza: " + testo)

            .call()

            .entity(Analisi.class);

    }

}

Il metodo .entity(Analisi.class) mostra una delle funzionalità più potenti: gli Structured Outputs, che mappano automaticamente la risposta del modello su un POJO Java, eliminando il parsing manuale del JSON.

5. RAG e Vector Store: AI che conosce i tuoi dati

Il pattern RAG (Retrieval-Augmented Generation) è fondamentale per costruire assistenti AI che rispondano basandosi su documenti aziendali specifici invece di sole conoscenze generali del modello. Spring AI lo supporta nativamente.

Il flusso è il seguente:

• Ingestione: i documenti vengono letti, suddivisi in chunk (TokenTextSplitter) e convertiti in vettori (EmbeddingModel)
• Indicizzazione: i vettori vengono salvati in un VectorStore (es. PGVector su PostgreSQL)
• Retrieval: a ogni query utente, vengono recuperati i chunk semanticamente più simili
• Generazione: i chunk recuperati vengono inclusi nel prompt come contesto per il modello LLM

// Ingestione documenti (es. da PDF)

@Bean

CommandLineRunner ingestDocuments(VectorStore vectorStore,

                                   ResourceLoader loader) {

    return args -> {

        var doc = new TikaDocumentReader(loader.getResource("classpath:manuale.pdf"));

        var splitter = new TokenTextSplitter();

        vectorStore.add(splitter.apply(doc.get()));

    };

}

// Query con RAG tramite QuestionAnswerAdvisor

String risposta = chatClient.prompt()

    .user(domandaUtente)

    .advisors(new QuestionAnswerAdvisor(vectorStore))

    .call()

    .content();

Con poche righe di codice Spring AI costruisce l’intera pipeline RAG. Il QuestionAnswerAdvisor si occupa automaticamente di recuperare i documenti rilevanti e arricchire il prompt prima dell’invio al modello.

6. Tool Calling e Advisors API – Guida Spring AI

Il Tool Calling (o Function Calling) permette al modello LLM di richiamare metodi Java reali per ottenere informazioni in tempo reale, superando il limite della data di training del modello.

// Un meteo service esposto al modello come tool

@Service

public class MeteoService {

    @Tool(description = "Restituisce le condizioni meteo attuali per una città")

    public String meteoAttuale(String citta) {

        // Chiamata reale a un'API meteo esterna

        return "Temperatura a " + citta + ": 22°C, soleggiato";

    }

}

// Utilizzo nel ChatClient

String risposta = chatClient.prompt()

    .user("Che tempo fa a Milano oggi?")

    .tools(meteoService)  // Spring AI genera automaticamente lo schema JSON

    .call()

    .content();

La Advisors API è invece il meccanismo di Spring AI per incapsulare pattern trasversali. Oltre al già citato QuestionAnswerAdvisor per il RAG, sono disponibili MessageChatMemoryAdvisor per la memoria conversazionale e SafeGuardAdvisor per il guardrailing dei contenuti. La composizione di più advisor permette di costruire pipeline AI sofisticate in modo dichiarativo.

7. MCP (Model Context Protocol): Spring AI 1.1 e 2.0

Una delle aggiunte più rilevanti della versione 1.1 (novembre 2025) è il supporto completo al Model Context Protocol (MCP), lo standard aperto per connettere modelli AI a strumenti e sorgenti di dati esterni. Spring AI 1.1 fornisce sia il MCP Client (per consumare server MCP esistenti) sia il MCP Server (per esporre le proprie applicazioni Spring come sorgenti di contesto per agenti AI).

L’annotazione @McpTool, introdotta in Spring AI 1.1, permette di esporre un metodo Spring come tool MCP con una singola riga. Spring AI 2.0, attualmente in milestone (M3 a marzo 2026) e atteso in GA a metà 2026, porta queste funzionalità sulle basi di Spring Boot 4 e Spring Framework 7, con supporto Jackson 3, null-safety JSpecify e modularizzazione avanzata.

8. Best practice: pro e contro di Spring AI

Prima di adottare Spring AI in produzione è utile avere un quadro chiaro dei punti di forza e delle limitazioni.

✅  PRO	❌  CONTRO
Integrazione nativa con Spring Boot — nessuna configurazione extra	Dipendenza stretta dall’ecosistema Spring: difficile usarlo fuori da Spring Boot
API unificata e portabile su tutti i principali provider AI (OpenAI, Anthropic, Google, Ollama…)	Evoluzione rapida: aggiornamenti frequenti possono introdurre breaking changes (es. migrazione 1.x → 2.x)
Supporto RAG, memoria conversazionale e Tool Calling già inclusi	Documentazione ancora in crescita rispetto a framework più maturi come LangChain4j
Observability integrata con Micrometer e Spring Actuator	Overhead dell’ecosistema Spring per applicazioni AI stand-alone o serverless leggere
Supporto Vector Store su oltre 15 provider (PGVector, Redis, Chroma, Milvus…)	Il cambio di provider LLM può richiedere tuning del prompt: l’astrazione non copre il comportamento del modello
Community attiva, roadmap chiara verso Spring AI 2.0 con Spring Boot 4	Spring AI 2.0 (Spring Boot 4) richiede migrazione non banale per progetti esistenti

Consigli pratici per l’adozione in produzione:

• Usare il BOM per gestire le versioni di tutte le dipendenze Spring AI e prevenire conflitti
• Esternalizzare le chiavi API con variabili d’ambiente o Vault: mai committare credenziali nel codice
• Abilitare l’observability con Micrometer: Spring AI include già tracciamento delle chiamate AI per analizzare costi e latenze
• Limitare il context window: usare TokenTextSplitter con dimensioni adeguate al modello scelto per evitare errori e costi elevati
• Testare con modelli locali (Ollama) in sviluppo e integrazione, riservando i provider cloud alla produzione
• Pianificare la migrazione a 2.0: se si inizia oggi un nuovo progetto, usare Spring Boot 3.3+ con Spring AI 1.1; tenere d’occhio le note di upgrade per 2.0

9. Conclusioni e formazione professionale

Spring AI rappresenta oggi la soluzione più matura e produttiva per integrare l’intelligenza artificiale generativa in applicazioni Java enterprise. La curva di apprendimento è ridotta grazie alla familiarità con i pattern Spring, l’API è stabile (1.x GA), e la roadmap verso la 2.0 dimostra un investimento a lungo termine da parte del team Broadcom.

Il mercato dello sviluppo software è in continua e rapida evoluzione: nuovi modelli, nuovi framework, nuovi paradigmi emergono ogni trimestre. L’unico modo per mantenere competitivo il proprio team di sviluppatori è investire nella formazione continua. Chi non si aggiorna rischia di lavorare con strumenti e pratiche obsolete in un settore dove l’obsolescenza arriva in mesi, non anni.

Per costruire solide fondamenta, indispensabili prima di affrontare Spring AI, ti consigliamo il Corso Spring Java Framework di Innovaformazione: un percorso pratico per sviluppatori che vogliono padroneggiare Spring Boot, Spring MVC, Spring Data e Spring Security a livello professionale.

Su richiesta è possibile attivare un Corso Spring AI dedicato per le aziende: un programma formativo personalizzato che guida il team dai fondamentali di Spring AI fino all’implementazione di pipeline RAG, agenti AI e integrazione MCP in ambienti enterprise reali.

Fondimpresa e formazione finanziata: le aziende aderenti a Fondimpresa possono finanziare questi percorsi formativi attingendo al conto formazione aziendale, abbattendo fino al 100% dei costi. Il nostro team è a disposizione per supportare l’iter burocratico e massimizzare il contributo disponibile.

Per informazioni, preventivi e attivazione corsi:

• Email: info@innovaformazione.net
• Telefono: TEL. 347 101 2275 — Dario Carrassi
• Sito: innovaformazione.net

Non aspettare che il tuo team resti indietro. Contattaci oggi per scoprire come costruire le competenze AI che il mercato richiede.

Per altri articoli tecnici consigliamo di navigare sul nostro blog: innovaformazione.net/blog

(fonte) (fonte) (fonte)