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 verringern und die Betriebskosten senken.

Hinweise

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

  1. 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.

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

    Go to project selector

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

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

    Enable the APIs

    5.

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

    Go to project selector

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

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

    Enable the APIs

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

    10. Erforderliche Rollen

    Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle AI Platform User (roles/aiplatform.user) für das Dienstkonto zuzuweisen, mit dem Sie Apigee-Proxys bereitstellen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwenden der semantischen Caching-Richtlinien 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

    Verwenden Sie im Google Cloud -Projekt, das Ihre Apigee-Instanz enthält, den folgenden Befehl, um Umgebungsvariablen festzulegen: 

    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 den semantischen Cache sollen Apigee-Nutzern mit LLM-Modellen dabei helfen, identische oder semantisch ähnliche Prompts intelligent und effizient zu präsentieren, um Backend-API-Aufrufe zu minimieren und den Ressourcenverbrauch zu reduzieren.

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

    Wenn die Ähnlichkeitssuche keinen ähnlichen vorherigen Prompt zurückgibt, generiert das LLM-Modell Inhalte als Antwort auf den Nutzerprompt und der Apigee-Cache wird mit der Antwort gefüllt. Es wird eine Feedbackschleife erstellt, um die Indexeinträge der Vektorsuche zur Vorbereitung auf zukünftige Anfragen zu aktualisieren.

    In den folgenden Abschnitten werden die Schritte zum Erstellen und Konfigurieren der semantischen Caching-Richtlinien beschrieben:

    1. Konfigurieren Sie ein Dienstkonto für den Vektorsuchindex.
    2. Erstellen Sie einen Vektorsuchindex und stellen Sie ihn bereit.
    3. Erstellen Sie einen API-Proxy, um das semantische Caching zu aktivieren.
    4. Konfigurieren Sie die Richtlinien für das semantische Caching.
    5. Testen Sie die Richtlinien für das semantische Caching.

    Dienstkonto für den Vektorsuchindex konfigurieren

    So konfigurieren Sie ein Dienstkonto für den Vector Search-Index:

    1. 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"
    2. 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.

    3. 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:

    1. Erstellen Sie einen Vektorsuchindex, der Streaming-Updates zulässt: 
      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 Ihre Apigee-Instanz zu verwenden. Diese Umgebungsvariable wurde in einem vorherigen Schritt festgelegt.

      Nach Abschluss dieses Vorgangs 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.

    2. 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 einige 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.

    3. 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

    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 mit der Vorlage Proxy mit semantischem Cache einen neuen API-Proxy, falls Sie dies noch nicht getan haben.

    Legen Sie vor dem Erstellen des API-Proxy 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 dem semantischen Caching:

    1. Rufen Sie in der Google Cloud Console die Seite API-Proxys auf.

      Zu „API-Proxys“

    2. Klicken Sie auf + Erstellen, um den Bereich API-Proxy erstellen zu öffnen.
    3. Wählen Sie im Feld Proxyvorlage die Option Proxy mit semantischem Cache aus.
    4. 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
    5. Geben Sie die folgenden Semantic Cache-URLs ein:
      • Embeddings-URL generieren: 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
      • Nearest Neighbor-URL abfragen: Mit diesem Vertex AI-Dienst wird im Vektorsuchindex nach ähnlicher Texteingabe aus früheren Anfragen gesucht, 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 die folgenden Befehle verwenden, um diese Werte abzurufen: 

          echo $PUBLIC_DOMAIN_NAME
  echo $INDEX_ENDPOINT_ID

      • Upsert-Index-URL: Mit diesem Vertex AI-Dienst wird der Index mit neuen oder geänderten Einträgen aktualisiert.

        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
    6. Klicken Sie auf Weiter.
    7. Klicken Sie auf Erstellen.

    Die XML-Konfiguration des API-Proxy wird auf dem Tab Entwickeln angezeigt. SemanticCacheLookup- und SemanticCachePopulate-Richtlinien mit Standardwerten sind bereits an die Proxy-Anfrage- und Antwortabläufe angehängt.

    Richtlinien für das semantische Caching konfigurieren

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

    So bearbeiten Sie die Richtlinien:

    • SemanticCacheLookup-Richtlinie:
      • Entfernen Sie das <UserPromptSource>-Element, um den Standardwert zu verwenden.
      • Aktualisieren Sie das Element <DeployedIndexId> so, dass der Wert semantic_cache verwendet wird.
      • Konfigurieren Sie den Wert für die semantische Ähnlichkeit <Threshold>, um festzulegen, wann zwei Prompts als übereinstimmend betrachtet werden. Der Standardwert ist 0, 9.Sie können diesen Wert jedoch an die Anforderungen Ihrer Anwendung anpassen. Je höher die Zahl, desto ähnlicher müssen die Prompts sein, um als Cache-Treffer zu gelten. Für diese Anleitung empfehlen wir, diesen Wert auf 0,95 festzulegen.
      • Klicken Sie auf Speichern.
    • SemanticCachePopulate-Richtlinie:
      • Legen Sie mit dem Element <TTLInSeconds> die Anzahl der Sekunden fest, bis der Cache abläuft. 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 außerdem die Google-Authentifizierung hinzufügen, um Proxyaufrufe an das Ziel zu ermöglichen.

    So fügen Sie das Google-Zugriffstoken hinzu:

    1. Klicken Sie auf dem Tab Entwickeln im Ordner Zielendpunkte auf Standard. In der Codeansicht wird die XML-Konfiguration des Elements <TargetEndpoint> angezeigt.
    2. Bearbeiten Sie die XML-Datei und fügen Sie unter <HTTPTargetConnection> die folgende Konfiguration hinzu: 
      <Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>
    3. Klicken Sie auf Speichern.

    Erstellen Sie den API-Proxy

    So stellen Sie den API-Proxy bereit:

    1. Klicken Sie auf Bereitstellen, um den Bereich API-Proxy bereitstellen zu öffnen.
    2. Das Feld Revision sollte auf 1 gesetzt sein. Falls nicht, klicken Sie auf 1, um sie auszuwählen.
    3. 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.
    4. Geben Sie das Dienstkonto ein, das Sie in einem früheren Schritt erstellt haben.
    5. Klicken Sie auf Bereitstellen.

    Richtlinien für semantisches Caching testen

    So testen Sie die Richtlinien für das semantische Caching:

    1. 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.

      2. Wiederholen Sie den API-Aufruf und ersetzen Sie den Prompt-String durch die folgenden semantisch ähnlichen Prompt-Strings:
      • Warum ist der Himmel blau?
      • Warum ist der Himmel blau?
      • Warum ist der Himmel blau?
      • Können Sie erklären, warum der Himmel blau ist?
      • Warum ist der Himmel blau?
    2. Vergleichen Sie die Antwortzeit für jeden Aufruf, nachdem ein ähnlicher Prompt im Cache gespeichert wurde.

    Prüfen Sie anhand der Antwortheader, ob Ihre Aufrufe aus dem Cache stammen. 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 das Caching sensibler Daten verhindern

      Um das Caching vertraulicher Daten zu verhindern, empfehlen wir die Verwendung von Model Armor für die Inhaltsfilterung. 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 Vertex AI-Datenpunkt-Entwertung und Gültigkeitsdauer (TTL) verwalten

      Wir empfehlen, geeignete Strategien zur Datenpunkt-Ungültigmachung zu implementieren, damit die im Cache gespeicherten Antworten auf dem neuesten Stand sind und die neuesten Informationen aus Ihren Backend-Systemen widerspiegeln. Weitere Informationen finden Sie unter Aktiven Index aktualisieren und neu erstellen.

      Sie können die TTL für im Cache gespeicherte Antworten auch anhand der Datenvolatilität und der Aktualisierungshäufigkeit 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 die Implementierung vordefinierter Caching-Strategien wie den folgenden:

      • Generische 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 Aktualisierungen erfordern.

    Beschränkungen

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

    • Die maximale Größe für im Cache gespeicherten Text beträgt 256 KB. Weitere Informationen finden Sie unter Größe des Cachewerts auf der Seite Apigee-Limits.
    • Apigee ignoriert alle Cache-Control-Header, die vom LLM-Modell empfangen werden.
    • Wenn der Cache nicht richtig ungültig gemacht wird oder der Algorithmus zur semantischen Ähnlichkeit nicht genau genug ist, um zwischen Eingaben mit sehr ähnlicher Bedeutung zu unterscheiden, werden in der Antwort möglicherweise veraltete oder falsche Informationen zurückgegeben.
    • Die Funktion „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 das semantische Caching werden nicht für die Verwendung mit API-Proxys unterstützt, die EventFlows für das kontinuierliche Streaming von Antworten auf vom Server gesendete Ereignisse (SSE) verwenden.
    • Die JsonPath-Funktion in <UserPromptSource> unterstützt die Funktion ignoreUnresolvedVariables nicht. Standardmäßig werden Null- oder Leerwerte bei der Anwendung von Nachrichtenvorlagen ignoriert.