SemanticCacheLookup-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Übersicht

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

Bei der Richtlinie wird die Text-Einbettungs-API von Vertex AI verwendet, um Texteinbettungen zu generieren, und die Vektorsuche, um ähnliche Prompts basierend auf semantischer Ähnlichkeit statt auf genauen Übereinstimmungen zu finden.

Mit der Richtlinie „SemanticCacheLookup“ 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 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 Richtlinie „SemanticCacheLookup“ 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.

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 Richtlinie „SemanticCacheLookup“ 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 für den zu extrahierenden Prompttext. Es werden nur Stringwerte unterstützt.

Dieses Feld unterstützt die Syntax von Apigee-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 für Ähnlichkeitssuchen erforderlich sind.

Weitere Informationen finden Sie unter Öffentlichen Index abfragen, um den 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 ist nicht zulässig, wenn <DefaultValue> angegeben ist.

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

<UserPromptSource>

Der Speicherort der Nutzlast für den zu extrahierenden Prompttext. Es werden nur Stringwerte unterstützt.

Dieses Feld unterstützt die Syntax von Apigee-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 Text-Embeddings 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 Element <URL> 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. Unter Unterstützte Modelle finden Sie eine Liste der Modelle, die Text-Embeddings für die SemanticCacheLookup-Richtlinie bereitstellen können.

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 den 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 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://{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 Datenpunkt mit der höchsten Übereinstimmung, basierend auf dem Ähnlichkeitsgrenzwert, ist der einzige verwendete Datenpunkt.
<Threshold> Optional String

Ähnlichkeitsfaktor, mit dem bestimmt wird, ob zwei Prompts als übereinstimmend eingestuft werden. Ein Wert zwischen 0 und 1.

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

Die ID des Indexes, der auf dem Indexendpunkt bereitgestellt wird und für das semantische Caching verwendet 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 vollständigen 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 Prompt der Anfrage extrahiert wurden und zum Generieren von Einbettungen oder zum Ausführen von Ähnlichkeitssuchen verwendet werden.
semanticcache.lookup.policy_name.embeddings_request Enthält die Anfragenutzlast, 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 mit den 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 für die angegebene Anfrage ein nächster Nachbar gefunden wurde und der Datenpunkt den Ähnlichkeitsgrenzwert 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 Antwort, die aus dem semantischen Cache abgerufen wurde (falls ein Cache-Treffer aufgetreten ist).

Fehlerreferenz

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee speziell 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 Es konnte keine Daten mit dem JSONPath-Ausdruck aus der Anfrage extrahiert werden.
steps.semanticcache.lookup.FailedToExtractUserPrompt 500 Der Nutzerhinweis 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 Dienst „Vertex AI Vektorsuche“ ist fehlgeschlagen.
steps.semanticcache.lookup.AuthenticationFailure 500 Das Dienstkonto hat nicht die erforderlichen Berechtigungen.
steps.semanticcache.lookup.InternalError 500 In der Richtlinie „SemanticCacheLookup“ ist ein unerwarteter Fehler aufgetreten.
steps.semanticcache.lookup.CalloutError 500 Der Vertex AI-Dienstaufruf ist fehlgeschlagen.

Bereitstellungsfehler

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

Fehlername Ursache
The Embeddings/VertexAI element is required. Dieser Fehler 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. Dieser Fehler tritt auf, wenn das <URL>-Element in <Embeddings> leer ist.
The SimilaritySearch/URL element is required. Tritt auf, wenn das <URL>-Element in <SimilaritySearch> leer ist.
Embeddings URL {url} is invalid. Dieser Fehler tritt auf, wenn das Element <URL> in <Embeddings> leer oder ungültig ist.
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 Embeddings URL {url} must be one of http, https. Tritt auf, wenn das http-Schema des Embeddings-Elements <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 der Wert des Attributs 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.