Generative UI-Website in Cloud Run bereitstellen

1. Einführung

Übersicht

In diesem Lab erstellen und stellen Sie eine Website bereit, deren Inhalte von den Large Language Models (LLMs) von Google Gemini dynamisch generiert werden. Die Website ist ein einfacher Navigator im Stil von „Wähle dein eigenes Abenteuer“, mit dem Sie Themen erkunden können. Bei jedem Klick wird eine neue Seite mit neuen Links basierend auf Ihrer Auswahl generiert. Sie erstellen die Website mit Node.js und Fastify, verwenden das Vertex AI SDK, um Gemini aufzurufen, stellen sie als sicheren, produktionsbereiten Dienst in Cloud Run bereit und sichern sie mit Identity-Aware Proxy (IAP).

Aufgaben

  • Node.js-Fastify-Anwendung erstellen, die Vertex AI verwendet
  • Anwendung aus der Quelle in Cloud Run bereitstellen, ohne Dockerfile
  • Cloud Run-Endpunkt mit Identity-Aware Proxy (IAP) sichern

Lerninhalte

  • Vertex AI SDK für Node.js zum Generieren von Inhalten verwenden
  • Node.js-Anwendung in Cloud Run bereitstellen
  • Cloud Run-Anwendung mit IAP sichern

2. Projekt einrichten

  1. Wenn Sie noch kein Google-Konto haben, müssen Sie ein Google-Konto erstellen.
    • Verwenden Sie ein privates Konto anstelle eines Arbeits- oder Schulkontos. Bei Arbeits- und Schulkonten können Einschränkungen gelten, die verhindern, dass Sie die für dieses Lab erforderlichen APIs aktivieren.
  2. Melden Sie sich in der Google Cloud Console an.
  3. Abrechnung aktivieren in der Cloud Console.
    • Die Kosten für dieses Lab sollten weniger als 1 $für Cloud-Ressourcen betragen.
    • Am Ende dieses Labs finden Sie eine Anleitung zum Löschen von Ressourcen, um weitere Kosten zu vermeiden.
    • Neue Nutzer können die kostenlose Testversion im Wert von 300$ nutzen.
  4. Erstellen Sie ein neues Projekt oder verwenden Sie ein vorhandenes Projekt wieder.
    • Wenn ein Fehler wegen des Projektkontingents angezeigt wird, verwenden Sie ein vorhandenes Projekt wieder oder löschen Sie ein vorhandenes Projekt, um ein neues zu erstellen.

3. Cloud Shell-Editor öffnen

  1. Klicken Sie auf diesen Link, um direkt zu Cloud Shell-Editor zu gelangen.
  2. Wenn Sie aufgefordert werden, sich zu authentifizieren, klicken Sie auf Autorisieren , um fortzufahren. Klicken Sie, um Cloud Shell zu autorisieren.
  3. Wenn das Terminal nicht unten auf dem Bildschirm angezeigt wird, öffnen Sie es:
    • Klicken Sie auf Anzeigen.
    • Klicken Sie auf TerminalNeues Terminal im Cloud Shell-Editor öffnen
  4. Legen Sie im Terminal mit diesem Befehl Ihr Projekt fest:
    • Format:
      gcloud config set project [PROJECT_ID]
    • Beispiel:
      gcloud config set project lab-project-id-example
    • Wenn Sie sich nicht an Ihre Projekt-ID erinnern können:
      • Sie können alle Ihre Projekt-IDs mit diesem Befehl auflisten:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      Projekt-ID im Cloud Shell Editor-Terminal festlegen
  5. Es sollte folgende Meldung angezeigt werden:
    Updated property [core/project].
    Wenn eine WARNING angezeigt wird und Sie gefragt werden Do you want to continue (Y/n)?, haben Sie wahrscheinlich die Projekt-ID falsch eingegeben. Drücken Sie n, drücken Sie Enter, und versuchen Sie noch einmal, den Befehl gcloud config set project auszuführen.
  1. Legen Sie die Umgebungsvariable GOOGLE_CLOUD_PROJECT fest. 
    export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)

4. APIs aktivieren

Aktivieren Sie im Terminal die APIs:

gcloud services enable \
  run.googleapis.com \
  aiplatform.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iap.googleapis.com

Wenn Sie aufgefordert werden, sich zu authentifizieren, klicken Sie auf Autorisieren , um fortzufahren. Klicken Sie, um Cloud Shell zu autorisieren.

Die Ausführung dieses Befehls kann einige Minuten dauern. Am Ende sollte jedoch eine Erfolgsmeldung wie diese angezeigt werden:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

5. Node.js-Projekt vorbereiten

  1. Erstellen Sie einen Ordner mit dem Namen gen-ui-on-cloudrun, um den Quellcode für die Bereitstellung zu speichern:
    mkdir gen-ui-on-cloudrun && cd gen-ui-on-cloudrun
  2. Initialisieren Sie ein Node.js-Projekt:
    npm init -y
  3. Konfigurieren Sie das Projekt so, dass ES-Module verwendet werden, und definieren Sie ein Startskript, indem Sie diese Befehle ausführen:
    npm pkg set type="module"
  4. Installieren Sie fastify für den Webserver und @google/genai für das Vertex AI SDK:
    npm install fastify @google/genai

6. Anwendungscode erstellen

  1. Erstellen und öffnen Sie eine neue index.ts-Datei für den Quellcode der Anwendung:
    cloudshell edit ~/gen-ui-on-cloudrun/index.ts
    Mit dem Befehl cloudshell edit wird die Datei index.ts im Editor über dem Terminal geöffnet.
  2. Fügen Sie in der Datei index.ts den folgenden Quellcode für den generativen UI-Server hinzu:
    import fastifyLib from 'fastify';
import { GoogleGenAI } from '@google/genai';

const fastify = fastifyLib({ logger: true });

const ai = new GoogleGenAI({
    vertexai: true,
    project: process.env.GOOGLE_CLOUD_PROJECT,
    location: process.env.GOOGLE_CLOUD_LOCATION || 'europe-west4',
});

const SYSTEM_INSTRUCTION = `The user should have submitted an html page and the id of the element just clicked.
Given the next page description, create a new webpage with a link back to "Start Over" (the / route), a brief overview of the topic, and a list of clickable link elements related to the page.
When an element is clicked, the webpage should link to the base route / with the nextPageDescription as a query string parameter.
All information needed to generate the next page should be included in the nextPageDescription without additional context.
Each nextPageDescription should be less than 1500 characters.

Example:
If the current HTML page is for a small pet store, it might include a link to an "About" page.
The href for the about page link should be /?nextPageDescription=about%20page%20for%20small%20pet%20store%20website

All responses should be valid HTML without markdown backticks.`;

interface QueryParams {
    nextPageDescription?: string;
}

fastify.get<{ Querystring: QueryParams }>('/', async (request, reply) => {
    const {
        nextPageDescription = 'A web page with interesting fun facts where I can select a fact to learn more about that topic.'
    } = request.query;

    try {
        const response = await ai.models.generateContent({
            model: 'gemini-2.5-flash',
            contents: nextPageDescription,
            config: {
                systemInstruction: SYSTEM_INSTRUCTION,
                temperature: 0.9,
            }
        });

        reply.type('text/html; charset=utf-8').send(response.text);
    } catch (error: any) {
        request.log.error(error);
        reply.status(500).send('An error occurred calling the AI.');
    }
});

const start = async () => {
    try {
        await fastify.listen({ port: Number(process.env.PORT) || 8080, host: '0.0.0.0' });
    } catch (err) {
        fastify.log.error(err);
        process.exit(1);
    }
};

start();

Dieser Code richtet einen Webserver ein, der auf HTTP-GET-Anfragen im Stammverzeichnis (/) wartet. Wenn eine Anfrage eingeht, wird der Abfrageparameter nextPageDescription (oder ein Standardwert) als Prompt für das Gemini 2.5 Flash-Modell über Vertex AI verwendet. Das Modell wird von SYSTEM_INSTRUCTION angewiesen, eine HTML-Seite mit Links zurückzugeben. Jeder Link enthält eine nextPageDescription zum Generieren der nachfolgenden Seite.

7. Dienstkonto erstellen

Sie benötigen ein Dienstkonto für Ihren Cloud Run-Dienst, um sich bei der Vertex AI API zu authentifizieren.

  1. Erstellen Sie ein Dienstkonto mit dem Namen gen-navigator-sa:
    gcloud iam service-accounts create gen-navigator-sa --display-name="Generative Navigator Service Account"
  2. Gewähren Sie dem Dienstkonto die Berechtigung zur Verwendung von Vertex AI:
    gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
    --member="serviceAccount:gen-navigator-sa@$GOOGLE_CLOUD_PROJECT.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

8. In Cloud Run bereitstellen

Stellen Sie die Anwendung jetzt direkt aus dem Quellcode in Cloud Run bereit, ohne dass ein Dockerfile erforderlich ist.

  1. Führen Sie den Befehl gcloud aus, um die Anwendung bereitzustellen:
    cd ~/gen-ui-on-cloudrun
gcloud beta run deploy generative-web-navigator \
    --source . \
    --no-build \
    --base-image=nodejs24 \
    --command="node" \
    --args="index.ts" \
    --region=europe-west4 \
    --no-allow-unauthenticated \
    --iap \
    --service-account="gen-navigator-sa@$GOOGLE_CLOUD_PROJECT.iam.gserviceaccount.com" \
    --set-env-vars GOOGLE_CLOUD_PROJECT="$GOOGLE_CLOUD_PROJECT",GOOGLE_CLOUD_LOCATION="europe-west4"
    Hier verwenden wir einige wichtige Flags:
    • --source . --no-build --base-image=nodejs24: Damit wird Cloud Run angewiesen, den Quellcode aus dem aktuellen Verzeichnis bereitzustellen, die Build-Phase zu überspringen und die Anwendung mit einem vordefinierten Node.js 24-Basis-Image auszuführen.
    • --no-allow-unauthenticated: Dadurch wird sichergestellt, dass nur authentifizierte Nutzer auf den Dienst zugreifen können.
    • --iap: Dadurch wird Identity-Aware Proxy (IAP) aktiviert, um den Zugriff auf Ihre Anwendung zu verwalten. Mit IAP können Sie den Zugriff basierend auf der Nutzeridentität und dem Kontext steuern, nicht nur anhand von IP-Adressen.
  2. Nach einigen Minuten wird eine Meldung wie diese angezeigt:
    Service [generative-web-navigator] revision [generative-web-navigator-12345-abc] has been deployed and is serving 100 percent of traffic.

Sie haben Ihre Anwendung bereitgestellt, müssen aber noch IAP konfigurieren, um den Zugriff zu ermöglichen.

9. IAP-Zugriff konfigurieren

Wenn Sie IAP in Cloud Run aktivieren, fängt IAP alle Anfragen ab und erfordert, dass sich Nutzer authentifizieren und autorisiert werden, bevor sie Ihren Dienst erreichen können. Dazu müssen Sie zwei Berechtigungen gewähren:

  • Erlauben Sie dem IAP-Dienst selbst, Ihren Cloud Run-Dienst aufzurufen.
  • Erlauben Sie sich selbst (oder anderen Nutzern/Gruppen), über IAP auf die Anwendung zuzugreifen.
  1. Rufen Sie Ihre Projektnummer ab, die zur Identifizierung des IAP-Dienst-Agents erforderlich ist:
    export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)")
  2. Weisen Sie dem IAP-Dienst-Agent die Rolle roles/run.invoker für Ihren Cloud Run-Dienst zu. Dadurch kann IAP Ihren Dienst aufrufen, nachdem ein Nutzer authentifiziert und autorisiert wurde.
    gcloud run services add-iam-policy-binding generative-web-navigator \
    --region=europe-west4 \
    --member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com" \
    --role="roles/run.invoker"
  3. Weisen Sie Ihrem Nutzerkonto die Rolle roles/iap.httpsResourceAccessor zu. Damit können Sie auf IAP-gesicherte HTTPS-Ressourcen zugreifen.
    gcloud beta iap web add-iam-policy-binding \
    --resource-type=cloud-run \
    --region=europe-west4 \
    --service=generative-web-navigator \
    --member="user:$(gcloud config get-value account)" \
    --role="roles/iap.httpsResourceAccessor"

10. Anwendung testen

  1. Rufen Sie die URL Ihres bereitgestellten Dienstes ab: 
    gcloud run services describe generative-web-navigator --format='value(status.url)' --region=europe-west4
  2. Kopieren Sie die URL und öffnen Sie sie in Ihrem Webbrowser. Da der Dienst mit IAP gesichert ist, werden Sie aufgefordert, sich mit Ihrem Google-Konto anzumelden, wenn Sie noch nicht angemeldet sind. Nach der Authentifizierung sollte die erste automatisch generierte Seite angezeigt werden.
  3. Klicken Sie auf einen Link, um zu einer neuen Seite zu gelangen, die von der KI basierend auf dem angeklickten Link generiert wird.

Fertig! Sie haben erfolgreich eine generative UI-Website in Cloud Run bereitgestellt und mit IAP gesichert.

11. Fazit

Glückwunsch! Sie haben mit Cloud Run, Vertex AI und IAP erfolgreich eine generative UI-Website bereitgestellt und gesichert.

(Optional) Bereinigen

Wenn Sie die erstellten Ressourcen bereinigen möchten, können Sie Ihr Cloud-Projekt löschen, um zusätzliche Kosten zu vermeiden.

Während für Cloud Run keine Kosten anfallen, wenn der Dienst nicht verwendet wird, wird Ihnen dennoch das Speichern von Build-Artefakten möglicherweise in Rechnung gestellt, falls welche erstellt wurden. Durch das Löschen des Cloudprojekts wird die Abrechnung für alle in diesem Projekt verwendeten Ressourcen beendet.

Wenn Sie möchten, löschen Sie das Projekt:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Möglicherweise möchten Sie auch unnötige Ressourcen von Ihrem Cloud Shell-Laufwerk löschen. Sie haben folgende Möglichkeiten:

  1. Löschen Sie das Codelab-Projektverzeichnis: 
    rm -rf ~/gen-ui-on-cloudrun
  2. Warnung! Diese Aktion kann nicht rückgängig gemacht werden. Wenn Sie alle Daten in Ihrer Cloud Shell löschen möchten, um Speicherplatz freizugeben, können Sie Ihr gesamtes Basisverzeichnis löschen. Achten Sie darauf, dass alle Daten, die Sie behalten möchten, an einem anderen Ort gespeichert sind. 
    sudo rm -rf $HOME