Política SemanticCachePopulate

Información general

La política SemanticCachePopulate 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 almacenar en caché las respuestas de la API en función de la similitud semántica, en lugar de las coincidencias exactas.

La política SemanticCachePopulate puede reducir los tiempos de respuesta de las consultas repetidas y optimizar los costes al reducir el volumen de llamadas a los LLMs.

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

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 SemanticCachePopulate, debes completar 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 y permisos

Para obtener los permisos que necesitas para aplicar y usar la política SemanticCachePopulate, 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.

Enable the APIs

Elemento <SemanticCachePopulate>

Define una política SemanticCachePopulate.

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

El elemento <SemanticCachePopulate> utiliza la siguiente sintaxis:

Sintaxis

El elemento <SemanticCachePopulate> utiliza la siguiente sintaxis:

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>{EXPIRATION_TIME_IN_SECONDS}</TTLInSeconds>
</SemanticCachePopulate>

Política predeterminada

En el siguiente ejemplo se muestran los ajustes predeterminados al añadir una política SemanticCachePopulate a un proxy de API en la interfaz de usuario de Apigee:

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>60</TTLInSeconds>
</SemanticCachePopulate>

Cuando insertas una nueva política SemanticCachePopulate 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 <SemanticCachePopulate>:

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 un conjunto de propiedades.
<SimilaritySearch> Obligatorio Elemento que contiene la información necesaria para actualizar el índice vectorial.

Para obtener más información, consulta Insertar o actualizar puntos de datos.

El tiempo de vencimiento de los puntos de datos es <TTLInSeconds> desde el momento de la entrada.

<TTLInSeconds> Opcional Tiempo de vida (TTL) de las respuestas almacenadas en caché, en segundos.

El valor predeterminado es 60.

Ejemplo

En esta sección se muestra un ejemplo con <SemanticCachePopulate>.

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>60</TTLInSeconds>
</SemanticCachePopulate>

Referencia de elemento secundario

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

<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 <SemanticCachePopulate>
Elementos secundarios Ninguno

<SimilaritySearch>

Elemento que contiene la información necesaria para actualizar el índice vectorial.

Para obtener más información, consulta Insertar o actualizar puntos de datos.

Los datos caducan <TTLInSeconds> después de introducirse.

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

El elemento <SimilaritySearch> utiliza la siguiente sintaxis:

<SimilaritySearch>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
  </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://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

<URL> (elemento secundario de <VertexAI>)

URL que se usa para insertar o actualizar puntos de datos en el índice vectorial.

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}/indexes/{INDEX_ID}:upsertDatapoints</URL>

<TTLInSeconds>

Elemento que especifica el tiempo de vida (TTL) de las respuestas almacenadas en caché, en segundos. El valor predeterminado es 60.

Para obtener más información, consulta Actualizar y volver a compilar un índice activo.

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

Variables de flujo

Las variables de flujo se pueden usar para configurar 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.

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

Nombre de variable Descripción
response.content Contiene el contenido completo de la respuesta de la API.
semanticcache.populate.policy_name.upsert_index_request Contiene la carga útil de la solicitud enviada a la API Vertex AI Vector Search para actualizar el índice de vectores con nuevas inserciones y metadatos.
semanticcache.populate.policy_name.upsert_index_response Contiene la respuesta de la API Vertex AI Vector Search, que indica si la operación de actualización del índice se ha realizado correctamente o no.

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 se definen en Apigee en relación con la política <SemanticCachePopulate>. Es importante conocer 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 pueden producirse cuando se ejecuta la política.

Código de fallo Estado de HTTP Causa
steps.semanticcachepopulate.VectorSearchUpsertServiceUnavailable 400

Este error se produce si la API Vector Search Upsert Datapoints no está disponible.
steps.semanticcache.populate.VectorSearchUpsertAPIFailed 500

Este error se produce si falla el servicio de la API Vector Search Upsert Datapoints.
steps.semanticcache.populate.AuthenticationFailure 500

Este error se produce si la cuenta de servicio no tiene los permisos necesarios.
steps.semanticcache.populate.CalloutError 500 No se ha podido llamar al servicio Vertex AI.
steps.semanticcache.populate.InternalError 500

Este error se produce si se da un error inesperado en la política de <SemanticCachePopulate>.

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga esta política.

Nombre del error Causa
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 SimilaritySearch URL {url} must be one of http, https. Se produce si el esquema http del elemento <URL> de SimilaritySearch no es válido.
The TTLInSeconds element must be >= 0. Si el valor es cero o un número negativo, no se podrá desplegar el proxy de API.

Variables de error

Estas variables se definen cuando esta política activa un error en 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"
semanticcachepopulate.POLICY_NAME.failed POLICY_NAME es el nombre de la política especificado por el usuario que ha provocado el error. semanticcachepopulate.SC-populate.failed = true

Ejemplo de respuesta de error

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

Regla de error 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.