Caché semántico con un extremo privado (Private Service Connect)

Esta página se aplica a Apigee, pero no a 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 basada en la similitud semántica. En este ejemplo, las políticas ejecutan su búsqueda de similitud en un índice de Vector Search que se implementa en un extremo privado (Private Service Connect). Usar estas políticas en tu proxy de API de Apigee minimiza las llamadas redundantes a la API de backend, reduce la latencia y disminuye los costos operativos.

Antes de comenzar

Antes de comenzar, completa las siguientes tareas:

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

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

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  4. Habilita y configura la API de Text embeddings de Vertex AI en tu proyecto de Google Cloud .
  5. Crea (o ten acceso a) un índice de Vector Search implementado en un extremo privado (Private Service Connect). En este instructivo, no se duplican los pasos de configuración de Vector Search. Consulta los requisitos previos del índice de la Búsqueda de vectores para conocer los requisitos específicos de SemanticCacheLookup y los vínculos a la documentación de Vector Search.
  6. Confirma que tienes un entorno intermedio o integral disponible en tu instancia de Apigee. Las políticas de almacenamiento en caché semántico solo se pueden implementar en entornos intermedios o integrales.
  7. Confirma que tienes un grupo de entornos con un nombre de host de tiempo de ejecución que puedes usar para enviar solicitudes a tu proxy de API.

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 a través de roles personalizados o cualquier otro rol predefinido.

Configura las variables de entorno

En el proyecto Google Cloud que contiene tu instancia de Apigee, usa el siguiente comando para establecer 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

Requisitos previos del índice de Vector Search

En este instructivo, se supone que ya tienes (o crearás) un índice de Vector Search implementado en un extremo privado (Private Service Connect). La creación, el formato y la implementación de un índice de Vector Search se documentan en las guías de Vector Search, por lo que este instructivo no duplica esos pasos. Sigue la documentación de Vector Search para hacer lo siguiente:

Cuando crees el índice, este debe cumplir con los siguientes requisitos específicos de SemanticCacheLookup:

  • El índice debe usar STREAM_UPDATE ("indexUpdateMethod": "STREAM_UPDATE") para que las llamadas upsertDatapoints de la política SemanticCachePopulate se puedan consultar casi en tiempo real.
  • El índice dimensions debe coincidir con la dimensionalidad de salida del modelo de embeddings que usas en la política SemanticCacheLookup. En este instructivo, se usa gemini-embedding-001, que produce incorporaciones de 3,072 dimensiones de forma predeterminada. Si truncas el resultado a una dimensionalidad inferior (por ejemplo, 768 o 1536), establece dimensions en el mismo valor.
  • Crea el índice con la medida de distancia (distanceMeasureType) que coincida con el <DistanceMeasureType> de tu política. El elemento <SimilaritySearch><VertexAI><DistanceMeasureType> en la política SemanticCacheLookup es opcional y, de forma predeterminada, se establece en DOT_PRODUCT_DISTANCE; también se admite COSINE_DISTANCE. La medida de distancia del índice y la política <DistanceMeasureType> deben ser las mismas.

En el siguiente ejemplo mínimo, se crea un índice compatible. Para ver el cuerpo completo de la solicitud y todas las opciones disponibles, consulta Crea y administra un índice:

ACCESS_TOKEN=$(gcloud auth print-access-token) && curl -X POST \
  "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "semantic-cache-index",
    "metadata": {
      "config": {
        "dimensions": 3072,
        "distanceMeasureType": "DOT_PRODUCT_DISTANCE"
      }
    },
    "indexUpdateMethod": "STREAM_UPDATE"
  }'

Ten en cuenta el INDEX_ID numérico que se devolvió en la respuesta. Lo usarás en la política SemanticCachePopulate. Después de crear el índice, crea un extremo del índice de Private Service Connect y, luego, implementa el índice en él.

Cuando crees el extremo del índice de Private Service Connect, este debe cumplir con los siguientes requisitos específicos de SemanticCacheLookup:

  • El projectAllowlist debe incluir el proyecto de Apigee que inicia la conexión:
    • Apigee: Usa el proyecto de usuario de Apigee. Obtén el ID del proyecto de usuario de la API de Organizations (campo apigeeProjectId).
    El projectAllowlist no se puede modificar después de que se crea el extremo del índice. Si incluyes en la lista de entidades permitidas el proyecto incorrecto, debes borrar y volver a crear el extremo del índice.

Ten en cuenta el INDEX_ENDPOINT_ID numérico del extremo del índice.

Configura la cuenta de servicio para el proxy de Apigee

El proxy de Apigee usa una cuenta de servicio para sus llamadas a la API de REST de Vertex AI: la API de Embeddings en la política SemanticCacheLookup, upsertDatapoints en la política SemanticCachePopulate y el destino del modelo. Otorga a esa cuenta de servicio el rol AI Platform User (roles/aiplatform.user):

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

Aquí, SERVICE_ACCOUNT es la dirección de correo electrónico de la cuenta de servicio que usa el proxy. Haces referencia a esta cuenta de servicio cuando implementas el proxy en el Paso 4: Importa e implementa el proxy de API.

Descripción general

Las políticas de almacenamiento en caché semántico ayudan a los usuarios de Apigee con modelos de LLM a entregar de forma inteligente instrucciones idénticas o semánticamente similares de manera eficiente, lo que minimiza las llamadas a la API de 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 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é, la respuesta almacenada en caché se devuelve al cliente.

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

En este caso, el índice de Vector Search se implementa en un extremo privado (Private Service Connect) a través de gRPC. Consulta más detalles sobre la compatibilidad de Private Service Connect de Vector Search en Cómo consultar índices de acceso privado a servicios o de Private Service Connect.

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

  1. Verifica tus recursos y obtén los valores que necesita Apigee.
  2. Conéctate al adjunto del servicio.
  3. Compila el paquete del proxy de API.
  4. Importa e implementa el proxy de API.
  5. Prueba las políticas de almacenamiento en caché semántico.

Paso 1: Verifica tus recursos y obtén los valores que necesita Apigee

Antes de configurar Apigee, confirma que tu extremo del índice de Vector Search esté habilitado para Private Service Connect y que tu índice esté implementado. Luego, lee los dos valores que consume el proxy de Apigee: la vinculación de servicio y DEPLOYED_INDEX_ID.

Confirma que el índice esté implementado y que el extremo exponga un adjunto de servicio de Private Service Connect:

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.privateEndpoints.serviceAttachment)"

El comando devuelve un nombre de recurso de adjunto de servicio con el formato projects/TENANT_PROJECT/regions/REGION/serviceAttachments/SERVICE_ATTACHMENT_NAME. En esta guía, se hace referencia a ese valor como SERVICE_ATTACHMENT. Si el comando devuelve un valor vacío, el índice aún no se implementó en un extremo de Private Service Connect. Regresa a Requisitos previos del índice de Vector Search y termina de implementar el índice antes de continuar.

Lee el DEPLOYED_INDEX_ID del índice implementado en el extremo:

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.id)"

En esta guía, se hace referencia a ese valor como DEPLOYED_INDEX_ID. La usarás en la política SemanticCacheLookup en el Paso 3: Compila el paquete del proxy de API.

Para obtener más información sobre cómo implementar y consultar extremos de índice privados, consulta Implementa un índice en un extremo de Private Service Connect y Consulta índices de acceso privado a servicios o de Private Service Connect.

Paso 2: Conéctate al adjunto de servicio

Este paso te proporciona el host privado al que llama el proxy de <GrpcEndpoint>. En Apigee, crea un adjunto de endpoint de Apigee. El adjunto de endpoint es el lado del consumidor de Private Service Connect de Apigee: se conecta al adjunto de servicio de Vector Search y te proporciona un host privado al que llama el proxy.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
        "location": "'"$REGION"'",
        "serviceAttachment": "SERVICE_ATTACHMENT"
      }' \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments?endpointAttachmentId=ENDPOINT_ATTACHMENT"

Consulta hasta que el state del adjunto sea ACTIVE y su connectionState sea ACCEPTED. Luego, toma nota del host: 

curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments/ENDPOINT_ATTACHMENT"

La respuesta contiene el host en el campo host. En esta guía, se hace referencia a ese valor como TARGET_HOST.

Para conectarte al adjunto de servicio de Vector Search desde tu proxy, puedes usar una de las siguientes opciones:

  • La dirección IP: Usa la dirección IP que se devolvió en el campo host directamente como TARGET_HOST (por ejemplo, 7.0.3.4).
  • Un registro DNS privado: Si configuraste una zona del DNS privada de Cloud DNS en tu Google Cloud proyecto con intercambio de tráfico de DNS a Apigee, puedes crear un registro A en tu zona privada que apunte a la dirección IP del adjunto de endpoint y usar ese nombre de dominio (como vectorsearch.example.com) como TARGET_HOST. Para obtener más información, consulta Usa un registro DNS y Conéctate con zonas de intercambio de tráfico de DNS privadas.

Paso 3: Compila el paquete del proxy de API

Crea el paquete del proxy

Crea el siguiente diseño de directorio: 

apiproxy/
├── PROXY_NAME.xml
├── proxies/default.xml
├── targets/default.xml
└── policies/
    ├── SCL-1.xml
    └── SCP-1.xml

policies/SCL-1.xml: La política SemanticCacheLookup El bloque <SimilaritySearch> usa <PrivateServiceConnect><GrpcEndpoint> (no <URL>).

Nota: Reglas de <GrpcEndpoint>:

  • El formato es grpc://TARGET_HOST:PORT y el esquema debe ser grpc://. grpcs:// (TLS) no se admite en esta versión.
  • El puerto es 10000 para Vector Search. Los extremos del plano de datos de Private Service Connect publican gRPC en el puerto 10000, por lo que el extremo siempre es grpc://TARGET_HOST:10000.
  • TARGET_HOST puede ser la dirección IP del adjunto de endpoint (del paso 2) o un registro DNS personalizado creado en tu zona de DNS privada.
  • El salto de gRPC es de texto sin formato y no está autenticado (está protegido por el aislamiento de la red).
<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-1">
  <DisplayName>SCL-1</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-embedding-001:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <PrivateServiceConnect>
        <GrpcEndpoint>grpc://TARGET_HOST:10000</GrpcEndpoint>
      </PrivateServiceConnect>
      <DeployedIndexID>DEPLOYED_INDEX_ID</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

policies/SCP-1.xml: Es la política SemanticCachePopulate. Populate es solo para REST y debe usar <URL> (rechaza <PrivateServiceConnect> en el momento de la implementación): 

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

targets/default.xml: Es el objetivo del modelo. El destino llama a una API de Google, por lo que necesita un token. <GoogleAccessToken> usa la cuenta de servicio de la implementación: 

<TargetEndpoint name="default">
  <PreFlow name="PreFlow"><Request/><Response/></PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

proxies/default.xml: Ejecuta la política SemanticCacheLookup en la solicitud y la política SemanticCachePopulate en la respuesta. 

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request><Step><Name>SCL-1</Name></Step></Request>
    <Response><Step><Name>SCP-1</Name></Step></Response>
  </PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPProxyConnection>
    <BasePath>/PROXY_NAME</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

PROXY_NAME.xml: Es el descriptor del paquete. 

<APIProxy name="PROXY_NAME">
  <BasePaths>/PROXY_NAME</BasePaths>
  <Policies><Policy>SCL-1</Policy><Policy>SCP-1</Policy></Policies>
  <ProxyEndpoints><ProxyEndpoint>default</ProxyEndpoint></ProxyEndpoints>
  <TargetEndpoints><TargetEndpoint>default</TargetEndpoint></TargetEndpoints>
</APIProxy>

Paso 4: Importa e implementa el proxy de API

Comprime el paquete, impórtalo para crear una revisión nueva y, luego, implementa la revisión con tu cuenta de servicio: 

TOKEN=$(gcloud auth print-access-token)
(cd BUNDLE_DIR && zip -r ../PROXY_NAME.zip apiproxy)
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -F "file=@PROXY_NAME.zip" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/apis?action=import&name=PROXY_NAME"
curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments?override=true&serviceAccount=SERVICE_ACCOUNT"

Aquí:

  • BUNDLE_DIR es el directorio que contiene la carpeta apiproxy/. El archivo debe contener la carpeta apiproxy/ en su raíz.
  • ENV es el entorno de Apigee en el que implementas el proxy. El entorno debe ser intermedio o integral.
  • REVISION es el número de revisión que devuelve la llamada de importación.
  • SERVICE_ACCOUNT es la dirección de correo electrónico de la cuenta de servicio que usas para implementar el proxy.

Espera hasta que la implementación informe READY: 

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments" | jq .state

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

Envía una instrucción nueva. Esto es un error de caché: se llama al modelo y se almacena en caché la respuesta. 

curl -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

Vuelve a enviar la misma instrucción. Se trata de un acierto de caché: la respuesta se entrega desde la caché y no se llama al modelo. 

curl -i -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

En el hit, la respuesta incluye el encabezado Cached-content: true, la misma respuesta y una latencia notablemente más baja.

También puedes verificar el almacenamiento en caché con una sesión de depuración. Cuando se produce un acierto, la política SemanticCacheLookup establece las siguientes variables de flujo:

Variable Valor en un hit
SemanticCacheLookup.SCL-1.dense_embeddings Es el vector de embedding de la instrucción.
SemanticCacheLookup.SCL-1.is_nearest_neighbor_hit true
SemanticCacheLookup.SCL-1.cache_hit true
SemanticCacheLookup.SCL-1.cached_llm_response Es la respuesta almacenada en caché.

Cuando se produce un acierto, no se invoca el destino del modelo, sino que el flujo se cortocircuita y devuelve la respuesta almacenada en caché.

Soluciona problemas

Para obtener la referencia completa de errores, consulta la política SemanticCacheLookup.

¿Qué sigue?