Gambar layar

Model Armor menyaring gambar mandiri dan gambar yang disematkan dalam dokumen rich text yang didukung dalam perintah dan respons untuk membantu melindungi aplikasi AI generatif Anda dari risiko yang disematkan dalam gambar.

Model Armor menyaring gambar menggunakan metode berikut:

Spesifikasi dan batasan

Pertimbangkan spesifikasi dan batasan berikut saat Anda menggunakan Model Armor untuk menyaring gambar:

  • Format gambar yang didukung: Model Armor menyaring gambar mandiri dalam format JPEG, PNG, dan BMP. Alat ini juga mengekstrak dan menyaring gambar yang disematkan dari file rich text yang didukung.
  • Batas ukuran: Setiap gambar mandiri harus berukuran 4 MB atau lebih kecil. File rich text harus berukuran total maksimal 4 MB dan berisi maksimal 5 gambar tersemat. Jika salah satu batas ini terlampaui, Model Armor akan melewati pemindaian seluruh file. Untuk mengetahui informasi selengkapnya, lihat Batas sistem ukuran file dan Menyaring gambar yang disematkan dalam dokumen.
  • Perintah mandiri: Saat Anda memanggil metode SanitizeUserPrompt dan SanitizeModelResponse dengan gambar mandiri, Model Armor akan menyaring satu gambar per permintaan. Pemeriksaan beberapa gambar mandiri dalam satu permintaan tidak didukung. Selain itu, Model Armor tidak mendukung perintah mandiri yang menggabungkan teks dan gambar dalam satu permintaan. Namun, Anda dapat menyaring dokumen rich text yang berisi teks dan gambar dengan mengaktifkan modalitas teks dan gambar.
  • De-identifikasi: Saat Anda mengonfigurasi template de-identifikasi Sensitive Data Protection, Model Armor akan menyamarkan teks atau gambar mandiri, bukan keduanya. De-identifikasi tidak didukung untuk dokumen rich text saat modalitas gambar (MODALITY_IMAGE) dipilih. Untuk mengetahui informasi selengkapnya, lihat Menyamarkan data sensitif dalam gambar mandiri dan Memeriksa gambar tersemat dalam dokumen.
  • Streaming: Metode streaming Model Armor hanya mendukung input tekstual dan tidak mendukung gambar atau file.
  • Integrasi yang didukung: Anda dapat menyaring gambar dengan memanggil REST API Model Armor secara langsung atau melalui integrasi Gemini Enterprise. Semua integrasi Model Armor lainnya hanya memindai dan membersihkan teks. Untuk mengetahui informasi selengkapnya, lihat Modalitas yang didukung.
  • Ketersediaan regional: Penyaringan gambar hanya didukung di multi-region tertentu. Jika Anda mengirim perintah yang berisi gambar ke endpoint tempat Model Armor tidak mendukung penyaringan gambar, kolom invocationResult dalam respons akan menunjukkan FAILURE. Untuk mengetahui daftar lokasi yang mendukung penyaringan gambar, lihat Fitur yang didukung menurut wilayah.

Penghitungan token dan harga untuk gambar

Model Armor menggunakan model harga berbasis token terpadu, dengan token gambar ditagih dengan tarif yang sama seperti token teks.

Anda tidak akan ditagih jika Model Armor menolak atau melewati input sebelum pemrosesan filter, seperti input kosong atau file dan gambar yang melebihi batas ukuran file atau gambar tersemat. Namun, jika input lulus validasi awal, Anda akan ditagih untuk token yang dihitung, bahkan dalam kasus berikut:

  • Semua detektor dilewati: Beberapa atau semua filter (detektor) yang dikonfigurasi dilewati dan menampilkan EXECUTION_SKIPPED (misalnya, saat payload gambar dalam batas 4 MB tidak dapat diuraikan oleh detektor, atau saat filter dilewati untuk modalitas).
  • File non-gambar yang digabungkan dengan jenis data byte IMAGE: File non-gambar (seperti ZIP, CSV, atau dokumen Microsoft Word) dikirim dengan byteDataType yang ditetapkan ke IMAGE (hingga 4 MB). Model Armor menagih permintaan menggunakan penghitungan token gambar mandiri meskipun filter menampilkan EXECUTION_SKIPPED.

Model Armor menghitung token untuk gambar dan dokumen berdasarkan jenis input dan modalitas yang dikonfigurasi:

  • Gambar mandiri: Model Armor mengonversi setiap gambar yang diproses (hingga 4 MB) menjadi token menggunakan jumlah dasar 5.000 token per gambar, ditambah 1.000 token per megabyte (MB) ukuran gambar. Saat menghitung token berbasis ukuran, Model Armor membulatkan ukuran gambar ke MB utuh berikutnya:

    Token per gambar = 5.000 + (1.000 × ukuran gambar dalam MB, dibulatkan ke atas ke MB utuh berikutnya)

    Teks yang diekstrak dari gambar melalui OCR disertakan dalam penghitungan token gambar dan tidak dikenai biaya token teks terpisah.

  • Dokumen rich text: Penghitungan token bergantung pada modalitas yang dikonfigurasi dalam template Anda:

    • Modalitas teks (MODALITY_TEXT): Model Armor menghitung token dari teks yang diekstrak dari dokumen (sekitar 4 karakter per token). Gambar yang disematkan tidak akan diekstrak atau ditagih.
    • Modalitas gambar (MODALITY_IMAGE): Model Armor menghitung token satu per satu untuk setiap gambar tersemat yang diproses menggunakan formula token gambar. Teks dokumen tidak ditagih.
    • Modalitas teks dan gambar (MODALITY_TEXT dan MODALITY_IMAGE): Model Armor menghitung total jumlah token sebagai jumlah token dari teks dokumen yang diekstrak dan token untuk setiap gambar tersemat yang diproses.

Tabel berikut menunjukkan contoh cara Model Armor menghitung token untuk gambar yang diproses:

Ukuran gambar Ukuran yang dibulatkan untuk penghitungan Penghitungan token Total token
500 KB 1 MB 5.000 + (1 × 1.000) 6.000 token
1,9 MB 2 MB 5.000 + (2 × 1.000) 7.000 token
4 MB 4 MB 5.000 + (4 × 1.000) 9.000 token

Sebelum memulai

Sebelum Anda menyaring gambar, selesaikan prasyarat berikut:

Membuat atau memperbarui template dengan modalitas gambar diaktifkan

Saat Anda membuat atau memperbarui template, pilih modalitas untuk menyertakan MODALITY_IMAGE (Image atau All di konsol Google Cloud , atau "modalities": ["MODALITY_IMAGE", "MODALITY_TEXT"] di templateMetadata saat menggunakan REST API). Jika Anda tidak menentukan modalitas, biarkan kolom modalities kosong, atau tentukan hanya MODALITY_TEXT, Model Armor hanya akan memindai teks dan menampilkan EXECUTION_SKIPPED untuk filter yang memindai modalitas yang dilewati.

Mendapatkan izin yang diperlukan

Pastikan Anda memiliki peran Identity and Access Management yang diperlukan untuk membersihkan perintah dan respons (seperti roles/modelarmor.user) dan, jika Anda menggunakan mode Sensitive Data Protection lanjutan di seluruh project, berikan peran DLP yang diperlukan ke agen layanan Model Armor. Untuk mengetahui petunjuknya, lihat Mendapatkan izin yang diperlukan.

Membersihkan gambar mandiri

Untuk menyaring gambar mandiri dalam perintah pengguna atau respons model, tetapkan kolom byteDataType ke IMAGE dan berikan gambar berenkode base64 dalam format yang didukung (JPEG, PNG, atau BMP) di kolom byteData.

Gunakan perintah berikut untuk membersihkan perintah yang berisi gambar:

curl -X POST \
    -d "$(jq -n \
    --arg data "$(base64 -w 0 -i IMAGE)" \
    '{userPromptData: {byteItem: {byteDataType: "IMAGE", byteData: $data}}}')" \
    -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:sanitizeUserPrompt"

Ganti kode berikut:

  • PROJECT_ID: ID project yang berisi template.
  • LOCATION: lokasi template.
  • TEMPLATE_ID: ID template yang dikonfigurasi untuk memindai gambar (MODALITY_IMAGE).
  • IMAGE: jalur ke file gambar dalam format yang didukung.

Responsnya mirip dengan hal berikut ini:

{
  "sanitizationResult": {
    "filterMatchState": "MATCH_FOUND",
    "invocationResult": "SUCCESS",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "pi_and_jailbreak": {
        "piAndJailbreakFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "MATCH_FOUND",
          "confidenceLevel": "HIGH"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "inspectResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "MATCH_FOUND"
          }
        }
      }
    }
  }
}

Menyamarkan data sensitif dalam gambar mandiri

Saat Anda menggunakan mode lanjutan Sensitive Data Protection, Model Armor akan menyamarkan temuan sensitif dalam gambar mandiri jika Anda mengonfigurasi template Model Armor dengan template pemeriksaan Sensitive Data Protection dan template de-identifikasi Sensitive Data Protection. Pastikan Anda mengonfigurasi redaksi gambar di template de-identifikasi. Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi Sensitive Data Protection di Model Armor, lihat Menetapkan setelan Sensitive Data Protection. Untuk mengetahui informasi tentang batasan de-identifikasi, lihat Spesifikasi dan batasan serta Menyaring gambar tersemat dalam dokumen.

Contoh berikut menunjukkan konfigurasi filter dengan penyamaran Sensitive Data Protection diaktifkan:

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate": "projects/PROJECT_ID/locations/LOCATION/inspectTemplates/INSPECT_TEMPLATE_ID",
        "deidentifyTemplate": "projects/PROJECT_ID/locations/LOCATION/deidentifyTemplates/DEIDENTIFY_TEMPLATE_ID"
      }
    }
  }
}

Ganti kode berikut:

  • PROJECT_ID: ID project yang berisi template Sensitive Data Protection.
  • LOCATION: lokasi template.
  • INSPECT_TEMPLATE_ID: ID template pemeriksaan.
  • DEIDENTIFY_TEMPLATE_ID: ID template de-identifikasi.

Saat Anda membersihkan gambar mandiri menggunakan template dengan pengeditan gambar diaktifkan, responsnya akan menyertakan gambar yang diedit dan koordinat kotak pembatas untuk setiap temuan:

{
  "sanitizationResult": {
    "filterMatchState": "MATCH_FOUND",
    "invocationResult": "SUCCESS",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "redactResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "MATCH_FOUND",
            "redactedImage": "[REDACTED_IMAGE]",
            "findings": [
              {
                "infoType": "EMAIL_ADDRESS",
                "likelihood": "LIKELY",
                "location": {
                  "contentLocations": [
                    {
                      "imageFindingLocation": {
                        "boundingBoxes": {
                          "top": 16,
                          "left": 121,
                          "width": 620,
                          "height": 90
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    }
  }
}

Memeriksa gambar yang disematkan dalam dokumen

Saat Anda mengaktifkan modalitas gambar (MODALITY_IMAGE) di template dan membersihkan dokumen rich text (PDF, WORD_DOCUMENT, EXCEL_DOCUMENT, atau POWERPOINT_DOCUMENT), Model Armor akan otomatis mengekstrak dan menyaring hingga 5 gambar yang disematkan dalam dokumen. Jika Anda mengaktifkan MODALITY_TEXT dan MODALITY_IMAGE, Model Armor akan menyaring teks dokumen dan gambar tersemat.

Baik Anda hanya mengaktifkan MODALITY_IMAGE atau mengaktifkan MODALITY_IMAGE dan MODALITY_TEXT, Model Armor akan melewati pemindaian seluruh dokumen, termasuk teks dan gambar tersemat, tanpa pemindaian parsial. Metode ini menampilkan EXECUTION_SKIPPED untuk semua filter yang dikonfigurasi, termasuk pemeriksaan, dan filterMatchState keseluruhan NO_MATCH_FOUND dalam kasus berikut:

  • Dokumen melebihi batas ukuran file 4 MB atau batas 5 gambar.
  • Template de-identifikasi Sensitive Data Protection dikonfigurasi. Untuk memeriksa dokumen rich text saat modalitas gambar diaktifkan, konfigurasikan hanya template pemeriksaan tanpa template de-identifikasi.

Untuk contoh kode yang menunjukkan cara mengirim perintah berbasis file menggunakan REST dan library klien, lihat Perintah berbasis file.

Pemeriksaan file parsial

Model Armor menampilkan hasil parsial (invocationResult: PARTIAL) hanya di tingkat filter (detektor) di seluruh file, bukan per gambar:

  • Kegagalan per gambar (seluruh file dilewati): Jika beberapa gambar tersemat dalam file berhasil dipindai, tetapi satu atau beberapa gambar lain dalam file gagal diekstrak atau dipindai, Model Armor akan melewati seluruh file. Metode ini menampilkan executionState: EXECUTION_SKIPPED untuk semua filter yang dikonfigurasi dan filterMatchState keseluruhan sebesar NO_MATCH_FOUND.
  • Kegagalan tingkat detektor (hasil parsial): Jika beberapa filter yang dikonfigurasi berhasil di seluruh file sementara satu atau beberapa filter lainnya dilewati untuk seluruh file (misalnya, karena waktu tunggu detektor habis), Model Armor akan menampilkan hasil parsial dengan kolom berikut:
    • Hasil pemanggilan: Kolom invocationResult ditetapkan ke PARTIAL (bukan SUCCESS), yang menunjukkan bahwa satu atau beberapa filter yang dikonfigurasi dilewati untuk file tersebut, sementara filter lainnya menyelesaikan pemeriksaan.
    • Status eksekusi filter: Filter yang dilewati untuk laporan file executionState: EXECUTION_SKIPPED. Filter yang telah menyelesaikan pemeriksaan di seluruh laporan file executionState: EXECUTION_SUCCESS.
    • Status kecocokan: Kolom filterMatchState mencerminkan temuan dari filter yang telah menyelesaikan pemeriksaan. Jika ada filter yang selesai mendeteksi pelanggaran, filterMatchState akan ditetapkan ke MATCH_FOUND. Jika tidak ada pelanggaran yang terdeteksi oleh filter yang telah selesai, filterMatchState akan ditetapkan ke NO_MATCH_FOUND.

Pertimbangan keamanan dengan pemeriksaan parsial

Dari sudut pandang keamanan, nilai invocationResult PARTIAL menunjukkan bahwa satu atau beberapa filter yang dikonfigurasi tidak dapat mengevaluasi file. Potensi ancaman keamanan atau pelanggaran kebijakan yang ditargetkan oleh filter yang dilewati mungkin masih ada dalam file.

Secara default, jika filter yang menyelesaikan pemeriksaan tidak mendeteksi pelanggaran kebijakan, filterMatchState adalah NO_MATCH_FOUND. Jika aplikasi Anda mengharuskan semua filter yang dikonfigurasi menyelesaikan pemeriksaan sebelum mengizinkan perintah mencapai model AI, periksa kolom invocationResult dalam respons. Jika nilainya adalah PARTIAL, konfigurasikan logika aplikasi Anda untuk menangani permintaan sesuai dengan toleransi risiko organisasi Anda, seperti menolak perintah atau merutekannya untuk peninjauan sekunder.

Contoh respons pemeriksaan parsial

Contoh berikut menunjukkan respons saat filter materi pelecehan seksual terhadap anak-anak (CSAM) dilewati untuk file tersebut, sementara filter lain yang dikonfigurasi menyelesaikan pemeriksaan. Model Armor menampilkan invocationResult PARTIAL, status EXECUTION_SKIPPED untuk filter CSAM, dan EXECUTION_SUCCESS untuk filter lainnya:

{
  "sanitizationResult": {
    "filterMatchState": "NO_MATCH_FOUND",
    "invocationResult": "PARTIAL",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SKIPPED",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "pi_and_jailbreak": {
        "piAndJailbreakFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "inspectResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "NO_MATCH_FOUND"
          }
        }
      }
    }
  }
}

Langkah berikutnya