Guida introduttiva a Gemini Fullstack LangGraph

Se vuoi sfruttare al massimo il modello Gemini, l'approccio migliore è usare la Google Gen AI API insieme all'app di chat Gemini Fullstack LangGraph. Questa configurazione offre un assistente di ricerca IA full-stack, con un frontend React e un backend LangGraph.

In questo tutorial imparerai a configurare l'applicazione da zero: installerai sia il frontend sia il backend, li avvierai insieme con un unico comando e testerai l'app per assicurarti che tutto funzioni senza intoppi. 

Successivamente vedremo come distribuire l'applicazione con Docker, un metodo molto più accessibile per iniziare a usare l'app e scoprire le capacità del modello Gemini nel generare risposte molto accurate e dettagliate.

Se cerchi altri progetti basati su Gemini o LangGraph, leggi anche i nostri tutorial Gemini 2.5 Pro API: guida con progetto demo e Tutorial LangGraph: cos’è LangGraph e come usarlo. 

1. Configurazione

Se usi Windows, è altamente consigliato utilizzare Windows Subsystem for Linux (WSL) per un'esperienza di sviluppo più fluida. WSL ti consente di eseguire un ambiente Linux completo direttamente su Windows, semplificando l'uso degli strumenti Linux.

1. Apri PowerShell come Amministratore ed esegui il comando wsl --install. Questo installerà Ubuntu per impostazione predefinita e potrebbe richiedere il riavvio del sistema. 

2. Dopo il riavvio, avvia Ubuntu dal menu Start oppure digitando wsl in PowerShell.

3. Installa Node.js 18 usando NVM (Node Version Manager).

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18

4. Verifica la versione di Node.js installata e assicurati che sia la 18 o superiore.

node --version
npm --version
v18.20.8
10.8.2

2. Installazione di frontend e backend

1. Clona il repository Gemini Fullstack LangGraph Quickstart e spostati nella directory del progetto:

git clone https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart.git
cd gemini-fullstack-langgraph-quickstart

Ora la struttura delle directory dovrebbe essere simile a questa:

2. Vai su Google AI Studio e genera una chiave API per Gemini. 

Fonte: Get API key | Google AI Studio

3. Vai nella directory del backend e crea il file .env con la chiave API di Gemini. Sostituisci “YOUR_ACTUAL_API_KEY” con la chiave che hai generato.

4. Installa tutti i pacchetti Python usando il comando PIP. 

cd backend                                
echo 'GEMINI_API_KEY="YOUR_ACTUAL_API_KEY"' > .env
pip install .

5. Torna alla root del progetto e vai nella directory del frontend. Installa le dipendenze del frontend usando npm.

cd ..
cd frontend                               
npm install  

3. Esecuzione dell'applicazione 

Dopo aver installato tutte le dipendenze, puoi avviare sia il server frontend sia quello backend in modalità di sviluppo dalla root del progetto.

1. Dalla directory root del progetto, esegui:

make dev

Questo comando avvierà sia il frontend (con Vite) sia il backend (con LangGraph/FastAPI) in modalità di sviluppo.

2. Il frontend è alimentato da Vite, uno strumento di build moderno che offre un'esperienza di sviluppo veloce ed efficiente per i progetti web. 

> frontend@0.0.0 dev
> vite


  VITE v6.3.4  ready in 392 ms

  ➜  Local:   http://localhost:5173/app/
  ➜  Network: use --host to expose

3. Il server backend si avvierà e mostrerà informazioni come:

INFO:langgraph_api.cli:

        Welcome to

╦  ┌─┐┌┐┌┌─┐╔═╗┬─┐┌─┐┌─┐┬ ┬
║  ├─┤││││ ┬║ ╦├┬┘├─┤├─┘├─┤
╩═╝┴ ┴┘└┘└─┘╚═╝┴└─┴ ┴┴  ┴ ┴

- 🚀 API: http://127.0.0.1:2024
- 🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
- 📚 API Docs: http://127.0.0.1:2024/docs

This in-memory server is designed for development and testing.
For production use, please use LangGraph Cloud.

• API del backend: http://127.0.0.1:2024
• Documentazione API: http://127.0.0.1:2024/docsPuoi usare questa documentazione OpenAPI per testare gli endpoint del backend direttamente dal browser.
• Interfaccia LangGraph Studio: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024Questa dashboard ti consente di visualizzare e testare i tuoi workflow LangGraph.

4. Puoi testare il workflow LangGraph andando sulla LangGraph Studio UI. 

Fonte: smith.langchain.com

L'API del backend è disponibile all'indirizzo: http://127.0.0.1:2024. La documentazione API è disponibile all'indirizzo: http://127.0.0.1:2024/docs. Puoi testare ogni endpoint del backend usando la documentazione OpenAPI.

Apri http://localhost:5173/app/ nel browser per accedere all'interfaccia dell'app di chat. L'app è simile a ChatGPT: scrivi la domanda e inizierà a fare la sua magia. 

Come funziona l'app di chat nel backend:

1. In base all'input dell'utente, genera un set di query di ricerca iniziali usando un modello Gemini.
2. Per ogni query, usa il modello Gemini con la Google Search API per trovare pagine web rilevanti.
3. L'agente analizza i risultati di ricerca per identificare lacune di conoscenza, usando il modello Gemini per la riflessione.
4. Se trova lacune, genera query di follow-up e ripete i passaggi di ricerca e riflessione (fino a un limite impostato).
5. Quando ha raccolto informazioni sufficienti, l'agente sintetizza una risposta coerente con citazioni.

Poiché l'app è ancora nelle fasi iniziali, potresti incontrare alcuni bug e incoerenze, in particolare nell'interfaccia frontend. Un problema frequente è il rendering incoerente del frontend.

Per risolverlo, aggiorna la riga 57 in frontend/src/App.tsx come segue:

-           : `Need more information, searching for ${event.reflection.follow_up_queries.join(
+           : `Need more information, searching for ${(event.reflection.follow_up_queries || []).join(

4. Distribuzione dell'app con Docker

Distribuire l'applicazione con Docker è semplice ed efficiente. Docker ti permette di impacchettare l'app e le sue dipendenze in un unico container.

1. Scarica e installa Docker Desktop per il tuo sistema operativo (Windows, macOS o Linux). Trovi l'installer e le istruzioni dettagliate sul sito ufficiale Docker. Una volta installato, avvia Docker Desktop per verificare che funzioni correttamente.

2. Vai nella directory root del progetto ed esegui il seguente comando nel terminale per creare l'immagine Docker:

docker build -t gemini-fullstack-langgraph -f Dockerfile .

3. Per eseguire l'applicazione ti serviranno due chiavi API:

• Chiave API Gemini: ottienila da Google AI Studio .
• Chiave API LangSmith: visita il sito ufficiale LangSmith, registrati gratuitamente e genera la tua chiave API.

Fonte: LangSmith

4. Avvia l'applicazione usando Docker Compose, sostituendo i segnaposto con le tue chiavi API reali:

GEMINI_API_KEY=<your_gemini_api_key> LANGSMITH_API_KEY=<your_langsmith_api_key> docker-compose up

5. Accedi all'applicazione:

• Frontend: http://localhost:8123/app/
• Documentazione API: http://localhost:8123/docs

5. Test dell'applicazione 

Vai su http://localhost:8123/app/ nel browser. Scrivi una domanda nel campo di input: “Elenca le prime 5 notizie di oggi”.

Dopo l'invio, l'applicazione avvierà il processo di ricerca. Vedrai una scomposizione passo dopo passo di come l'agente raccoglie e analizza le informazioni per rispondere alla tua richiesta.

L'applicazione fornirà una risposta dettagliata, inclusi link diretti alle pubblicazioni pertinenti. La qualità e la profondità delle risposte spesso superano quelle di altri strumenti di ricerca avanzata, offrendo maggiore trasparenza e contesto nei risultati.

Per un'analisi ancora più approfondita, visita la tua dashboard LangSmith. Qui puoi rivedere un log completo di ogni passaggio compiuto dall'agente per generare la risposta. Questo tracciamento dettagliato ti aiuta a comprendere il processo di ragionamento dell'agente e garantisce trasparenza nella costruzione delle risposte.

Fonte: LangSmith

Conclusione

In meno di 10 minuti puoi creare l'immagine Docker e lanciare in locale la tua applicazione di ricerca avanzata con IA, usando le API gratuite fornite da Google Gemini e LangSmith. 

Questa guida ti ha accompagnato in un'implementazione semplice, mostrando come il modello Gemini stia progredendo nella capacità di individuare gli strumenti giusti e generare risposte di ricerca molto dettagliate, accurate e aggiornate.

Hai imparato a configurare l'applicazione, installare sia il backend sia il frontend ed eseguire tutto in locale. Inoltre, abbiamo visto un metodo alternativo di distribuzione con Docker, che rende ancora più semplice iniziare e sperimentare la potenza della ricerca profonda con l'IA.

Se cerchi il prossimo progetto, dai un'occhiata alla nostra guida su Gemini Diffusion: guida con 8 esempi pratici.