Se usó la API de Cloud Translation para traducir esta página.

Comienza a usar las políticas de almacenamiento en caché semántica

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

Consulta la documentación de Apigee Edge.

En esta página, se describe cómo configurar y usar las políticas de almacenamiento en caché semántico de Apigee para habilitar la reutilización inteligente de respuestas según la similitud semántica. Usar estas políticas en tu proxy de API de Apigee puede minimizar las llamadas redundantes a la API de backend, reducir la latencia y disminuir los costos operativos.

Antes de comenzar

Antes de comenzar, asegúrate de completar las siguientes tareas:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

Enable the APIs

Configura la API de Text embeddings y Vector Search de Vertex AI en tu proyecto Google Cloud .
Confirma que tienes un entorno Integral disponible en tu instancia de Apigee. Las políticas de almacenamiento en caché semántico solo se pueden implementar en entornos integrales.

Roles obligatorios

Para obtener los permisos que necesitas para crear y usar las políticas de almacenamiento en caché semántico, pídele a tu administrador que te otorgue el rol de IAM de 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 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.

Configure las variables de entorno

En el proyecto Google Cloud que contiene tu instancia de Apigee, usa el siguiente comando para configurar las variables de entorno:

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

Aquí:

PROJECT_ID es el ID del proyecto con tu instancia de Apigee.
REGION es la Google Cloud región de tu instancia de Apigee.
RUNTIME_HOSTNAME es el nombre de host de tu entorno de ejecución de Apigee.

Para confirmar que las variables de entorno estén configuradas correctamente, ejecuta el siguiente comando y revisa el resultado:

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Cómo establecer el proyecto

Configura el proyecto Google Cloud en tu entorno de desarrollo:

    gcloud auth login
    gcloud config set project $PROJECT_ID

Descripción general

Las políticas de almacenamiento en caché semántico están diseñadas para ayudar a los usuarios de Apigee con modelos de LLM a entregar de forma inteligente instrucciones idénticas o similares semánticamente de manera eficiente, lo que minimiza las llamadas a la API del backend y reduce el consumo de recursos.

Las políticas SemanticCacheLookup y SemanticCachePopulate se adjuntan a los flujos de solicitud y respuesta, respectivamente, de un proxy de API de Apigee. Cuando el proxy recibe una solicitud, la política de SemanticCacheLookup extrae la instrucción del usuario de la solicitud y la convierte en una representación numérica con la API de Text embeddings. Se realiza una búsqueda de similitud semántica con Vector Search para encontrar instrucciones similares. Si se encuentra un dato de instrucción similar, se realiza una búsqueda en la caché. Si se encuentran datos almacenados en caché, se devuelve la respuesta almacenada en caché al cliente.

Si la búsqueda de similitud no devuelve una instrucción anterior similar, el modelo de LLM genera contenido en respuesta a la instrucción del usuario y la caché de Apigee se completa con la respuesta. Se crea un bucle de retroalimentación para actualizar las entradas del índice de Vector Search en preparación para solicitudes futuras.

En las siguientes secciones, se describen los pasos necesarios para crear y configurar las políticas de almacenamiento en caché semántico:

Configura una cuenta de servicio para el índice de Vector Search.
Crea e implementa un índice de Vector Search.
Crea un proxy de API para habilitar el almacenamiento en caché semántico.
Configura las políticas de almacenamiento en caché semántico.
Prueba las políticas de almacenamiento en caché semántico.

Configura una cuenta de servicio para el índice de Vector Search

Para configurar una cuenta de servicio para el índice de Vector Search, completa los siguientes pasos:

Crea una cuenta de servicio con el siguiente comando:

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="SERVICE_ACCOUNT_DISPLAY_NAME"

Aquí:

SERVICE_ACCOUNT_NAME es el nombre de la cuenta de servicio.
DESCRIPTION es una descripción de la cuenta de servicio.
SERVICE_ACCOUNT_DISPLAY_NAME es el nombre visible de la cuenta de servicio.

Por ejemplo:

gcloud iam service-accounts create ai-client \
  --description="semantic cache client" \
  --display-name="ai-client"

Otorga a la cuenta de servicio el rol AI Platform User con el siguiente comando:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Aquí, SERVICE_ACCOUNT_NAME es el nombre de la cuenta de servicio que creaste en el paso anterior.

Asigna el rol de IAM Service Account User a la cuenta de servicio con el siguiente comando:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"

Aquí, SERVICE_ACCOUNT_NAME es el nombre de la cuenta de servicio que creaste en el paso anterior.

Compila e implementa un índice de Vector Search

Para crear e implementar un índice de Vector Search, haz lo siguiente:

Crea un índice de Vector Search que permita actualizaciones de transmisión:

ACCESS_TOKEN=$(gcloud auth print-access-token) && curl --location --request POST \
  "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    --header 'Content-Type: application/json' \
    --data-raw \
    '{
      "displayName": "semantic-cache-index",
      "description": "semantic-cache-index",
      "metadata": {
        "config": {
          "dimensions": "768",
          "approximateNeighborsCount": 150,
          "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
          "featureNormType": "NONE",
          "algorithmConfig": {
            "treeAhConfig": {
              "leafNodeEmbeddingCount": "10000",
              "fractionLeafNodesToSearch": 0.05
              }
            },
          "shardSize": "SHARD_SIZE_MEDIUM"
          },
        },
      "indexUpdateMethod": "STREAM_UPDATE"
    }'

La variable $REGION define la región en la que se implementa el índice de la Búsqueda de vectores. Te recomendamos que uses la misma región que tu instancia de Apigee. Esta variable de entorno se estableció en un paso anterior.

Cuando se complete esta operación, deberías ver una respuesta similar a la siguiente:

{
  "name": "projects/976063410430/locations/us-west1/indexes/5695338290484346880/operations/9084564741162008576",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexOperationMetadata",
    "genericMetadata": {
      "createTime": "2025-04-25T18:45:27.996136Z",
      "updateTime": "2025-04-25T18:45:27.996136Z"
    }
  }
}

Para obtener más información sobre cómo crear índices de Vector Search, consulta Crea un índice.

Crea un IndexEndpoint con el siguiente comando:

gcloud ai index-endpoints create \
  --display-name=semantic-cache-index-endpoint \
  --public-endpoint-enabled \
  --region=$REGION \
  --project=$PROJECT_ID

Este paso puede tardar varios minutos en completarse. Cuando se complete, deberías ver una respuesta similar a la siguiente:

Waiting for operation [8278420407862689792]...done.
  Created Vertex AI index endpoint: projects/976063410430/locations/us-west1/indexEndpoints/7953875911424606208.

Para obtener más información sobre cómo crear un IndexEndpoint, consulta Crea un IndexEndpoint.

Implementa el índice en el extremo con el siguiente comando:

INDEX_ENDPOINT_ID=$(gcloud ai index-endpoints list \
  --project=$PROJECT_ID \
  --region=$REGION \
  --format="json" | jq -c -r \
  '.[] | select(.displayName=="semantic-cache-index-endpoint") | .name | split("/") | .[5]' \
  ) && INDEX_ID=$(gcloud ai indexes list \
  --project=$PROJECT_ID \
  --region=$REGION \
  --format="json" | jq -c -r \
  '.[] | select(.displayName=="semantic-cache-index") | .name | split("/") | .[5]' \
  ) && gcloud ai index-endpoints deploy-index \
  $INDEX_ENDPOINT_ID \
  --deployed-index-id=semantic_cache \
  --display-name=semantic-cache \
  --index=$INDEX_ID \
  --region=$REGION \
  --project=$PROJECT_ID

Nota: El comando para implementar el índice en el extremo requiere jq. Si esta utilidad de procesamiento de JSON aún no está instalada en tu entorno de desarrollo, puedes instalarla con el siguiente comando: $ sudo apt install jq.

La implementación inicial de un índice en un extremo puede tardar entre 20 y 30 minutos en completarse. Para verificar el estado de la operación, usa el siguiente comando:

gcloud ai operations describe OPERATION_ID \
  --project=$PROJECT_ID \
  --region=$REGION

Confirma que se haya implementado el índice:

gcloud ai operations describe OPERATION_ID \
  --index-endpoint=$INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID

El comando debería devolver $ done: true.

Crea un proxy de API para habilitar el almacenamiento en caché semántico

En este paso, crearás un proxy de API nuevo con la plantilla Proxy with Semantic Cache, si aún no lo hiciste.

Antes de crear el proxy de API, configura la siguiente variable de entorno:

export PUBLIC_DOMAIN_NAME=$(gcloud ai index-endpoints describe $INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID | grep "publicEndpointDomainName" | awk '{print $2}')

Para crear un proxy para usar con el almacenamiento en caché semántico, haz lo siguiente:

Ve a la página Proxies de API en la consola de Google Cloud .
Ir a los proxies de API
Haz clic en + Crear para abrir el panel Crear proxy de API.
En el cuadro Plantilla de proxy, selecciona Proxy con caché semántica.
Ingresa los siguientes detalles:
- Nombre del proxy: Ingresa el nombre del proxy.
- Descripción: Ingresa una descripción del proxy (opcional).
- Destino (API existente): Ingresa la URL del servicio de backend al que llama el proxy. Este es el extremo del modelo LLM que se usa para generar contenido.
  En este instructivo, el destino (API existente) se puede establecer en lo siguiente:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent
```
Ingresa las siguientes URLs de la caché semántica:
Nota: Estas URLs también se pueden agregar a la configuración XML en el editor de proxy de la pestaña Desarrollar.
- URL de Generate Embeddings: Este servicio de Vertex AI convierte la entrada de texto en una forma numérica para el análisis semántico.
  En este instructivo, esta URL se puede configurar de la siguiente manera:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/text-embedding-004:predict
```
- URL de Query Nearest Neighbor: Este servicio de Vertex AI busca entradas de texto similares de solicitudes anteriores en el índice de Vector Search para evitar el reprocesamiento.
  En este instructivo, esta URL se puede configurar de la siguiente manera:
```
PUBLIC_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/REGION/indexEndpoints/INDEX_ENDPOINT_ID:findNeighbors
```
  Los valores PUBLIC_DOMAIN_NAME y INDEX_ENDPOINT_ID se configuraron en un paso anterior. Para obtener estos valores, puedes usar los siguientes comandos:
```
  echo $PUBLIC_DOMAIN_NAME
  echo $INDEX_ENDPOINT_ID
```
- URL de Upsert index: Este servicio de Vertex AI actualiza el índice con entradas nuevas o modificadas.
  En este instructivo, esta URL se puede configurar de la siguiente manera:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints
```
Haz clic en Siguiente.
Haz clic en Crear.

La configuración XML del proxy de API se puede ver en la pestaña Develop. Las políticas SemanticCacheLookup y SemanticCachePopulate que contienen valores predeterminados ya están adjuntas a los flujos de solicitud y respuesta del proxy.

Configura las políticas de almacenamiento en caché semántico

Para ver la configuración XML de cada política, haz clic en el nombre de la política en la vista Detail de la pestaña Develop del proxy de API. Las ediciones del XML de la política se pueden realizar directamente en la vista de código de la pestaña Desarrollar.

Edita las políticas:

Política SemanticCacheLookup:
- Quita el elemento <UserPromptSource> para usar el valor predeterminado.
- Actualiza el elemento <DeployedIndexId> para usar el valor semantic_cache.
- Configura el valor de similitud semántica <Threshold> para determinar cuándo se consideran coincidentes dos instrucciones. El valor predeterminado es 0.9, pero puedes ajustarlo según la sensibilidad de tu aplicación. Cuanto mayor sea el número, más estrechamente se deben relacionar las instrucciones para que se consideren un acierto de caché. Para este instructivo, te recomendamos que establezcas este valor en 0.95.
- Haz clic en Guardar.
Política SemanticCachePopulate:
- Establece el elemento <TTLInSeconds> para especificar la cantidad de segundos hasta que caduque la caché. El valor predeterminado es 60 s. Ten en cuenta que Apigee ignorará cualquier encabezado de cache-control que reciba del modelo de LLM.
- Haz clic en Guardar.

Agrega la autenticación de Google al proxy de API

También debes agregar la autenticación de Google al extremo de destino del proxy de API para habilitar las llamadas del proxy al destino.

Para agregar el token de acceso de Google, sigue estos pasos:

En la pestaña Develop, haz clic en default en la carpeta Target endpoints. La vista de código muestra la configuración XML del elemento <TargetEndpoint>.

Edita el XML para agregar la siguiente configuración en <HTTPTargetConnection>:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Haz clic en Guardar.

Implementa el proxy de API:

Para implementar el proxy de API, sigue estos pasos:

Haz clic en Implementar para abrir el panel Implementar proxy de API.
El campo Revisión debe establecerse en 1. De lo contrario, haz clic en 1 para seleccionarlo.
En la lista Entorno, selecciona el entorno en el que deseas implementar el proxy. El entorno debe ser integral.
Ingresa la cuenta de servicio que creaste en un paso anterior.
Haz clic en Implementar.

Prueba las políticas de almacenamiento en caché semántico

Para probar las políticas de almacenamiento en caché semántico, haz lo siguiente:

Envía una solicitud al proxy con el siguiente comando:

curl https://$RUNTIME_HOSTNAME/PROXY_NAME -H 'Content-Type: application/json' --data '{
  "contents": [
      {
          "role": "user",
          "parts": [
              {
                  "text": "Why is the sky blue?"
              }
          ]
      }
  ]
}'

Aquí, PROXY_NAME es la ruta base del proxy de API que implementaste en el paso anterior.

¿Por qué el cielo es azul?
¿Qué hace que el cielo sea azul?
¿Por qué el cielo es de color azul?
¿Puedes explicar por qué el cielo es azul?
¿Por qué el cielo es azul?

Compara el tiempo de respuesta de cada llamada una vez que se haya almacenado en caché una instrucción similar.

Para verificar que tus llamadas se publiquen desde la caché, revisa los encabezados de respuesta. Debería haber un encabezado Cached-Content: true adjunto.

Prácticas recomendadas

Te recomendamos que incorpores las siguientes prácticas recomendadas a tu programa de administración de APIs cuando uses las políticas de almacenamiento en caché semántico:

Evita el almacenamiento en caché de datos sensibles con Model Armor.
Para evitar el almacenamiento en caché de datos sensibles, te recomendamos que uses Model Armor para el filtrado de contenido. Model Armor puede marcar las respuestas como no aptas para el almacenamiento en caché si detecta información sensible. Para obtener más información, consulta la descripción general de Model Armor.
Administra la actualización de los datos con la invalidación de puntos de datos de Vertex AI y el tiempo de actividad (TTL).
Te recomendamos que implementes estrategias adecuadas de invalidación de puntos de datos para garantizar que las respuestas almacenadas en caché estén actualizadas y reflejen la información más reciente de tus sistemas de backend. Para obtener más información, consulta Actualiza y vuelve a compilar un índice activo.

También puedes ajustar el TTL de las respuestas almacenadas en caché según la volatilidad de los datos y la frecuencia de las actualizaciones. Para obtener más información sobre el uso de TTL en la política SemanticCachePopulate, consulta <TTLInSeconds>.
Usa estrategias de almacenamiento en caché predefinidas para garantizar los datos de respuesta más precisos.
Te recomendamos que implementes estrategias de almacenamiento en caché predefinidas similares a las siguientes:
- Respuestas genéricas de IA: Configura un TTL largo (por ejemplo, una hora) para las respuestas que no son específicas del usuario.
- Respuestas específicas del usuario: No implementes el almacenamiento en caché ni establezcas un TTL corto (por ejemplo, cinco minutos) para las respuestas que contengan información específica del usuario.
- Respuestas urgentes: Configura un TTL corto (por ejemplo, cinco minutos) para las respuestas que requieren actualizaciones frecuentes o en tiempo real.

Limitaciones

Se aplican las siguientes limitaciones a las políticas de almacenamiento en caché semántico:

El tamaño máximo de texto que se puede almacenar en caché es de 256 KB. Para obtener más información, consulta Tamaño del valor de caché en la página Límites de Apigee.
Apigee ignorará cualquier encabezado de control de caché que reciba del modelo de LLM.
Si la caché no se invalida correctamente o si el algoritmo de similitud semántica no es lo suficientemente preciso como para diferenciar entre entradas con significados muy similares, es posible que la respuesta devuelva información desactualizada o incorrecta.
La función de Vector Search no está disponible en todas las regiones. Para obtener una lista de las regiones compatibles, consulta la sección Disponibilidad de funciones de la página Ubicaciones de Vertex AI. Si tu organización de Apigee se encuentra en una región no admitida, deberás crear extremos de índice en una región diferente a la de tu organización de Apigee.
Las políticas de almacenamiento en caché semántico no se admiten para su uso con proxies de API que usan EventFlows para la transmisión continua de respuestas de eventos enviados por el servidor (SSE).
La función JsonPath dentro de <UserPromptSource> no admite la funcionalidad ignoreUnresolvedVariables. De forma predeterminada, los valores nulos o vacíos se ignoran durante la aplicación de la plantilla de mensajes.

¿Qué sigue?

Obtén más información para comenzar a usar las políticas de Model Armor.