Mengonfigurasi kebijakan Apigee dengan pemroses ekstensi

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Prosesor ekstensi Apigee memungkinkan Anda menerapkan kemampuan gateway AI dari Apigee ke traffic yang tidak mengalir melalui proxy Apigee. Misalnya, layanan yang berjalan di Google Kubernetes Engine, API yang dikelola oleh gateway lain, atau server MCP untuk agen AI. Karena jalur traffic berbeda dengan proxy API standar, beberapa konfigurasi kebijakan khusus untuk pemroses ekstensi. Halaman ini menjelaskan pertimbangan tersebut dan memberikan contoh konfigurasi. Setiap bagian kebijakan ditautkan ke tutorial lengkap kebijakan tersebut.

Kebijakan di halaman ini berlaku dengan cara yang sama di mana pun pemroses ekstensi terpasang:

Pertimbangan utama

Pertimbangan berikut berlaku saat Anda melampirkan kebijakan apa pun ke proxy prosesor ekstensi. Untuk mengetahui tempat melampirkannya, lihat Menggunakan kebijakan dengan pemroses ekstensi di panduan memulai.

Cocokkan contoh dengan API model Anda

Contoh di halaman ini menggunakan bentuk permintaan dan respons Gemini. Penyedia model lainnya berfungsi dengan cara yang sama: UserPromptSource, LLMTokenUsageSource, dan LLMModelSource adalah template pesan, jadi Anda menetapkannya ke lokasi yang setara di payload API tersebut. Kebijakannya sendiri tidak berubah.

Mencakup traffic yang Anda proses

Dengan proxy API standar, Anda menetapkan jalur dasar dan klien memanggil URL tertentu tersebut, sehingga proxy hanya menerima traffic yang ditujukan untuknya. Prosesor ekstensi tidak memiliki jalur dasar, sehingga Anda mencakup trafficnya di dua tempat: di ekstensi, yang memutuskan apa yang mencapai Apigee, dan di proxy, yang memutuskan apa yang berjalan pada traffic yang tiba. Gunakan keduanya.

Filter terlebih dahulu di ekstensi, sehingga traffic yang tidak ingin Anda atur tidak pernah dikirim ke Apigee:

  • Pada ekstensi lalu lintas, tetapkan kondisi kecocokan CEL pada rantai ekstensi, misalnya matchCondition.celExpression: 'request.host == "example.com"'.
  • Pada ekstensi otorisasi, cocokkan host dan awalan jalur di bagian httpRules.to.operations dalam kebijakan otorisasi.

Kemudian, cakup kebijakan individual di dalam proxy. Satu proxy pemroses ekstensi menerima semua yang dipilih ekstensi, dan itu masih bisa berupa campuran: panggilan model agen AI, panggilan sesi dan status, serta panggilan telemetri dapat berbagi host. Kebijakan yang memeriksa payload model gagal pada panggilan yang tidak membawanya, dan kebijakan yang gagal akan memblokir permintaan. Lampirkan setiap kebijakan dengan kondisi yang mencakupnya ke traffic yang diinginkan:

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

Menggunakan proxy tanpa target

Proxy pemroses ekstensi memproses traffic yang dicegat dan tidak memiliki endpoint target. Deploy proxy tersebut sebagai proxy extensible. Semua proxy di lingkungan pemroses ekstensi harus memiliki jenis proxy yang sama.

Membaca isi panggilan yang disadap

Kebijakan yang memeriksa payload beroperasi pada pesan sebagaimana muncul di jaringan. Untuk panggilan model, ini adalah permintaan dan respons model. Misalnya, perintah pengguna ada di $.contents[-1].parts[-1].text dan respons model ada di $.candidates[-1].content.parts[-1].text.

Memberi akun layanan untuk kebijakan yang memanggil layanan Google

Kebijakan yang memanggil layanan Google—misalnya, Model Armor, atau pencarian indeks dan penyematan yang digunakan oleh penyimpanan semantik—memerlukan akun layanan deployment. Deploy proxy dengan parameter serviceAccount.

Keamanan AI dengan Model Armor

Lampirkan kebijakan SanitizeUserPrompt dan SanitizeModelResponse yang dicakup ke panggilan model. Untuk penyiapan template, lihat Mulai menggunakan 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>

Lampirkan SUP-sanitize dalam alur permintaan dengan kondisi (request.uri Like "*generateContent*"). Jika perintah cocok dengan template Model Armor, kebijakan akan menolak permintaan, sehingga perintah tidak pernah mencapai model.

Caching semantik

Lampirkan kebijakan SemanticCacheLookup dalam alur permintaan dan kebijakan SemanticCachePopulate dalam alur respons, yang keduanya dicakup ke panggilan model. Untuk penyiapan indeks dan embedding, lihat Mulai menggunakan cache semantik. Jika permintaan cocok dengan perintah yang di-cache, respons akan disajikan dari cache tanpa memanggil model.

Batas token untuk panggilan model

Dua kebijakan membatasi penggunaan token model bahasa besar (LLM) pada panggilan model. Cakupan keduanya ke panggilan model dengan kondisi (request.uri Like "*generateContent*"). Untuk penyiapan, lihat Mulai menggunakan kebijakan token LLM.

Membatasi token perintah

Kebijakan PromptTokenLimit membatasi token berdasarkan perintah pengguna—pembatasan lonjakan untuk perintah. Lampirkan dalam alur permintaan; membaca perintah dari permintaan yang dicegat dan menolak panggilan saat batas tarif terlampaui, sehingga perintah yang terlalu besar tidak pernah mencapai model. Contoh berikut membatasi perintah hingga 1.000 token per menit:

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

Membatasi penggunaan token respons

Kebijakan LLMTokenQuota menerapkan kuota penggunaan token selama interval waktu, dengan menghitung token yang ditampilkan dalam respons model. Lampirkan instance EnforceOnly dalam alur permintaan untuk menolak panggilan setelah kuota terlampaui, dan instance CountOnly dalam alur respons untuk menghitung token yang digunakan, dibaca dari $.usageMetadata.candidatesTokenCount. Beri kedua instance SharedName yang sama sehingga keduanya memperbarui satu penghitung. Kebijakan ini memerlukan proxy yang dapat di-extend. Pasangan berikut menerapkan 15.000 token per 30 menit:

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

Tata kelola traffic: kuota, otorisasi, dan penanganan lonjakan

Kebijakan ini diterapkan pada traffic melalui pemroses ekstensi ke backend mana pun, termasuk backend yang tidak dihosting di Apigee, seperti API yang dihosting di GKE atau alat atau server MCP yang dipanggil oleh agen AI. Cakupan setiap kebijakan ke backend yang ingin Anda lindungi:

<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>
  • Otorisasi: gunakan kebijakan VerifyAPIKey atau OAuthV2. Panggilan tidak sah ditolak sebelum mencapai backend.
  • Quota: gunakan kebijakan Quota untuk menerapkan batas panggilan yang tepat. Konfigurasi kebijakan sebagai terdistribusi dan sinkron sehingga batas diterapkan sebagai satu jumlah bersama di seluruh runtime.
  • Penahanan lonjakan: gunakan kebijakan SpikeArrest untuk memperlancar lonjakan traffic. Pembatasan lonjakan diterapkan per pemroses pesan dan tidak menjamin tarif global yang tepat; jika Anda memerlukan batas yang tepat, gunakan kebijakan Kuota.

Mengubah pesan dan mengekstrak variabel

Gunakan kebijakan AssignMessage untuk menambahkan, mengubah, atau menghapus bagian pesan—header, parameter kueri, atau payload—dan kebijakan ExtractVariables untuk membaca nilai dari pesan ke dalam variabel yang dapat digunakan oleh kebijakan selanjutnya. Dengan prosesor ekstensi, kedua kebijakan bekerja dalam alur permintaan, beroperasi pada permintaan yang dicegat, dan dalam alur respons, beroperasi pada respons backend. Seperti kebijakan prosesor ekstensi lainnya, cakup setiap lampiran dengan kondisi sehingga hanya berjalan pada traffic yang dimaksud.

Contoh berikut menggunakan ExtractVariables untuk membaca kolom dari isi permintaan, dan dalam alur respons untuk membaca kolom dari isi respons:

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

Contoh berikut menggunakan AssignMessage untuk menyetel header pada permintaan sebelum mencapai backend, dan pada respons sebelum kembali ke pemanggil:

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

Langkah berikutnya