Mengonfigurasi ekstensi untuk memanggil layanan Google

Service Extensions memungkinkan Load Balancer Aplikasi yang didukung untuk mengonfigurasi ekstensi menggunakan info ke layanan Google. Halaman ini menunjukkan cara mengonfigurasi ekstensi tersebut.

Untuk ringkasannya, lihat Integrasi dengan layanan Google.

Mengonfigurasi ekstensi traffic untuk memanggil layanan Model Armor

Anda dapat mengonfigurasi ekstensi traffic untuk memanggil Model Armor guna menerapkan kebijakan keamanan secara seragam pada traffic inferensi AI generatif ke load balancer aplikasi, termasuk GKE Inference Gateway.

Ekstensi traffic mengelompokkan layanan ekstensi terkait ke dalam satu atau beberapa rantai. Anda dapat mengonfigurasi plugin dan info dalam rantai ekstensi yang sama. Setiap rantai ekstensi memilih traffic yang akan ditindaklanjuti menggunakan Common Expression Language (CEL) kondisi kecocokan. Load balancer mengevaluasi permintaan terhadap kondisi kecocokan setiap rantai secara berurutan. Saat permintaan cocok dengan kondisi yang ditentukan oleh rantai, semua ekstensi dalam rantai akan menindaklanjuti permintaan tersebut. Hanya satu rantai yang cocok dengan permintaan tertentu.

Setiap ekstensi dalam rantai dapat memiliki kumpulan peristiwa yang didukungnya sendiri. Perubahan yang dilakukan oleh ekstensi pada konten permintaan dan respons dapat dilihat oleh ekstensi yang tersisa dalam rantai. Untuk ekstensi yang dikonfigurasi untuk mendukung peristiwa respons, urutan ekstensi akan dibalik pada jalur respons.

Ekstensi traffic dilampirkan ke aturan penerusan load balancer yang dibuat menggunakan Inference Gateway. Setelah Anda mengonfigurasi resource, permintaan yang cocok akan dikirim ke layanan Model Armor.

Sebelum memulai

  1. Identifikasi project yang sesuai tempat Anda memiliki peran pemilik atau editor project atau peran IAM Compute Engine berikut:

  2. Mengaktifkan API yang diperlukan.

    Konsol

    1. Di Google Cloud konsol, buka halaman Enable access to APIs.

      Buka Enable access to APIs

    2. Ikuti petunjuk untuk mengaktifkan API yang diperlukan, yang mencakup Compute Engine API, Model Armor API, dan Network Services API.

    gcloud

    Gunakan perintah gcloud services enable:

    gcloud services enable compute.googleapis.com modelarmor.googleapis.com networkservices.googleapis.com

  3. Buat template Model Armor yang diperlukan.

  4. Siapkan infrastruktur Google Kubernetes Engine Anda dengan men-deploy Inference Gateway. Uji dengan mengirim permintaan inferensi.

    Dengan beberapa batasan, endpoint OpenAI API berikut didukung: Assistants, Chat Completions, Completions (legacy), Messages, dan Threads.

Batasan saat mengonfigurasi endpoint OpenAI API

Saat mengonfigurasi endpoint OpenAI API untuk infrastruktur GKE Anda, pertimbangkan batasan berikut yang berkaitan dengan sanitasi perintah dan respons:

  • Respons Streaming API tidak didukung untuk API apa pun. Model Armor melakukan sanitasi respons non-streaming dan mengabaikan respons streaming.

  • Saat melakukan sanitasi perintah dan respons, hanya operasi berikut yang didukung; operasi lainnya akan diabaikan dan diizinkan untuk dilanjutkan tanpa sanitasi:

    • Assistants API: Create, Delete, List, Modify, dan Retrieve
    • Chat Completions API: Create, Delete, Get Chat Completion, Get Chat Message, List, dan Update
    • Completions (legacy) API: Create
    • Messages API: Create, Delete, List, Modify, dan Retrieve
    • Responses API: Create, Delete, dan Get
    • Threads API: Create, Delete, Modify, dan Retrieve

  • Untuk panggilan API yang menampilkan beberapa pilihan dalam respons (seperti POST https://api.openai.com/v1/chat/completions), hanya item pertama dalam daftar pilihan yang disanitasi.

Mengonfigurasi ekstensi traffic

  1. Periksa perilaku sebelum ekstensi dikonfigurasi dengan mengirim permintaan inferensi ke load balancer dan menentukan alamat IP load balancer yang diekspos:

    curl -v http://${IP}/v1/chat/completions
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'

    Permintaan ini menghasilkan kode status HTTP 200 OK meskipun data sensitif telah dikirim ke LLM.

  2. Agar Model Armor memblokir perintah yang berisi data sensitif, konfigurasikan ekstensi traffic.

    Konsol

    1. Di Google Cloud konsol, buka halaman Service Extensions.

      Buka Service Extensions

    2. Klik Create extension. Wizard akan terbuka untuk memandu Anda melalui beberapa langkah awal.

    3. Untuk produk, pilih Load Balancing. Kemudian, klik Continue. Daftar Load Balancer Aplikasi yang didukung akan muncul.

    4. Pilih jenis load balancer.

    5. Tentukan region sebagai us-central1. Klik Continue.

    6. Untuk jenis ekstensi, pilih Traffic extensions, lalu klik Continue.

    7. Untuk membuka formulir Create extension, klik Continue. Di formulir Create extension, perhatikan bahwa pilihan sebelumnya tidak dapat diedit.

    8. Di bagian Basics, lakukan hal berikut:

      1. Tentukan nama unik untuk ekstensi.

        Nama harus dimulai dengan huruf kecil, diikuti dengan maksimal 62 huruf kecil, angka, atau tanda hubung, dan tidak boleh diakhiri dengan tanda hubung.

      2. Opsional: Masukkan deskripsi singkat tentang ekstensi menggunakan maksimal 1.024 karakter.

    9. Opsional: Di bagian Labels, klik Add label. Kemudian, di baris yang muncul, lakukan hal berikut:

      • Untuk Key, masukkan nama kunci.
      • Untuk Value, masukkan nilai untuk kunci.

      Untuk menambahkan pasangan nilai kunci lainnya, klik Add label. Anda dapat menambahkan maksimal 64 pasangan nilai kunci.

      Untuk mengetahui informasi selengkapnya tentang label, lihat Membuat dan memperbarui label untuk project.

    10. Untuk Forwarding rules, pilih satu atau beberapa aturan penerusan yang akan dikaitkan dengan ekstensi. Pilih aturan penerusan yang dibuat sebagai bagian dari men-deploy Inference Gateway. Aturan penerusan yang sudah dikaitkan dengan ekstensi lain tidak dapat dipilih dan akan terlihat tidak tersedia.

    11. Untuk Extension, guna menambahkan ekstensi yang akan dijalankan untuk permintaan yang cocok, lakukan hal berikut:

      • Untuk mencocokkan permintaan yang akan menjalankan rantai ekstensi, untuk Match condition, tentukan ekspresi Common Expression Language (CEL) —misalnya, request.path == "/v1/chat/completions".

        Untuk mengetahui informasi selengkapnya tentang ekspresi CEL, klik Get syntax help atau lihat Referensi bahasa pencocokan CEL.

      • Tambahkan satu atau beberapa ekstensi yang akan dijalankan untuk permintaan yang cocok.

        Untuk setiap ekstensi, di bagian Extensions, lakukan hal berikut, dan lalu klik Done:

      • Untuk Programmability type, pilih Google services dan lalu pilih endpoint layanan Model Armor —misalnya modelarmor.us-central1.rep.googleapis.com.

      • Untuk Timeout, tentukan nilai antara 10 dan 1.000 milidetik setelah pesan di streaming mengalami waktu tunggu. Perhatikan bahwa Model Armor memiliki latensi sekitar 250 milidetik.

      • Untuk Events, pilih semua jenis peristiwa HTTP.

      • Untuk Forward headers, klik Add header, lalu tambahkan header HTTP yang akan diteruskan ke ekstensi (dari klien atau backend). Jika header tidak ditentukan, semua header akan dikirim.

      • Opsional: Jika ekstensi mengalami waktu tunggu atau gagal dan Anda ingin pemrosesan permintaan atau respons dilanjutkan, untuk Fail open, pilih Enabled. Ekstensi berikutnya dalam rantai juga akan dijalankan.

        Secara default, opsi Fail open tidak dipilih. Dalam hal ini, jika terjadi error, pemrosesan permintaan atau respons akan berhenti. Jika header respons belum dikirim ke klien hilir, kode status HTTP 500 generik akan ditampilkan ke klien. Jika header respons telah dikirim, streaming HTTP ke klien akan direset.

        Opsi default untuk tidak memilih Fail open lebih disukai saat memprioritaskan keamanan atau integritas. Mengaktifkan Fail open, terutama untuk operasi non-kritis, akan membantu saat memprioritaskan ketersediaan.

      • Untuk Metadata, klik Add metadata untuk menentukan template Model Armor yang akan digunakan untuk menyaring perintah dan respons yang sesuai dengan model tertentu.

        Untuk Key, tentukan model_armor_settings. Untuk Value, tentukan template sebagai string JSON, seperti berikut:

        [{ "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" }]

        Ganti kode berikut:

        Template default juga dapat ditentukan untuk digunakan saat permintaan tidak cocok dengan model. Untuk mengonfigurasi template default, tentukan MODEL_NAME sebagai default.

        Jika Anda tidak ingin menyaring traffic perintah atau respons, buat dan sertakan template filter kosong.

        Ukuran total metadata harus kurang dari 1 KiB. Jumlah total kunci dalam metadata harus kurang dari 20. Panjang setiap kunci harus kurang dari 64 karakter. Panjang setiap nilai harus kurang dari 1.024 karakter. Semua nilai harus berupa string.

        Saat permintaan diblokir, Model Armor akan menampilkan kode status 403 Forbidden standar. Anda dapat mengganti status dengan menentukan setelan respons kustom (termasuk kode status dan pesan kustom) dalam kebijakan keamanan template Model Armor. Untuk mengetahui detailnya, lihat TemplateMetadata.

      Jika Anda ingin menentukan lebih dari satu ekstensi atau rantai ekstensi, bukan satu ekstensi, klik tombol Switch to advanced mode di akhir formulir dan tentukan ekstensi dan rantai yang diperlukan. Ekstensi dijalankan dalam urutan yang tercantum.

      Tentukan nama unik untuk setiap ekstensi dan rantai ekstensi. Nama harus sesuai dengan RFC-1034, hanya menggunakan huruf kecil, angka, dan tanda hubung, serta memiliki panjang maksimum 63 karakter. Selain itu, karakter pertama harus berupa huruf dan karakter terakhir harus berupa huruf atau angka.

    12. Klik Create extension.

    gcloud

    1. Tentukan info dalam file YAML dan kaitkan dengan aturan penerusan yang dibuat saat men-deploy Inference Gateway. Gunakan nilai contoh yang disediakan.

      cat >traffic_callout_service.yaml <<EOF
    name: traffic-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/LB_PROJECT_ID/regions/us-central1/forwardingRules/FORWARDING_RULE
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1-model-armor"
      matchCondition:
        celExpression: 'request.path == "/v1/chat/completions"'
      extensions:
      - name: extension-chain-1-model-armor
        service: modelarmor.us-central1.rep.googleapis.com
        failOpen: true
        supportedEvents:
        - REQUEST_HEADERS
        - REQUEST_BODY
        - REQUEST_TRAILERS
        - RESPONSE_HEADERS
        - RESPONSE_BODY
        - RESPONSE_TRAILERS
        timeout: 1s
        metadata:
          model_armor_settings: '[
            {
              "model": "MODEL_NAME",
              "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE",
              "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE"
            }
          ]'
EOF

      Ganti kode berikut:

      • TEMPLATE_PROJECT_ID: project ID template Model Armor
      • LB_PROJECT_ID: project ID aturan penerusan load balancer

      • FORWARDING_RULE: satu atau beberapa aturan penerusan yang akan dikaitkan dengan ekstensi. Pilih aturan penerusan yang dibuat sebagai bagian dari men-deploy Inference Gateway.

        Aturan penerusan yang sudah dikaitkan dengan ekstensi lain tidak dapat dipilih dan akan terlihat tidak tersedia.

      • MODEL_NAME: nama model seperti yang dikonfigurasi dengan resource InferenceModel—misalnya, meta-llama/Llama-3.1-8B-Instruct

      • LOCATION: lokasi template Model Armor—misalnya, us-central1

      • RESPONSE_TEMPLATE: template respons yang akan digunakan model

      • PROMPT_TEMPLATE: template perintah yang akan digunakan model

      Di kolom metadata, tentukan setelan dan template Model Armor yang akan digunakan saat menyaring perintah dan respons yang sesuai dengan model tertentu.

      Template default juga dapat ditentukan untuk digunakan saat permintaan tidak cocok dengan model. Untuk mengonfigurasi template default, tentukan MODEL_NAME sebagai default.

      Jika Anda tidak ingin menyaring traffic perintah atau respons, buat dan sertakan template filter kosong.

      Ukuran total metadata harus kurang dari 1 KiB. Jumlah total kunci dalam metadata harus kurang dari 16. Panjang setiap kunci harus kurang dari 64 karakter. Panjang setiap nilai harus kurang dari 1.024 karakter. Semua nilai harus berupa string.

      Saat permintaan diblokir, Model Armor akan menampilkan kode status 403 Forbidden standar. Anda dapat mengganti status dengan menentukan setelan respons kustom (termasuk kode status dan pesan kustom) dalam kebijakan keamanan template Model Armor. Untuk mengetahui detailnya, lihat TemplateMetadata.

    2. Impor ekstensi traffic. Gunakan perintah gcloud service-extensions lb-traffic-extensions importdengan nilai contoh berikut. 

      gcloud service-extensions lb-traffic-extensions import traffic-ext \
    --source=traffic_callout_service.yaml \
    --location=us-central1

    kubectl

    1. Jika Anda menggunakan versi GKE yang lebih lama dari v1.32.2-gke.1182001, instal CRD ekstensi traffic:

      kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml

    2. Tentukan ekstensi dalam file YAML. Resource kustom ini menautkan Inference Gateway Anda ke layanan Model Armor. Gunakan nilai contoh yang disediakan.

      cat >traffic_callout_service.yaml <<EOF
apiVersion: networking.gke.io/v1
kind: GCPTrafficExtension
metadata:
  name: traffic-ext
spec:
  targetRefs:
  - group: "gateway.networking.k8s.io"
    kind: Gateway
    name: inference-gateway
  extensionChains:
  - name: "chain1-model-armor"
    matchCondition:
      celExpressions:
      - celMatcher: 'request.path == "/v1/chat/completions"'
      extensions:
      - name: extension-chain-1-model-armor
        googleAPIServiceName: modelarmor.us-central1.rep.googleapis.com
        failOpen: true
        supportedEvents:
        - RequestHeaders
        - RequestBody
        - RequestTrailers
        - ResponseHeaders
        - ResponseBody
        - ResponseTrailers
        timeout: 1s
        metadata:
          model_armor_settings: '[
            {
              "model": "MODEL_NAME",
              "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE",
              "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE"
            }
          ]'
EOF

      Ganti kode berikut:

      Di kolom metadata, tentukan setelan dan template Model Armor yang akan digunakan saat menyaring perintah dan respons yang sesuai dengan model tertentu.

      Template default juga dapat ditentukan untuk digunakan saat permintaan tidak cocok dengan model. Untuk mengonfigurasi template default, tentukan MODEL_NAME sebagai default.

      Jika Anda tidak ingin menyaring traffic perintah atau respons, buat dan sertakan template filter kosong.

      Ukuran total metadata harus kurang dari 1 KiB. Jumlah total kunci dalam metadata harus kurang dari 16. Panjang setiap kunci harus kurang dari 64 karakter. Panjang setiap nilai harus kurang dari 1.024 karakter. Semua nilai harus berupa string.

      Saat permintaan diblokir, Model Armor akan menampilkan kode status 403 Forbidden standar. Anda dapat mengganti status dengan menentukan setelan respons kustom (termasuk kode status dan pesan kustom) dalam kebijakan keamanan template Model Armor. Untuk mengetahui detailnya, lihat TemplateMetadata.

    3. Terapkan konfigurasi yang ditentukan dalam file traffic_callout_service.yaml ke cluster GKE Anda. Perintah ini membuat resource GCPTrafficExtension, yang menautkan Inference Gateway Anda ke layanan Model Armor.

      kubectl apply -f traffic_callout_service.yaml

  3. Berikan peran yang diperlukan ke akun layanan Service Extensions. Gunakan perintah gcloud projects add-iam-policy-binding:

    gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/container.admin
gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

    Ganti kode berikut:

    • TEMPLATE_PROJECT_ID: project ID template Model Armor
    • LB_PROJECT_NUMBER: nomor project load balancer

    Nilai ini tercantum di panel Project info di Google Cloud konsol untuk project Anda.

  4. Untuk memverifikasi bahwa ekstensi traffic berfungsi seperti yang diharapkan, jalankan perintah curl yang sama:

    curl -v http://${IP}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'
  ```

Dengan ekstensi layanan yang dikonfigurasi, permintaan dengan data sensitif akan menghasilkan kode status HTTP 403 Forbidden, mencatat pesan error seperti yang dikonfigurasi dalam template, dan menutup koneksi.

Jika permintaan aman, permintaan akan menghasilkan kode status HTTP 200 OK dan menampilkan respons LLM kepada pengguna.

Untuk memantau perilaku ekstensi, gunakan Logs Explorer. Di panel kueri, bergantung pada konfigurasi Inference Gateway Anda, filter menurut jenis resource load balancer yang sesuai.

Entri log Load Balancer Aplikasi berisi informasi yang membantu Anda men-debug traffic HTTP atau HTTPS.

Untuk melakukan analisis penilaian keamanan yang lebih mendetail, aktifkan logging audit Model Armor.

Langkah berikutnya