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 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 Anwendung mit Node.js und Fastify, verwenden das Vertex AI SDK, um Gemini aufzurufen, stellen sie als sicheren, produktionsbereiten Dienst in Cloud Run bereit und schützen sie mit Identity-Aware Proxy (IAP).

Aufgaben

  • Erstellen Sie eine Node.js-Fastify-Anwendung, die Vertex AI verwendet.
  • Die Anwendung aus der Quelle in Cloud Run bereitstellen, ohne dass ein Dockerfile erforderlich ist
  • Cloud Run-Endpunkt mit Identity-Aware Proxy (IAP) schützen

Lerninhalte

  • Verwendung des Vertex AI SDK für Node.js zum Generieren von Inhalten.
  • So stellen Sie eine Node.js-Anwendung in Cloud Run bereit.
  • Eine 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 stattdessen ein privates Konto. Bei Arbeitskonten und Konten von Bildungseinrichtungen kann es Einschränkungen geben, die verhindern, dass Sie die für dieses Lab erforderlichen APIs aktivieren.
  2. Melden Sie sich in der Google Cloud Console an.
  3. Aktivieren Sie die Abrechnung in der Cloud Console.
    • Die Cloud-Ressourcen, die für dieses Lab benötigt werden, sollten weniger als 1 $kosten.
    • Sie können die Schritte am Ende dieses Labs ausführen, um Ressourcen zu löschen und so weitere Kosten zu vermeiden.
    • Neue Nutzer haben Anspruch auf die kostenlose Testversion mit einem Guthaben von 300$.
  4. Erstellen Sie ein neues Projekt oder verwenden Sie ein vorhandenes Projekt wieder.
    • Wenn Sie eine Fehlermeldung zum Projektkontingent sehen, 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 zum Cloud Shell-Editor zu gelangen.
  2. Wenn Sie heute an irgendeinem Punkt zur Autorisierung aufgefordert werden, 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 Ansehen.
    • Klicken Sie auf TerminalNeues Terminal im Cloud Shell-Editor öffnen.
  4. Legen Sie im Terminal Ihr Projekt mit diesem Befehl 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 folgendem 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 Sie WARNING sehen und Do you want to continue (Y/n)? gefragt werden, haben Sie die Projekt-ID wahrscheinlich falsch eingegeben. Drücken Sie n, dann Enter und versuchen Sie, den Befehl gcloud config set project noch einmal 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 die APIs im Terminal:

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

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

Es kann einige Minuten dauern, bis dieser Befehl ausgeführt wird. Wenn die Ausführung erfolgreich war, erhalten Sie eine Meldung, die ungefähr so aussieht:

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 für die Verwendung von ES-Modulen und definieren Sie ein Startskript, indem Sie die folgenden 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 Sie eine neue index.ts-Datei für den Quellcode der Anwendung und öffnen Sie sie:
    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 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-west1',
});

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();

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

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-west1 \
    --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-west1"
    Wir verwenden hier 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 vorgefertigten Node.js 24-Basis-Image auszuführen.
    • --no-allow-unauthenticated: So wird dafür gesorgt, dass nur authentifizierte Nutzer auf den Dienst zugreifen können.
    • --iap: Dadurch kann Identity-Aware Proxy (IAP) den Zugriff auf Ihre Anwendung verwalten. Mit IAP können Sie den Zugriff anhand der Nutzeridentität und des Kontexts steuern, anstatt nur anhand von IP-Adressen.
  2. Nach einigen Minuten wird eine Meldung wie die folgende 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 Nutzer müssen sich authentifizieren und autorisiert werden, bevor sie Ihren Dienst erreichen können. Dazu müssen Sie zwei Berechtigungen erteilen:

  • Erlauben Sie dem IAP-Dienst selbst, Ihren Cloud Run-Dienst aufzurufen.
  • Erlauben Sie sich selbst (oder anderen Nutzern/Gruppen), über In-App-Abrechnung 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. So kann IAP Ihren Dienst aufrufen, nachdem ein Nutzer authentifiziert und autorisiert wurde.
    gcloud run services add-iam-policy-binding generative-web-navigator \
    --region=europe-west1 \
    --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. So können Sie auf IAP-gesicherte HTTPS-Ressourcen zugreifen.
    gcloud beta iap web add-iam-policy-binding \
    --resource-type=cloud-run \
    --region=europe-west1 \
    --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-west1
  2. Kopieren Sie die URL und öffnen Sie sie in Ihrem Webbrowser. Da der Dienst durch In-App-Abrechnung geschützt ist, werden Sie aufgefordert, sich mit Ihrem Google-Konto anzumelden, falls Sie noch nicht angemeldet sind. Nach der Authentifizierung sollte die erste automatisch generierte Seite angezeigt werden.
  3. Klicken Sie auf einen beliebigen Link, um zu einer neuen Seite zu gelangen, die von der KI basierend auf dem angeklickten Link generiert wird.

Sie haben es geschafft! Sie haben erfolgreich eine Website mit generativer KI-Benutzeroberfläche in Cloud Run bereitgestellt und mit IAP gesichert.

11. Fazit

Glückwunsch! Sie haben erfolgreich eine Website mit generativer Benutzeroberfläche mit Cloud Run, Vertex AI und IAP bereitgestellt und gesichert.

Optional: Bereinigen

Wenn Sie die von Ihnen erstellten Elemente bereinigen möchten, können Sie Ihr Cloud-Projekt löschen, um zusätzliche Gebühren 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, sofern welche erstellt wurden. Durch das Löschen des Cloud-Projekts wird die Abrechnung für alle in diesem Projekt verwendeten Ressourcen beendet.

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

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Möglicherweise möchten Sie auch unnötige Ressourcen von Ihrer Cloud Shell-Festplatte 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 alles in Ihrer Cloud Shell löschen möchten, um Speicherplatz freizugeben, können Sie Ihr gesamtes Basisverzeichnis löschen. Achten Sie darauf, dass alles, was Sie behalten möchten, an einem anderen Ort gespeichert ist. 
    sudo rm -rf $HOME