Política SemanticCachePopulate

Descripció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, en particular, las 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 vectorial 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 costos, ya que reduce el volumen de llamadas a los LLM.

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

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 SemanticCachePopulate, 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.

Funciones y permisos

Para obtener los permisos que necesitas para aplicar y usar la política SemanticCachePopulate, pídele a tu administrador que te otorgue el rol de IAM 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 <SemanticCachePopulate>

Define una política SemanticCachePopulate.

Valor predeterminado Consulta la pestaña Política predeterminada, a continuación
¿Es obligatorio? Obligatorio
Tipo Objeto complejo
Elemento principal N/A
Elementos secundarios <DisplayName>
<IgnoreUnresolvedVariables>
<SimilaritySearch>
<TTLInSeconds>

El elemento <SemanticCachePopulate> usa la siguiente sintaxis:

Sintaxis

El elemento <SemanticCachePopulate> usa 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 muestra la configuración predeterminada cuando agregas una política SemanticCachePopulate a tu proxy de API en la IU 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 IU de Apigee, la plantilla contiene stubs para todas las operaciones posibles. Consulta la información que aparece a continuación sobre los elementos obligatorios.

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

Atributo Predeterminada (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.

De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.
continueOnError falso Opcional Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta:
enabled true Opcional Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará, incluso si permanece conectada a un flujo.
async   falso Obsoleta Este atributo dejó de estar disponible.

En la siguiente tabla, se proporciona una descripción de alto nivel 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 un conjunto de propiedades no se resuelve.
<SimilaritySearch> Obligatorio Es un elemento que contiene la información necesaria para actualizar el índice vectorial.

Para obtener más información, consulta Cómo insertar y actualizar datos.

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

<TTLInSeconds> Opcional Es el tiempo de actividad (TTL) de las respuestas almacenadas en caché, en segundos.

El valor predeterminado es 60.

Ejemplo

En esta sección, se proporciona un ejemplo del uso de <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 del elemento secundario

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

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

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

El elemento <DisplayName> usa 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 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>.

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

<SimilaritySearch>

Es un elemento que contiene la información necesaria para actualizar el índice vectorial.

Para obtener más información, consulta Cómo insertar y actualizar datos.

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

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

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

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

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

El elemento VertexAI usa la siguiente sintaxis:

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

<URL> (secundario de <VertexAI>)

Es la URL que se usa para actualizar o insertar datos en el índice vectorial.

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

El elemento URL usa la siguiente sintaxis:

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>

<TTLInSeconds>

Es un elemento que especifica el tiempo de actividad (TTL) de las respuestas almacenadas en caché, en segundos. El valor predeterminado es 60.

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

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

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.

Nombre de la 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 que se envía a la API de Vertex AI Vector Search para actualizar el índice de vectores con incorporaciones y metadatos nuevos.
semanticcache.populate.policy_name.upsert_index_response Contiene la respuesta de la API de Vector Search de Vertex AI, que indica si la operación de actualización del índice se realizó correctamente o no.

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

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

Este error se produce si la API de Upsert Datapoints de la Búsqueda vectorial no está disponible.
steps.semanticcache.populate.VectorSearchUpsertAPIFailed 500

Este error se produce si falla el servicio de la API de Upsert Datapoints de la Búsqueda vectorial.
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 pudo realizar la llamada al servicio de Vertex AI.
steps.semanticcache.populate.InternalError 500

Este error se produce en caso de que se produzca un error inesperado en la política <SemanticCachePopulate>.

Errores en la implementación

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

Nombre del error Causa
The SimilaritySearch URL {url} is invalid. Ocurre si el elemento <URL> en <SimilaritySearch> está vacío o no es válido.
The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https. Ocurre si el esquema http del elemento SimilaritySearch <URL> no es válido.
The TTLInSeconds element must be >= 0. Si el valor se establece en cero o en un número negativo, la implementación del proxy de API falla.

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.

Variables Donde Ejemplo
fault.name="FAULT_NAME" FAULT_NAME es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. fault.name Matches "UnresolvedVariable"
semanticcachepopulate.POLICY_NAME.failed POLICY_NAME es el nombre especificado por el usuario de la política que generó la falla. 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"
  }
}
}

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.