Serverlose KI: EmbeddingGemma mit Cloud Run

1. Einführung

In diesem Codelab erfahren Sie, wie Sie EmbeddingGemma, ein leistungsstarkes mehrsprachiges Texteinbettungsmodell, mit GPUs in Cloud Run bereitstellen. Anschließend verwenden Sie diesen bereitgestellten Dienst, um Einbettungen für eine semantische Suchanwendung zu generieren.

Im Gegensatz zu herkömmlichen Large Language Models (LLMs), die Text generieren, wandeln Einbettungsmodelle Text in numerische Vektoren um. Diese Vektoren sind entscheidend für die Entwicklung von Retrieval-Augmented Generation (RAG)-Systemen, mit denen Sie die relevantesten Dokumente für die Anfrage eines Nutzers finden können.

Aufgaben

• Containerisieren Sie das Modell EmbeddingGemma mit Ollama.
• Stellen Sie den Container in Cloud Run mit GPU-Beschleunigung bereit.
• Testen Sie das bereitgestellte Modell, indem Sie Einbettungen für Beispieltext generieren.
• Erstellen Sie mit Ihrem bereitgestellten Dienst ein schlankes semantisches Suchsystem.

Voraussetzungen

• Google Cloud-Projekt mit aktivierter Abrechnungsfunktion.
• Grundlegende Kenntnisse von Docker und der Befehlszeile

2. Hinweis

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.

Cloud Shell starten

Cloud Shell ist eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird und mit den erforderlichen Tools vorinstalliert ist.

1. Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren.
2. Prüfen Sie nach der Verbindung mit Cloud Shell Ihre Authentifizierung:

   gcloud auth list
   

3. Prüfen Sie, ob Ihr Projekt ausgewählt ist:

   gcloud config get project
   

4. Legen Sie sie bei Bedarf fest:

   gcloud config set project <YOUR_PROJECT_ID>
   

APIs aktivieren

Führen Sie diesen Befehl aus, um alle erforderlichen APIs zu aktivieren:

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

3. Modell containerisieren

Damit EmbeddingGemma serverlos ausgeführt werden kann, muss es in einem Container verpackt werden. Wir verwenden Ollama, ein einfaches Framework zum Ausführen von LLMs, und Docker.

Dockerfile erstellen

Erstellen Sie in Cloud Shell ein neues Verzeichnis für Ihr Projekt und wechseln Sie in dieses Verzeichnis:

mkdir embedding-gemma-codelab
cd embedding-gemma-codelab

Erstellen Sie eine Datei mit dem Namen Dockerfile und dem folgendem Inhalt:

FROM ollama/ollama:latest

# Listen on all interfaces, port 8080
ENV OLLAMA_HOST=0.0.0.0:8080

# Store model weight files in /models
ENV OLLAMA_MODELS=/models

# Reduce logging verbosity
ENV OLLAMA_DEBUG=false

# Never unload model weights from the GPU
ENV OLLAMA_KEEP_ALIVE=-1

# Store the model weights in the container image
ENV MODEL=embeddinggemma:latest
RUN ollama serve & sleep 5 && ollama pull $MODEL

# Start Ollama
ENTRYPOINT ["ollama", "serve"]

Dieses Dockerfile hat folgende Funktion:

1. Beginnt mit dem offiziellen Ollama-Basis-Image.
2. Konfiguriert Ollama so, dass Port 8080 (Standardport von Cloud Run) überwacht wird.
3. Der Befehl RUN startet den ollama-Server und lädt das embeddinggemma-Modell während des Build-Prozesses herunter, sodass es im Image enthalten ist.
4. Legt OLLAMA_KEEP_ALIVE=-1 fest, damit das Modell im GPU-Arbeitsspeicher geladen bleibt und nachfolgende Anfragen schneller bearbeitet werden können.

4. Erstellen und bereitstellen

Wir verwenden die Quellcodebereitstellung für Cloud Run, um unseren Container in einem einzigen Schritt zu erstellen und bereitzustellen. Mit diesem Befehl wird das Image mit Cloud Build erstellt, in Artifact Registry gespeichert und in Cloud Run bereitgestellt.

Führen Sie zum Bereitstellen den folgenden Befehl aus:

gcloud run deploy embedding-gemma \
  --source . \
  --region europe-west1 \
  --concurrency 4 \
  --cpu 8 \
  --set-env-vars OLLAMA_NUM_PARALLEL=4 \
  --gpu 1 \
  --gpu-type nvidia-l4 \
  --max-instances 1 \
  --memory 32Gi \
  --no-allow-unauthenticated \
  --no-cpu-throttling \
  --no-gpu-zonal-redundancy \
  --timeout=600 \
  --labels dev-tutorial=codelab-embedding-gemma

Hinweis:Die Bereitstellung kann einige Minuten dauern, da die Modellgewichte abgerufen und der Container erstellt werden. Wenn Sie die Quellcodebereitstellung von Cloud Run zum ersten Mal verwenden, werden Sie möglicherweise aufgefordert, ein neues Artifact Registry-Repository zu erstellen. Antworten Sie mit y, um fortzufahren.

Konfiguration verstehen

• --source . gibt das aktuelle Verzeichnis als Quelle für den Build an.
• --region europe-west1 verwenden wir eine Region, die GPUs auf Cloud Run unterstützt.
• --concurrency 4 ist auf den Wert der Umgebungsvariablen OLLAMA_NUM_PARALLEL festgelegt.
• --gpu 1 mit --gpu-type nvidia-l4 weist jeder Cloud Run-Instanz im Dienst eine NVIDIA L4-GPU zu.
• --max-instances 1 gibt die maximale Anzahl von Instanzen an, auf die skaliert werden soll. Sie muss gleich oder niedriger als das NVIDIA L4-GPU-Kontingent Ihres Projekts sein.
• --no-allow-unauthenticated schränkt den nicht authentifizierten Zugriff auf den Dienst ein. Wenn Sie den Dienst privat nutzen, können Sie die integrierte Identity and Access Management (IAM)-Authentifizierung von Cloud Run für die Dienst-zu-Dienst-Kommunikation verwenden.
• --no-cpu-throttling ist erforderlich, um die GPU zu aktivieren.
• Legen Sie mit --no-gpu-zonal-redundancy zonale Redundanzoptionen fest, die Ihren Anforderungen an zonales Failover und dem verfügbaren Kontingent entsprechen.

Hinweise zu Regionen

GPUs in Cloud Run sind in bestimmten Regionen verfügbar. Die unterstützten Regionen finden Sie in der Dokumentation.

Bereitstellungsausgabe

Nach einigen Minuten ist die Bereitstellung abgeschlossen und Sie sehen eine Meldung wie diese:

Service [embedding-gemma] revision [embedding-gemma-12345-abc] has been deployed and is serving 100 percent of traffic.
Service URL: https://embedding-gemma-123456789012.europe-west1.run.app

Hinweis: Wenn Sie versuchen, die URL direkt aufzurufen, wird der Fehler „403: Forbidden“ (403: Unzulässig) angezeigt, da für Ihren Dienst eine Authentifizierung erforderlich ist.

5. Deployment testen

Da wir den Dienst mit --no-allow-unauthenticated bereitgestellt haben, können wir die öffentliche URL nicht einfach curl. Zuerst müssen wir uns die Berechtigung für den Zugriff auf den Dienst erteilen und das Autorisierungstoken in der Anfrage verwenden.

1. Gewähren Sie Ihrem Nutzerkonto die Berechtigung, den Dienst aufzurufen:

   gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
       --member=user:$(gcloud config get-value account) \
       --role='roles/run.invoker'
   

2. Speichern Sie Ihre Google Cloud-Anmeldedaten und die Projektnummer in Umgebungsvariablen, um sie in der Anfrage zu verwenden:

   export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)")
   export ID_TOKEN=$(gcloud auth print-identity-token)
   

3. Führen Sie den folgenden Befehl aus, um ein Embedding für „Beispieltext“ zu generieren:

   curl -X POST "https://embedding-gemma-$PROJECT_NUMBER.europe-west1.run.app/api/embed" \
       -H "Authorization: Bearer $ID_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
           "model": "embeddinggemma",
           "input": "Sample text"
       }'
   

Sie sollten eine JSON-Antwort mit einem Vektor (einer langen Liste von Zahlen) im Feld embedding sehen. Das bestätigt, dass Ihr serverloses GPU-basiertes Einbettungsmodell funktioniert.

Die Antwort sieht in etwa so aus:

Python-Client

Sie können auch Python verwenden, um mit dem Dienst zu interagieren. Erstellen Sie eine Datei mit dem Namen test_client.py:

import urllib.request
import urllib.parse
import json
import os

# 1. Setup the URL and Payload
url = f"https://embedding-gemma-{os.environ['PROJECT_NUMBER']}.europe-west1.run.app/api/embed"
payload = {
    "model": "embeddinggemma",
    "input": "Sample text"
}

# 2. Create the Request object
# Note: Providing 'data' automatically makes this a POST request
req = urllib.request.Request(
    url,
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['ID_TOKEN']}",
        "Content-Type": "application/json"
    }
)

# 3. Execute and print the response
response = urllib.request.urlopen(req)
result = json.loads(response.read().decode("utf-8"))
print(result)

Führen Sie das Namespace aus:

python test_client.py

6. Semantische Suchanwendung erstellen

Nachdem wir nun einen funktionierenden Einbettungsdienst haben, erstellen wir eine einfache semantische Suchanwendung. Wir verwenden die generierten Einbettungen, um das relevanteste Dokument für eine bestimmte Anfrage zu finden.

Abhängigkeiten

Wir verwenden chromadb als Vektordatenbank und die ollama-Clientbibliothek.

uv init semantic-search --description "Semantic Search Application"
cd semantic-search
uv add chromadb ollama

Suchanwendung erstellen

Erstellen Sie eine Datei mit dem Namen semantic_search.py und mit folgendem Code als Inhalt:

import ollama
import chromadb
import os

# 1. Define our knowledge base
documents = [
    "Poland is a country located in Central Europe.",
    "The capital and largest city of Poland is Warsaw.",
    "Poland's official language is Polish, which is a West Slavic language.",
    "Marie Curie, the pioneering scientist who conducted groundbreaking research on radioactivity, was born in Warsaw, Poland.",
    "Poland is famous for its traditional dish called pierogi, which are filled dumplings.",
    "The Białowieża Forest in Poland is one of the last and largest remaining parts of the immense primeval forest that once stretched across the European Plain.",
]

print("Initializing Vector Database...")
client = chromadb.Client()
collection = client.create_collection(name="docs")

# Configure the client to point to our Cloud Run proxy
ollama_client = ollama.Client(
    host=f"https://embedding-gemma-{os.environ['PROJECT_NUMBER']}.europe-west1.run.app",
    headers={'Authorization': 'Bearer ' + os.environ['ID_TOKEN']}
)

print("Generating embeddings and indexing documents...")
# 2. Store each document in the vector database
for i, d in enumerate(documents):
    # This calls our Cloud Run service to get the embedding
    response = ollama_client.embed(model="embeddinggemma", input=d)
    embeddings = response["embeddings"]
    collection.add(ids=[str(i)], embeddings=embeddings, documents=[d])

print("Indexing complete.\n")

# 3. Perform a Semantic Search
question = "What is Poland's official language?"
print(f"Query: {question}")

# Generate an embedding for the question
response = ollama_client.embed(model="embeddinggemma", input=question)

# Query the database for the most similar document
results = collection.query(
    query_embeddings=[response["embeddings"][0]],
    n_results=1
)

best_match = results["documents"][0][0]
print(f"Best Match Document: {best_match}")

Anwendung ausführen

Führen Sie das Skript aus:

uv run semantic_search.py

Hinweis:Wenn Sie einen Fehler wie KeyError: 'ID_TOKEN' oder KeyError: 'PROJECT_NUMBER' erhalten, haben Sie vergessen, die Umgebungsvariable ID_TOKEN oder PROJECT_NUMBER festzulegen. Führen Sie export ID_TOKEN=$(gcloud auth print-identity-token) und export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)") aus, um sie festzulegen.

Die Ausgabe sollte in etwa so aussehen:

Initializing Vector Database...
Generating embeddings and indexing documents...
Indexing complete.

Query: What is Poland's official language?
Best Match Document: Poland's official language is Polish, which is a West Slavic language.

Dieses Skript zeigt das Herzstück eines RAG-Systems: Ihren serverlosen EmbeddingGemma-Dienst verwenden, um sowohl Dokumente als auch Anfragen in Vektoren zu konvertieren. So können Sie genau die Informationen finden, die zum Beantworten einer Nutzerfrage erforderlich sind.

7. Bereinigen

Löschen Sie die in diesem Codelab erstellten Ressourcen, um laufende Gebühren für Ihr Google Cloud-Konto zu vermeiden.

Cloud Run-Dienst löschen

gcloud run services delete embedding-gemma --region europe-west1 --quiet

Container-Image löschen

gcloud artifacts docker images delete \
    europe-west1-docker.pkg.dev/${GOOGLE_CLOUD_PROJECT}/cloud-run-source-deploy/embedding-gemma \
    --quiet

Warnung:Prüfen Sie den Artifact Registry-Pfad noch einmal, wenn der obige Befehl fehlschlägt, da der Repository-Name je nach Ihren genauen Bereitstellungseinstellungen leicht variieren kann. Tipp: Mit gcloud artifacts docker images list $REPO_PATH können Sie Images in Ihren Artefakt-Repositories auflisten.

8. Glückwunsch

Glückwunsch! Sie haben EmbeddingGemma erfolgreich in Cloud Run mit GPUs bereitgestellt und damit eine semantische Suchanwendung unterstützt.

Sie haben jetzt eine skalierbare, serverlose Grundlage für die Entwicklung von KI-Anwendungen, die die Bedeutung von Text verstehen müssen.

Das haben Sie gelernt

• So containerisieren Sie ein Ollama-Modell mit Docker.
• So stellen Sie einen GPU-fähigen Dienst in Cloud Run bereit.
• So verwenden Sie das bereitgestellte Modell für die semantische Suche (RAG).

Nächste Schritte

• Weitere Modelle der Gemma-Familie
• Weitere Informationen zu Cloud Run-GPUs
• Weitere Cloud Run-Codelabs
• Erstellen Sie eine vollständige RAG-Pipeline, indem Sie diesen Abrufvorgang mit einem generativen Modell verbinden.

Referenzdokumente

• EmbeddingGemma-Modellkarte
• Ollama-Dokumentation