Mengintegrasikan dengan Platform Agen Gemini Enterprise

Model Armor dapat diintegrasikan langsung ke Platform Agen Gemini Enterprise baik menggunakan setelan minimum atau menggunakan template. Model Armor terintegrasi dengan Platform Agen Gemini Enterprise untuk menyaring permintaan yang dikirim ke dan respons yang diterima dari model Gemini. Model Armor memeriksa atau memblokir traffic yang melanggar setelan minimum.

Model Armor memberikan perlindungan perintah dan respons dalam Gemini API di Vertex AI untuk metode generateContent. Anda harus mengaktifkan Cloud Logging untuk mendapatkan visibilitas ke hasil sanitasi perintah dan respons.

Selain melindungi panggilan REST langsung ke layanan Platform Agen Gemini Enterprise, Anda juga dapat menggunakan Model Armor untuk melindungi antarmuka lain yang menyediakan akses ke Gemini API di Vertex AI, seperti Google Gen AI SDK atau Firebase AI Logic SDK.

Sebelum memulai

Berikan izin pengguna Model Armor ke akun layanan Platform Agen Gemini Enterprise.

gcloud projects add-iam-policy-binding PROJECT_ID --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com' --role='roles/modelarmor.user'

Ganti kode berikut:

  • PROJECT_ID: Project ID Google Cloud Anda.
  • PROJECT_NUMBER: nomor Google Cloud project Anda.

Mengonfigurasi setelan minimum

Anda menggunakan setelan minimum untuk mengonfigurasi batas deteksi minimum untuk template Model Armor. Setelan ini memverifikasi bahwa semua template baru dan yang diubah memenuhi persyaratan setelan minimum.

Untuk mengaktifkan integrasi Model Armor dan Platform Agen Gemini Enterprise, Anda dapat menetapkan setelan minimum hanya di tingkat project dengan menggunakan API atau Google Cloud konsol.

Untuk mengonfigurasi setelan minimum, lihat Mengonfigurasi setelan minimum.

Untuk mengonfigurasi setelan minimum dengan integrasi Platform Agen Gemini Enterprise, jalankan perintah berikut:

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --add-integrated-services=VERTEX_AI

Perintah ini mengaktifkan mode penerapan INSPECT_ONLY secara default. Untuk mengubah mode ke INSPECT_AND_BLOCK, jalankan perintah berikut:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

Untuk menghapus Platform Agen Gemini Enterprise dari layanan terintegrasi, jalankan perintah berikut:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --remove-integrated-services=VERTEX_AI

Untuk menghapus semua layanan terintegrasi yang dikonfigurasi dari setelan minimum, jalankan perintah berikut:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --clear-integrated-services

Ganti PROJECT_ID dengan ID project untuk setelan minimum.

REST

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{"filterConfig" : {"piAndJailbreakFilterSettings": { "filterEnforcement": "ENABLED"}}, "integratedServices": ["AI_PLATFORM"], "aiPlatformFloorSetting":{"inspectOnly":true, "enableCloudLogging":true}, "enableFloorSettingEnforcement":true}' \
  "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

Ganti PROJECT_ID dengan ID project yang berisi setelan minimum.

Setelah mengonfigurasi setelan minimum untuk mengaktifkan sanitasi Platform Agen Gemini Enterprise, Model Armor akan membersihkan semua panggilan API generateContent ke endpoint Gemini project menggunakan setelan filter yang ditentukan.

Contoh kode berikut menunjukkan cara menggunakan metode generateContent.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
  {
      "role": "user",
      "parts": [
          {
              "text": ""
          }
      ]
  }
]
, "generationConfig": {
  "responseModalities": ["TEXT"]
  ,"temperature": 0.2
  ,"maxOutputTokens": 1024
  ,"topP": 0.8
}
}'

Ganti kode berikut:

  • PROJECT_ID: Project ID Google Cloud Anda.
  • LOCATION: lokasi endpoint Gemini . Google Cloud Untuk mengetahui lokasi yang didukung, lihat Lokasi untuk Model Armor API.

Contoh kode berikut menunjukkan respons dari metode generateContent.

{
"promptFeedback": {
  "blockReason": "MODEL_ARMOR",
  "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection and Jailbreak filters."
},
"usageMetadata": {
  "trafficType": "ON_DEMAND"
},
"modelVersion": "gemini-2.5-flash",
"createTime": "2025-03-26T13:14:36.961184Z",
"responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Menentukan jenis penerapan untuk setelan minimum

Untuk mengonfigurasi cara Model Armor menangani deteksi, tetapkan jenis penerapan. Contoh berikut menunjukkan konfigurasi setelan minimum dengan jenis penerapan INSPECT_AND_BLOCK.

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/modelarmor-api-test/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

REST

export FLOOR_SETTING='{
  "filterConfig": {
    "raiSettings": {
      "raiFilters": [
        { "filterType": "HATE_SPEECH", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "DANGEROUS", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "HARASSMENT", "confidenceLevel": "LOW_AND_ABOVE" }
      ]
    },
    "sdpSettings": {
      "basicConfig": { "filterEnforcement": "ENABLED" }
    },
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED",
      "confidenceLevel": "LOW_AND_ABOVE"
    },
    "maliciousUriFilterSettings": { "filterEnforcement": "ENABLED" }
  },
  "integratedServices": ["AI_PLATFORM"],
  "aiPlatformFloorSetting": {
    "inspectAndBlock": true,
    "enableCloudLogging": true
  },
  "enableFloorSettingEnforcement": true
}'

curl -X PATCH \
    -d "$FLOOR_SETTING" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

Ganti PROJECT_ID dengan ID project yang berisi setelan minimum.

Mengonfigurasi template Model Armor

Model Armor juga dapat diintegrasikan dengan Platform Agen Gemini Enterprise menggunakan template Model Armor. Template memungkinkan Anda mengonfigurasi cara Model Armor menyaring perintah dan respons serta menentukan konfigurasi filter keamanan.

Anda harus membuat template terlebih dahulu, lalu menggunakan template ini dengan metode generateContent Gemini. Untuk mengetahui informasi selengkapnya tentang template, lihat Membuat dan mengelola template Model Armor.

Setelah mengonfigurasi template Model Armor, teruskan ID template sebagai parameter saat melakukan panggilan ke Gemini API menggunakan metode generateContent. Platform Agen Gemini Enterprise akan merutekan permintaan ke Model Armor untuk diproses.

Contoh kode berikut menunjukkan permintaan ke metode generateContent.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": "PROMPT"
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
},
 "model_armor_config": {
        "prompt_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "response_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
    }
}'

Ganti kode berikut:

  • PROJECT_ID: Google Cloud Project ID.
  • LOCATION: lokasi endpoint Gemini. Google Cloud Lokasi yang didukung adalah us-central1, us-east4, us-west1, dan europe-west4.
  • PROMPT: perintah teks.
  • TEMPLATE_ID: ID template Model Armor.

Contoh kode berikut menunjukkan respons dari metode generateContent.

{
  "promptFeedback": {
    "blockReason": "MODEL_ARMOR",
    "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection and Jailbreak filters."
  },
  "usageMetadata": {
    "trafficType": "ON_DEMAND"
  },
  "modelVersion": "gemini-2.5-flash",
  "createTime": "2025-03-26T13:14:36.961184Z",
  "responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Prioritas konfigurasi

Saat menggunakan Model Armor dengan Platform Agen Gemini Enterprise, Anda dapat memiliki konfigurasi keamanan yang ditentukan di beberapa tingkat. Dalam kasus tersebut, Model Armor dan Platform Agen Gemini Enterprise mengikuti urutan prioritas tertentu:

  1. Template Model Armor: Konfigurasi apa pun yang secara eksplisit diberikan dalam konfigurasi yang ditentukan dalam permintaan API memiliki prioritas tertinggi. Setelan ini mengganti konfigurasi lain yang bertentangan untuk permintaan tertentu tersebut.

  2. Setelan minimum Model Armor: Jika tidak ada konfigurasi pengganti yang diberikan dalam permintaan API, setelan minimum Model Armor akan diterapkan.

  3. Filter keamanan Platform Agen Gemini Enterprise: Filter keamanan default yang ada di Platform Agen Gemini Enterprise memiliki prioritas terendah. Filter ini hanya diterapkan jika tidak ada template Model Armor atau setelan minimum tertentu yang ditentukan.

Pendekatan hierarkis ini memberikan kombinasi standar minimum yang luas dan berlaku di seluruh organisasi (menggunakan setelan minimum) dan kontrol per permintaan (menggunakan template), sekaligus memanfaatkan fitur keamanan bawaan Platform Agen Gemini Enterprise sebagai dasar.

Pertimbangan

Pertimbangkan hal berikut saat mengintegrasikan Model Armor dengan Platform Agen Gemini Enterprise:

  • Pengeditan Sensitive Data Protection untuk template de-identifikasi tidak didukung.
  • Sanitasi perintah dan respons yang berisi dokumen tidak didukung.

  • Platform Agen Gemini Enterprise akan melewati langkah sanitasi Model Armor dan terus memproses permintaan dalam kondisi berikut:

    • Model Armor tidak tersedia di region tempat Platform Agen Gemini Enterprise berada.
    • Model Armor tidak dapat dijangkau untuk sementara.
    • Terjadi error dalam Model Armor.

    Semua instance ini terkadang dapat mengekspos perintah atau respons yang tidak disaring karena permintaan berlanjut tanpa sanitasi perintah dan respons.

    Meskipun integrasi dirancang untuk menjaga layanan tetap berjalan meskipun koneksi gagal, mode INSPECT_AND_BLOCK tetap menampilkan error konfigurasi seperti masalah izin atau kuota.