Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

KI-Gateway mit Routing, Model Armor und semantischem Cache erstellen

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

In dieser Anleitung erfahren Sie, wie Sie Apigee als KI-Gateway konfigurieren und verwenden, das LLM-Anfragen (Large Language Model) basierend auf flexiblen, richtliniengesteuerten Routingregeln an verschiedene Backend-Modelle weiterleitet. Ein KI-Gateway hilft Ihnen, den Modell-Traffic zu sichern, zu verwalten und zu optimieren, um Kosten zu senken und die unkontrollierte Ausweitung von Modellen zu verhindern.

Jede Phase der Anleitung baut auf der vorherigen Konfiguration auf und fügt eine bestimmte Funktion über wiederverwendbare AFT-Dateien (Apigee Feature Template) hinzu:

Phase 1: Stellen Sie einen minimalen API-Proxy bereit, der vor einem einzelnen LLM-Anbieter steht.
Phase 2: Prompt- und Antwortbereinigung von Model Armor hinzufügen, um schädliche Eingaben zu filtern und Datenlecks zu verhindern.
Phase 3: Anbieterübergreifendes Modell-Routing und einen semantischen Cache hinzufügen, der von der Vektorsuche der Agent Platform unterstützt wird.
Phase 4: Cross-Provider-Fallback konfigurieren, um Anfragen automatisch an einen sekundären Anbieter zu senden, wenn das primäre Ziel den HTTP-Statuscode 4xx oder 5xx zurückgibt.

Wenn Sie eine Funktion hinzufügen möchten, hängen Sie eine einzelne Zeile an den Block features in Ihrer Vorlage an. Wenn Sie die vollständigen Beispieldateien, einschließlich der AFT-Dateien und Hilfsskripts, ansehen oder herunterladen möchten, rufen Sie das Apigee-Vorlagen-Repository auf GitHub auf.

Hinweis

Bevor Sie diese Anleitung durchgehen, benötigen Sie Folgendes:

Ein aktives Google Cloud -Projekt mit aktivierter Abrechnung.
Eine umfassende Umgebung, die in Ihrer Apigee-Instanz verfügbar ist. Sie können Model Armor-, SemanticCacheLookup- und SemanticCachePopulate-Richtlinien nur in umfassenden Umgebungen bereitstellen.
Die Google Cloud CLI (gcloud) ist installiert und mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) konfiguriert. Führen Sie gcloud auth application-default login aus, um Anmeldedaten zu generieren.
Ein Laufzeitdienstkonto mit den folgenden IAM-Rollen:
- roles/aiplatform.user
- roles/modelarmor.user
Das Dienstkonto benötigt außerdem Zugriff auf alle anbieterspezifischen Anmeldedaten.
Geben Sie für die Phasen 2, 3 und 4 einen Ressourcenpfad für die Model Armor-Vorlage an. Beispiel: projects/YOUR_PROJECT/locations/us-central1/templates/apigee-aft-demo-ma.
Für die Phasen 3 und 4: Eine Apigee-Schlüssel/Wert-Zuordnung (KVM) mit dem Namen openai-credentials in Ihrer Umgebung, die einen api-key-Eintrag mit einem gültigen OpenAI API-Schlüssel enthält.
Für Phase 3 und 4: Ein bereitgestellter Indexendpunkt für die Vektorsuche in Vertex AI für den semantischen Cache. Eine detaillierte Anleitung zur Indexeinrichtung finden Sie in der README-Datei des Apigee-Vorlagen-Repositorys auf GitHub.

Übersicht

Alle vier Phasen akzeptieren das OpenAI Chat Completions-Anfrageformat unter /v1/chat/completions[-stageN], sodass dieselben Client-SDKs in allen Phasen funktionieren. Das Feldpräfix model bestimmt die Routing-Entscheidung: Anfragen für google/*-Modelle werden an Gemini auf der Agent Platform weitergeleitet, alle anderen Anfragen an OpenAI. Dieser umgekehrte Standardwert sorgt dafür, dass neue OpenAI-Modellfamilien wie o1-*, o3-* und chatgpt-* richtig weitergeleitet werden, anstatt dass stillschweigend eine gpt-*-Präfixübereinstimmung fehlt.

Phase	Funktion hinzugefügt	Basispfad
1	Hello LLM (Anfrage im OpenAI-Format an Gemini auf der Agent Platform)	`/v1/chat/completions`
2	Model Armor (Filter für Prompt Injection, verantwortungsbewusste KI und Sensitive Data Protection)	`/v1/chat/completions-stage2`
3	Anbieterübergreifendes Routing und ein semantischer Cache für die Vektorsuche der Agent Platform	`/v1/chat/completions-stage3`
4	Anbieterübergreifendes Fallback (das vollständige KI-Gateway)	`/v1/chat/completions-stage4`

Phase 1: Hallo LLM

Der minimale Proxy stellt ein einzelnes Gemini-Ziel über seinen OpenAI-kompatiblen Endpunkt bereit. Zwei kleine Feature-Dateien stellen das grundlegende Proxy-Skelett und einen JSON-Extraktor bereit. Der Extractor kopiert $.model und $.messages[-1].content in die Ablaufvariablen llm.model und llm.prompt, damit spätere Phasen konsistente Eingaben haben.

llm-base.yaml definiert das Basis-Proxy-Skelett:

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 extrahiert die OpenAI-Anfragefelder:

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 definiert ein Agent Platform-Ziel, das den OpenAI-kompatiblen Endpunkt verwendet:

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

Fügen Sie die Featuredateien in die Vorlage für Phase 1 (01-hello-llm.yaml) ein:

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

Vorlage bereitstellen:

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

Proxy testen:

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"}]}'

Ersetzen Sie Folgendes:

APIGEE_ORG: der Name Ihrer Apigee-Organisation.
APIGEE_HOSTNAME: der Hostname Ihrer Apigee-Umgebungsgruppe, in der Regel ein Google Cloud -Load-Balancer.

Phase 2: Model Armor hinzufügen

Model Armor prüft den eingehenden Prompt vor dem Zielaufruf auf Prompt Injection, unzulässige Inhalte und sensible Daten. Anschließend wird die Modellantwort gescannt, bevor sie den Client erreicht.

Fügen Sie der Vorlage llm-model-armor.yaml eine Featuredatei hinzu:

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)}"

In der Vorlage für Phase 2, 02-add-model-armor.yaml, wird eine Zeile hinzugefügt:

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

Der Parameter MA_TEMPLATE_PATH ist standardmäßig auf eine Vorlage mit dem Namen apigee-aft-demo-ma in us-central1 festgelegt. Wenn Sie Ihre eigene Model Armor-Vorlage verwenden möchten, überschreiben Sie den Parameter im parameters-Block der Vorlage.

Phase 3: Anbieterübergreifendes Routing und semantischen Cache hinzufügen

In Phase 3 fügen Sie ein zweites Ziel (OpenAI) hinzu, ersetzen die Routingregel für eine einzelne Route durch modellbasiertes Routing und konfigurieren einen semantischen Cache, der von der Agent Platform-Vektorsuche unterstützt wird, vor beiden Zielen.

Um Phase 3 zu konfigurieren, hängen Sie dem features-Block in Ihrer Vorlage drei Feature-Dateien an:

target-openai-gpt.yaml: Fügt OpenAI als sekundären Zielendpunkt hinzu.
llm-routing.yaml: Leitet Anfragen dynamisch basierend auf dem angeforderten Modellnamen weiter.
llm-semantic-cache.yaml: Fügt vor beiden Anbietern einen semantischen Cache hinzu.

Das folgende Beispiel zeigt, wie die Routing-Logik in der llm-routing.yaml-Funktionsdatei definiert wird:

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

Der semantische Cache wird nur bei Cache-Fehlern mit SemanticCacheLookup im Anfrage-PreFlow und mit SemanticCachePopulate im Antwort-PostFlow ausgeführt. Für beide Richtlinien wird ein Agent Platform-Vektorsuchindexendpunkt verwendet, den Sie separat bereitstellen. Der folgende Auszug zeigt die wichtigsten Teile der Richtliniendefinitionen:

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)

Die Vorlage für Phase 3 setzt alle Featuredateien zusammen:

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"

Stellen Sie die Vorlage mit demselben gcloud beta apigee apis import-Befehl mit dem Flag --from-template bereit, den Sie in Phase 1 verwendet haben.

Phase 4: Anbieterübergreifendes Fallback hinzufügen

In Phase 4 wird beiden Zielen ein DefaultFaultRule angehängt. Wenn das primäre Ziel einen 4xx- oder 5xx-Status zurückgibt, sendet die Fehlerregel einen ServiceCallout mit demselben Prompt an den anderen Anbieter und gibt diese Antwort an den Client zurück. Der Client erhält eine erfolgreiche 200-Antwort mit normalem Abschluss und benötigt keine eigene Wiederholungslogik oder Fehlerbehandlung.

Durch die llm-fallback.yaml-Funktionsdatei wird dieses Verhalten hinzugefügt. Das folgende Beispiel ist abgekürzt. Die vollständige Datei finden Sie im GitHub-Repository.

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

Der Fallback basiert auf zwei Einstellungen:

success.codes: 2XX für beide httpTargetConnection-Blöcke. Apigee behandelt jede Zielantwort, die nicht 2xx ist, als Zielserverfehler und wechselt direkt zum Fehlerablauf.
Eine RaiseFault-Richtlinie im PostFlow der Antwort jedes Ziels, die auf response.status.code >= 400 beschränkt ist. Diese Richtlinie garantiert, dass DefaultFaultRule für jede Fehlerantwort ausgeführt wird.

Erstellen Sie die Vorlage für Phase 4, die der Vorlage für Phase 3 eine Zeile hinzufügt:

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

Vorlage bereitstellen:

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

End-to-End-Verhalten überprüfen

Das GitHub-Repository enthält ein routing-diagnostic.sh-Skript, das alle Routing- und Fallback-Pfade mit thematisch unterschiedlichen Prompts durchläuft. Da der semantische Cache ähnliche Prompts abfängt, muss jeder Test-Prompt eindeutig formuliert sein.

STAGE=4 ./routing-diagnostic.sh

Das Skript sendet fünf Anfragen über den Proxy für Phase 4:

Ein kanonisches OpenAI-Modell
Ein Gemini-Modell mit dem Präfix google/
Ein Gemini-Modellname ohne Präfix, der unter dem umgekehrten Standard an OpenAI weitergeleitet wird
Ein OpenAI-Reasoning-Modell
Ein Modellname mit dem Präfix openai/

Für jede Anfrage meldet das Script, welcher Upstream-Anbieter die Antwort bereitgestellt hat und ob ein Fallback aufgetreten ist.

Wenn Sie jeden Richtlinienschritt, Zielaufruf und jede Übergangsregel für eine einzelne Anfrage sehen möchten, erstellen Sie eine Apigee-Debug-Sitzung für die bereitgestellte Revision:

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"