Política SemanticCacheLookup

Esta página se aplica a Apigee, pero no a Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Informació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, especialmente las que implican modelos de lenguaje extensos (LLMs).

La política usa la API de inserciones de texto de Vertex AI para generar inserciones de texto y Vector Search para encontrar peticiones similares basadas en la similitud semántica, en lugar de en coincidencias exactas.

La política SemanticCacheLookup reduce los tiempos de respuesta de las consultas repetidas y optimiza los costes al reducir el volumen de llamadas a los LLMs.

Esta política funciona junto con la política SemanticCachePopulate.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Antes de empezar

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

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

Para obtener más información sobre cómo completar estas tareas, consulta el artículo Empezar a usar políticas de almacenamiento semántico en caché.

Roles obligatorios

Para obtener los permisos que necesitas para aplicar y usar la política SemanticCacheLookup, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Usuario de AI Platform (roles/aiplatform.user) en la cuenta de servicio que usas para implementar proxies de Apigee. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Habilitar APIs

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Elemento <SemanticCacheLookup>

Define una política SemanticCacheLookup.

Valor predeterminado Consulta la pestaña Política predeterminada que aparece más abajo.
¿Es obligatorio? Obligatorio
Tipo Objeto complejo
Elemento principal N/A
Elementos secundarios <DisplayName>
<IgnoreUnresolvedVariables>
<UserPromptSource>
<Embeddings>
<SimilaritySearch>

El elemento <SemanticCacheLookup> utiliza la siguiente sintaxis:

Sintaxis

El elemento <SemanticCacheLookup> utiliza 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>

Política predeterminada

En el siguiente ejemplo se muestran los ajustes predeterminados al añadir una política SemanticCacheLookup a tu flujo en la interfaz de usuario de Apigee:

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

Cuando insertas una política SemanticCacheLookup en la interfaz de usuario de Apigee, la plantilla contiene stubs para todas las operaciones posibles. Consulta la información sobre los elementos obligatorios más abajo.

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

Atributo Predeterminado ¿Es obligatorio? Descripción
name N/A Obligatorio

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.
continueOnError falso Opcional Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también:
enabled true Opcional Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.
async   falso Obsoleto Este atributo está obsoleto.

En la siguiente tabla se ofrece una descripción general de los elementos secundarios de <SemanticCacheLookup>:

Elemento secundario ¿Es obligatorio? Descripción
<DisplayName> Opcional El nombre de la política.
<IgnoreUnresolvedVariables> Opcional Determina si el procesamiento se detiene cuando no se resuelve una variable. Asigna el valor true para ignorar las variables sin resolver y continuar con el proceso.
<UserPromptSource> Opcional Ubicación de la carga útil del texto de la petición del usuario que se va a extraer. Solo se admiten valores de texto de cadena.

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

Por ejemplo: 

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

<Embeddings> Obligatorio Elemento que contiene la información necesaria para generar las inserciones.
<SimilaritySearch> Obligatorio Elemento que contiene la información necesaria para realizar búsquedas por similitud.

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

Referencia de elemento secundario

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

<DisplayName>

Se usa junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente que suene más natural.

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

Valor predeterminado N/A
¿Es obligatorio? Opcional. Si omite <DisplayName>, se usará el valor del atributo name de la política.
Tipo Cadena
Elemento principal <PolicyElement>
Elementos secundarios Ninguno

El elemento <DisplayName> utiliza la siguiente sintaxis:

Sintaxis

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

Ejemplo

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

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

<IgnoreUnresolvedVariables>

Determina si el procesamiento se detiene cuando no se resuelve una variable. Asigna el valor true para ignorar las variables sin resolver y continuar con el procesamiento.

IgnoreUnresolvedVariables no se aplica cuando se proporciona <DefaultValue>.

Valor predeterminado Falso
¿Es obligatorio? Opcional
Tipo Booleano
Elemento principal <SemanticCacheLookup>
Elementos secundarios Ninguno

<UserPromptSource>

Ubicación de la carga útil del texto de la petición del usuario que se va a extraer. Solo se admiten valores de texto de cadena.

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

Por ejemplo: 

{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}
Valor predeterminado {jsonPath('$.contents[-1].parts[-1].text',request.content,true)}
¿Es obligatorio? Opcional
Tipo Cadena
Elemento principal <SemanticCacheLookup>
Elementos secundarios Ninguno

<Embeddings>

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

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Cadena
Elemento principal <SemanticCacheLookup>
Elementos secundarios <VertexAI>

El elemento <Embeddings> utiliza 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> (subetiqueta de <Embeddings>)

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

Valor predeterminado N/A
¿Es obligatorio? Obligatorio
Tipo Cadena
Elemento principal <Embeddings>
Elementos secundarios <URL>

El elemento VertexAI utiliza 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> (elemento secundario de <VertexAI>)

URL usada para generar incrustaciones de texto. Consulta la lista de modelos admitidos que proporcionan inserciones de texto para la política SemanticCacheLookup.

Valor predeterminado N/A
¿Es obligatorio? Obligatorio
Tipo Cadena
Elemento principal <VertexAI>
Elementos secundarios Ninguno

El elemento URL utiliza la siguiente sintaxis:

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

El elemento URL admite el uso de plantillas de URL. Si quiere, puede proporcionar una variable en este elemento para almacenar el valor de la URL, como se muestra en el siguiente ejemplo: 

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

<SimilaritySearch>

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

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

Valor predeterminado N/A
¿Es obligatorio? Obligatorio
Tipo Cadena
Elemento principal <SemanticCacheLookup>
Elementos secundarios <VertexAI>

El elemento <SimilaritySearch> utiliza 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> (subetiqueta de <SimilaritySearch>)

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

Valor predeterminado N/A
¿Es obligatorio? Obligatorio
Tipo Cadena
Elemento principal <SimilaritySearch>
Elementos secundarios <URL>

El elemento VertexAI utiliza 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 ofrece una descripción general de los elementos secundarios de <VertexAI>.

Elemento secundario ¿Es obligatorio? Descripción
<URL> Obligatorio Cadena

La URL que se usa para realizar búsquedas de similitud. El punto de datos que mejor se ajusta, según el umbral de similitud, es el único que se utiliza.

El elemento URL admite el uso de plantillas de URL. Si quiere, puede proporcionar una variable en este elemento para almacenar el valor de la URL, como se muestra en el siguiente ejemplo: 

<URL>https://{URL_VARIABLE}</URL>
<Threshold> Opcional Cadena

Puntuación de similitud que se usa para determinar si dos peticiones se consideran una coincidencia. Un valor entre 0 y 1.

El valor predeterminado es 0,9.

Consulta

<DeployedIndexID> Obligatorio Cadena

ID del índice implementado en el endpoint de índice usado para el almacenamiento en caché semántico.

Variables de flujo

Las variables de flujo configuran el comportamiento dinámico del tiempo de ejecución de las políticas y los flujos en función de los encabezados HTTP, el contenido de los mensajes o el contexto disponible en el flujo. Para obtener más información sobre las variables de flujo, consulta la referencia de variables de flujo.

Esta política proporciona el siguiente conjunto de variables de flujo de solo lectura durante la ejecución. Puede usar estas variables de flujo con la política DataCapture para crear informes analíticos personalizados. Para obtener más información, consulta el artículo Recoger datos de clientes con la política DataCapture.

Nombre de variable Descripción
request.content Contiene el contenido completo de la solicitud de API entrante.
request.url Contiene la URL de la solicitud de API entrante.
semanticcache.lookup.policy_name.user_prompt Contiene componentes específicos extraídos de la petición, que se usa para generar inserciones o realizar búsquedas de similitud.
semanticcache.lookup.policy_name.embeddings_request Contiene la carga útil de la solicitud enviada a la API Embeddings de Vertex AI para generar las inserciones de texto del texto de entrada.
semanticcache.lookup.policy_name.embeddings_response Contiene la respuesta de la API Vertex AI Embeddings, que incluye las inserciones de texto generadas.
semanticcache.lookup.policy_name.dense_embeddings Contiene los valores de incrustación numéricos reales generados por la API Vertex AI Embeddings.
semanticcache.lookup.policy_name.is_nearest_neighbor_hit Especifica si se ha encontrado un vecino más cercano en la base de datos de vectores para la solicitud dada y si el punto de datos cumple el umbral de similitud.
semanticcache.lookup.policy_name.cache_hit Especifica si la respuesta se ha encontrado en la caché semántica.
semanticcache.lookup.policy_name.cached_llm_response Contiene la respuesta obtenida de la caché semántica (si se ha encontrado en la caché).

Referencia de errores

En esta sección se describen los códigos de error y los mensajes de error que devuelve Apigee, así como las variables de error que define Apigee, en relación con la política <SemanticCacheLookup>. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de política y Gestionar errores.

Errores de tiempo de ejecución

Estos errores se producen cuando se ejecuta la política.

Código de fallo Estado de HTTP Causa
steps.semanticcache.lookup.MessageTemplateExtractionFailed 400 No se han podido extraer datos de la solicitud mediante la expresión de ruta JSON.
steps.semanticcache.lookup.FailedToExtractUserPrompt 500 No se ha podido extraer la petición del usuario de la solicitud de la API.
steps.semanticcache.lookup.EmbeddingsServiceUnavailable 400 El servicio Vertex AI Embeddings no está disponible en este momento.
steps.semanticcache.lookup.EmbeddingsAPIFailed 400 Se ha producido un error en el servicio Vertex AI Embeddings.
steps.semanticcache.lookup.VectorSearchServiceUnavailable 400 El servicio Vertex AI Vector Search no está disponible en este momento.
steps.semanticcache.lookup.VectorSearchAPIFailed 400 El servicio Vertex AI Vector Search ha fallado.
steps.semanticcache.lookup.AuthenticationFailure 500 La cuenta de servicio no tiene los permisos necesarios.
steps.semanticcache.lookup.InternalError 500 Se ha producido un error inesperado en la política SemanticCacheLookup.
steps.semanticcache.lookup.CalloutError 500 No se ha podido llamar al servicio Vertex AI.

Errores de implementación

Estos errores se producen cuando implementas un proxy que contiene esta política.

Nombre del error Causa
The Embeddings/VertexAI element is required. Se produce si el elemento <VertexAI> de <Embeddings> está vacío.
The SimilaritySearch/VertexAI element is required. Se produce si el elemento <VertexAI> de <SimilaritySearch> está vacío.
The Embeddings/URL element is required. Se produce si el elemento <URL> de <Embeddings> está vacío.
The SimilaritySearch/URL element is required. Se produce si el elemento <URL> de <SimilaritySearch> está vacío.
Embeddings URL {url} is invalid. Se produce si el elemento <URL> de <Embeddings> está vacío o no es válido.
The SimilaritySearch URL {url} is invalid. Se produce si el elemento <URL> de <SimilaritySearch> está vacío o no es válido.
The scheme {http-scheme} of Embeddings URL {url} must be one of http, https. Se produce si el esquema http del elemento <URL> de Embeddings no es válido.
The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https. Se produce si el esquema http del elemento <URL> de SimilaritySearch no es válido.
SimilaritySearch/Threshold element must be >= 0 and <= 1. Si el atributo no está entre 0 y 1, se produce un error al implementar el proxy de API.
SimilaritySearch/DeployedIndexID element is required. Se produce si el elemento <DeployedIndexID> de <SimilaritySearch> está vacío.
SimilaritySearch/DeployedIndexID element must not contain spaces. Se produce si el elemento <DeployedIndexID> de <SimilaritySearch> contiene espacios.

Variables de error

Esta política define estas variables cuando se produce un error durante el tiempo de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de las políticas.

Variables Dónde Ejemplo
fault.name="FAULT_NAME" FAULT_NAME es el nombre del fallo, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error. fault.name Matches "UnresolvedVariable"
semanticcachelookup.POLICY_NAME.failed POLICY_NAME es el nombre de la política especificado por el usuario que ha provocado el error. semanticcachelookup.SC-lookup.failed = true

Ejemplo de respuesta de error

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

Regla de fallo de ejemplo

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

Esquemas

Cada tipo de política se define mediante un esquema XML (.xsd). Puedes consultar los esquemas de políticas en GitHub.