運用轉送、Model Armor 和語意快取，建構 AI 閘道

本頁面適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本教學課程說明如何設定及使用 Apigee 做為 AI 閘道，根據彈性的政策導向路由規則，將大型語言模型 (LLM) 要求轉送至不同的後端模型。AI 閘道可協助您保護、管理及最佳化模型流量，以控管成本並防止模型擴散。

本教學課程的每個階段都會以前一個設定為基礎，透過可重複使用的 Apigee 功能範本 (AFT) 檔案新增特定功能：

  • 第 1 階段：部署最簡單的 API Proxy，做為單一 LLM 供應商的前端。
  • 第 2 階段：新增 Model Armor 提示詞和回覆清理功能，篩除惡意輸入內容，並防止機密資料外洩。
  • 第 3 階段：新增跨供應商模型路由，以及由 Agent Platform 向量搜尋支援的語意快取。
  • 第 4 階段：設定跨供應商備援，在主要目標傳回 4xx 或 5xx HTTP 狀態碼時，自動對次要供應商重試要求。

如要新增功能，請在範本的 features 區塊中附加一行。如要查看或下載完整範例檔案集 (包括 AFT 檔案和輔助指令碼)，請參閱 GitHub 上的 Apigee 範本存放區。

事前準備

完成本教學課程前，請確認您具備以下項目：

  • 已啟用計費功能的有效 Google Cloud 專案。
  • Apigee 執行個體中可用的全方位環境。您只能在全方位環境中部署 Model Armor、SemanticCacheLookup 和 SemanticCachePopulate 政策。
  • 已安裝並設定 Google Cloud CLI (gcloud) 和應用程式預設憑證 (ADC)。如要產生憑證，請執行 gcloud auth application-default login。
  • 具備下列 IAM 角色的執行階段服務帳戶：
    • roles/aiplatform.user
    • roles/modelarmor.user
    服務帳戶也需要存取任何供應商專屬憑證。
  • 在第 2、3 和 4 階段，請指定 Model Armor 範本資源路徑。例如：projects/YOUR_PROJECT/locations/us-central1/templates/apigee-aft-demo-ma。
  • 第 3 和第 4 階段：環境中名為 openai-credentials 的 Apigee 鍵/值對應 (KVM)，其中包含具有有效 OpenAI API 金鑰的 api-key 項目。
  • 階段 3 和 4：已部署的 Vertex AI 向量搜尋索引端點，用於語意快取。如需逐步索引設定，請參閱 GitHub 上的 Apigee 範本存放區 README。

總覽

這四個階段都接受 /v1/chat/completions[-stageN] 的 OpenAI Chat Completions 要求形式，因此相同的用戶端 SDK 適用於每個階段。model 欄位前置字元會決定模型路由決策：google/* 模型的要求會路由至 Agent Platform 上的 Gemini，所有其他要求則會路由至 OpenAI。這項反向預設設定可確保新的 OpenAI 模型系列 (例如 o1-*、o3-* 和 chatgpt-*) 正確轉送，而不會在背景遺漏 gpt-* 前置字元比對。

階段 已新增功能 基本路徑
1 Hello LLM (在 Agent Platform 向 Gemini 傳送 OpenAI 格式要求) /v1/chat/completions
2 Model Armor (提示詞注入、負責任的 AI 和 Sensitive Data Protection 篩選器) /v1/chat/completions-stage2
3 跨供應商路由和 Agent Platform 向量搜尋語意快取 /v1/chat/completions-stage3
4 跨供應商備援 (完整的 AI 閘道) /v1/chat/completions-stage4

階段 1：Hello LLM

這個精簡 Proxy 會透過與 OpenAI 相容的端點，為單一 Gemini 目標提供前端。兩個小型功能檔案提供基本 Proxy 架構和 JSON 擷取器。擷取器會將 $.model 和 $.messages[-1].content 複製到 llm.model 和 llm.prompt 流程變數中，確保後續階段的輸入內容一致。

llm-base.yaml 定義基本 Proxy 架構：

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 會擷取 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 定義使用 OpenAI 相容端點的 Agent Platform 目標：

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

將功能檔案組合成第 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

部署範本：

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

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

更改下列內容：

  • APIGEE_ORG：Apigee 組織名稱。
  • APIGEE_HOSTNAME：Apigee 環境群組的主機名稱，通常是 Google Cloud 負載平衡器。

階段 2：新增 Model Armor

Model Armor 會在目標呼叫前，檢查傳入的提示詞，確認是否有提示詞注入、不允許的內容和機密資料。然後在回覆傳送給用戶端前掃描模型回覆。

將一個功能檔案新增至範本，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)}"

第 2 階段範本 02-add-model-armor.yaml 會新增一行：

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

MA_TEMPLATE_PATH 參數預設為 us-central1 中名為 apigee-aft-demo-ma 的範本。如要使用自己的 Model Armor 範本，請覆寫範本 parameters 區塊中的參數。

第 3 階段：新增跨供應商的路由和語意快取

在第 3 階段，您會新增第二個目標 (OpenAI)，以模型式路徑取代單一路徑規則，並在兩個目標前方設定由 Agent Platform 向量搜尋支援的語意快取。

如要設定階段 3，請將三個功能檔案附加到範本中的 features 區塊：

  • target-openai-gpt.yaml：將 OpenAI 新增為次要目標端點。
  • llm-routing.yaml：根據要求的模型名稱，動態轉送要求。
  • llm-semantic-cache.yaml：在兩個供應商前方新增語意快取。

以下範例說明 llm-routing.yaml 功能檔案如何定義路由邏輯：

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

語意快取會在要求 PreFlow 中執行 SemanticCacheLookup，並在回應 PostFlow 中執行 SemanticCachePopulate (僅限快取失敗時)。這兩項政策都使用您另外佈建的 Agent Platform 向量搜尋索引端點。以下摘錄顯示政策定義的重要部分：

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)

第 3 階段範本會編譯所有功能檔案：

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"

使用與第 1 階段相同的 gcloud beta apigee apis import 指令，並加上 --from-template 旗標，部署範本。

第 4 階段：新增跨供應商備用方案

階段 4 會將 DefaultFaultRule 附加至這兩個目標。當主要目標傳回任何 4xx 或 5xx 狀態時，錯誤規則會將含有相同提示詞的 ServiceCallout 傳送至其他供應商，並將該回應傳回用戶端。用戶端會收到成功的 200 回應，並正常完成作業，因此不需要自己的重試邏輯或錯誤處理機制。

llm-fallback.yaml 功能檔案會新增這項行為。以下範例為縮寫。如需完整檔案，請參閱 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

備用廣告取決於兩項設定：

  • success.codes: 2XX 兩個 httpTargetConnection 區塊。Apigee 會將任何非 2xx 目標回應視為目標失敗，並直接轉換至錯誤流程。
  • 每個目標的回應 PostFlow 中都有 RaiseFault 政策，並由 response.status.code >= 400 控管。這項政策可確保 DefaultFaultRule 會針對每個錯誤回應執行。

編寫第 4 階段範本，在第 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

部署範本：

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

驗證端對端行為

GitHub 存放區包含 routing-diagnostic.sh 指令碼，可使用主題多元的提示，測試所有轉送和備用路徑。由於語意快取會略過相似的提示，因此每個測試提示的用詞必須不同。

STAGE=4 ./routing-diagnostic.sh

指令碼會透過第 4 階段 Proxy 傳送五項要求：

  • 標準 OpenAI 模型
  • 前置字串為 google/ 的 Gemini 模型
  • 不含前置字串的 Gemini 模型名稱，會根據反向預設值將要求傳送至 OpenAI
  • OpenAI 推論模型
  • 模型名稱 (含 openai/ 前置字串)

對於每項要求，指令碼會回報哪個上游供應商提供回應，以及是否發生備援。

如要查看單一要求的每個政策步驟、目標呼叫和錯誤規則轉換，請針對已部署的修訂版本建立 Apigee 偵錯工作階段：

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"

更改下列內容：

  • APIGEE_ORG：Apigee 組織名稱。
  • APIGEE_ENV：部署 Proxy 的環境。
  • REVISION：已部署的 aft-demo-04-add-fallback Proxy 修訂版本號碼。

然後傳送要求，執行備援：

curl -X POST https://APIGEE_HOSTNAME/v1/chat/completions-stage4 \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini",
       "messages":[{"role":"user","content":"Describe nuclear fusion in stars in two sentences."}]}'

使用 Apigee API 擷取擷取的偵錯工作階段訊息時，追蹤記錄會顯示下列執行流程：

  1. 擷取要求變數：Apigee 會從傳入的酬載中擷取 llm.model 和 llm.prompt 變數。
  2. 評估安全政策：要求通過 Model Armor 安全篩選。
  3. 檢查語意快取：查詢未命中語意快取，因此要求會繼續傳送至目標。
  4. 評估轉送條件：條件 llm.model StartsWith "google/" 的評估結果為 false。
  5. 轉送至主要目標：Apigee 會將要求轉送至 openai-target。
  6. 處理目標錯誤：OpenAI 目標會傳回非 2xx HTTP 狀態碼，導致 Apigee 引發目標錯誤。
  7. 執行錯誤規則：DefaultFaultRule 會執行 AM-BuildVertexFallbackRequest、SC-FallbackToVertex 和 AM-CopyVertexFallbackResponse，觸發備用序列。
  8. 傳回回覆：用戶端會收到 HTTP 200 回覆，其中包含 Gemini 在 Agent Platform 生成的酬載。

後續步驟

  • 設定驗證：在 Proxy 前方導入同盟 JWT、OpenID Connect (OIDC) 或 Apigee API 金鑰，強制執行租戶專屬的權杖配額和供應商存取權控管。
  • 監控成本和延遲時間：將 Apigee 數據分析資訊主頁附加至 API Proxy，依模型追蹤延遲時間和營運成本。
  • 套用租戶專屬安全政策：使用 MA_TEMPLATE_PATH 參數設定各租戶的 Model Armor 範本，對企業、開發人員和公開流量套用量身打造的清理規則。
  • 探索範例設定：如要下載完整範例集，包括 llm-fallback.yaml 範本、八個功能檔案、routing-diagnostic.sh 指令碼，以及 KVM、Model Armor 和 Agent Platform 向量搜尋的佈建指令碼，請參閱 GitHub 上的 Apigee 進化式 AI 閘道存放區。