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

Diese Seite gilt für Apigee, aber nicht für 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.

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.

    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 Vertex AI Text Embeddings API in Ihrem Google Cloud -Projekt.
  5. 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.
  6. 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.
  7. 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.

Ü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 wird der private Host angegeben, den der Proxy mit <GrpcEndpoint> aufruft. Erstellen Sie in Apigee einen Apigee-Endpunktanhang. Der Endpunktanhang ist die Private Service Connect-Nutzerseite von Apigee: Er stellt eine Verbindung zum Vektorsuche-Dienstanhang 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.

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.

Nächste Schritte