SemanticCacheLookup-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Übersicht

Die SemanticCacheLookup-Richtlinie ist eine erweiterte Caching-Richtlinie, die die Leistung von KI-Arbeitslasten optimieren soll, insbesondere von Arbeitslasten, die Large Language Models (LLMs) umfassen.

In der Richtlinie wird die Vertex AI Text Embeddings API verwendet, um Einbettungen für Text zu generieren, und die Vektorsuche, um ähnliche Prompts basierend auf semantischer Ähnlichkeit und nicht auf exakten Übereinstimmungen zu finden.

Die Richtlinie „SemanticCacheLookup“ kann die Antwortzeiten für wiederholte Anfragen verkürzen und die Kosten optimieren, indem das Anrufvolumen an LLMs reduziert wird.

Diese Richtlinie wird in Verbindung mit der SemanticCachePopulate-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 SemanticCacheLookup-Richtlinie 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 zum Ausführen dieser Aufgaben finden Sie unter Erste Schritte mit Richtlinien für semantisches Caching.

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 Anwenden und Verwenden der SemanticCacheLookup-Richtlinie 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 <SemanticCacheLookup>

Definiert eine SemanticCacheLookup-Richtlinie.

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

Das <SemanticCacheLookup>-Element verwendet die folgende Syntax:

Syntax

Das <SemanticCacheLookup>-Element verwendet die folgende Syntax:

<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

Standardrichtlinie

Das folgende Beispiel zeigt die Standardeinstellungen, wenn Sie Ihrem Ablauf in der Apigee-UI eine SemanticCacheLookup-Richtlinie hinzufügen:

<SemanticCacheLookup async="false" continueOnError="false"enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict
      </URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <Threshold>0.9</Threshold>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

Wenn Sie eine neue SemanticCacheLookup-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 <SemanticCacheLookup>:

Untergeordnetes Element Erforderlich? Beschreibung
<DisplayName> Optional Der Name der Richtlinie.
<IgnoreUnresolvedVariables> Optional 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.
<UserPromptSource> Optional Der Speicherort der Nutzlast, aus der der Text für die Nutzeraufforderung extrahiert werden soll. Es werden nur String-Textwerte unterstützt.

Dieses Feld unterstützt die Apigee-Syntax für Nachrichtenvorlagen, einschließlich der Verwendung von Variablen oder JSON-Pfadfunktionen.

Beispiel: 

{jsonPath($.contents[-1].parts[-1].text,request.content,true)}

<Embeddings> Erforderlich Element mit den Informationen, die zum Generieren von Einbettungen erforderlich sind.
<SimilaritySearch> Erforderlich Element mit den Informationen, die zum Ausführen von Ähnlichkeitssuchen erforderlich sind.

Weitere Informationen finden Sie unter Öffentlichen Index abfragen, um die nächsten Nachbarn abzurufen.

Verweis auf untergeordnetes Element

In diesem Abschnitt werden die untergeordneten Elemente von <SemanticCacheLookup> 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 gilt nicht, wenn <DefaultValue> angegeben ist.

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

<UserPromptSource>

Der Speicherort der Nutzlast, aus der der Text für die Nutzeraufforderung extrahiert werden soll. Es werden nur String-Textwerte unterstützt.

Dieses Feld unterstützt die Apigee-Syntax für Nachrichtenvorlagen, einschließlich der Verwendung von Variablen oder JSON-Pfadfunktionen.

Beispiel: 

{jsonPath($.contents[-1].parts[-1].text,request.content,true)}
Standardwert {jsonPath($.contents[-1].parts[-1].text,request.content,true)}
Erforderlich? Optional
Typ String
Übergeordnetes Element <SemanticCacheLookup>
Untergeordnete Elemente Keine

<Embeddings>

Dieses Element enthält die Informationen, die zum Generieren von Texteinbettungen erforderlich sind.

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

Das <Embeddings>-Element verwendet die folgende Syntax:

<Embeddings>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
  </VertexAI>
</Embeddings>

<VertexAI> (untergeordnetes Element von <Embeddings>)

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

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

Das VertexAI-Element verwendet die folgende Syntax:

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
</VertexAI>

<URL> (untergeordnetes Element von <VertexAI>)

Die URL, die zum Generieren von Texteinbettungen verwendet wird. Eine Liste der Modelle, die Texteinbettungen für die SemanticCacheLookup-Richtlinie bereitstellen können, finden Sie unter Unterstützte Modelle.

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}/publishers/google/models/{MODEL_ID}:predict</URL>

<SimilaritySearch>

Dieses Element enthält die Informationen, die für Ähnlichkeitssuchen erforderlich sind.

Weitere Informationen finden Sie unter Öffentlichen Index abfragen, um die nächsten Nachbarn abzurufen.

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

Das <SimilaritySearch>-Element verwendet die folgende Syntax:

<SimilaritySearch>
  <VertexAI>
    <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors
    </URL>
    <Threshold>0.9</Threshold>
    <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
  </VertexAI>
</SimilaritySearch>

<VertexAI> (untergeordnetes Element von <SimilaritySearch>)

Enthält das <URL>-Element 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://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
  <Threshold>0.9</Threshold>
  <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>

Die folgende Tabelle enthält eine allgemeine Beschreibung der untergeordneten Elemente von <VertexAI>.

Untergeordnetes Element Erforderlich? Beschreibung
<URL> Erforderlich String

Die URL, die für Ähnlichkeitssuchen verwendet wird. Der höchste übereinstimmende Datenpunkt, der den Ähnlichkeitsschwellenwert erfüllt, ist der einzige Datenpunkt, der verwendet wird.
<Threshold> Optional String

Ähnlichkeitswert, mit dem bestimmt wird, ob zwei Prompts als Übereinstimmung gelten. Ein Wert zwischen 0 und 1.

Der Standardwert ist 0,9.
<DeployedIndexID> Erforderlich String

Die ID des Index, der auf dem für das semantische Caching verwendeten Indexendpunkt bereitgestellt wird.

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
request.content Enthält den gesamten Inhalt der eingehenden API-Anfrage.
request.url Enthält die URL der eingehenden API-Anfrage.
semanticcache.lookup.policy_name.user_prompt Enthält bestimmte Komponenten, die aus dem Anfrage-Prompt extrahiert wurden und zum Generieren von Einbettungen oder zum Ausführen von Ähnlichkeitssuchen verwendet werden.
semanticcache.lookup.policy_name.embeddings_request Enthält die Anfrage-Payload, die an die Vertex AI Embeddings API gesendet wird, um Texteinbettungen für den Eingabetext zu generieren.
semanticcache.lookup.policy_name.embeddings_response Enthält die Antwort der Vertex AI Embeddings API, einschließlich der generierten Texteinbettungen.
semanticcache.lookup.policy_name.dense_embeddings Enthält die tatsächlichen numerischen Einbettungswerte, die von der Vertex AI Embeddings API generiert wurden.
semanticcache.lookup.policy_name.is_nearest_neighbor_hit Gibt an, ob in der Vektordatenbank ein nächster Nachbar für die angegebene Anfrage gefunden wurde und ob der Datenpunkt den Ähnlichkeitsschwellenwert erfüllt.
semanticcache.lookup.policy_name.cache_hit Gibt an, ob die Antwort im semantischen Cache gefunden wurde.
semanticcache.lookup.policy_name.cached_llm_response Enthält die aus dem semantischen Cache abgerufene Antwort (falls ein Cache-Treffer aufgetreten ist).

Fehlerreferenz

In diesem Abschnitt werden die Fehlercodes und Fehlermeldungen beschrieben, die zurückgegeben werden, und die Fehlervariablen, die von Apigee für die <SemanticCacheLookup>-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.semanticcache.lookup.MessageTemplateExtractionFailed 400 Daten konnten mit dem JSONPath-Ausdruck nicht aus der Anfrage extrahiert werden.
steps.semanticcache.lookup.FailedToExtractUserPrompt 500 Der Nutzer-Prompt konnte nicht aus der API-Anfrage extrahiert werden.
steps.semanticcache.lookup.EmbeddingsServiceUnavailable 400 Der Vertex AI Embeddings-Dienst ist derzeit nicht verfügbar.
steps.semanticcache.lookup.EmbeddingsAPIFailed 400 Der Vertex AI Embeddings-Dienst ist fehlgeschlagen.
steps.semanticcache.lookup.VectorSearchServiceUnavailable 400 Der Vertex AI-Vektorsuchdienst ist derzeit nicht verfügbar.
steps.semanticcache.lookup.VectorSearchAPIFailed 400 Der Vertex AI-Vektorsuchdienst ist fehlgeschlagen.
steps.semanticcache.lookup.AuthenticationFailure 500 Das Dienstkonto hat nicht die erforderlichen Berechtigungen.
steps.semanticcache.lookup.InternalError 500 In der SemanticCacheLookup-Richtlinie ist ein unerwarteter Fehler aufgetreten.
steps.semanticcache.lookup.CalloutError 500 Der Vertex AI-Dienstanruf ist fehlgeschlagen.

Bereitstellungsfehler

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

Fehlername Ursache
The Embeddings/VertexAI element is required. Tritt auf, wenn das Element <VertexAI> in <Embeddings> leer ist.
The SimilaritySearch/VertexAI element is required. Tritt auf, wenn das Element <VertexAI> in <SimilaritySearch> leer ist.
The Embeddings/URL element is required. Tritt auf, wenn das Element <URL> in <Embeddings> leer ist.
The SimilaritySearch/URL element is required. Tritt auf, wenn das Element <URL> in <SimilaritySearch> leer ist.
Embeddings URL {url} is invalid. Tritt auf, wenn das <URL>-Element in <Embeddings> leer oder ungültig ist.
The SimilaritySearch URL {url} is invalid. Tritt auf, wenn das Element <URL> in <SimilaritySearch> leer oder ungültig ist.
The scheme {http-scheme} of Embeddings URL {url} must be one of http, https. Tritt auf, wenn das http-Schema des Elements „Embeddings“ <URL> 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.
SimilaritySearch/Threshold element must be >= 0 and <= 1. Wenn das Attribut nicht zwischen 0 und 1 liegt, schlägt die Bereitstellung des API-Proxy fehl.
SimilaritySearch/DeployedIndexID element is required. Tritt auf, wenn das Element <DeployedIndexID> in <SimilaritySearch> leer ist.
SimilaritySearch/DeployedIndexID element must not contain spaces. Tritt auf, wenn das Element <DeployedIndexID> in <SimilaritySearch> Leerzeichen enthält.

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"
semanticcachelookup.POLICY_NAME.failed POLICY_NAME ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. semanticcachelookup.SC-lookup.failed = true

Beispiel für eine Fehlerantwort

{
  "fault": {
    "faultstring": "SemanticCacheLookup[SC-lookup]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.semanticcachelookup.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.