Semantisches Caching mit einem privaten (Private Service Connect-)Endpunkt

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Auf dieser Seite wird beschrieben, wie Sie die Apigee-Richtlinien für semantisches Caching konfigurieren und verwenden, um die intelligente Wiederverwendung von Antworten auf Basis semantischer Ähnlichkeit zu ermöglichen. In diesem Beispiel führen die Richtlinien ihre Ähnlichkeitssuche für einen Vektorsuchindex aus, der auf einem privaten Endpunkt (Private Service Connect) bereitgestellt wird. Durch den Einsatz dieser Richtlinien in Ihrem Apigee API-Proxy minimieren Sie redundante Backend-API-Aufrufe, reduzieren die Latenz und senken die Betriebskosten.

Dieser Leitfaden gilt sowohl für Apigee als auch für Apigee Hybrid. Die Richtlinienkonfiguration ist auf beiden Plattformen identisch. Nur die Art und Weise, wie die Laufzeit den privaten Endpunkt erreicht, unterscheidet sich, wie in Schritt 2: Verbindung zum Dienstanhang herstellen beschrieben. In Apigee Hybrid wird semantisches Caching über einen privaten Endpunkt (Private Service Connect) in Version 1.16.11 und höher sowie in Version 1.17.0 und höher unterstützt. Weitere Informationen finden Sie unter In Apigee Hybrid einrichten.

Hinweis

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

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Compute Engine, AI Platform, and Cloud Storage APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  4. Aktivieren und konfigurieren Sie die Texteinbettungen API von Vertex AI in Ihrem Google Cloud -Projekt.
  5. Erstellen Sie einen Vektorsuchindex, der auf einem privaten (Private Service Connect) Endpunkt bereitgestellt wird, oder greifen Sie darauf zu. In dieser Anleitung werden die Schritte zur Einrichtung der Vektorsuche nicht wiederholt. Informationen zu den spezifischen Anforderungen für SemanticCacheLookup und Links zur Dokumentation der Vektorsuche finden Sie unter Voraussetzungen für den Vektorsuchindex.
  6. Prüfen Sie, ob in Ihrer Apigee-Instanz eine Zwischenumgebung oder eine umfassende Umgebung verfügbar ist. Richtlinien für semantisches Caching können nur in Intermediate- oder Comprehensive-Umgebungen bereitgestellt werden.
  7. Prüfen Sie, ob Sie eine Umgebungsgruppe mit einem Laufzeit-Hostnamen haben, mit dem Sie Anfragen an Ihren API-Proxy senden können.

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

Verwenden Sie im Projekt Google Cloud , 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 Projekt Google Cloud in Ihrer Entwicklungsumgebung fest: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Voraussetzungen für den Vektorsuchindex

In dieser Anleitung wird davon ausgegangen, dass Sie bereits einen Vektorsuchindex auf einem privaten (Private Service Connect) Endpunkt bereitgestellt haben oder erstellen werden. Das Erstellen, Formatieren und Bereitstellen eines Vektorsuchindex wird in den Leitfäden zur Vektorsuche dokumentiert. Diese Schritte werden in dieser Anleitung nicht wiederholt. Folgen Sie der Dokumentation zur Vektorsuche, um:

Der Index muss die folgenden SemanticCacheLookup-spezifischen Anforderungen erfüllen:

  • Der Index muss STREAM_UPDATE ("indexUpdateMethod": "STREAM_UPDATE") verwenden, damit die upsertDatapoints-Aufrufe der Richtlinie „SemanticCachePopulate“ nahezu in Echtzeit abgefragt werden können.
  • Der Index dimensions muss mit der Ausgabedimensionalität des Einbettungsmodells übereinstimmen, das Sie in der Richtlinie „SemanticCacheLookup“ verwenden. In dieser Anleitung wird gemini-embedding-001 verwendet, das standardmäßig 3072-dimensionale Einbettungen erzeugt. Wenn Sie die Ausgabe auf eine niedrigere Dimensionalität kürzen (z. B. 768 oder 1536), setzen Sie dimensions auf denselben Wert.
  • Erstellen Sie den Index mit dem Distanzmaß (distanceMeasureType), das dem <DistanceMeasureType> Ihrer Richtlinie entspricht. Das Element <SimilaritySearch><VertexAI><DistanceMeasureType> in der Richtlinie „SemanticCacheLookup“ ist optional und hat den Standardwert DOT_PRODUCT_DISTANCE. COSINE_DISTANCE wird ebenfalls unterstützt. Das Indexabstandsmaß und die Richtlinie <DistanceMeasureType> müssen identisch sein.

Im folgenden Minimalbeispiel wird ein kompatibler Index erstellt. Den vollständigen Anfragetext und alle verfügbaren Optionen finden Sie unter Index erstellen und verwalten:

ACCESS_TOKEN=$(gcloud auth print-access-token) && curl -X POST \
  "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "semantic-cache-index",
    "metadata": {
      "config": {
        "dimensions": 3072,
        "distanceMeasureType": "DOT_PRODUCT_DISTANCE"
      }
    },
    "indexUpdateMethod": "STREAM_UPDATE"
  }'

Notieren Sie sich den numerischen INDEX_ID, der in der Antwort zurückgegeben wird. Sie verwenden ihn in der SemanticCachePopulate-Richtlinie. Nachdem Sie den Index erstellt haben, erstellen Sie einen Private Service Connect-Indexendpunkt und stellen den Index darauf bereit.

Wenn Sie den Private Service Connect-Indexendpunkt erstellen, muss er die folgenden SemanticCacheLookup-spezifischen Anforderungen erfüllen:

  • Die projectAllowlist muss das Apigee-Projekt enthalten, das die Verbindung initiiert:
    • Apigee: Verwenden Sie das Apigee-Mandantenprojekt. Rufen Sie die Mandantenprojekt-ID über die Organizations API (Feld apigeeProjectId) ab.
    Der projectAllowlist kann nach dem Erstellen des Indexendpunkts nicht mehr geändert werden. Wenn Sie das falsche Projekt auf die Zulassungsliste setzen, müssen Sie den Indexendpunkt löschen und neu erstellen.

Notieren Sie sich die numerische INDEX_ENDPOINT_ID des Indexendpunkts.

Dienstkonto für den Apigee-Proxy konfigurieren

Der Apigee-Proxy verwendet ein Dienstkonto für seine Vertex AI-REST-Aufrufe: die Embeddings API in der SemanticCacheLookup-Richtlinie, upsertDatapoints in der SemanticCachePopulate-Richtlinie und das Modellziel. Weisen Sie diesem Dienstkonto die Rolle AI Platform User (roles/aiplatform.user) zu:

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

Dabei ist SERVICE_ACCOUNT die E-Mail-Adresse des Dienstkontos, das der Proxy verwendet. Sie verweisen auf dieses Dienstkonto, wenn Sie den Proxy in Schritt 4: API-Proxy importieren und bereitstellen bereitstellen.

Zusätzliche Voraussetzungen für Apigee Hybrid-Bereitstellungen

Prüfen Sie bei Apigee Hybrid-Bereitstellungen die folgenden zusätzlichen Anforderungen:

  • Eine Hybridlaufzeit der Version 1.16.11 oder höher oder 1.17.0 oder höher, die in Ihrem eigenen Kubernetes-Cluster installiert ist. Weitere Informationen finden Sie in der Installationsdokumentation für Apigee Hybrid. Dieses Feature stellt keine eigenen Clusteranforderungen. Jeder unterstützte Hybridcluster funktioniert.
  • Eine Intermediate- oder Comprehensive-Umgebung und eine Umgebungsgruppe mit einem Laufzeit-Hostnamen, wie in Apigee. Richtlinien für semantisches Caching werden nur in Zwischenumgebungen oder umfassenden Umgebungen bereitgestellt.
  • Netzwerkerreichbarkeit von der Laufzeit zum privaten Endpunkt. Der Message Processor muss eine gRPC-Verbindung im Klartext zum Private Service Connect-Endpunkt der Vektorsuche auf TARGET_HOST:10000 öffnen können.
  • Ausgehender Traffic für die REST-Aufrufe. Die Aufrufe „Embeddings“, „Populate“ und „model-target“ werden an die öffentliche REGION-aiplatform.googleapis.com-Oberfläche gesendet. Daher benötigt die Laufzeit auch einen Pfad zu Google APIs – entweder direkt oder über einen privaten Pfad, wenn Ihr Cluster keinen öffentlichen ausgehenden Traffic hat.

In Apigee Hybrid einrichten

Semantisches Caching über einen privaten Endpunkt (Private Service Connect) wird in Apigee Hybrid Version 1.16.11 und höher sowie Version 1.17.0 und höher unterstützt. Die Richtlinienkonfiguration und die Schritte für die Vektorsuche in dieser Anleitung sind mit denen für Apigee identisch. Der Unterschied besteht darin, dass Sie bei Hybrid die Laufzeit selbst ausführen und die Konnektivität selbst bereitstellen. Da Hybridbereitstellungen sehr unterschiedlich sind, enthält dieser Abschnitt allgemeine Anleitungen und keine genauen Befehle. Die einzige Anforderung, die dieses Feature hinzufügt, ist, dass die Laufzeit den privaten Endpunkt über Klartext-gRPC erreichen können muss.

Netzwerk-Erreichbarkeit bereitstellen

In Hybridbereitstellungen müssen Sie die Konnektivität manuell verwalten, da es keinen von Apigee verwalteten Endpunktanhang gibt. Erstellen Sie in Ihrer Nutzer-VPC einen Private Service Connect-Endpunkt, der auf die Vektorsuche SERVICE_ATTACHMENT verweist, und verwenden Sie die interne IP-Adresse als TARGET_HOST im Proxy. Weitere Informationen finden Sie unter Schritt 2: Verbindung zum Dienstanhang herstellen. Das spezifische Routing (z.B. freigegebene VPC oder VPC-natives GKE) hängt von der Konfiguration Ihres Clusters ab.

Wenn Ihr Cluster keinen ausgehenden Internet-Traffic hat, muss die Laufzeit einen privaten Pfad zu Google APIs haben, z. B. Privater Google-Zugriff, um die REST-Kommunikation zu verarbeiten.

Nachdem Sie die Verbindung zu grpc://TARGET_HOST:10000 hergestellt haben, führen Sie die folgenden Schritte aus: Index erstellen und bereitstellen, Proxy erstellen und testen. Diese Schritte sind für Apigee und Apigee Hybrid identisch.

Übersicht

Die Richtlinien für semantisches Caching helfen Apigee-Nutzern mit LLM-Modellen, identische oder semantisch ähnliche Prompts intelligent und effizient bereitzustellen. So lassen sich Backend-API-Aufrufe minimieren und der Ressourcenverbrauch wird spürbar gesenkt.

Die Richtlinien SemanticCacheLookup und SemanticCachePopulate werden an die Anfrage- bzw. Antwortabläufe eines Apigee API-Proxy angehängt. Wenn der Proxy eine Anfrage empfängt, extrahiert die Richtlinie „SemanticCacheLookup“ den Nutzer-Prompt aus der Anfrage und wandelt ihn mithilfe der API für Texteinbettungen in eine numerische Darstellung um. Eine semantische Ähnlichkeitssuche wird mit der Vektorsuche 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 die Ähnlichkeitssuche keinen ähnlichen vorherigen Prompt zurückgibt, generiert das LLM-Modell Inhalte als Antwort auf den Nutzerprompt und füllt den Apigee-Cache mit der Antwort. Es wird eine Feedbackschleife erstellt, um die Vektorsuchindexeinträge für zukünftige Anfragen zu aktualisieren.

In diesem Szenario wird der Vektorsuchindex auf einem privaten (Private Service Connect) Endpunkt über gRPC bereitgestellt. Weitere Informationen zur Unterstützung von Private Service Connect für die Vektorsuche finden Sie unter Zugriff auf private Dienste oder Private Service Connect-Indexe abfragen.

In den folgenden Abschnitten werden die Schritte zum Erstellen und Konfigurieren der Richtlinien für semantisches Caching beschrieben:

  1. Überprüfen Sie Ihre Ressourcen und rufen Sie die Werte ab, die Apigee benötigt.
  2. Stellen Sie eine Verbindung zum Dienstanhang her.
  3. Erstellen Sie das API-Proxy-Bundle.
  4. Importieren Sie den API-Proxy und stellen Sie ihn bereit.
  5. Semantische Caching-Richtlinien testen

Schritt 1: Ressourcen prüfen und die von Apigee benötigten Werte abrufen

Bevor Sie Apigee konfigurieren, prüfen Sie, ob der Endpunkt Ihres Vektorsuchindex für Private Service Connect aktiviert ist und ob Ihr Index bereitgestellt wurde. Lesen Sie dann die beiden Werte, die der Apigee-Proxy verwendet: den Dienstanhang und den DEPLOYED_INDEX_ID.

Prüfen Sie, ob der Index bereitgestellt ist und der Endpunkt einen Private Service Connect-Dienstanhang verfügbar macht:

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.privateEndpoints.serviceAttachment)"

Der Befehl gibt den Ressourcennamen eines Dienstanhangs im Format projects/TENANT_PROJECT/regions/REGION/serviceAttachments/SERVICE_ATTACHMENT_NAME zurück. In diesem Leitfaden wird dieser Wert als SERVICE_ATTACHMENT bezeichnet. Wenn der Befehl einen leeren Wert zurückgibt, ist der Index noch nicht auf einem Private Service Connect-Endpunkt bereitgestellt. Kehren Sie zu den Voraussetzungen für den Vektorsuchindex zurück und schließen Sie die Bereitstellung des Index ab, bevor Sie fortfahren.

Lesen Sie die DEPLOYED_INDEX_ID des auf dem Endpunkt bereitgestellten Index:

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.id)"

In diesem Leitfaden wird dieser Wert als DEPLOYED_INDEX_ID bezeichnet. Sie verwenden ihn in der Richtlinie „SemanticCacheLookup“ in Schritt 3: API-Proxy-Bundle erstellen.

Weitere Informationen zum Bereitstellen und Abfragen privater Indexendpunkte finden Sie unter Index auf einem Private Service Connect-Endpunkt bereitstellen und Zugriff auf private Dienste oder Private Service Connect-Indexe abfragen.

Schritt 2: Verbindung zum Dienstanhang herstellen

In diesem Schritt erhalten Sie den privaten Host, den der <GrpcEndpoint> des Proxys aufruft. Wie Sie sie erstellen, hängt von Ihrer Plattform ab. Die Proxy-Konfiguration in den späteren Schritten ist in beiden Fällen identisch.

Apigee: Endpunktanhang erstellen

Erstellen Sie in Apigee einen Apigee-Endpunktanhang. Der Endpunktanhang ist die Private Service Connect-Nutzerseite von Apigee. Er stellt eine Verbindung zum Dienstanhang für die Vektorsuche her und bietet Ihnen einen privaten Host, den der Proxy aufruft.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
        "location": "'"$REGION"'",
        "serviceAttachment": "SERVICE_ATTACHMENT"
      }' \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments?endpointAttachmentId=ENDPOINT_ATTACHMENT"

Fragen Sie den Status ab, bis der state des Anhangs ACTIVE und der connectionState ACCEPTED ist. Notieren Sie sich dann den Host: 

curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments/ENDPOINT_ATTACHMENT"

Die Antwort enthält den Host im Feld host. In diesem Leitfaden wird dieser Wert als TARGET_HOST bezeichnet.

Sie haben zwei Möglichkeiten, um von Ihrem Proxy eine Verbindung zum Dienstanhang für die Vektorsuche herzustellen:

  • Die IP-Adresse: Verwenden Sie die im Feld host zurückgegebene IP-Adresse direkt als TARGET_HOST (z. B. 7.0.3.4).
  • Ein privater DNS-Eintrag: Wenn Sie in Ihrem Google Cloud -Projekt eine private Cloud DNS-Zone mit DNS-Peering zu Apigee konfiguriert haben, können Sie in Ihrer privaten Zone einen A-Eintrag erstellen, der auf die IP-Adresse des Endpunktanhangs verweist, und diesen Domainnamen (z. B. vectorsearch.example.com) als TARGET_HOST verwenden. Weitere Informationen finden Sie unter DNS-Eintrag verwenden und Verbindung mit privaten DNS-Peering-Zonen herstellen.

Private Service Connect-Endpunkt für Apigee Hybrid

In Apigee stellt Google eine „Endpunktanhang“-Ressource bereit, die die Private Service Connect-Verbindung verarbeitet. In Apigee Hybrid verwalten Sie jedoch die Laufzeit und die Netzwerkumgebung. Unabhängig davon, wo Ihr Cluster ausgeführt wird, muss er den Private Service Connect-Endpunkt der Vektorsuche über eine gRPC-Verbindung im Klartext zu host:10000 erreichen können.

Erstellen Sie für Apigee Hybrid einen Private Service Connect-Endpunkt in einer Google Cloud -Nutzer-VPC, die auf die Vektorsuche SERVICE_ATTACHMENT verweist. Verwenden Sie die interne IP-Adresse des Endpunkts als TARGET_HOST in Ihrer Proxy-Konfiguration. Achten Sie darauf, dass das Projekt Google Cloud , das diesen Endpunkt hostet, im projectAllowlist des Endpunkts des Vektorsuchindex enthalten ist. Weitere Informationen finden Sie unter Voraussetzungen für Vektorsuchindex.

Schritt 3: API-Proxy-Bundle erstellen

Proxy-Bundle erstellen

Erstellen Sie das folgende Verzeichnislayout: 

apiproxy/
├── PROXY_NAME.xml
├── proxies/default.xml
├── targets/default.xml
└── policies/
    ├── SCL-1.xml
    └── SCP-1.xml

policies/SCL-1.xml: die Richtlinie „SemanticCacheLookup“. Der Block <SimilaritySearch> verwendet <PrivateServiceConnect><GrpcEndpoint> (kein <URL>).

Hinweis: <GrpcEndpoint>-Regeln:

  • Das Format ist grpc://TARGET_HOST:PORT. Das Schema muss grpc:// sein. grpcs:// (TLS) wird in dieser Version nicht unterstützt.
  • Der Port für die Vektorsuche ist 10000. Private Service Connect-Endpunkte auf Datenebene stellen gRPC auf Port 10000 bereit. Der Endpunkt ist also immer grpc://TARGET_HOST:10000.
  • TARGET_HOST kann entweder die IP-Adresse des Endpunktanhangs (aus Schritt 2) oder ein benutzerdefinierter DNS-Eintrag sein, der in Ihrer privaten DNS-Zone erstellt wurde.
  • Der gRPC-Hop ist Klartext und nicht authentifiziert (durch Netzwerkisolation gesichert).
<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-1">
  <DisplayName>SCL-1</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-embedding-001:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <PrivateServiceConnect>
        <GrpcEndpoint>grpc://TARGET_HOST:10000</GrpcEndpoint>
      </PrivateServiceConnect>
      <DeployedIndexID>DEPLOYED_INDEX_ID</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

policies/SCP-1.xml: die Richtlinie „SemanticCachePopulate“. „Populate“ ist nur für REST verfügbar und muss <URL> verwenden (<PrivateServiceConnect> wird bei der Bereitstellung abgelehnt): 

<SemanticCachePopulate async="false" continueOnError="true" enabled="true" name="SCP-1">
  <DisplayName>SCP-1</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>3600</TTLInSeconds>
</SemanticCachePopulate>

targets/default.xml: das Modellziel. Das Ziel ruft eine Google API auf und benötigt daher ein Token. <GoogleAccessToken> verwendet das Dienstkonto des Deployments: 

<TargetEndpoint name="default">
  <PreFlow name="PreFlow"><Request/><Response/></PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

proxies/default.xml: Die Richtlinie „SemanticCacheLookup“ wird für die Anfrage und die Richtlinie „SemanticCachePopulate“ für die Antwort ausgeführt: 

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request><Step><Name>SCL-1</Name></Step></Request>
    <Response><Step><Name>SCP-1</Name></Step></Response>
  </PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPProxyConnection>
    <BasePath>/PROXY_NAME</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

PROXY_NAME.xml: der Bundle-Deskriptor: 

<APIProxy name="PROXY_NAME">
  <BasePaths>/PROXY_NAME</BasePaths>
  <Policies><Policy>SCL-1</Policy><Policy>SCP-1</Policy></Policies>
  <ProxyEndpoints><ProxyEndpoint>default</ProxyEndpoint></ProxyEndpoints>
  <TargetEndpoints><TargetEndpoint>default</TargetEndpoint></TargetEndpoints>
</APIProxy>

Schritt 4: API-Proxy importieren und bereitstellen

Komprimieren Sie das Bundle, importieren Sie es, um eine neue Überarbeitung zu erstellen, und stellen Sie die Überarbeitung mit Ihrem Dienstkonto bereit: 

TOKEN=$(gcloud auth print-access-token)
(cd BUNDLE_DIR && zip -r ../PROXY_NAME.zip apiproxy)
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -F "file=@PROXY_NAME.zip" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/apis?action=import&name=PROXY_NAME"
curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments?override=true&serviceAccount=SERVICE_ACCOUNT"

Wobei:

  • BUNDLE_DIR ist das Verzeichnis, das den Ordner apiproxy/ enthält. Das Archiv muss den Ordner apiproxy/ im Stammverzeichnis enthalten.
  • ENV ist die Apigee-Umgebung, in der Sie den Proxy bereitstellen. Die Umgebung muss eine Intermediate- oder Comprehensive-Umgebung sein.
  • REVISION ist die Versionsnummer, die vom Importaufruf zurückgegeben wird.
  • SERVICE_ACCOUNT ist die E-Mail-Adresse des Dienstkontos, das Sie zum Bereitstellen des Proxys verwenden.

Warten Sie, bis die Bereitstellung READY meldet: 

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments" | jq .state

Schritt 5: Richtlinien für semantisches Caching testen

Senden Sie einen neuen Prompt. Das ist ein Cache-Fehler: Das Modell wird aufgerufen und die Antwort wird im Cache gespeichert. 

curl -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

Senden Sie denselben Prompt noch einmal. Dies ist ein Cache-Treffer: Die Antwort wird aus dem Cache bereitgestellt und das Modell wird nicht aufgerufen. 

curl -i -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

Bei einem Treffer enthält die Antwort den Header Cached-content: true, dieselbe Antwort und eine deutlich geringere Latenz.

Sie können das Caching auch mit einer Debugging-Sitzung prüfen. Bei einem Treffer legt die Richtlinie „SemanticCacheLookup“ die folgenden Ablaufvariablen fest:

Variable Wert für einen Treffer
SemanticCacheLookup.SCL-1.dense_embeddings Der Einbettungsvektor des Prompts.
SemanticCacheLookup.SCL-1.is_nearest_neighbor_hit true
SemanticCacheLookup.SCL-1.cache_hit true
SemanticCacheLookup.SCL-1.cached_llm_response Die im Cache gespeicherte Antwort.

Bei einem Treffer wird das Modellziel nicht aufgerufen. Der Ablauf wird abgebrochen und die im Cache gespeicherte Antwort wird zurückgegeben.

Fehlerbehebung

Eine vollständige Fehlerreferenz finden Sie in der Richtlinie „SemanticCacheLookup“.

Beschränkungen

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

  • Die maximale cachebare Textgröße beträgt 256 KB. Weitere Informationen finden Sie unter Cache-Wertgröße auf der Apigee-Seite Limits.
  • Apigee ignoriert alle Cache-Control-Header, die es vom LLM-Modell empfängt.
  • Wenn der Cache nicht ordnungsgemäß 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 Ihre Apigee-Organisation erstellen.
  • Die Richtlinien für semantisches Caching werden nicht für die Verwendung mit API-Proxys unterstützt, die EventFlows für das kontinuierliche Streaming von Antworten von Server-Sent Events (SSE) verwenden.
  • Die Richtlinien für semantisches Caching verwenden LLM APIs, was zu höheren Latenzen im Bereich von Hunderten von Millisekunden führen kann.
  • In Apigee Hybrid-Installationen ist die Unterstützung für die Richtlinien für semantisches Caching auf Installationen in der Google Cloud Platform beschränkt.
  • Wenn die SemanticCacheLookup-Richtlinie so konfiguriert ist, dass sie einen privaten Vektorsuche-Endpunkt über Private Service Connect (PSC) verwendet, wird der Aufruf für die Ähnlichkeitssuche über eine direkte gRPC-Verbindung an den privaten Endpunkt gesendet und nicht über einen konfigurierten Forward-Proxy.

Nächste Schritte