Configurare i criteri Apigee con il processore di estensioni

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il processore di estensioni Apigee ti consente di applicare le funzionalità del gateway AI di Apigee al traffico che non passa attraverso un proxy Apigee. Ad esempio, un servizio in esecuzione su Google Kubernetes Engine, un'API gestita da un altro gateway o un server MCP per un agente AI. Poiché il percorso del traffico è diverso da un proxy API standard, alcune configurazioni delle policy sono specifiche del processore di estensione. Questa pagina descrive queste considerazioni e fornisce configurazioni di esempio. Ogni sezione delle norme rimanda al tutorial completo relativo a queste norme.

I criteri in questa pagina vengono applicati allo stesso modo ovunque sia collegato il processore di estensioni:

Considerazioni principali

Le seguenti considerazioni si applicano quando colleghi una policy a un proxy del processore di estensioni. Per sapere dove allegarli, consulta Utilizzare i criteri con il processore di estensioni nella guida rapida.

Corrispondenza degli esempi con l'API del modello

Gli esempi in questa pagina utilizzano la forma della richiesta e della risposta di Gemini. Gli altri fornitori di modelli funzionano allo stesso modo: UserPromptSource, LLMTokenUsageSource e LLMModelSource sono modelli di messaggi, quindi li imposti sulla posizione equivalente nel payload dell'API. Le norme stesse rimangono invariate.

Definisci l'ambito del traffico che elabori

Con un proxy API standard, assegni un percorso di base e i client chiamano quell'URL specifico, quindi il proxy riceve solo il traffico a cui è destinato. Il processore di estensioni non ha un percorso di base, quindi il suo traffico viene limitato in due punti: nell'estensione, che decide cosa raggiunge Apigee, e nel proxy, che decide cosa viene eseguito sul traffico in arrivo. Utilizza entrambi.

Filtra prima l'estensione, in modo che il traffico che non intendi gestire non venga mai inviato ad Apigee:

  • In un'estensione del traffico, imposta una condizione di corrispondenza CEL nella catena di estensioni, ad esempio matchCondition.celExpression: 'request.host == "example.com"'.
  • In un'estensione di autorizzazione, abbina host e prefissi di percorso in httpRules.to.operations nel criterio di autorizzazione.

Poi definisci l'ambito dei singoli criteri all'interno del proxy. Un singolo proxy del processore di estensioni riceve tutto ciò che l'estensione seleziona e può comunque essere un mix: le chiamate del modello di un agente AI, le chiamate di sessione e di stato e le chiamate di telemetria possono condividere un host. Una policy che ispeziona un payload del modello non riesce a essere eseguita su una chiamata che non ne contiene uno e una policy non riuscita blocca la richiesta. Collega ogni criterio con una condizione che lo limita al traffico previsto:

<!-- 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>

Utilizza un proxy senza target

I proxy del processore delle estensioni elaborano il traffico intercettato e non hanno un endpoint di destinazione. Esegui il deployment come proxy estensibili. Tutti i proxy in un ambiente di elaborazione delle estensioni devono essere dello stesso tipo.

Leggere il corpo della chiamata intercettata

I criteri che esaminano il payload operano sul messaggio così come appare sul cavo. Per una chiamata al modello, si tratta della richiesta e della risposta del modello. Ad esempio, il prompt dell'utente si trova in $.contents[-1].parts[-1].text e la risposta del modello si trova in $.candidates[-1].content.parts[-1].text.

Concedi un account di servizio per i criteri che chiamano i servizi Google

I criteri che chiamano un servizio Google, ad esempio Model Armor o le ricerche di incorporamenti e indici utilizzate dalla memorizzazione semantica nella cache, richiedono un account di servizio di deployment. Esegui il deployment del proxy con il parametro serviceAccount.

Sicurezza dell'AI con Model Armor

Collega le policy SanitizeUserPrompt e SanitizeModelResponse con ambito limitato alla chiamata del modello. Per la configurazione dei modelli, vedi Inizia a utilizzare 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>

Allega SUP-sanitize nel flusso della richiesta con la condizione (request.uri Like "*generateContent*"). Quando il prompt corrisponde al template Model Armor, il criterio rifiuta la richiesta, quindi il prompt non raggiunge mai il modello.

Memorizzazione nella cache semantica

Collega la policy SemanticCacheLookup nel flusso di richieste e la policy SemanticCachePopulate nel flusso di risposte, entrambe con ambito limitato alla chiamata del modello. Per la configurazione di indice ed embedding, vedi Guida introduttiva alla memorizzazione nella cache semantica. Quando una richiesta corrisponde a un prompt memorizzato nella cache, la risposta viene pubblicata dalla cache senza chiamare il modello.

Limiti di token per le chiamate al modello

Due criteri limitano l'utilizzo dei token del modello linguistico di grandi dimensioni (LLM) nella chiamata al modello. Ambiti entrambi alla chiamata del modello con la condizione (request.uri Like "*generateContent*"). Per la configurazione, consulta Guida introduttiva alle policy sui token LLM.

Limita i token del prompt

La policy PromptTokenLimit limita i token in base al prompt dell'utente, un meccanismo di controllo dei picchi per i prompt. Allegalo al flusso di richiesta; legge il prompt dalla richiesta intercettata e rifiuta la chiamata quando la frequenza viene superata, in modo che un prompt sovradimensionato non raggiunga mai il modello. L'esempio seguente limita le richieste a 1000 token al minuto:

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

Limitare il consumo di token di risposta

Il criterio LLMTokenQuota applica una quota di consumo di token in un intervallo di tempo, conteggiando i token restituiti nella risposta del modello. Allega un'istanza EnforceOnly nel flusso di richiesta per rifiutare le chiamate una volta superata la quota e un'istanza CountOnly nel flusso di risposta per conteggiare i token utilizzati, letti da $.usageMetadata.candidatesTokenCount. Assegna a entrambe le istanze lo stesso SharedName in modo che aggiornino un unico contatore. Questa policy richiede un proxy estensibile. La seguente coppia applica 15.000 token ogni 30 minuti:

<!-- 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>

Governance del traffico: quota, autorizzazione e protezione dai picchi

Queste norme vengono applicate al traffico tramite il processore delle estensioni a qualsiasi backend, inclusi i backend non ospitati su Apigee, ad esempio un'API ospitata su GKE o uno strumento o un server MCP chiamato da un agente AI. Definisci l'ambito di ogni policy per il backend che vuoi proteggere:

<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>
  • Autorizzazione: utilizza la policy VerifyAPIKey o OAuthV2. Le chiamate non autorizzate vengono rifiutate prima di raggiungere il backend.
  • Quota: utilizza i criteri Quota per applicare un limite preciso di chiamate. Configura il criterio come distribuito e sincrono in modo che il limite venga applicato come un unico conteggio condiviso durante l'esecuzione.
  • Spike Arrest: utilizza la policy SpikeArrest per attenuare i picchi di traffico. L'arresto dei picchi viene applicato per ogni processore di messaggi e non garantisce una velocità globale esatta; quando hai bisogno di un limite preciso, utilizza il criterio Quota.

Trasformare i messaggi ed estrarre le variabili

Utilizza il criterio AssignMessage per aggiungere, modificare o rimuovere parti di un messaggio (intestazioni, parametri di ricerca o payload) e il criterio ExtractVariables per leggere i valori di un messaggio in variabili che possono essere utilizzate da criteri successivi. Con il processore di estensione, entrambe le norme funzionano nel flusso di richiesta, operando sulla richiesta intercettata, e nel flusso di risposta, operando sulla risposta del backend. Come per qualsiasi policy del processore di estensioni, definisci l'ambito di ogni allegato con una condizione in modo che venga eseguito solo sul traffico previsto.

L'esempio seguente utilizza ExtractVariables per leggere un campo dal corpo della richiesta e nel flusso di risposta per leggere un campo dal corpo della risposta:

<!-- 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>

L'esempio seguente utilizza AssignMessage per impostare un'intestazione nella richiesta prima che raggiunga il backend e nella risposta prima che venga restituita al chiamante:

<!-- 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>

Passaggi successivi