Guida rapida: crea ed esegui il deployment di un'app web Python (LangChain) in Cloud Run

Guida rapida: crea ed esegui il deployment di un'app web Python (LangChain) in Cloud Run

Scopri come creare ed eseguire il deployment di un'applicazione LangChain utilizzando Cloud Run e Gemini per rispondere alle query sulle capitali delle città.

Se segui i passaggi descritti in questa guida rapida, Cloud Run crea automaticamente un Dockerfile quando esegui il deployment dal codice sorgente.

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

Installa Google Cloud CLI.

Nota: se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo gcloud components update.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un Google Cloud progetto.

Ruoli richiesti per selezionare o creare un progetto

• Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
• Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

• Creare un progetto Google Cloud :

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

• Seleziona il progetto Google Cloud che hai creato:

  gcloud config set project PROJECT_ID

  Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Se utilizzi un progetto esistente per questa guida, verifica di disporre delle autorizzazioni necessarie per completare la guida. Se hai creato un nuovo progetto, disponi già delle autorizzazioni necessarie.

Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .

Installa Google Cloud CLI.

Nota: se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo gcloud components update.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un Google Cloud progetto.

Ruoli richiesti per selezionare o creare un progetto

• Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
• Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

• Creare un progetto Google Cloud :

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

• Seleziona il progetto Google Cloud che hai creato:

  gcloud config set project PROJECT_ID

  Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Se utilizzi un progetto esistente per questa guida, verifica di disporre delle autorizzazioni necessarie per completare la guida. Se hai creato un nuovo progetto, disponi già delle autorizzazioni necessarie.

Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .

1. Se il tuo progetto è soggetto a un criterio dell'organizzazione con restrizioni di dominio che limitano le chiamate non autenticate, devi accedere al servizio di cui è stato eseguito il deployment come descritto in Test dei servizi privati.

2. Abilita le API Cloud Run Admin e Cloud Build:

   Ruoli richiesti per abilitare le API

   Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

   gcloud services enable run.googleapis.com cloudbuild.googleapis.com

   Una volta abilitata l'API Cloud Run Admin, viene creato automaticamente il account di servizio predefinito di Compute Engine.

3. Consulta i prezzi di Cloud Run o stima i costi con il Calcolatore prezzi.
4. Per eseguire il deployment dell'app LangChain con un modello Gemini, è necessaria una chiave API di Google AI Studio. Per generare una chiave API utilizzando Google AI Studio, consulta la sezione Utilizzo delle chiavi API Gemini nella documentazione dell'API Gemini. Fai riferimento a questa chiave quando esegui il deployment del servizio.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare questa guida rapida, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Cloud Run Admin (roles/run.admin) sul progetto
• Cloud Run Source Developer (roles/run.sourceDeveloper) sul progetto
• Service Account User (roles/iam.serviceAccountUser) sull'identità di servizio
• Visualizzatore log (roles/logging.viewer) sul progetto

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Concedi al account di servizio Cloud Build l'accesso al tuo progetto

Cloud Build utilizza automaticamente l'account di servizio predefinito di Compute Engine come account di servizio Cloud Build predefinito per creare il codice sorgente e la risorsa Cloud Run, a meno che tu non esegua l'override di questo comportamento.

Affinché Cloud Build possa creare le tue origini, concedi al service account Cloud Build il ruolo Cloud Run Builder (roles/run.builder) nel tuo progetto:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder

Sostituisci PROJECT_ID con il tuo ID progetto Google Cloude SERVICE_ACCOUNT_EMAIL_ADDRESS con l'indirizzo email del account di servizio Cloud Build. Se utilizzi il service account predefinito di Compute Engine come service account Cloud Build, utilizza il seguente formato per l'indirizzo email dell'account di servizio:

[e-mail]

Sostituisci PROJECT_NUMBER con il numero del tuo progetto Google Cloud.

Per istruzioni dettagliate su come trovare l'ID progetto e il numero di progetto, vedi Creazione e gestione dei progetti.

La concessione del ruolo di builder Cloud Run richiede un paio di minuti per la propagazione.

scrivi l'applicazione di esempio

Per scrivere un'applicazione in Python:

1. Crea una nuova directory denominata langchain-gemini-fastapi-app e passa a questa directory:

   mkdir langchain-gemini-fastapi-app
   cd langchain-gemini-fastapi-app
   

2. Crea un file denominato main.py e incolla il seguente codice:

   import os
   import uvicorn
   from fastapi import FastAPI, HTTPException
   from pydantic import BaseModel
   from langchain_google_genai import ChatGoogleGenerativeAI
   from langchain_core.prompts import ChatPromptTemplate
   from langchain_core.output_parsers import StrOutputParser
   
   # Initialize FastAPI
   app = FastAPI(title="LangChain Gemini Cloud Run App")
   
   # 1. Setup Gemini Model
   # We expect GOOGLE_API_KEY to be set in the environment variables
   llm = ChatGoogleGenerativeAI(
     model="gemini-2.5-flash",
     temperature=0.7
   )
   
   # 2. Define the Chain
   prompt = ChatPromptTemplate.from_template("You are a helpful assistant. Answer the following question concisely: {topic}")
   output_parser = StrOutputParser()
   
   # Chain: Prompt -> Model -> String Parser
   chain = prompt | llm | output_parser
   
   # 3. Define Request Model
   class QueryRequest(BaseModel):
     topic: str
   
   # 4. Define Endpoint
   @app.post("/chat")
   async def chat(request: QueryRequest):
     try:
         response = await chain.ainvoke({"topic": request.topic})
         return {"response": response}
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
   
   @app.get("/")
   def health_check():
     return {"status": "ok", "service": "Gemini-FastAPI"}
   

3. Crea un file denominato requirements.txt e incolla il seguente codice:

   fastapi
   uvicorn
   langchain
   langchain-google-genai
   python-dotenv
   

Esegui il deployment in Cloud Run dall'origine

Il deployment dall'origine crea automaticamente un'immagine container dal codice sorgente ed esegue il deployment.

Per eseguire il deployment dall'origine utilizzando il comando seguente:

  gcloud run deploy gemini-fastapi-service \
    --source . \
    --region us-central1 \
    --no-allow-unauthenticated \
    --set-env-vars GEMINI_API_KEY=API_KEY

Sostituisci API_KEY con la tua chiave API di Google AI Studio. Per la produzione, ti consigliamo di utilizzare Secret Manager per gestire la chiave API, anziché variabili di ambiente semplici.

Cloud Run visualizza l'URL del servizio, ad esempio https://gemini-fastapi-service-xyz-uc.a.run.app, dopo il deployment riuscito dell'app.

Operazione riuscita: hai eseguito il deployment di un'app web LangChain su Cloud Run.

Testare il servizio Cloud Run

Testa il servizio inviando una query all'agente utilizzando il seguente comando curl:

  curl -X POST YOUR-SERVICE-URL/chat \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
    -d '{"topic": "What is the capital of France?"}'

Sostituisci YOUR-SERVICE-URL con l'URL del tuo servizio.

L'agente invia la seguente risposta:

  {
  "response": "Paris"
  }

Per verificare che il servizio funzioni correttamente, controlla la scheda Log del servizio Cloud Run.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questa pagina, elimina il progetto Google Cloud con le risorse.

Per evitare costi aggiuntivi al tuo account Google Cloud , elimina tutte le risorse che hai eseguito il deployment con questa guida rapida.

Eliminare il repository

Cloud Run non ti addebita costi quando il servizio di cui hai eseguito il deployment non è in uso. Tuttavia, potresti comunque pagare l'archiviazione dell'immagine container in Artifact Registry. Per eliminare i repository Artifact Registry, segui i passaggi descritti in Elimina repository nella documentazione di Artifact Registry.

Eliminare il servizio

I servizi Cloud Run non comportano costi finché non ricevono richieste. Per eliminare il servizio Cloud Run, segui uno di questi passaggi:

Console

Per eliminare un servizio:

1. Nella console Google Cloud , vai alla pagina Servizi di Cloud Run:

   Vai a Cloud Run

2. Individua il servizio che vuoi eliminare nell'elenco dei servizi e fai clic sulla relativa casella di controllo per selezionarlo.

3. Fai clic su Elimina. Vengono eliminate tutte le revisioni del servizio.

gcloud

Per eliminare un servizio, esegui questo comando:

gcloud run services delete SERVICE --region REGION

Sostituisci quanto segue:

• SERVICE: il nome del servizio.
• REGION: Google Cloud regione del servizio.

Eliminare il progetto di test

L'eliminazione del progetto Google Cloud interrompe la fatturazione per tutte le risorse al suo interno. Per rilasciare tutte le Google Cloud risorse nel progetto:

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:
• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per, le attività descritte in questo documento, eliminerai anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Elimina un progetto Google Cloud :

gcloud projects delete PROJECT_ID

Passaggi successivi

Per saperne di più sulla creazione di un container dal codice sorgente e sul push in un repository, consulta:

• Sviluppo dei servizi Cloud Run
• Creazione di container
• Testare un servizio Cloud Run localmente
• Deployment dal codice sorgente