SemanticCachePopulate-Richtlinie

Übersicht

Die Richtlinie „SemanticCachePopulate“ ist eine erweiterte Caching-Richtlinie, die die Leistung von KI-Arbeitslasten optimieren soll, insbesondere bei Large Language Models (LLMs).

Bei der Richtlinie wird die Text-Einbettungs-API von Vertex AI verwendet, um Einbettungen für Text zu generieren, und die Vektorsuche, um API-Antworten basierend auf semantischer Ähnlichkeit statt auf genauen Übereinstimmungen im Cache zu speichern.

Mit der Richtlinie „SemanticCachePopulate“ können Sie die Antwortzeiten für wiederholte Abfragen reduzieren und die Kosten optimieren, indem Sie das Aufrufvolumen an LLMs verringern.

Diese Richtlinie wird in Verbindung mit der SemanticCacheLookup-Richtlinie verwendet.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Hinweise

Bevor Sie die Richtlinie „SemanticCachePopulate“ verwenden können, müssen Sie die folgenden Aufgaben ausführen:

  • Erstellen Sie ein Vertex AI-Projekt.
  • Erstellen Sie einen Vektorsuchindex.
  • Erstellen Sie einen Vertex AI-Endpunkt für den Index.
  • Erstellen Sie eine SemanticCachePopulate-Richtlinie.

Weitere Informationen zu diesen Aufgaben finden Sie unter Einführung in Richtlinien für semantisches Caching.

Rollen und Berechtigungen

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 Anwenden und Verwenden der Richtlinie „SemanticCachePopulate“ 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.

APIs aktivieren

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

Enable the APIs

Element <SemanticCachePopulate>

Definiert eine SemanticCachePopulate-Richtlinie.

Standardwert Siehe Standardrichtlinie Tab unten
Erforderlich? Erforderlich
Typ Komplexes Objekt
Übergeordnetes Element –
Untergeordnete Elemente <DisplayName>
<IgnoreUnresolvedVariables>
<SimilaritySearch>
<TTLInSeconds>

Das <SemanticCachePopulate>-Element verwendet die folgende Syntax:

Syntax

Das <SemanticCachePopulate>-Element verwendet die folgende Syntax:

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

Standardrichtlinie

Das folgende Beispiel zeigt die Standardeinstellungen, wenn Sie Ihrem API-Proxy in der Apigee-Benutzeroberfläche eine SemanticCachePopulate-Richtlinie hinzufügen:

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

Wenn Sie eine neue SemanticCachePopulate-Richtlinie in die Apigee-UI einfügen, enthält die Vorlage Stubs für alle möglichen Vorgänge. Informationen zu den erforderlichen Elementen finden Sie unten.

Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:

Attribut Standard Erforderlich? Beschreibung
name - Erforderlich

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.
continueOnError false Optional Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Weitere Informationen:
enabled wahr Optional Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht durchgesetzt, selbst wenn sie mit einem Ablauf verknüpft ist.
async   false Verworfen Dieses Attribut wurde verworfen.

Die folgende Tabelle enthält eine allgemeine Beschreibung der untergeordneten Elemente von <SemanticCachePopulate>:

Untergeordnetes Element Erforderlich? Beschreibung
<DisplayName> Optional Der Name der Richtlinie.
<IgnoreUnresolvedVariables> Optional Bestimmt, ob die Verarbeitung beendet wird, wenn ein Property-Set nicht aufgelöst werden kann.
<SimilaritySearch> Erforderlich Element mit den Informationen, die zum Aktualisieren des Vektorindexes erforderlich sind.

Weitere Informationen finden Sie unter Datenpunkte upserten.

Die Gültigkeitsdauer für Datenpunkte beträgt <TTLInSeconds> ab dem Zeitpunkt des Eintrags.

<TTLInSeconds> Optional Die Gültigkeitsdauer (TTL) für die im Cache gespeicherten Antworten in Sekunden.

Der Standardwert ist 60.

Beispiel

In diesem Abschnitt finden Sie ein Beispiel für <SemanticCachePopulate>.

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

Verweis auf untergeordnetes Element

In diesem Abschnitt werden die untergeordneten Elemente von <SemanticCachePopulate> beschrieben.

<DisplayName>

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen, natürlicher klingenden Namen zu versehen.

Das Element <DisplayName> ist für alle Richtlinien gleich.

Standardwert –
Erforderlich? Optional. Wenn Sie <DisplayName> weglassen, wird der Wert des Attributs name der Richtlinie verwendet.
Typ String
Übergeordnetes Element <PolicyElement>
Untergeordnete Elemente Keine

Das <DisplayName>-Element verwendet die folgende Syntax:

Syntax

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Beispiel

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Das <DisplayName>-Element hat keine Attribute oder untergeordneten Elemente.

<IgnoreUnresolvedVariables>

Bestimmt, ob die Verarbeitung beendet wird, wenn eine Variable nicht aufgelöst werden kann. Auf true festlegen, um nicht aufgelöste Variablen zu ignorieren und die Verarbeitung fortzusetzen.

IgnoreUnresolvedVariables ist nicht zulässig, wenn <DefaultValue> angegeben ist.

Standardwert Falsch
Erforderlich? Optional
Typ Boolesch
Übergeordnetes Element <SemanticCachePopulate>
Untergeordnete Elemente Keine

<SimilaritySearch>

Element mit den Informationen, die zum Aktualisieren des Vektorindexes erforderlich sind.

Weitere Informationen finden Sie unter Datenpunkte upserten.

Die Ablaufzeit für Datenpunkte beträgt <TTLInSeconds> Stunden nach der Eingabe.

Standardwert –
Erforderlich? Erforderlich
Typ String
Übergeordnetes Element <SemanticCachePopulate>
Untergeordnete Elemente <VertexAI>

Das <SimilaritySearch>-Element verwendet die folgende Syntax:

<SimilaritySearch>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
  </VertexAI>
</SimilaritySearch>

<VertexAI> (untergeordnetes Element von <SimilaritySearch>)

Enthält das Element <URL> für Vertex AI-spezifische Attribute.

Standardwert –
Erforderlich? Erforderlich
Typ String
Übergeordnetes Element <SimilaritySearch>
Untergeordnete Elemente <URL>

Das VertexAI-Element verwendet die folgende Syntax:

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

<URL> (untergeordnetes Element von <VertexAI>)

Die URL, die zum Upserten von Datenpunkten in den Vektorindex verwendet wird.

Standardwert –
Erforderlich? Erforderlich
Typ String
Übergeordnetes Element <VertexAI>
Untergeordnete Elemente Keins

Das URL-Element verwendet die folgende Syntax:

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>

<TTLInSeconds>

Element, das die Gültigkeitsdauer (TTL) für die im Cache gespeicherten Antworten in Sekunden angibt. Der Standardwert ist 60.

Weitere Informationen finden Sie unter Aktiven Index aktualisieren und neu erstellen.

Standardwert –
Erforderlich? Optional
Typ String
Übergeordnetes Element <SemanticCachePopulate>
Untergeordnete Elemente Keins

Ablaufvariablen

Ablaufvariablen können verwendet werden, um das dynamische Laufzeitverhalten für Richtlinien und Abläufe auf der Grundlage von HTTP-Headern oder Nachrichteninhalten oder dem Kontext zu konfigurieren, der im Ablauf verfügbar ist. Weitere Informationen zu Ablaufvariablen finden Sie in der Referenz zu Ablaufvariablen.

Die Richtlinie kann diese schreibgeschützten Variablen während der Ausführung festlegen.

Variablenname Beschreibung
response.content Enthält den vollständigen Inhalt der API-Antwort.
semanticcache.populate.policy_name.upsert_index_request Enthält die Anfragen-Nutzlast, die an die Vertex AI Vector Search API gesendet wird, um den Vektorindex mit neuen Einbettungen und Metadaten zu aktualisieren.
semanticcache.populate.policy_name.upsert_index_response Enthält die Antwort der Vertex AI Vector Search API, die den Erfolg oder Misserfolg des Indexaktualisierungsvorgangs angibt.

Fehlerreferenz

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee speziell für die <SemanticCachePopulate>-Richtlinie festgelegt werden. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Fehlercode HTTP-Status Ursache
steps.semanticcachepopulate.VectorSearchUpsertServiceUnavailable 400

Dieser Fehler tritt auf, wenn die Vector Search Upsert Datapoints API nicht verfügbar ist.
steps.semanticcache.populate.VectorSearchUpsertAPIFailed 500

Dieser Fehler tritt auf, wenn der API-Dienst „Vector Search Upsert Datapoints“ fehlschlägt.
steps.semanticcache.populate.AuthenticationFailure 500

Dieser Fehler tritt auf, wenn das Dienstkonto nicht die erforderlichen Berechtigungen hat.
steps.semanticcache.populate.CalloutError 500 Der Vertex AI-Dienstaufruf ist fehlgeschlagen.
steps.semanticcache.populate.InternalError 500

Dieser Fehler tritt auf, wenn in der <SemanticCachePopulate>-Richtlinie ein unerwarteter Fehler auftritt.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlername Ursache
The SimilaritySearch URL {url} is invalid. Dieser Fehler tritt auf, wenn das Element <URL> in <SimilaritySearch> leer oder ungültig ist.
The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https. Tritt auf, wenn das http-Schema des SimilaritySearch-Elements <URL> ungültig ist.
The TTLInSeconds element must be >= 0. Wenn der Wert auf null oder eine negative Zahl gesetzt ist, schlägt die Bereitstellung des API-Proxy fehl.

Fehlervariablen

Diese Variablen werden festgelegt, wenn diese Richtlinie zur Laufzeit einen Fehler auslöst. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Variablen Wo Beispiel
fault.name="FAULT_NAME" FAULT_NAME ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name Matches "UnresolvedVariable"
semanticcachepopulate.POLICY_NAME.failed POLICY_NAME ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. semanticcachepopulate.SC-populate.failed = true

Beispiel für eine Fehlerantwort

{
"fault": {
  "faultstring": "SemanticCacheLookup[SC-populate]: unable to resolve variable [variable_name]",
  "detail": {
    "errorcode": "steps.semanticcachepopulate.UnresolvedVariable"
  }
}
}

Beispiel für eine Fehlerregel

<FaultRule name="SemanticCacheLookup Faults">
  <Step>
      <Name>SCL-CustomSetVariableErrorResponse</Name>
      <Condition>(fault.name = "SetVariableFailed")</Condition>
  </Step>
  <Condition>(semanticcachelookup.failed = true)</Condition>
</FaultRule>

Schemas

Jeder Richtlinientyp wird durch ein XML-Schema (.xsd) definiert. Zu Referenzzwecken sind Richtlinienschemas auf GitHub verfügbar.