Mengonfigurasi logging

Dokumen ini menjelaskan cara mengonfigurasi Model Armor untuk mencatat operasi berikut:

Operasi yang membuat, memperbarui, atau menghapus template
Operasi yang menyaring perintah pengguna atau respons model

Model Armor menggunakan log audit untuk mencatat aktivitas pengelolaan administratif dan resource. Untuk mengetahui informasi selengkapnya, lihat Log audit Model Armor.

Untuk mengetahui informasi tentang harga log, lihat halaman harga Cloud Logging. Biaya penggunaan Model Armor juga mungkin berlaku berdasarkan volume data yang diproses; lihat Harga Model Armor untuk mengetahui detailnya.

Sebelum memulai

Selesaikan tugas ini sebelum Anda menyelesaikan tugas lainnya dalam dokumen ini.

Mendapatkan izin yang diperlukan

Untuk mendapatkan izin yang diperlukan guna mengonfigurasi logging untuk Model Armor, minta administrator untuk memberi Anda peran IAM Model Armor Admin (roles/modelarmor.admin) di template Model Armor. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Mengaktifkan API

Anda harus mengaktifkan Model Armor API sebelum dapat menggunakan Model Armor.

Konsol

Aktifkan Model Armor API.
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.
Mengaktifkan API
Pilih project tempat Anda ingin mengaktifkan Model Armor.

gcloud

Sebelum memulai, ikuti langkah-langkah berikut menggunakan Google Cloud CLI dengan Model Armor API:

Di konsol Google Cloud , aktifkan Cloud Shell.

Aktifkan Cloud Shell

Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.
Tetapkan penggantian endpoint API menggunakan gcloud CLI.

Menetapkan penggantian endpoint API menggunakan gcloud CLI

Langkah ini hanya diperlukan jika Anda menggunakan gcloud CLI untuk mengaktifkan Model Armor API. Anda harus menetapkan penggantian endpoint API secara manual untuk memastikan gcloud CLI merutekan permintaan dengan benar ke layanan Model Armor.

Jalankan perintah berikut untuk menetapkan endpoint API bagi layanan Model Armor.

gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

Ganti LOCATION dengan region tempat Anda ingin menggunakan Model Armor.

Menyiapkan pembersihan traffic

Untuk server Model Context Protocol (MCP) yang dikelola Google, siapkan pembersihan traffic melalui setelan batas bawah. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi perlindungan untuk server Google dan MCP jarak jauh. Google Cloud (Pratinjau)

Mengonfigurasi logging dalam template

Template menentukan filter dan batasan untuk berbagai kategori keamanan dan keselamatan. Saat membuat atau memperbarui template Model Armor, Anda dapat menentukan apakah Model Armor mencatat operasi tertentu. Gunakan tanda berikut dalam metadata template:

log_template_operations: Nilai boolean yang mengaktifkan logging operasi pembuatan, pembaruan, pembacaan, dan penghapusan template.
log_sanitize_operations: Nilai boolean yang mengaktifkan logging operasi pembersihan. Log mencakup perintah dan respons, hasil evaluasi Model Armor, dan kolom metadata tambahan.

Konsol

Di konsol Google Cloud , buka halaman Model Armor.

Buka Model Armor
Pastikan Anda melihat project tempat Anda mengaktifkan Model Armor.
Di halaman Model Armor, klik Create Template. Untuk mengetahui informasi selengkapnya tentang cara membuat template, lihat Membuat template Model Armor.
Di bagian Configure logging, pilih operasi yang ingin Anda konfigurasi logging-nya.
Klik Create.

REST

  curl -X POST \
      -d '{ "filterConfig": {}, "templateMetadata": { "logTemplateOperations": true, "logSanitizeOperations": true } }' \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"

Ganti kode berikut:

PROJECT_ID: ID project tempat template berada.
LOCATION: lokasi template.
TEMPLATE_ID: ID template.

Python

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu dan instal Model Armor Python SDK.

   request = modelarmor_v1.CreateTemplateRequest(
     parent="projects/PROJECT_ID/locations/LOCATION",
     template_id="TEMPLATE_ID",
     template={
        "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "filter_config": {},
        "template_metadata": {
           "log_template_operations": True,
           "log_sanitize_operations": True
        }
     }
   )
   response = client.create_template(request=request)

Ganti kode berikut:

PROJECT_ID: ID project tempat template berada.
LOCATION: lokasi template.
TEMPLATE_ID: ID template.

Mengonfigurasi logging di setelan ruang

Setelan lantai menetapkan filter keamanan dan perlindungan dasar di semua model Gemini di Vertex AI dan server Model Context Protocol (MCP) yang dikelola Google (Pratinjau) dalam project Anda. Saat memperbarui setelan batas bawah Model Armor, Anda dapat menentukan apakah operasi pembersihan Model Armor dicatat.

Anda dapat mengaktifkan logging operasi pembersihan untuk Vertex AI dan server MCP yang dikelola Google secara terpisah. Jika diaktifkan, log akan menyertakan perintah dan respons (untuk Vertex AI) atau panggilan alat dan respons alat (untuk server MCP), hasil evaluasi Model Armor, dan kolom metadata tambahan.

Konsol

Di konsol Google Cloud , buka halaman Model Armor.

Buka Model Armor
Pastikan Anda melihat project tempat Anda mengaktifkan Model Armor.
Buka tab Setelan Lantai.
Di bagian Log, pilih MCP yang dikelola Google.
Klik Simpan.

gcloud

Anda dapat menggunakan salah satu tanda berikut untuk mengelola logging operasi pembersihan di setelan lantai.

Untuk mengaktifkan logging, gunakan salah satu tanda berikut:

Untuk Vertex AI, gunakan tanda --enable-vertex-ai-cloud-logging.
Untuk server MCP yang dikelola Google, gunakan flag --enable-google-mcp-server-cloud-logging.

Untuk menonaktifkan logging, gunakan salah satu flag berikut:

Untuk Vertex AI, gunakan tanda --no-enable-vertex-ai-cloud-logging.
Untuk server MCP yang dikelola Google, gunakan flag --no-enable-google-mcp-server-cloud-logging.

Catatan: Anda dapat mengaktifkan atau menonaktifkan logging untuk satu atau kedua layanan menggunakan satu perintah.

Contoh perintah berikut mengaktifkan logging operasi pembersihan untuk server MCP yang dikelola Google dan Vertex AI:

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-vertex-ai-cloud-logging \
--enable-google-mcp-server-cloud-logging

Ganti PROJECT_ID dengan ID project Anda.

REST

Anda dapat menggunakan metode UpdateFloorSetting untuk memperbarui setelan lantai guna mengaktifkan logging operasi sanitasi. Saat menggunakan metode ini, pastikan untuk menetapkan parameter yang sesuai ke benar (true) untuk mengaktifkan logging:

Untuk Vertex AI, tetapkan aiPlatformFloorSetting.enableCloudLogging ke true.
Untuk server MCP yang dikelola Google, setel googleMcpServerFloorSetting.enableCloudLogging ke true.

Contoh perintah berikut mengaktifkan logging operasi pembersihan untuk server MCP yang dikelola Google dan Vertex AI:

curl -X PATCH \
 -d '{ "aiPlatformFloorSetting":{ "enableCloudLogging": true}, "googleMcpServerFloorSetting":{ "enableCloudLogging": true}}' \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting?updateMask=aiPlatformFloorSetting.enableCloudLogging,googleMcpServerFloorSetting.enableCloudLogging"

Ganti PROJECT_ID dengan ID project Anda.

Python

Untuk menjalankan kode ini, siapkan lingkungan pengembangan Python terlebih dahulu dan instal Model Armor Python SDK.

from google.cloud.modelarmor import v1 as modelarmor_v1
from google.protobuf import field_mask_pb2

# TODO: Initialize the ModelArmorClient, "client"
# client = modelarmor_v1.ModelArmorClient()

project_id = "PROJECT_ID"
location = "global"

floor_setting_name = f"projects/{project_id}/locations/{location}/floorSetting"

request = modelarmor_v1.UpdateFloorSettingRequest(
    floor_setting=modelarmor_v1.FloorSetting(
        name=floor_setting_name,
        ai_platform_floor_setting=modelarmor_v1.FloorSetting.AiPlatformFloorSetting(
            enable_cloud_logging=True
        ),
        google_mcp_server_floor_setting=modelarmor_v1.FloorSetting.GoogleMcpServerFloorSetting(
            enable_cloud_logging=True
        ),
    ),
    update_mask=field_mask_pb2.FieldMask(
        paths=["ai_platform_floor_setting.enable_cloud_logging", "google_mcp_server_floor_setting.enable_cloud_logging"]
    )
)

try:
    response = client.update_floor_setting(request=request)
    print("Successfully updated floor settings logging.")
    print(response)
except Exception as e:
    print(f"An error occurred: {e}")

Ganti PROJECT_ID dengan ID project Anda.

Melihat log

Untuk melihat log Model Armor, Anda dapat menggunakan Logs Explorer di Logging dengan mengikuti langkah-langkah berikut:

Buka Logs Explorer di konsol Google Cloud . Untuk mengetahui informasi selengkapnya, lihat Melihat log menggunakan Logs Explorer.
Filter log menurut nama layanan modelarmor.googleapis.com.
Cari entri yang terkait dengan operasi yang Anda aktifkan di template. Untuk mengetahui daftar semua nama layanan dan jenis resource yang dimonitor, lihat Resource dan layanan yang dimonitor.

Memfilter log Model Armor

Anda dapat menggunakan label log untuk memfilter log Model Armor untuk operasi sanitasi dan logging template. Untuk melakukannya, ikuti petunjuk berikut:

Jalankan kueri berikut di Logs Explorer untuk memfilter log operasi sanitasi.

jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"

Untuk lebih menyaring log operasi sanitasi, Anda dapat menentukan nama klien atau ID korelasi dalam kueri.

Menggunakan nama klien: Saat Model Armor diintegrasikan dengan layanan seperti Vertex AI atau Gemini Enterprise, Anda dapat menggunakan nama klien untuk memfilter log untuk integrasi tertentu.
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
```

Menggunakan ID korelasi:

labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"

Ganti kode berikut:

CLIENT_NAME: nama klien Anda; misalnya, VERTEX_AI.
CORRELATION_ID: ID unik yang Anda buat untuk permintaan tertentu.

Menghubungkan log dan peristiwa terkait

Untuk mengaitkan log dan peristiwa untuk interaksi tertentu, Anda dapat menggunakan ID korelasi klien. ID ini adalah ID unik yang Anda buat (misalnya, UUID) yang melacak permintaan tertentu di seluruh sistem Anda. Untuk menyetel ID korelasi klien di header curl, gunakan opsi -H untuk menyertakan header kustom dalam permintaan Anda.

Berikut contoh formatnya:

uuid=$(uuidgen) \
curl -X POST -d  '{"userPromptData": { "text": "USER_PROMPT" } }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeUserPrompt"

curl -X POST \
    -d  '{"modelResponseData": { "text": "MODEL_RESPONSE" }, "userPrompt": "USER_PROMPT" }' \
    -H "Content-Type: application/json" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeModelResponse"

Ganti kode berikut:

PROJECT_ID: ID project tempat template berada.
LOCATION: lokasi template.
TEMPLATE_ID: ID template.
USER_PROMPT: perintah yang diberikan ke model.
MODEL_RESPONSE: respons yang diterima dari model.

Mengonfigurasi logging Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Mendapatkan izin yang diperlukan

Mengaktifkan API

Konsol

gcloud

Menetapkan penggantian endpoint API menggunakan gcloud CLI

Menyiapkan pembersihan traffic

Mengonfigurasi logging dalam template

Konsol

REST

Python

Mengonfigurasi logging di setelan ruang

Konsol

gcloud

REST

Python

Melihat log

Memfilter log Model Armor

Menghubungkan log dan peristiwa terkait

Mengonfigurasi logging