Diese Seite wurde von der Cloud Translation API übersetzt.

Erste Schritte mit Richtlinien für semantisches Caching

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Auf dieser Seite wird beschrieben, wie Sie die semantischen Caching-Richtlinien von Apigee konfigurieren und verwenden, um die intelligente Wiederverwendung von Antworten basierend auf semantischer Ähnlichkeit zu ermöglichen. Wenn Sie diese Richtlinien in Ihrem Apigee API-Proxy verwenden, können Sie redundante Backend-API-Aufrufe minimieren, die Latenz reduzieren und die Betriebskosten senken.

Hinweise

Führen Sie die folgenden Aufgaben aus, bevor Sie beginnen:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Compute Engine, AI Platform, and Cloud Storage APIs.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Compute Engine, AI Platform, and Cloud Storage APIs.

Enable the APIs

Richten Sie die Vertex AI Text Embeddings API und die Vektorsuche in Ihrem Google Cloud Projekt ein und konfigurieren Sie sie.
Prüfen Sie, ob in Ihrer Apigee-Instanz eine Comprehensive-Umgebung verfügbar ist. Semantische Caching-Richtlinien können nur in umfassenden Umgebungen bereitgestellt werden.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle AI Platform User (roles/aiplatform.user) für das Dienstkonto zuzuweisen, das Sie zum Bereitstellen von Apigee-Proxys verwenden, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwenden der Richtlinien für semantisches Caching benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Umgebungsvariablen festlegen

Legen Sie im Google Cloud -Projekt, das Ihre Apigee-Instanz enthält, mit dem folgenden Befehl Umgebungsvariablen fest:

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

Wobei:

PROJECT_ID ist die ID des Projekts mit Ihrer Apigee-Instanz.
REGION ist die Google Cloud Region Ihrer Apigee-Instanz.
RUNTIME_HOSTNAME ist der Hostname Ihrer Apigee-Laufzeit.

Führen Sie den folgenden Befehl aus und prüfen Sie die Ausgabe, um zu bestätigen, dass die Umgebungsvariablen richtig festgelegt sind:

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Projekt festlegen

Legen Sie das Google Cloud -Projekt in Ihrer Entwicklungsumgebung fest:

    gcloud auth login
    gcloud config set project $PROJECT_ID

Übersicht

Die Richtlinien für semantisches Caching sollen Apigee-Nutzern mit LLM-Modellen helfen, identische oder semantisch ähnliche Prompts effizient zu verarbeiten. So werden Backend-API-Aufrufe minimiert und der Ressourcenverbrauch gesenkt.

Die Richtlinien „SemanticCacheLookup“ und „SemanticCachePopulate“ sind jeweils an die Anfrage- und Antwortabläufe eines Apigee-API-Proxy angehängt. Wenn der Proxy eine Anfrage empfängt, wird mit der SemanticCacheLookup-Richtlinie der Nutzer-Prompt aus der Anfrage extrahiert und mithilfe der Text Embeddings API in eine numerische Darstellung umgewandelt. Mit der Vektorsuche wird eine Suche nach semantischer Ähnlichkeit durchgeführt, um ähnliche Prompts zu finden. Wenn ein ähnlicher Prompt-Datenpunkt gefunden wird, wird eine Cache-Suche durchgeführt. Wenn im Cache gespeicherte Daten gefunden werden, wird die im Cache gespeicherte Antwort an den Client zurückgegeben.

Wenn bei der Ähnlichkeitssuche kein ähnlicher vorheriger Prompt zurückgegeben wird, generiert das LLM-Modell Inhalte als Reaktion auf den Nutzer-Prompt und der Apigee-Cache wird mit der Antwort gefüllt. Es wird ein Feedback-Loop erstellt, um die Indexeinträge der Vektorsuche für zukünftige Anfragen zu aktualisieren.

In den folgenden Abschnitten wird beschrieben, wie Sie die Richtlinien für das semantische Caching erstellen und konfigurieren:

Dienstkonto für den Vektorsuchindex konfigurieren
Vektorsuchindex erstellen und bereitstellen.
API-Proxy erstellen, um semantisches Caching zu aktivieren
Semantische Caching-Richtlinien konfigurieren
Semantische Caching-Richtlinien testen

Dienstkonto für den Vektorsuchindex konfigurieren

So konfigurieren Sie ein Dienstkonto für den Vektorsuchindex:

Erstellen Sie ein Dienstkonto mit dem folgenden Befehl:

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="SERVICE_ACCOUNT_DISPLAY_NAME"

Wobei:

SERVICE_ACCOUNT_NAME ist der Name des Dienstkontos.
DESCRIPTION ist eine Beschreibung des Dienstkontos.
SERVICE_ACCOUNT_DISPLAY_NAME ist der Anzeigename des Dienstkontos.

Beispiel:

gcloud iam service-accounts create ai-client \
  --description="semantic cache client" \
  --display-name="ai-client"

Weisen Sie dem Dienstkonto mit dem folgenden Befehl die Rolle AI Platform User zu:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Dabei ist SERVICE_ACCOUNT_NAME der Name des Dienstkontos, das Sie im vorherigen Schritt erstellt haben.

Weisen Sie dem Dienstkonto mit dem folgenden Befehl die IAM-Rolle Service Account User zu:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"

Dabei ist SERVICE_ACCOUNT_NAME der Name des Dienstkontos, das Sie im vorherigen Schritt erstellt haben.

Erstellen Sie einen Vektorsuchindex und stellen Sie ihn bereit.

So erstellen und stellen Sie einen Vektorsuchindex bereit:

Erstellen Sie einen Vektorsuchindex, der Streaming-Updates ermöglicht:

ACCESS_TOKEN=$(gcloud auth print-access-token) && curl --location --request POST \
  "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    --header 'Content-Type: application/json' \
    --data-raw \
    '{
      "displayName": "semantic-cache-index",
      "description": "semantic-cache-index",
      "metadata": {
        "config": {
          "dimensions": "768",
          "approximateNeighborsCount": 150,
          "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
          "featureNormType": "NONE",
          "algorithmConfig": {
            "treeAhConfig": {
              "leafNodeEmbeddingCount": "10000",
              "fractionLeafNodesToSearch": 0.05
              }
            },
          "shardSize": "SHARD_SIZE_MEDIUM"
          },
        },
      "indexUpdateMethod": "STREAM_UPDATE"
    }'

Mit $REGION wird die Region definiert, in der der Vektorsuchindex bereitgestellt wird. Wir empfehlen, dieselbe Region wie für Ihre Apigee-Instanz zu verwenden. Diese Umgebungsvariable wurde in einem vorherigen Schritt festgelegt.

Wenn der Vorgang abgeschlossen ist, sollte eine Antwort ähnlich der folgenden angezeigt werden:

{
  "name": "projects/976063410430/locations/us-west1/indexes/5695338290484346880/operations/9084564741162008576",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexOperationMetadata",
    "genericMetadata": {
      "createTime": "2025-04-25T18:45:27.996136Z",
      "updateTime": "2025-04-25T18:45:27.996136Z"
    }
  }
}

Weitere Informationen zum Erstellen von Vektorsuchindizes finden Sie unter Index erstellen.

Erstellen Sie mit dem folgenden Befehl eine IndexEndpoint:

gcloud ai index-endpoints create \
  --display-name=semantic-cache-index-endpoint \
  --public-endpoint-enabled \
  --region=$REGION \
  --project=$PROJECT_ID

Dieser Schritt kann mehrere Minuten dauern. Nach Abschluss des Vorgangs sollte eine Antwort wie die folgende angezeigt werden:

Waiting for operation [8278420407862689792]...done.
  Created Vertex AI index endpoint: projects/976063410430/locations/us-west1/indexEndpoints/7953875911424606208.

Weitere Informationen zum Erstellen einer IndexEndpoint finden Sie unter IndexEndpoint erstellen.

Stellen Sie den Index mit dem folgenden Befehl am Endpunkt bereit:

INDEX_ENDPOINT_ID=$(gcloud ai index-endpoints list \
  --project=$PROJECT_ID \
  --region=$REGION \
  --format="json" | jq -c -r \
  '.[] | select(.displayName=="semantic-cache-index-endpoint") | .name | split("/") | .[5]' \
  ) && INDEX_ID=$(gcloud ai indexes list \
  --project=$PROJECT_ID \
  --region=$REGION \
  --format="json" | jq -c -r \
  '.[] | select(.displayName=="semantic-cache-index") | .name | split("/") | .[5]' \
  ) && gcloud ai index-endpoints deploy-index \
  $INDEX_ENDPOINT_ID \
  --deployed-index-id=semantic_cache \
  --display-name=semantic-cache \
  --index=$INDEX_ID \
  --region=$REGION \
  --project=$PROJECT_ID

Hinweis:Für den Befehl zum Bereitstellen des Index auf dem Endpunkt ist jq erforderlich. Wenn dieses JSON-Verarbeitungstool noch nicht in Ihrer Entwicklungsumgebung installiert ist, können Sie es mit dem folgenden Befehl installieren: $ sudo apt install jq

Die erste Bereitstellung eines Index auf einem Endpunkt kann zwischen 20 und 30 Minuten dauern. Verwenden Sie den folgenden Befehl, um den Status des Vorgangs zu prüfen:

gcloud ai operations describe OPERATION_ID \
  --project=$PROJECT_ID \
  --region=$REGION

Prüfen Sie, ob der Index bereitgestellt wurde:

gcloud ai operations describe OPERATION_ID \
  --index-endpoint=$INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID

Der Befehl sollte $ done: true zurückgeben.

API-Proxy erstellen, um semantisches Caching zu aktivieren

In diesem Schritt erstellen Sie einen neuen API-Proxy mit der Vorlage Proxy with Semantic Cache (Proxy mit semantischem Cache), falls Sie dies noch nicht getan haben.

Bevor Sie den API-Proxy erstellen, legen Sie die folgende Umgebungsvariable fest:

export PUBLIC_DOMAIN_NAME=$(gcloud ai index-endpoints describe $INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID | grep "publicEndpointDomainName" | awk '{print $2}')

So erstellen Sie einen Proxy für die Verwendung mit semantischem Caching:

Rufen Sie in der Google Cloud Console die Seite API-Proxys auf.
Zu „API-Proxys“
Klicken Sie auf + Erstellen, um den Bereich API-Proxy erstellen zu öffnen.
Wählen Sie im Feld Proxyvorlage die Option Proxy mit semantischem Cache aus.
Geben Sie die folgenden Informationen ein:
- Proxyname: Geben Sie den Namen des Proxys ein.
- Beschreibung: (Optional) Geben Sie eine Beschreibung des Proxys ein.
- Ziel (vorhandene API): Geben Sie die URL des Backend-Dienstes ein, den der Proxy aufruft. Dies ist der LLM-Modellendpunkt, der zum Generieren von Inhalten verwendet wird.
  Für diese Anleitung kann Ziel (vorhandene API) auf Folgendes festgelegt werden:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent
```
Geben Sie die folgenden URLs für den semantischen Cache ein:
Hinweis:Diese URLs können auch in der XML-Konfiguration im Proxy-Editor auf dem Tab Entwickeln hinzugefügt werden.
- URL zum Generieren von Einbettungen: Dieser Vertex AI-Dienst wandelt Texteingaben in eine numerische Form für die semantische Analyse um.
  Für diese Anleitung kann diese URL auf Folgendes festgelegt werden:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/text-embedding-004:predict
```
- URL für die Suche nach dem nächsten Nachbarn: Dieser Vertex AI-Dienst sucht im Vector Search-Index nach ähnlichen Texteingaben aus früheren Anfragen, um eine erneute Verarbeitung zu vermeiden.
  Für diese Anleitung kann diese URL auf Folgendes festgelegt werden:
```
PUBLIC_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/REGION/indexEndpoints/INDEX_ENDPOINT_ID:findNeighbors
```
  Die Werte PUBLIC_DOMAIN_NAME und INDEX_ENDPOINT_ID wurden in einem vorherigen Schritt festgelegt. Sie können diese Werte mit den folgenden Befehlen abrufen:
```
  echo $PUBLIC_DOMAIN_NAME
  echo $INDEX_ENDPOINT_ID
```
- Upsert-Index-URL: Dieser Vertex AI-Dienst aktualisiert den Index mit neuen oder geänderten Einträgen.
  Für diese Anleitung kann diese URL auf Folgendes festgelegt werden:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints
```
Klicken Sie auf Weiter.
Klicken Sie auf Erstellen.

Die XML-Konfiguration des API-Proxy kann auf dem Tab Develop (Entwickeln) aufgerufen werden. Die Richtlinien „SemanticCacheLookup“ und „SemanticCachePopulate“ mit Standardwerten sind bereits an die Proxy-Anfrage- und ‑Antwortabläufe angehängt.

Semantische Caching-Richtlinien konfigurieren

Sie können die XML-Konfiguration jeder Richtlinie aufrufen, indem Sie auf dem Tab Entwickeln des API-Proxy in der Ansicht Details auf den Richtliniennamen klicken. Änderungen an der XML-Datei der Richtlinie können direkt in der Codeansicht auf dem Tab Entwickeln vorgenommen werden.

Richtlinien bearbeiten:

SemanticCacheLookup-Richtlinie:
- Entfernen Sie das <UserPromptSource>-Element, um den Standardwert zu verwenden.
- Aktualisieren Sie das Element <DeployedIndexId>, sodass der Wert semantic_cache verwendet wird.
- Konfigurieren Sie den Wert für die semantische Ähnlichkeit <Threshold>, um festzulegen, wann zwei Prompts als Übereinstimmung gelten. Der Standardwert ist 0, 9.Sie können ihn jedoch an die Sensibilität Ihrer Anwendung anpassen. Je größer die Zahl, desto enger müssen die Prompts zusammenhängen, damit sie als Cache-Treffer gelten. Für diese Anleitung empfehlen wir, diesen Wert auf 0,95 zu setzen.
- Klicken Sie auf Speichern.
SemanticCachePopulate-Richtlinie:
- Legen Sie das <TTLInSeconds>-Element fest, um die Anzahl der Sekunden bis zum Ablauf des Cache anzugeben. Der Standardwert ist 60 Sekunden. Beachten Sie, dass Apigee alle Cache-Control-Header ignoriert, die vom LLM-Modell empfangen werden.
- Klicken Sie auf Speichern.

Google-Authentifizierung zum API-Proxy hinzufügen

Sie müssen dem Zielendpunkt des API-Proxy auch die Google-Authentifizierung hinzufügen, um Proxyaufrufe an das Ziel zu ermöglichen.

So fügen Sie das Google-Zugriffstoken hinzu:

Klicken Sie auf dem Tab Entwickeln unter dem Ordner Zielendpunkte auf Standard. In der Codeansicht wird die XML-Konfiguration des Elements <TargetEndpoint> angezeigt.

Bearbeiten Sie das XML, um die folgende Konfiguration unter <HTTPTargetConnection> hinzuzufügen:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Klicken Sie auf Speichern.

Erstellen Sie den API-Proxy

So stellen Sie den API-Proxy bereit:

Klicken Sie auf Bereitstellen, um den Bereich API-Proxy bereitstellen zu öffnen.
Das Feld Revision sollte auf 1 gesetzt sein. Falls nicht, klicken Sie auf 1, um sie auszuwählen.
Wählen Sie in der Liste Umgebung die Umgebung aus, in der Sie den Proxy bereitstellen möchten. Die Umgebung muss eine umfassende Umgebung sein.
Geben Sie das Dienstkonto ein, das Sie in einem vorherigen Schritt erstellt haben.
Klicken Sie auf Bereitstellen.

Semantische Caching-Richtlinien testen

So testen Sie die semantischen Caching-Richtlinien:

Senden Sie mit dem folgenden Befehl eine Anfrage an den Proxy:

curl https://$RUNTIME_HOSTNAME/PROXY_NAME -H 'Content-Type: application/json' --data '{
  "contents": [
      {
          "role": "user",
          "parts": [
              {
                  "text": "Why is the sky blue?"
              }
          ]
      }
  ]
}'

Dabei ist PROXY_NAME der Basispfad des API-Proxy, den Sie im vorherigen Schritt bereitgestellt haben.

Warum ist der Himmel blau?
Warum ist der Himmel blau?
Warum ist der Himmel blau?
Kannst du erklären, warum der Himmel blau ist?
Warum ist der Himmel blau?

Vergleichen Sie die Reaktionszeit für jeden Aufruf, nachdem ein ähnlicher Prompt im Cache gespeichert wurde.

Prüfen Sie die Antwortheader, um zu bestätigen, dass Ihre Aufrufe aus dem Cache bereitgestellt werden. Es sollte ein Cached-Content: true-Header angehängt sein.

Best Practices

Wir empfehlen, die folgenden Best Practices in Ihr API-Verwaltungsprogramm aufzunehmen, wenn Sie die Richtlinien für semantisches Caching verwenden:

Mit Model Armor können Sie das Caching sensibler Daten verhindern.
Um das Caching vertraulicher Daten zu verhindern, empfehlen wir, Model Armor für die Inhaltsfilterung zu verwenden. Model Armor kann Antworten als nicht im Cache speicherbar kennzeichnen, wenn vertrauliche Informationen erkannt werden. Weitere Informationen finden Sie in der Übersicht über Model Armor.
Datenaktualität mit der Vertex AI-Funktion zum Ungültigmachen von Datenpunkten und der Gültigkeitsdauer (Time-to-Live, TTL) verwalten.
Wir empfehlen, geeignete Strategien zur Ungültigkeitserklärung von Datenpunkten zu implementieren, damit zwischengespeicherte Antworten auf dem neuesten Stand sind und die aktuellen Informationen aus Ihren Backend-Systemen widerspiegeln. Weitere Informationen

Sie können die TTL für im Cache gespeicherte Antworten auch an die Volatilität der Daten und die Häufigkeit der Aktualisierungen anpassen. Weitere Informationen zur Verwendung von TTL in der SemanticCachePopulate-Richtlinie finden Sie unter <TTLInSeconds>.
Verwenden Sie vordefinierte Caching-Strategien, um möglichst genaue Antwortdaten zu erhalten.
Wir empfehlen, vordefinierte Caching-Strategien wie die folgenden zu implementieren:
- Allgemeine KI-Antworten: Konfigurieren Sie eine lange TTL (z. B. eine Stunde) für nicht nutzerspezifische Antworten.
- Nutzerspezifische Antworten: Implementieren Sie kein Caching oder legen Sie eine kurze TTL (z. B. fünf Minuten) für Antworten fest, die nutzerspezifische Informationen enthalten.
- Zeitkritische Antworten: Konfigurieren Sie eine kurze TTL (z. B. fünf Minuten) für Antworten, die Echtzeit- oder häufige Updates erfordern.

Beschränkungen

Für die Richtlinien für semantisches Caching gelten die folgenden Einschränkungen:

Die maximale Größe für im Cache speicherbaren Text beträgt 256 KB. Weitere Informationen finden Sie auf der Apigee-Seite Limits unter Cache value size (Größe von Cache-Werten).
Apigee ignoriert alle Cache-Control-Header, die vom LLM-Modell empfangen werden.
Wenn der Cache nicht richtig ungültig gemacht wird oder der Algorithmus für semantische Ähnlichkeit nicht genau genug ist, um zwischen Eingaben mit sehr ähnlichen Bedeutungen zu unterscheiden, kann die Antwort veraltete oder falsche Informationen enthalten.
Die Vektorsuche wird nicht in allen Regionen unterstützt. Eine Liste der unterstützten Regionen finden Sie auf der Seite „Vertex AI-Standorte“ im Abschnitt Featureverfügbarkeit. Wenn sich Ihre Apigee-Organisation in einer nicht unterstützten Region befindet, müssen Sie Indexendpunkte in einer anderen Region als Ihrer Apigee-Organisation erstellen.
Die Richtlinien für semantisches Caching werden nicht für API-Proxys mit EventFlows für das kontinuierliche Streaming von vom Server gesendeten Ereignissen (SSE) unterstützt.
Die JsonPath-Funktion in <UserPromptSource> unterstützt die ignoreUnresolvedVariables-Funktion nicht. Standardmäßig werden Nullwerte oder leere Werte bei der Anwendung von Nachrichtenvorlagen ignoriert.

Nächste Schritte

Weitere Informationen zu Model Armor-Richtlinien