使用擴充功能處理器設定 Apigee 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

Apigee 擴充功能處理器可讓您將 Apigee 的 AI 閘道功能套用至未流經 Apigee Proxy 的流量。例如在 Google Kubernetes Engine 上執行的服務、由其他閘道管理的 API，或是 AI 代理程式的 MCP 伺服器。由於流量路徑與標準 API Proxy 不同，因此部分政策設定專屬於擴充功能處理器。本頁面將說明這些考量事項，並提供設定範例。每個政策章節都會連結到該政策的完整教學課程。

無論擴充功能處理器附加在何處，本頁面的政策都適用：

重要考量事項

將任何政策附加至擴充功能處理器 Proxy 時，請注意下列事項。如要瞭解附加位置，請參閱快速入門導覽課程中的「使用擴充功能處理器搭配政策」。

根據模型 API 調整範例

本頁面的範例使用 Gemini 要求和回應形狀。其他模型供應商的運作方式也相同：UserPromptSource、LLMTokenUsageSource 和 LLMModelSource 是訊息範本，因此您可以在該 API 的酬載中，將這些範本設為對等位置。政策本身維持不變。

處理的流量範圍

使用標準 API Proxy 時，您會指派基本路徑，而用戶端會呼叫該特定網址，因此 Proxy 只會接收預定流量。擴充功能處理器沒有基本路徑，因此您必須在兩個位置設定流量範圍：擴充功能 (決定哪些流量會抵達 Apigee) 和 Proxy (決定抵達的流量會執行哪些作業)。請同時使用這兩項功能。

請先在擴充功能中篩選，這樣一來，您不打算控管的流量就不會傳送至 Apigee：

  • 在流量擴充功能中，於擴充功能鏈結上設定 CEL 比對條件，例如 matchCondition.celExpression: 'request.host == "example.com"'。
  • 在授權擴充功能中，比對授權政策的 httpRules.to.operations 下方的主機和路徑前置字元。

然後在 Proxy 內設定個別政策的範圍。單一擴充功能處理器 Proxy 會接收擴充功能選取的所有內容，且這些內容仍可混合使用：AI 代理程式的模型呼叫、工作階段和狀態呼叫，以及遙測呼叫可共用主機。如果政策會檢查模型有效負載，但呼叫時未攜帶有效負載，政策就會失敗，並封鎖要求。為每項政策附加條件，將政策範圍限定在預期流量：

<!-- Run only on the model (generateContent) call -->
<Step>
  <Name>My-Policy</Name>
  <Condition>(request.uri Like "*generateContent*")</Condition>
</Step>

<!-- Or scope by backend host -->
<Step>
  <Name>My-Policy</Name>
  <Condition>(request.header.host = "backend.example.com")</Condition>
</Step>

使用無目標 Proxy

擴充功能處理器 Proxy 會處理攔截的流量，且沒有目標端點。 將其部署為可擴充 Proxy。擴充功能處理器環境中的所有 Proxy 必須屬於相同類型。

讀取攔截通話的內容

檢查酬載的政策會對訊息在網路上的顯示方式進行操作。如果是模型呼叫，這就是模型的要求和回應。舉例來說，使用者提示詞位於 $.contents[-1].parts[-1].text，模型回覆位於 $.candidates[-1].content.parts[-1].text。

授予服務帳戶權限，以便政策呼叫 Google 服務

呼叫 Google 服務的政策 (例如 Model Armor，或是語意快取使用的嵌入和索引查詢) 需要部署服務帳戶。使用 serviceAccount 參數部署 Proxy。

使用 Model Armor 確保 AI 安全

附加 SanitizeUserPrompt 和 SanitizeModelResponse 政策，並將範圍設為模型呼叫。如要設定範本，請參閱「開始使用 Model Armor」一文。

<SanitizeUserPrompt name="SUP-sanitize" continueOnError="false">
  <ModelArmor>
    <TemplateName>projects/PROJECT/locations/LOCATION/templates/TEMPLATE</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</SanitizeUserPrompt>

在要求流程中附加 SUP-sanitize，並設定 (request.uri Like "*generateContent*") 條件。如果提示與 Model Armor 範本相符，政策會拒絕要求，因此提示不會傳送至模型。

語意快取

在要求流程中附加 SemanticCacheLookup 政策，在回應流程中附加 SemanticCachePopulate 政策，兩者都以模型呼叫為範圍。如要瞭解如何設定索引和嵌入，請參閱「開始使用語意快取」。如果要求與快取中的提示相符，系統會從快取提供回覆，不會呼叫模型。

模型呼叫的權杖限制

有兩項政策會限制模型呼叫時的大型語言模型 (LLM) 權杖用量。使用 (request.uri Like "*generateContent*") 條件，將兩者都納入模型呼叫範圍。如需設定，請參閱「開始使用 LLM 權杖政策」。

限制提示詞詞元數

PromptTokenLimit 政策會根據使用者提示詞節流，也就是針對提示詞的尖峰流量抑制。在要求流程中附加，系統會從攔截的要求讀取提示，並在超出速率時拒絕呼叫，因此過大的提示永遠不會傳送至模型。以下範例將提示限制為每分鐘 1,000 個權杖：

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limit-prompt">
  <Rate>1000pm</Rate>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

限制回覆詞元消耗量

LLMTokenQuota 政策會在時間間隔內強制執行詞元用量配額，並計算模型回覆中傳回的詞元。在要求流程中附加 EnforceOnly 執行個體，以便在超出配額時拒絕呼叫，並在回應流程中附加 CountOnly 執行個體，以便從 $.usageMetadata.candidatesTokenCount 讀取並計算使用的權杖。為兩個執行個體提供相同的 SharedName，以便更新單一計數器。這項政策需要可擴充的 Proxy。 以下配對會強制執行每 30 分鐘 15,000 個權杖：

<!-- Request flow: reject when the token quota is exceeded -->
<LLMTokenQuota name="LTQ-enforce" type="rollingwindow">
  <SharedName>llm-token-counter</SharedName>
  <EnforceOnly>true</EnforceOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
</LLMTokenQuota>

<!-- Response flow: count the tokens used in the model response -->
<LLMTokenQuota name="LTQ-count" type="rollingwindow">
  <SharedName>llm-token-counter</SharedName>
  <CountOnly>true</CountOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
  <LLMTokenUsageSource>{jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}</LLMTokenUsageSource>
</LLMTokenQuota>

流量控管：配額、授權和尖峰流量防護

這些政策會對透過擴充功能處理器傳送至任何後端的流量強制執行，包括未在 Apigee 上代管的後端，例如 GKE 代管的 API，或是 AI 代理呼叫的工具或 MCP 伺服器。將每項政策的範圍設為要保護的後端：

<Step><Name>Verify-API-Key</Name><Condition>(request.header.host = "backend.example.com")</Condition></Step>
<Step><Name>Quota-Limit</Name><Condition>(request.header.host = "backend.example.com")</Condition></Step>
<Step><Name>Spike-Arrest</Name><Condition>(request.header.host = "backend.example.com")</Condition></Step>
  • 授權：使用 VerifyAPIKey 或 OAuthV2 政策。未經授權的通話會在抵達後端前遭到拒絕。
  • Quota：使用Quota政策強制執行精確的呼叫限制。將政策設為分散式和同步，這樣一來，系統就會在執行階段強制執行限制，並將限制設為單一共用計數。
  • 尖峰流量防範：使用 SpikeArrest 政策，緩和流量暴增的情況。尖峰流量限制是針對每個訊息處理器強制執行，無法保證確切的全球速率；如需精確的限制，請使用配額政策。

轉換訊息並擷取變數

使用 AssignMessage 政策新增、變更或移除郵件的各個部分 (標頭、查詢參數或酬載)，並使用 ExtractVariables 政策將郵件中的值讀取至變數，供後續政策使用。使用擴充功能處理器時，這兩項政策都會在要求流程中運作，處理攔截到的要求，並在回應流程中處理後端回應。與任何擴充功能處理器政策一樣，請為每個附件設定條件，確保附件只會在預期流量上執行。

下列範例使用 ExtractVariables 從要求主體讀取欄位，並在回應流程中從回應主體讀取欄位：

<!-- Request flow: read a field from the intercepted request -->
<ExtractVariables name="EV-from-request">
  <Source>request</Source>
  <JSONPayload>
    <Variable name="user.prompt">
      <JSONPath>$.contents[-1].parts[-1].text</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

<!-- Response flow: read a field from the backend response -->
<ExtractVariables name="EV-from-response">
  <Source>response</Source>
  <JSONPayload>
    <Variable name="model.answer">
      <JSONPath>$.candidates[-1].content.parts[-1].text</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

下列範例會使用 AssignMessage，在要求送達後端之前，以及在回應傳回給呼叫端之前，設定要求和回應的標頭：

<!-- Request flow: add a header to the intercepted request -->
<AssignMessage name="AM-set-request-header">
  <Set>
    <Headers>
      <Header name="X-Apigee-Processed">true</Header>
    </Headers>
  </Set>
  <AssignTo createNew="false" type="request"/>
</AssignMessage>

<!-- Response flow: add a header to the backend response -->
<AssignMessage name="AM-set-response-header">
  <Set>
    <Headers>
      <Header name="X-Apigee-Cache">miss</Header>
    </Headers>
  </Set>
  <AssignTo createNew="false" type="response"/>
</AssignMessage>

後續步驟