SemanticCacheLookup-Richtlinie

Erweiterbare Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

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

Die Richtlinie verwendet die Text-Einbettungen-API von Vertex AI, 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“ verkürzt die Antwortzeiten für wiederholte Abfragen und optimiert die Kosten, indem sie das Aufrufvolumen für LLMs reduziert.

Diese Richtlinie wird in Verbindung mit der Richtlinie „SemanticCachePopulate“ 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.

Hinweis

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 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 KI-Plattform-Nutzer (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

Aktivieren Sie die Compute Engine API, die Vertex AI API und die Cloud Storage API, falls sie noch nicht aktiviert sind.

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

APIs aktivieren

Element <SemanticCacheLookup>

Definiert eine SemanticCacheLookup-Richtlinie.

Standardwert Siehe Tab Standardrichtlinie 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>
      <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType>
    </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>
      <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType>
    </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 den Nutzer-Prompt 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, das die Informationen enthält, die zum Ausführen von Suchen nach Ähnlichkeiten 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. Legen Sie sie auf true fest, um nicht aufgelöste Variablen zu ignorieren und die Verarbeitung fortzusetzen.

IgnoreUnresolvedVariables ist nicht zutreffend, wenn <DefaultValue> angegeben ist.

Standardwert False
Erforderlich? Optional
Typ Boolescher Wert
Übergeordnetes Element <SemanticCacheLookup>
Untergeordnete Elemente Keine

<UserPromptSource>

Der Speicherort der Nutzlast, aus der der Text für den Nutzer-Prompt 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 Element <Embeddings> 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 Element VertexAI 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 Richtlinie „SemanticCacheLookup“ bereitstellen, finden Sie unter Unterstützte Modelle.

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

Das Element URL verwendet die folgende Syntax:

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

Das Element URL unterstützt die Verwendung von URL-Vorlagen. Optional können Sie in diesem Element eine Variable angeben, die den Wert der URL enthält, wie im folgenden Beispiel gezeigt: 

<URL>https://{URL_VARIABLE}</URL>

<SimilaritySearch>

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

Die Ähnlichkeitssuche kann für einen Vektorsuchindex ausgeführt werden, der entweder an einem öffentlichen oder an einem privaten (Private Service Connect) Endpunkt bereitgestellt wird. Sie müssen im <VertexAI>-Element genau einen der folgenden Transporte angeben:

  • <URL>: für einen öffentlichen Endpunkt über REST (:findNeighbors).
  • <PrivateServiceConnect>: für einen privaten Endpunkt über gRPC. Ein privater (Private Service Connect) bereitgestellter Indexendpunkt akzeptiert nur gRPC.

Weitere Informationen finden Sie unter Öffentlichen Index abfragen, um die nächsten Nachbarn abzurufen und Semantisches Caching mit einem privaten Endpunkt (Private Service Connect).

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

Das Element <SimilaritySearch> verwendet die folgende Syntax:

Öffentlicher Endpunkt (REST):

<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>
    <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType>
  </VertexAI>
</SimilaritySearch>

Privater Endpunkt (Private Service Connect, gRPC):

<SimilaritySearch>
  <VertexAI>
    <PrivateServiceConnect>
      <GrpcEndpoint>grpc://{TARGET_HOST}:10000</GrpcEndpoint>
    </PrivateServiceConnect>
    <Threshold>0.9</Threshold>
    <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
  </VertexAI>
</SimilaritySearch>

<VertexAI> (untergeordnetes Element von <SimilaritySearch>)

Enthält die Vertex AI-spezifischen Attribute, die für die Ähnlichkeitssuche verwendet werden. Geben Sie genau einen der folgenden Transporte an: ein <URL>-Element (für einen öffentlichen Endpunkt über REST) oder ein <PrivateServiceConnect>-Element (für einen privaten Endpunkt über gRPC).

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

Für einen öffentlichen Endpunkt verwendet das VertexAI-Element 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>
  <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType>
</VertexAI>

Für einen privaten Endpunkt (Private Service Connect) verwendet das Element VertexAI die folgende Syntax:

<VertexAI>
  <PrivateServiceConnect>
    <GrpcEndpoint>grpc://{TARGET_HOST}:10000</GrpcEndpoint>
  </PrivateServiceConnect>
  <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 (entweder <URL> oder <PrivateServiceConnect> angeben) String

Die URL, die für die Ähnlichkeitssuche in einem öffentlichen Vektorsuchindex-Endpunkt über REST (:findNeighbors) verwendet wird. Der Datenpunkt mit der höchsten Übereinstimmung basierend auf dem Ähnlichkeitsschwellenwert ist der einzige verwendete Datenpunkt.

Das Element URL unterstützt die Verwendung von URL-Vorlagen. Wenn Sie möchten, können Sie in diesem Element eine Variable angeben, die den Wert der URL enthält, wie im folgenden Beispiel gezeigt: 

<URL>https://{URL_VARIABLE}</URL>
<PrivateServiceConnect> Erforderlich (entweder <URL> oder <PrivateServiceConnect> angeben) Komplexes Objekt

Enthält die Verbindungsinformationen, die zum Ausführen von Ähnlichkeitssuchen in einem privaten Vektorsuchindex verwendet werden, der an einem Private Service Connect-Endpunkt bereitgestellt wird. Ein privater Endpunkt für bereitgestellte Indexe akzeptiert nur gRPC.

Dieses Element enthält ein einzelnes untergeordnetes Element, <GrpcEndpoint>:

<PrivateServiceConnect>
  <GrpcEndpoint>grpc://{TARGET_HOST}:10000</GrpcEndpoint>
</PrivateServiceConnect>

Das Element <GrpcEndpoint> gibt die gRPC-Adresse des privaten Endpunkts an. Es gelten die folgenden Regeln:

  • Das Format dafür ist grpc://TARGET_HOST:PORT. Das Schema muss grpc:// sein. grpcs:// (TLS) wird in dieser Version nicht unterstützt. TARGET_HOST ist entweder die IP-Adresse des Endpunktanhangs oder ein privater DNS-Eintrag in einer per Peering verbundenen Cloud DNS-Zone.
  • Der Port ist 10000 für die Datenebene-Endpunkte von Private Service Connect für die Vektorsuche.
  • Der gRPC-Hop ist unverschlüsselt und nicht authentifiziert. Er wird durch Netzwerkisolation geschützt.

Weitere Informationen finden Sie unter Semantisches Caching mit einem privaten Endpunkt (Private Service Connect).
<Threshold> Optional String

Der Wert, den ein nächster Nachbar erreichen muss, um als Übereinstimmung zu gelten. <DistanceMeasureType> legt die Richtung des Vergleichs fest.

Der Standardwert ist 0,9, was für DOT_PRODUCT_DISTANCE geeignet ist.

Weitere Informationen finden Sie unter Grenzwert für das Distanzmaß auswählen.
<DeployedIndexID> Erforderlich String

Die ID des Index, der für den semantischen Cache auf dem Indexendpunkt bereitgestellt wird.
<DistanceMeasureType> Optional String

Das Distanzmaß, mit dem Ihr Vertex AI-Vektorsuchindex erstellt wurde. Damit wird die Richtung des <Threshold>-Vergleichs festgelegt.

Gültige Werte sind DOT_PRODUCT_DISTANCE, COSINE_DISTANCE, SQUARED_L2_DISTANCE und L1_DISTANCE, die genau übereinstimmen müssen. Jeder andere Wert führt dazu, dass die Bereitstellung fehlschlägt. Informationen dazu, was die einzelnen Messwerte berechnen, finden Sie unter Parameter für die Indexkonfiguration.

Der Standardwert ist DOT_PRODUCT_DISTANCE.

Weitere Informationen finden Sie unter Grenzwert für die Entfernung festlegen.

Schwellenwert für die Distanzmessung auswählen

Das Maß, mit dem Ihr Index erstellt wurde, bestimmt die Richtung des <Threshold>-Vergleichs: Das Punktprodukt ist eine Ähnlichkeit, sodass ein größerer Wert eine bessere Übereinstimmung bedeutet, während die anderen drei Distanzen sind, bei denen ein kleinerer Wert eine bessere Übereinstimmung bedeutet. Stellen Sie <DistanceMeasureType> so ein, dass es mit Ihrem Index übereinstimmt, und passen Sie dann den Grenzwert für diese Messung an.

Distanzmessung Cache-Schwellenwert
DOT_PRODUCT_DISTANCE (Standard) value >= threshold
COSINE_DISTANCE value <= threshold
SQUARED_L2_DISTANCE value <= threshold
L1_DISTANCE value <= threshold

Führen Sie gcloud ai indexes describe INDEX_ID --region=REGION aus und lesen Sie das Feld distanceMeasureType, um den Messwert zu finden, mit dem Ihr Index erstellt wurde. Um zu bestätigen, dass die Richtlinie angewendet wurde, senden Sie dieselbe Anfrage zweimal und prüfen Sie semanticcache.lookup.policy_name.measure_type und semanticcache.lookup.policy_name.nearest_neighbor_measure in einer Debugging-Sitzung.

Ablaufvariablen

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

Diese Richtlinie stellt während der Ausführung die folgenden schreibgeschützten Ablaufvariablen bereit. Sie können diese Ablaufvariablen mit der Richtlinie „DataCapture“ verwenden, um benutzerdefinierte Analyseberichte zu erstellen. Weitere Informationen finden Sie unter Kundendaten mit der Data Capture-Richtlinie erfassen.

Variablenname Beschreibung
request.content Enthält den vollständigen Inhalt der eingehenden API-Anfrage.
request.url Enthält die URL der eingehenden API-Anfrage.
SemanticCacheLookup.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.
SemanticCacheLookup.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.
SemanticCacheLookup.policy_name.embeddings_response Enthält die Antwort der Vertex AI Embeddings API, einschließlich der generierten Texteinbettungen.
SemanticCacheLookup.policy_name.dense_embeddings Enthält die tatsächlichen numerischen Einbettungswerte, die von der Vertex AI Embeddings API generiert wurden.
SemanticCacheLookup.policy_name.is_nearest_neighbor_hit Gibt an, ob in der Vektordatenbank für die angegebene Anfrage ein nächster Nachbar gefunden wurde und ob der Datenpunkt den Ähnlichkeitsstufe erfüllt.
SemanticCacheLookup.policy_name.cache_hit Gibt an, ob die Antwort im semantischen Cache gefunden wurde.
SemanticCacheLookup.policy_name.cached_llm_response Enthält die aus dem semantischen Cache abgerufene Antwort (falls ein Cache-Treffer aufgetreten ist).
semanticcache.lookup.policy_name.nearest_neighbor_measure Enthält den Rohwert, den der Vektorsuchindex für den nächsten Nachbarn zurückgegeben hat. Wird sowohl bei Treffern als auch bei Fehlern festgelegt, wenn ein Nachbar zurückgegeben wurde.
semanticcache.lookup.policy_name.measure_type Enthält das von der Richtlinie angewendete Distanzmaß, einschließlich des Fallbacks auf den Standardwert. Wird sowohl bei Treffern als auch bei Nichterfolgen festgelegt, wenn ein Nachbar zurückgegeben wurde.

Fehlerreferenz

In diesem Abschnitt werden die Fehlercodes und Fehlermeldungen beschrieben, die von Apigee zurückgegeben werden, sowie 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 treten bei Ausführung der Richtlinie auf.

Fehlercode HTTP-Status Ursache
steps.semanticcache.lookup.MessageTemplateExtractionFailed 400 Daten konnten mit dem JSON-Pfadausdruck 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 Dienst „Vertex AI Vector Search“ 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 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. 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.
Embeddings/VertexAI cannot have both URL and PrivateServiceConnect elements. Tritt auf, wenn sowohl das Element <URL> als auch das Element <PrivateServiceConnect> in <Embeddings> angegeben sind.
SimilaritySearch/VertexAI cannot have both URL and PrivateServiceConnect elements. Tritt auf, wenn sowohl das Element <URL> als auch das Element <PrivateServiceConnect> in <SimilaritySearch> angegeben sind.
Embeddings/VertexAI/URL or Embeddings/PrivateServiceConnect/GrpcEndpoint element is required. Tritt auf, wenn weder das Element <URL> noch das Element <GrpcEndpoint> in <Embeddings> angegeben ist.
SimilaritySearch/VertexAI/URL or SimilaritySearch/PrivateServiceConnect/GrpcEndpoint element is required. Tritt auf, wenn weder das Element <URL> noch das Element <GrpcEndpoint> in <SimilaritySearch> angegeben ist.
The Embeddings/VertexAI/PrivateServiceConnect element is not supported. Use URL instead. Tritt auf, wenn das Element <PrivateServiceConnect> in <Embeddings> verwendet wird.
Embeddings URL {url} is invalid. Tritt auf, wenn das Element <URL> 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 <URL>-Elements für Einbettungen 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 SimilaritySearch /VertexAI/PrivateServiceConnect/GrpcEndpoint {grpc-endpoint} must be in the format "grpc://TARGET_HOST:PORT". Tritt auf, wenn das Element <GrpcEndpoint> in <SimilaritySearch> nicht das Format grpc://TARGET_HOST:PORT hat.
The scheme {grpc-scheme} of SimilaritySearch /VertexAI/PrivateServiceConnect/GrpcEndpoint {grpc-endpoint} must be "grpc". Tritt auf, wenn das grpc-Schema des SimilaritySearch-Elements <GrpcEndpoint> ungültig ist.
SimilaritySearch/Threshold element must not be NaN. Tritt auf, wenn das Element <Threshold> in <SimilaritySearch> NaN ist. Infinity und -Infinity sind zulässig.
Invalid DistanceMeasureType {value}. Supported values are DOT_PRODUCT_DISTANCE, COSINE_DISTANCE, SQUARED_L2_DISTANCE and L1_DISTANCE Tritt auf, wenn das Element <DistanceMeasureType> in <SimilaritySearch> nicht einer der vier unterstützten Werte ist. Die Übereinstimmung ist exakt. Siehe Indexkonfigurationsparameter.
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 Richtlinie legt diese Variablen fest, wenn sie zur Laufzeit einen Fehler auslöst. Weitere Informationen finden Sie unter Wissenswertes über Richtlinienfehler.

Variablen Definition Beispiel
fault.name="FAULT_NAME" FAULT_NAME ist der Name des Fehlers, wie in der obigen Tabelle Laufzeitfehler aufgeführt. 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 ausgegeben 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.