Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Crea una puerta de enlace de IA con enrutamiento, Model Armor y caché semántica

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

Consulta la documentación de Apigee Edge.

En este instructivo, se muestra cómo configurar y usar Apigee como una puerta de enlace de IA que enruta solicitudes de modelos de lenguaje grandes (LLMs) a diferentes modelos de backend según reglas de enrutamiento flexibles basadas en políticas. Una puerta de enlace de IA te ayuda a proteger, administrar y optimizar el tráfico de tus modelos para controlar los costos y evitar la proliferación de modelos.

Cada etapa del instructivo se basa en la configuración anterior y agrega una capacidad específica a través de archivos de plantillas de funciones de Apigee (AFT) reutilizables:

Etapa 1: Implementa un proxy de API mínimo que esté frente a un solo proveedor de LLM.
Etapa 2: Agrega la limpieza de instrucciones y respuestas de Model Armor para filtrar las entradas maliciosas y evitar la filtración de datos sensibles.
Etapa 3: Agrega el enrutamiento a modelos entre proveedores y una caché semántica respaldada por la búsqueda de vectores de Agent Platform.
Etapa 4: Configura el resguardo entre proveedores para volver a intentar automáticamente las solicitudes con un proveedor secundario si el destino principal devuelve un código de estado HTTP 4xx o 5xx.

Para agregar una capacidad, agrega una sola línea al bloque features de tu plantilla. Para ver o descargar el conjunto completo de archivos de ejemplo, incluidos los archivos de AFT y las secuencias de comandos auxiliares, consulta el repositorio de plantillas de Apigee en GitHub.

Antes de comenzar

Antes de completar este instructivo, asegúrate de tener lo siguiente:

Un proyecto de Google Cloud activo con la facturación habilitada
Un entorno integral disponible en tu instancia de Apigee. Solo puedes implementar las políticas de Model Armor, SemanticCacheLookup y SemanticCachePopulate en entornos integrales.
Google Cloud CLI (gcloud) instalada y configurada con las credenciales predeterminadas de la aplicación (ADC). Para generar credenciales, ejecuta gcloud auth application-default login.
Una cuenta de servicio de tiempo de ejecución con los siguientes roles de IAM:
- roles/aiplatform.user
- roles/modelarmor.user
La cuenta de servicio también necesita acceso a las credenciales específicas del proveedor.
Para las etapas 2, 3 y 4, especifica una ruta de acceso al recurso de la plantilla de Model Armor. Por ejemplo, projects/YOUR_PROJECT/locations/us-central1/templates/apigee-aft-demo-ma.
Para las etapas 3 y 4: Un mapa de pares clave-valor (KVM) de Apigee llamado openai-credentials en tu entorno que contiene una entrada api-key con una clave de API de OpenAI válida.
Para las etapas 3 y 4: Un extremo de índice de Vector Search de Vertex AI implementado para la caché semántica. Para obtener instrucciones paso a paso sobre la configuración del índice, consulta el archivo README del repositorio de plantillas de Apigee en GitHub.

Descripción general

Las cuatro etapas aceptan la forma de solicitud de Chat Completions de OpenAI en /v1/chat/completions[-stageN], por lo que los mismos SDKs del cliente funcionan en todas las etapas. El prefijo del campo model impulsa la decisión de enrutamiento: las solicitudes de modelos google/* se enrutan a Gemini en Agent Platform, y todas las demás solicitudes se enrutan a OpenAI. Este valor predeterminado invertido garantiza que las nuevas familias de modelos de OpenAI, como o1-*, o3-* y chatgpt-*, se enruten correctamente en lugar de omitir de forma silenciosa una coincidencia de prefijo gpt-*.

Etapa	Se agregó la capacidad	Ruta de acceso base
1	Hello LLM (solicitud en formato de OpenAI a Gemini en Agent Platform)	`/v1/chat/completions`
2	Model Armor (inyección de instrucciones, IA responsable y filtros de Sensitive Data Protection)	`/v1/chat/completions-stage2`
3	Enrutamiento entre proveedores y una caché semántica de Vector Search de Agent Platform	`/v1/chat/completions-stage3`
4	Resguardo entre proveedores (la puerta de enlace de IA completa)	`/v1/chat/completions-stage4`

Etapa 1: Hello LLM

El proxy mínimo se encuentra frente a un único destino de Gemini a través de su extremo compatible con OpenAI. Dos archivos de funciones pequeños proporcionan el esqueleto del proxy base y un extractor de JSON. El extractor copia $.model y $.messages[-1].content en las variables de flujo llm.model y llm.prompt para que las etapas posteriores tengan entradas coherentes.

llm-base.yaml define el esqueleto del proxy base:

gateway: apigee
schemaVersion: 1.0.0
name: llm-base
type: feature
parameters:
  - name: BASE_PATH
    default: /v1/chat/completions
endpoints:
  - name: default
    basePath: "{BASE_PATH}"
    routes:
      - name: primary
        target: gemini-target

llm-openai-format.yaml extrae los campos de solicitud con formato de OpenAI:

gateway: apigee
schemaVersion: 1.0.0
name: llm-openai-format
type: feature
defaultEndpoint:
  name: default
  flows:
    - name: PreFlow
      mode: Request
      steps:
        - name: EV-ExtractOpenAIRequest
policies:
  - name: EV-ExtractOpenAIRequest
    type: ExtractVariables
    content:
      ExtractVariables:
        metadata:
          name: EV-ExtractOpenAIRequest
          continueOnError: "true"
        Source:
          _text: request
        JSONPayload:
          Variable:
            - metadata:
                name: model
              JSONPath:
                _text: "$.model"
            - metadata:
                name: prompt
              JSONPath:
                _text: "$.messages[-1].content"
        VariablePrefix:
          _text: llm

target-vertex-gemini.yaml define un destino de Agent Platform que usa el extremo compatible con OpenAI:

gateway: apigee
schemaVersion: 1.0.0
name: target-vertex-gemini
type: feature
targets:
  - name: gemini-target
    httpTargetConnection:
      URL: https://aiplatform.googleapis.com/v1/projects/{organization.name}/locations/global/endpoints/openapi/chat/completions
      Authentication:
        GoogleAccessToken:
          Scopes:
            Scope: https://www.googleapis.com/auth/cloud-platform

Redacta los archivos de atributos en la plantilla de la etapa 1, 01-hello-llm.yaml:

gateway: apigee
schemaVersion: 1.0.0
name: aft-demo-01-hello-llm
features:
  - llm-base.yaml
  - llm-openai-format.yaml
  - target-vertex-gemini.yaml

Implementa la plantilla:

gcloud beta apigee apis import aft-demo-01-hello-llm \
  --from-template=01-hello-llm.yaml \
  --organization=APIGEE_ORG

Prueba el proxy:

curl -X POST https://APIGEE_HOSTNAME/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-2.5-flash",
       "messages":[{"role":"user","content":"Explain how AI works in a few words"}]}'

Reemplaza lo siguiente:

APIGEE_ORG: Es el nombre de tu organización de Apigee.
APIGEE_HOSTNAME: Es el nombre de host de tu grupo de entornos de Apigee, que suele ser un Google Cloud balanceador de cargas.

Etapa 2: Agrega Model Armor

Model Armor inspecciona la instrucción entrante en busca de inyección de instrucciones, contenido prohibido y datos sensibles antes de la llamada de destino. Luego, analiza la respuesta del modelo antes de que llegue al cliente.

Agrega un archivo de funciones a la plantilla, llm-model-armor.yaml:

gateway: apigee
schemaVersion: 1.0.0
name: llm-model-armor
type: feature
parameters:
  - name: MA_TEMPLATE_PATH
    default: projects/{organization.name}/locations/us-central1/templates/apigee-aft-demo-ma
defaultEndpoint:
  name: default
  flows:
    - name: PreFlow
      mode: Request
      steps:
        - name: MA-SanitizeUserPrompt
    - name: PostFlow
      mode: Response
      steps:
        - name: MA-SanitizeModelResponse
policies:
  - name: MA-SanitizeUserPrompt
    type: SanitizeUserPrompt
    content:
      SanitizeUserPrompt:
        metadata:
          name: MA-SanitizeUserPrompt
        ModelArmor:
          TemplateName:
            _text: "{MA_TEMPLATE_PATH}"
        UserPromptSource:
          _text: "{llm.prompt}"
  - name: MA-SanitizeModelResponse
    type: SanitizeModelResponse
    content:
      SanitizeModelResponse:
        metadata:
          name: MA-SanitizeModelResponse
        ModelArmor:
          TemplateName:
            _text: "{MA_TEMPLATE_PATH}"
        UserPromptSource:
          _text: "{llm.prompt}"
        LLMResponseSource:
          _text: "{jsonPath('$.choices[-1].message.content',response.content,true)}"

La plantilla de la etapa 2, 02-add-model-armor.yaml, agrega una línea:

gateway: apigee
schemaVersion: 1.0.0
name: aft-demo-02-add-model-armor
features:
  - llm-base.yaml
  - llm-openai-format.yaml
  - target-vertex-gemini.yaml
  - llm-model-armor.yaml           # <-- the change from Stage 1
parameters:
  - name: BASE_PATH
    default: /v1/chat/completions-stage2

El parámetro MA_TEMPLATE_PATH se establece de forma predeterminada en una plantilla llamada apigee-aft-demo-ma en us-central1. Para usar tu propia plantilla de Model Armor, anula el parámetro en el bloque parameters de la plantilla.

Etapa 3: Agrega enrutamiento entre proveedores y almacenamiento en caché semántico

En la etapa 3, agregarás un segundo destino (OpenAI), reemplazarás la regla de enrutamiento única por el enrutamiento basado en modelos y configurarás una caché semántica respaldada por Vector Search de Agent Platform frente a ambos destinos.

Para configurar la etapa 3, agrega tres archivos de funciones al bloque features de tu plantilla:

target-openai-gpt.yaml: Agrega OpenAI como un extremo de destino secundario.
llm-routing.yaml: Enruta las solicitudes de forma dinámica según el nombre del modelo solicitado.
llm-semantic-cache.yaml: Agrega una caché semántica delante de ambos proveedores.

En el siguiente ejemplo, se muestra cómo el archivo de funciones llm-routing.yaml define la lógica de enrutamiento:

gateway: apigee
schemaVersion: 1.0.0
name: llm-routing
type: feature
parameters:
  - name: BASE_PATH
    default: /v1/chat/completions
endpoints:
  - name: default
    basePath: "{BASE_PATH}"
    routes:
      - name: gemini
        condition: llm.model StartsWith "google/"
        target: gemini-target
      - name: openai
        target: openai-target      # default when the condition is false

La caché semántica ejecuta SemanticCacheLookup en el PreFlow de la solicitud y SemanticCachePopulate en el PostFlow de la respuesta, solo en los errores de caché. Ambas políticas usan un extremo del índice de Vector Search de Agent Platform que aprovisionas por separado. En el siguiente extracto, se muestran las partes clave de las definiciones de políticas:

policies:
  - name: SCLLookup
    type: SemanticCacheLookup
    content:
      SemanticCacheLookup:
        UserPromptSource:
          _text: "{llm.prompt}"
        Embeddings:
          VertexAI:
            URL:
              _text: "https://{EMBEDDINGS_LOCATION}-aiplatform.googleapis.com/v1/projects/{organization.name}/locations/{EMBEDDINGS_LOCATION}/publishers/google/models/{EMBEDDINGS_MODEL}:predict"
        SimilaritySearch:
          VertexAI:
            URL:
              _text: "https://{VECTOR_INDEX_ENDPOINT_SUBDOMAIN}.{EMBEDDINGS_LOCATION}-{PROJECT_NUMBER}.vdb.vertexai.goog/v1/projects/{organization.name}/locations/{EMBEDDINGS_LOCATION}/indexEndpoints/{VECTOR_INDEX_ENDPOINT_ID}:findNeighbors"
            DeployedIndexID:
              _text: "{DEPLOYED_INDEX_ID}"
            Threshold:
              _text: "{THRESHOLD}"
  - name: SCPPopulate
    type: SemanticCachePopulate
    # ... (see the GitHub repository for the full definition)

La plantilla de la etapa 3 compone todos los archivos de funciones:

gateway: apigee
schemaVersion: 1.0.0
name: aft-demo-03-add-routing-and-cache
features:
  - llm-base.yaml
  - llm-openai-format.yaml
  - target-vertex-gemini.yaml
  - llm-model-armor.yaml
  - target-openai-gpt.yaml         # <-- add OpenAI target
  - llm-routing.yaml               # <-- add model-name routing
  - llm-semantic-cache.yaml        # <-- add semantic cache
parameters:
  - name: BASE_PATH
    default: /v1/chat/completions-stage3
  - name: VECTOR_INDEX_ENDPOINT_ID
    default: "YOUR_INDEX_ENDPOINT_ID"
  - name: VECTOR_INDEX_ID
    default: "YOUR_INDEX_ID"
  - name: VECTOR_INDEX_ENDPOINT_SUBDOMAIN
    default: "YOUR_SUBDOMAIN"
  - name: PROJECT_NUMBER
    default: "YOUR_PROJECT_NUMBER"
  - name: DEPLOYED_INDEX_ID
    default: "YOUR_DEPLOYED_INDEX_ID"

Implementa la plantilla con el mismo comando gcloud beta apigee apis import con la marca --from-template que usaste en la etapa 1.

Etapa 4: Agrega un resguardo entre proveedores

En la etapa 4, se adjunta un DefaultFaultRule a ambos destinos. Cuando el destino principal devuelve cualquier estado 4xx o 5xx, la regla de error envía un ServiceCallout con la misma instrucción al otro proveedor y devuelve esa respuesta al cliente. El cliente recibe una respuesta 200 exitosa con una finalización normal y no necesita su propia lógica de reintento ni manejo de errores.

El archivo de funciones llm-fallback.yaml agrega este comportamiento. El siguiente ejemplo está abreviado. Para ver el archivo completo, consulta el repositorio de GitHub.

gateway: apigee
schemaVersion: 1.0.0
name: llm-fallback
type: feature
targets:
  # Vertex primary; on 4xx/5xx, fall back to OpenAI.
  - name: gemini-target
    httpTargetConnection:
      Properties:
        Property:
          metadata:
            name: success.codes
          _text: "2XX"
      URL: https://aiplatform.googleapis.com/v1/projects/{organization.name}/locations/global/endpoints/openapi/chat/completions
      Authentication:
        GoogleAccessToken:
          Scopes:
            Scope: https://www.googleapis.com/auth/cloud-platform
    flows:
      - name: PostFlow
        mode: Response
        steps:
          - name: RF-TargetErrorToFault
            condition: response.status.code >= 400
    defaultFaultRule:
      name: FallbackToOpenAI
      steps:
        - name: KVM-GetOpenAIKey
        - name: AM-BuildOpenAIFallbackRequest
        - name: SC-FallbackToOpenAI
        - name: AM-CopyOpenAIFallbackResponse
  # OpenAI primary; on 4xx/5xx, fall back to Vertex.
  - name: openai-target
    httpTargetConnection:
      Properties:
        Property:
          metadata:
            name: success.codes
          _text: "2XX"
      URL: https://api.openai.com/v1/chat/completions
    flows:
      - name: PreFlow
        mode: Request
        steps:
          - name: JS-StripOpenAIModelPrefix
          - name: KVM-GetOpenAIKey
          - name: AM-SetOpenAIAuth
      - name: PostFlow
        mode: Response
        steps:
          - name: RF-TargetErrorToFault
            condition: response.status.code >= 400
    defaultFaultRule:
      name: FallbackToVertex
      steps:
        - name: AM-BuildVertexFallbackRequest
        - name: SC-FallbackToVertex
        - name: AM-CopyVertexFallbackResponse
policies:
  # RaiseFault converts a target 4xx/5xx into a fault so DefaultFaultRule fires.
  - name: RF-TargetErrorToFault
    type: RaiseFault
    content:
      RaiseFault:
        IgnoreUnresolvedVariables: "true"
        # empty FaultResponse -- DefaultFaultRule builds the real response
  # ... AM-Build*, SC-Fallback*, AM-Copy* policies -- see GitHub repository

El resguardo se basa en dos parámetros de configuración:

success.codes: 2XX en ambos bloques httpTargetConnection. Apigee trata cualquier respuesta de destino que no sea 2xx como un error de destino y realiza la transición directamente al flujo de errores.
Una política RaiseFault en el PostFlow de respuesta de cada destino, controlada por response.status.code >= 400. Esta política garantiza que DefaultFaultRule se ejecute para cada respuesta de error.

Redacta la plantilla de la etapa 4, que agrega una línea a la plantilla de la etapa 3:

gateway: apigee
schemaVersion: 1.0.0
name: aft-demo-04-add-fallback
features:
  - llm-base.yaml
  - llm-openai-format.yaml
  - target-vertex-gemini.yaml
  - llm-model-armor.yaml
  - target-openai-gpt.yaml
  - llm-routing.yaml
  - llm-semantic-cache.yaml
  - llm-fallback.yaml              # <-- the change from Stage 3
parameters:
  - name: BASE_PATH
    default: /v1/chat/completions-stage4
  # ... Model Armor and Vector Search parameters as in Stage 3

Implementa la plantilla:

gcloud beta apigee apis import aft-demo-04-add-fallback \
  --from-template=04-add-fallback.yaml \
  --organization=APIGEE_ORG

Verifica el comportamiento de extremo a extremo

El repositorio de GitHub incluye una secuencia de comandos routing-diagnostic.sh que ejercita todas las rutas de enrutamiento y resguardo con instrucciones temáticamente diversas. Debido a que la caché semántica genera un cortocircuito en las instrucciones similares, cada instrucción de prueba debe redactarse de forma diferente.

STAGE=4 ./routing-diagnostic.sh

La secuencia de comandos envía cinco solicitudes a través del proxy de la etapa 4:

Un modelo canónico de OpenAI
Un modelo de Gemini con el prefijo google/
Un nombre de modelo de Gemini sin prefijo, que se enruta a OpenAI según el comportamiento predeterminado invertido
Un modelo de razonamiento de OpenAI
Un nombre de modelo con el prefijo openai/

Para cada solicitud, la secuencia de comandos informa qué proveedor ascendente entregó la respuesta y si se produjo una conmutación por recuperación.

Para ver cada paso de la política, llamada de destino y transición de regla de falla para una sola solicitud, crea una sesión de depuración de Apigee en la revisión implementada:

DEBUG_URL="https://apigee.googleapis.com/v1/organizations/APIGEE_ORG/environments/APIGEE_ENV/apis/aft-demo-04-add-fallback/revisions/REVISION/debugsessions"
curl -X POST -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"filter":"","count":10,"timeout":"600","validity":600}' \
  "$DEBUG_URL"