Política SemanticCacheLookup

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Descripción general

La política SemanticCacheLookup es una política de almacenamiento en caché avanzada diseñada para optimizar el rendimiento de las cargas de trabajo de IA, en particular, aquellas que involucran modelos de lenguaje grandes (LLM).

La política usa la API de incorporaciones de texto de Vertex AI para generar incorporaciones de texto y la búsqueda de vectores para encontrar instrucciones similares en función de la similitud semántica, en lugar de coincidencias exactas.

La política SemanticCacheLookup puede reducir los tiempos de respuesta de las consultas repetidas y optimizar los costos, ya que reduce el volumen de llamadas a los LLM.

Esta política se usa junto con la política SemanticCachePopulate.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Antes de comenzar

Antes de usar la política SemanticCacheLookup, debes completar las siguientes tareas:

• Crea un proyecto de Vertex AI.
• Crea un índice de Vector Search.
• Crea un extremo de Vertex AI para el índice.
• Crea una política SemanticCachePopulate.

Para obtener más información sobre cómo completar estas tareas, consulta Cómo comenzar a usar las políticas de almacenamiento en caché semántica.

Roles obligatorios

Para obtener los permisos que necesitas para aplicar y usar la política SemanticCacheLookup, pídele a tu administrador que te otorgue el rol de IAM de usuario de la plataforma de IA (roles/aiplatform.user) en la cuenta de servicio que usas para implementar proxies de Apigee. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Habilita las APIs

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

Enable the APIs

Elemento <SemanticCacheLookup>

Define una política SemanticCacheLookup.

El elemento <SemanticCacheLookup> usa la siguiente sintaxis:

<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>

<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>

Este elemento tiene los siguientes atributos que son comunes a todas las políticas:

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <SemanticCacheLookup>:

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

Referencia del elemento secundario

En esta sección, se describen los elementos secundarios de <SemanticCacheLookup>.

<DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

El elemento <DisplayName> es común a todas las políticas.

El elemento <DisplayName> usa la siguiente sintaxis:

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

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

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

<IgnoreUnresolvedVariables>

Determina si el procesamiento se detiene cuando una variable no se resuelve. Configúralo como true para ignorar las variables sin resolver y continuar con el procesamiento.

IgnoreUnresolvedVariables no es aplicable cuando se proporciona <DefaultValue>.

<UserPromptSource>

Es la ubicación de la carga útil para que se extraiga el texto de la instrucción del usuario. Solo se admiten valores de texto de cadena.

Este campo admite la sintaxis de plantillas de mensajes de Apigee, incluido el uso de variables o funciones de ruta de acceso JSON.

Por ejemplo:

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

<Embeddings>

Este elemento contiene la información necesaria para generar incorporaciones de texto.

El elemento <Embeddings> usa la siguiente sintaxis:

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

<VertexAI> (secundario de <Embeddings>)

Contiene el elemento <URL> para los atributos específicos de Vertex AI.

El elemento VertexAI usa la siguiente sintaxis:

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

<URL> (secundario de <VertexAI>)

La URL que se usa para generar incorporaciones de texto. Consulta Modelos compatibles para obtener una lista de modelos que pueden proporcionar incorporaciones de texto para la política SemanticCacheLookup.

El elemento URL usa la siguiente sintaxis:

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

<SimilaritySearch>

Este elemento contiene la información necesaria para realizar búsquedas de similitud.

Para obtener más información, consulta Consulta un índice público para obtener los vecinos más cercanos.

El elemento <SimilaritySearch> usa la siguiente sintaxis:

<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> (secundario de <SimilaritySearch>)

Contiene el elemento <URL> para los atributos específicos de Vertex AI.

El elemento VertexAI usa la siguiente sintaxis:

<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>

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <VertexAI>.

Variables de flujo

Las variables de flujo se pueden usar para configurar el comportamiento del entorno de ejecución dinámico de las políticas y los flujos, según los encabezados HTTP, el contenido del mensaje, o el contexto disponible en el flujo. Para obtener más información sobre las variables de flujo, consulta Referencia de variables de flujo.

La política puede establecer estas variables de solo lectura durante la ejecución.

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee específicas para la política <SemanticCacheLookup>. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Lo que necesitas saber sobre los errores de políticas y Controla fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Variables con fallas

Estas variables se configuran cuando esta política activa un error en el entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Ejemplo de respuesta de error

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

Ejemplo de regla de falla

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

Esquemas

Un esquema XML (.xsd) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.