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 Grundlage semantischer Ähnlichkeit zu ermöglichen. In diesem Beispiel wird die Ähnlichkeitssuche der Richtlinien für einen Vektorsuchindex ausgeführt, der auf einem privaten (Private Service Connect) Endpunkt 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 (Private Service Connect-)Endpunkt in Version 1.17.0 und höher unterstützt. Weitere Informationen finden Sie unter Einrichtung in Apigee Hybrid.

Hinweis

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

  1. Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

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

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

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

    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

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

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

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

    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

    8.
  8. Aktivieren und konfigurieren Sie die Vertex AI Text Embeddings API in Ihrem Google Cloud -Projekt.
  9. Sie haben einen Vektorsuchindex erstellt (oder haben Zugriff darauf), der an einem privaten (Private Service Connect)-Endpunkt bereitgestellt wird. In diesem Tutorial werden die Einrichtungsschritte für die Vektorsuche nicht wiederholt. Informationen zu den spezifischen Anforderungen für „SemanticCacheLookup“ und Links zur Dokumentation zur Vektorsuche finden Sie unter Voraussetzungen für den Vektorsucheindex.
  10. Prüfen Sie, ob in Ihrer Apigee-Instanz eine Intermediate- oder Comprehensive-Umgebung verfügbar ist. Semantische Caching-Richtlinien können nur in Intermediate- oder Comprehensive-Umgebungen bereitgestellt werden.
  11. Prüfen Sie, ob Sie eine Umgebungsgruppe mit einem Laufzeithostnamen 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 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

Voraussetzungen für Vektorsuchindex

In dieser Anleitung wird davon ausgegangen, dass Sie bereits einen Vektorsuchindex haben (oder erstellen werden), der auf einem privaten (Private Service Connect)-Endpunkt bereitgestellt wird. Das Erstellen, Formatieren und Bereitstellen eines Vektorsuchindex wird in den Anleitungen zur Vektorsuche dokumentiert. In dieser Anleitung werden diese Schritte daher nicht wiederholt. In der Dokumentation zur Vektorsuche erfahren Sie, wie Sie

Beim Erstellen des Index müssen die folgenden SemanticCacheLookup-spezifischen Anforderungen erfüllt sein:

  • 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 1.536), setzen Sie dimensions auf denselben Wert.
  • Erstellen Sie den Index mit dem Distanzmaß (distanceMeasureType), das dem <DistanceMeasureType> Ihrer Richtlinie entspricht. Das <SimilaritySearch><VertexAI><DistanceMeasureType>-Element in der SemanticCacheLookup-Richtlinie ist optional und hat standardmäßig den Wert DOT_PRODUCT_DISTANCE. COSINE_DISTANCE wird ebenfalls unterstützt. Der Indexabstandsmesswert und die Richtlinie <DistanceMeasureType> müssen identisch sein.

Im folgenden Minimalbeispiel wird ein kompatibler Index erstellt. Den vollständigen Anfragebody 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 die numerische INDEX_ID, die in der Antwort zurückgegeben wird. Sie verwenden sie in der Richtlinie „SemanticCachePopulate“. Nachdem Sie den Index erstellt haben, erstellen Sie einen Private Service Connect-Indexendpunkt und stellen Sie den Index darauf bereit.

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

  • 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.
    Die projectAllowlist kann nach der Erstellung 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 vom Proxy verwendet wird. 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 Hybrid-Laufzeitversion 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. Für diese Funktion gelten keine eigenen Clusteranforderungen. Jeder unterstützte Hybridcluster funktioniert.
  • Eine Umgebung vom Typ „Intermediate“ oder „Comprehensive“ und eine Umgebungsgruppe mit einem Laufzeithostnamen, der mit dem in Apigee identisch ist. Richtlinien für semantisches Caching werden nur in Intermediate- oder Comprehensive-Umgebungen bereitgestellt.
  • Netzwerkverfügbarkeit von der Laufzeit zum privaten Endpunkt: Der Nachrichtenprozessor muss eine Nur-Text-gRPC-Verbindung zum Private Service Connect-Endpunkt für die Vektorsuche auf TARGET_HOST:10000 öffnen können.
  • Ausgehender Traffic für die REST-Aufrufe. Die Aufrufe von „Embeddings“, „Populate“ und „model-target“ gehen an die öffentliche REGION-aiplatform.googleapis.com-Oberfläche. Die Laufzeit benötigt also auch einen Pfad zu Google APIs – direkt oder über einen privaten Pfad, wenn Ihr Cluster keinen öffentlichen ausgehenden Traffic hat.

Einrichtung in Apigee Hybrid

Semantisches Caching über einen privaten (Private Service Connect-)Endpunkt wird in Apigee Hybrid Version 1.17.0 und höher unterstützt. Die Richtlinienkonfiguration und die Schritte zur Vektorsuche in dieser Anleitung sind mit Apigee identisch. Der Unterschied besteht darin, dass Sie die Laufzeit in Hybrid selbst ausführen und die Verbindung selbst herstellen. Da hybride Bereitstellungen sehr unterschiedlich sein können, enthält dieser Abschnitt allgemeine Anleitungen und keine genauen Befehle. Die einzige Anforderung, die durch dieses Feature hinzugefügt wird, ist, dass die Laufzeit den privaten Endpunkt über Plaintext-gRPC erreichen muss.

Netzwerkverfügbarkeit angeben

Bei Hybridbereitstellungen müssen Sie die Konnektivität manuell verwalten, da es keine von Apigee verwaltete Endpunktanhänge gibt. Erstellen Sie in Ihrer Nutzer-VPC einen Private Service Connect-Endpunkt, der auf den Vektorsuchindex SERVICE_ATTACHMENT verweist, und verwenden Sie seine 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 öffentlichen Internet-Ausgang hat, muss die Laufzeit einen privaten Pfad zu Google APIs haben, z. B. privaten Google-Zugriff, um die REST-Kommunikation zu verarbeiten.

Nachdem Sie die Verbindung zu grpc://TARGET_HOST:10000 hergestellt haben, folgen Sie den nachfolgenden Schritten – Index erstellen und bereitstellen, Proxy erstellen und testen –, die sowohl für Apigee als auch für Apigee Hybrid identisch sind.

Ü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 jeweils an die Anfrage- und Antwortabläufe eines Apigee-API-Proxy angehängt. Wenn der Proxy eine Anfrage erhält, wird mit der Richtlinie „SemanticCacheLookup“ der Nutzer-Prompt aus der Anfrage extrahiert und mithilfe der API für Texteinbettungen in eine numerische Darstellung umgewandelt. 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 Reaktion auf den Nutzer-Prompt und füllt den Apigee-Cache mit der Antwort. Es wird ein Feedbackloop erstellt, um die Einträge im Vektorsuchindex für zukünftige Anfragen zu aktualisieren.

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

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

  1. Ressourcen überprüfen und die von Apigee benötigten Werte abrufen
  2. Verbindung zum Dienstanhang herstellen
  3. API-Proxy-Bundle erstellen
  4. API-Proxy importieren und bereitstellen
  5. Semantische Caching-Richtlinien testen:

Schritt 1: Ressourcen prüfen und die erforderlichen Werte für Apigee abrufen

Bevor Sie Apigee konfigurieren, prüfen Sie, ob Ihr Vektorsuchindex-Endpunkt für Private Service Connect aktiviert ist und Ihr Index bereitgestellt wurde. Lesen Sie dann die beiden Werte, die vom Apigee-Proxy verwendet werden: die Dienstanhänge und die DEPLOYED_INDEX_ID.

Prüfen Sie, ob der Index bereitgestellt wurde 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 einen Dienstanhang-Ressourcennamen 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 Voraussetzungen für Vektorsuchindex zurück und stellen Sie den Index bereit, bevor Sie fortfahren.

Lesen Sie die DEPLOYED_INDEX_ID des Index, der auf dem Endpunkt bereitgestellt wird:

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 sie in der Richtlinie „SemanticCacheLookup“ in Schritt 3: API-Proxy-Bundle erstellen.

Weitere Informationen zum Bereitstellen und Abfragen privater Indexendpunkte finden Sie unter Index an einem Private Service Connect-Endpunkt bereitstellen und Private Services Access- oder Private Service Connect-Indizes abfragen.

Schritt 2: Verbindung zum Dienstanhang herstellen

In diesem Schritt erhalten Sie den privaten Host, den der Proxy mit <GrpcEndpoint> aufruft. Wie Sie sie erstellen, hängt von Ihrer Plattform ab. Die Proxykonfiguration 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 ab, bis state des Anhangs ACTIVE und 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.

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

  • Die IP-Adresse:Verwenden Sie die im Feld host zurückgegebene IP-Adresse direkt als TARGET_HOST (z. B. 7.0.3.4).
  • 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 der Endpunktanhänge 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-Peeringzonen herstellen.

Private Service Connect-Endpunkt für Apigee Hybrid

In Apigee stellt Google eine „Endpunktanhang“-Ressource bereit, die die Private Service Connect-Verbindung verwaltet. 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 für die Vektorsuche über eine Nur-Text-gRPC-Verbindung zu host:10000 erreichen können.

Erstellen Sie für Apigee Hybrid einen Private Service Connect-Endpunkt in einer Google Cloud -VPC des Nutzers, der auf die SERVICE_ATTACHMENT-Vektorsuche verweist. Verwenden Sie die interne IP-Adresse des Endpunkts als TARGET_HOST in Ihrer Proxykonfiguration. Achten Sie darauf, dass das Google Cloud -Projekt, in dem dieser Endpunkt gehostet wird, in der projectAllowlist des Endpunkts des Vektorsuchindex enthalten ist. Weitere Informationen finden Sie unter Voraussetzungen für Vektorsuche-Index.

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“. Im Block <SimilaritySearch> wird <PrivateServiceConnect><GrpcEndpoint> verwendet (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-Datenebenenendpunkte stellen gRPC auf Port 10000 bereit. Der Endpunkt ist also immer grpc://TARGET_HOST:10000.
  • TARGET_HOST kann entweder die IP-Adresse der Endpunktanhänge (aus Schritt 2) oder ein benutzerdefinierter DNS-Eintrag sein, der in Ihrer privaten DNS-Zone erstellt wurde.
  • Der gRPC-Hop ist unverschlüsselt 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 Ziel des Modells. Das Ziel ruft eine Google API auf und benötigt daher ein Token. <GoogleAccessToken> verwendet das Dienstkonto der Bereitstellung: 

<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: Führen Sie die Richtlinie „SemanticCacheLookup“ für die Anfrage und die Richtlinie „SemanticCachePopulate“ für die Antwort aus: 

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

<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

Zippen 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 im Stammverzeichnis den Ordner apiproxy/ enthalten.
  • ENV ist die Apigee-Umgebung, in der Sie den Proxy bereitstellen. Die Umgebung muss eine Intermediate- oder Comprehensive-Umgebung sein.
  • REVISION ist die Überarbeitungsnummer, 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 bei der Bereitstellung READY gemeldet wird: 

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: Semantische Caching-Richtlinien 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."}]}]}'

Die Antwort enthält den Cached-content: true-Header, dieselbe Antwort und eine deutlich geringere Latenz.

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

Variable Wert für einen Hit
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 Antwort aus dem Cache.

Bei einem Treffer wird das Modellziel nicht aufgerufen. Der Ablauf wird abgekürzt und die Antwort aus dem Cache wird zurückgegeben.

Fehlerbehebung

Die vollständige Fehlerreferenz finden Sie in der SemanticCacheLookup-Richtlinie.

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 (Cache-Wertgröße).
  • 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 Funktionsverfü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 die Verwendung mit API-Proxys unterstützt, die EventFlows für das kontinuierliche Streaming von Antworten von Server-Sent Events (SSE) verwenden.
  • Für die Richtlinien für semantisches Caching werden LLM-APIs verwendet, 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 auf der Google Cloud Platform beschränkt.
  • Wenn die SemanticCacheLookup-Richtlinie so konfiguriert ist, dass ein privater Vektorsuch-Endpunkt über Private Service Connect (PSC) verwendet wird, wird der Ähnlichkeitssuchaufruf über eine direkte gRPC-Verbindung an den privaten Endpunkt gesendet und nicht über einen konfigurierten Forward-Proxy.

Nächste Schritte