Menggunakan kontrol akses sumber data

Halaman ini menjelaskan cara menerapkan kontrol akses sumber data untuk aplikasi penelusuran di Vertex AI Agent Builder.

Kontrol akses untuk sumber data Anda di Vertex AI Agent Builder membatasi data yang dapat dilihat pengguna di hasil aplikasi penelusuran Anda. Google menggunakan penyedia identitas Anda untuk mengidentifikasi pengguna akhir yang melakukan penelusuran dan menentukan apakah mereka memiliki akses ke dokumen yang ditampilkan sebagai hasil.

Misalnya, karyawan di perusahaan Anda menelusuri dokumen Confluence menggunakan aplikasi penelusuran Anda. Namun, Anda harus memastikan mereka tidak dapat melihat konten melalui aplikasi yang tidak diizinkan untuk diakses. Jika telah menyiapkan kumpulan tenaga kerja di Google Cloud untuk penyedia identitas organisasi, Anda juga dapat menentukan kumpulan tenaga kerja tersebut di Vertex AI Agent Builder. Sekarang, jika karyawan menggunakan aplikasi Anda, mereka hanya akan mendapatkan hasil penelusuran untuk dokumen yang sudah diakses oleh akun mereka di Confluence.

Tentang kontrol akses sumber data

Mengaktifkan kontrol akses adalah prosedur satu kali.

Kontrol akses tersedia untuk Cloud Storage, BigQuery, Google Drive, dan semua sumber data pihak ketiga.

Untuk mengaktifkan kontrol akses sumber data bagi Vertex AI Agent Builder, Anda harus mengonfigurasi penyedia identitas organisasi di Google Cloud. Framework autentikasi berikut didukung:

  • Identitas Google: Jika Anda menggunakan Identitas Google, semua identitas pengguna dan grup pengguna akan ada dan dikelola melalui Google Cloud. Untuk informasi selengkapnya tentang Google Identity, lihat dokumentasi Google Identity.

  • Federasi penyedia identitas pihak ketiga: Jika menggunakan penyedia identitas eksternal, misalnya Okta atau Azure AD, Anda harus menyiapkan workforce identity federation di Google Cloud sebelum dapat mengaktifkan kontrol akses sumber data untuk Vertex AI Agent Builder.

    Jika Anda menggunakan konektor pihak ketiga, atribut google.subject harus dipetakan ke kolom alamat email di penyedia identitas eksternal. Berikut adalah contoh pemetaan atribut google.subject dan google.groups untuk penyedia identitas yang umum digunakan:

Batasan

Kontrol akses memiliki batasan berikut:

  • 250 pembaca diizinkan per dokumen. Setiap akun utama dihitung sebagai pembaca, dengan akun utama dapat berupa grup atau pengguna individu.
  • Anda dapat memilih satu penyedia identitas per lokasi yang didukung Vertex AI Search.
  • Kontrol akses hanya diberlakukan untuk identitas dan grup yang ditentukan secara eksplisit di penyedia identitas Anda. Identitas atau grup yang ditentukan secara native dalam aplikasi pihak ketiga tidak didukung.
  • Untuk menetapkan sumber data sebagai dikontrol akses, Anda harus memilih setelan ini selama pembuatan penyimpanan data. Anda tidak dapat mengaktifkan atau menonaktifkan setelan ini untuk penyimpanan data yang ada.
  • Tab Data > Documents di konsol tidak menampilkan data untuk sumber data yang dikontrol akses karena data ini hanya boleh dilihat oleh pengguna yang memiliki akses lihat.
  • Untuk melihat pratinjau hasil UI aplikasi penelusuran yang menggunakan kontrol akses pihak ketiga, Anda harus login ke konsol gabungan atau menggunakan aplikasi web. Lihat Melihat pratinjau hasil untuk aplikasi yang dikontrol akses.

Sebelum memulai

Prosedur ini mengasumsikan bahwa Anda telah menyiapkan penyedia identitas di project Google Cloud Anda.

  • Identitas Google: Jika menggunakan Identitas Google, Anda dapat melanjutkan ke prosedur Menghubungkan ke penyedia identitas.
  • Penyedia identitas pihak ketiga: Pastikan Anda telah menyiapkan workforce identity pool untuk penyedia identitas pihak ketiga. Pastikan Anda telah menentukan pemetaan atribut subjek dan grup saat menyiapkan kumpulan tenaga kerja. Untuk informasi tentang pemetaan atribut, lihat Pemetaan atribut dalam dokumentasi IAM. Untuk mengetahui informasi selengkapnya tentang workforce identity pool, lihat Mengelola penyedia workforce identity pool dalam dokumentasi IAM.

Menghubungkan ke penyedia identitas Anda

Untuk menentukan penyedia identitas bagi Vertex AI Agent Builder dan mengaktifkan kontrol akses sumber data, ikuti langkah-langkah berikut:

  1. Di konsol Google Cloud, buka halaman Agent Builder.

    Agent Builder

  2. Buka halaman Settings > Authentication.

  3. Klik Tambahkan penyedia identitas untuk lokasi yang ingin Anda perbarui.

  4. Pilih penyedia identitas Anda di dialog Tambahkan penyedia identitas. Jika Anda memilih penyedia identitas pihak ketiga, pilih juga kumpulan tenaga kerja yang berlaku untuk sumber data Anda.

  5. Klik Simpan perubahan.

Mengonfigurasi sumber data dengan kontrol akses

Untuk menerapkan kontrol akses ke sumber data, gunakan langkah-langkah berikut, bergantung pada jenis sumber data yang Anda siapkan:

Data tidak terstruktur dari Cloud Storage

Saat menyiapkan penyimpanan data untuk data tidak terstruktur dari Cloud Storage, Anda juga harus mengupload metadata ACL dan menetapkan penyimpanan data sebagai akses yang dikontrol:

  1. Saat menyiapkan data, sertakan informasi ACL dalam metadata menggunakan kolom acl_info. Contoh:

    {
   "id": "<your-id>",
   "jsonData": "<JSON string>",
   "content": {
     "mimeType": "<application/pdf or text/html>",
     "uri": "gs://<your-gcs-bucket>/directory/filename.pdf"
   },
   "acl_info": {
     "readers": [
       {
         "principals": [
           { "group_id": "group_1" },
           { "user_id": "user_1" }
         ]
       }
     ]
   }
 }

    Untuk mengetahui informasi selengkapnya tentang data tidak terstruktur dengan metadata, lihat bagian Data tidak terstruktur di Menyiapkan data untuk proses transfer.

  2. Saat mengikuti langkah-langkah pembuatan penyimpanan data di Membuat penyimpanan data penelusuran, Anda dapat mengaktifkan kontrol akses dengan melakukan hal berikut di konsol atau menggunakan API:

    • Konsol: Saat membuat penyimpanan data, pilih Penyimpanan data ini berisi informasi kontrol akses selama pembuatan penyimpanan data.
    • API: Saat membuat penyimpanan data, sertakan tanda "aclEnabled": "true" dalam payload JSON Anda.

  3. Saat mengikuti langkah-langkah untuk impor data di Membuat penyimpanan data penelusuran, pastikan untuk melakukan hal berikut:

    • Upload metadata dengan informasi ACL dari bucket yang sama dengan data tidak terstruktur Anda
    • Jika menggunakan API, tetapkan GcsSource.dataSchema ke document

Data terstruktur dari Cloud Storage

Saat menyiapkan penyimpanan data untuk data terstruktur dari Cloud Storage, Anda juga harus mengupload metadata ACL dan menetapkan penyimpanan data sebagai akses yang dikontrol:

  1. Saat menyiapkan data, sertakan informasi ACL dalam metadata menggunakan kolom acl_info. Contoh:

    {
   "id": "<your-id>",
   "jsonData": "<JSON string>",
   "acl_info": {
     "readers": [
       {
         "principals": [
           { "group_id": "group_1" },
           { "user_id": "user_1" }
         ]
       }
     ]
   }
 }

  2. Saat mengikuti langkah-langkah pembuatan penyimpanan data di Membuat penyimpanan data penelusuran, Anda dapat mengaktifkan kontrol akses dengan melakukan hal berikut di konsol atau menggunakan API:

    • Konsol: Saat membuat penyimpanan data, pilih Penyimpanan data ini berisi informasi kontrol akses selama pembuatan penyimpanan data.
    • API: Saat membuat penyimpanan data, sertakan tanda "aclEnabled": "true" dalam payload JSON Anda.

  3. Saat mengikuti langkah-langkah untuk impor data di Membuat penyimpanan data penelusuran, pastikan untuk melakukan hal berikut:

    • Upload metadata dengan informasi ACL dari bucket yang sama dengan data tidak terstruktur Anda
    • Jika menggunakan API, tetapkan GcsSource.dataSchema ke document

Data tidak terstruktur dari BigQuery

Saat menyiapkan penyimpanan data untuk data tidak terstruktur dari BigQuery, Anda perlu menetapkan penyimpanan data sebagai akses yang dikontrol dan memberikan metadata ACL menggunakan skema yang telah ditentukan untuk Vertex AI Search:

  1. Saat menyiapkan data, tentukan skema berikut. Jangan gunakan skema kustom.

    [
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "content",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mimeType",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
  {
    "name": "acl_info",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "readers",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
          {
            "name": "principals",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
              {
                "name": "user_id",
                "type": "STRING",
                "mode": "NULLABLE"
              },
              {
                "name": "group_id",
                "type": "STRING",
                "mode": "NULLABLE"
              }
            ]
          }
        ]
      }
    ]
  }
]

  2. Sertakan metadata ACL sebagai kolom di tabel BigQuery.

  3. Saat mengikuti langkah-langkah di Membuat penyimpanan data penelusuran, aktifkan kontrol akses di konsol atau menggunakan API:

    • Konsol: Saat membuat penyimpanan data, pilih Penyimpanan data ini berisi informasi kontrol akses selama pembuatan penyimpanan data.
    • API: Saat membuat penyimpanan data, sertakan tanda "aclEnabled": "true" dalam payload JSON Anda.

  4. Saat mengikuti langkah-langkah untuk impor data di Membuat penyimpanan data penelusuran, jika menggunakan API, tetapkan BigQuerySource.dataSchema ke document.

Data terstruktur dari BigQuery

Saat menyiapkan penyimpanan data untuk data terstruktur dari BigQuery, Anda perlu menetapkan penyimpanan data sebagai akses yang dikontrol dan memberikan metadata ACL menggunakan skema yang telah ditentukan untuk Vertex AI Search:

  1. Saat menyiapkan data, tentukan skema berikut. Jangan gunakan skema kustom.

    [
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "acl_info",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "readers",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
          {
            "name": "principals",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
              {
                "name": "user_id",
                "type": "STRING",
                "mode": "NULLABLE"
              },
              {
                "name": "group_id",
                "type": "STRING",
                "mode": "NULLABLE"
              }
            ]
          }
        ]
      }
    ]
  }
]

  2. Sertakan metadata ACL sebagai kolom di tabel BigQuery.

  3. Saat mengikuti langkah-langkah di Membuat penyimpanan data penelusuran, aktifkan kontrol akses di konsol atau menggunakan API:

    • Konsol: Saat membuat penyimpanan data, pilih Penyimpanan data ini berisi informasi kontrol akses selama pembuatan penyimpanan data.
    • API: Saat membuat penyimpanan data, sertakan tanda "aclEnabled": "true" dalam payload JSON Anda.

  4. Saat mengikuti langkah-langkah untuk impor data di Membuat penyimpanan data penelusuran, pastikan untuk melakukan hal berikut:

    • Jika menggunakan konsol, saat menentukan jenis data yang Anda upload, pilih JSONL untuk data terstruktur dengan metadata
    • Jika menggunakan API, tetapkan BigQuerySource.dataSchema ke document

Melihat pratinjau hasil untuk aplikasi dengan kontrol akses pihak ketiga

Untuk melihat pratinjau hasil di konsol untuk aplikasi dengan kontrol akses pihak ketiga, Anda harus login dengan kredensial organisasi.

Anda dapat melihat pratinjau hasil UI dengan dua cara:

Melihat pratinjau hasil di konsol Workforce Identity Federation

Ikuti langkah-langkah berikut untuk menggunakan konsol Workforce Identity Federation guna melihat hasilnya:

  1. Di konsol Google Cloud, buka halaman Agent Builder.

    Agent Builder

  2. Klik nama aplikasi penelusuran yang hasilnya ingin Anda lihat pratinjaunya.

  3. Buka halaman Pratinjau.

  4. Klik Pratinjau dengan identitas gabungan untuk membuka konsol Workforce Identity Federation.

  5. Masukkan kredensial penyedia dan organisasi workforce pool Anda.

  6. Lihat pratinjau hasil untuk aplikasi Anda di halaman Pratinjau yang muncul.

    Untuk informasi selengkapnya tentang cara melihat pratinjau hasil penelusuran, lihat Mendapatkan hasil penelusuran.

Untuk informasi selengkapnya tentang konsol Workforce Identity Federation, lihat Tentang konsol (gabungan).

Memberikan izin penelusuran kepada pengguna

Untuk memberi pengguna kemampuan menelusuri data yang dikontrol akses menggunakan aplikasi, Anda harus memberikan akses kepada pengguna di domain atau kumpulan tenaga kerja Anda. Google menyarankan agar Anda memberikan peran IAM kustom ke grup pengguna.

  • Identitas Google: Jika Anda menggunakan Identitas Google, Google merekomendasikan agar Anda membuat grup Google yang menyertakan semua karyawan yang perlu melakukan penelusuran. Jika Anda adalah administrator Google Workspace, Anda dapat menyertakan semua pengguna di organisasi dalam grup Google dengan mengikuti langkah-langkah di Menambahkan semua pengguna organisasi ke grup.
  • Penyedia identitas pihak ketiga: Jika Anda menggunakan penyedia identitas eksternal, misalnya Okta atau Azure AD, tambahkan semua orang dalam kumpulan tenaga kerja Anda ke satu grup.

Google merekomendasikan agar Anda membuat peran IAM khusus untuk diberikan kepada grup pengguna, menggunakan izin berikut:

  • discoveryengine.answers.get
  • discoveryengine.servingConfigs.answer
  • discoveryengine.servingConfigs.search
  • discoveryengine.sessions.get

Untuk mengetahui informasi selengkapnya tentang izin untuk resource Vertex AI Agent Builder yang menggunakan Identity and Access Management (IAM), lihat Kontrol akses dengan IAM.

Untuk mengetahui informasi selengkapnya tentang peran khusus, lihat Peran khusus dalam dokumentasi IAM.

Memberi otorisasi widget penelusuran

Jika Anda ingin men-deploy widget penelusuran untuk aplikasi yang dikontrol akses, ikuti langkah-langkah berikut:

  1. Berikan peran Penampil Mesin Penemuan kepada pengguna di domain atau kumpulan tenaga kerja Anda yang perlu melakukan panggilan API penelusuran.

  2. Buat token otorisasi untuk diteruskan ke widget Anda:

  3. Ikuti langkah-langkah di Menambahkan widget dengan token otorisasi untuk meneruskan token ke widget Anda.

Mengaktifkan aplikasi web

Aplikasi web adalah situs khusus yang dibuat oleh Vertex AI Search tempat Anda dan pengguna lain dengan kredensial login dapat menggunakan aplikasi penelusuran Anda.

Untuk menyediakan aplikasi penelusuran kepada pengguna tanpa perlu mengintegrasikan widget penelusuran atau API penelusuran di aplikasi Anda sendiri, Anda dapat memberikan URL aplikasi web kepada pengguna.

Ikuti langkah-langkah berikut untuk mengaktifkan aplikasi web:

  1. Di konsol Google Cloud, buka halaman Agent Builder.

    Agent Builder

  2. Klik nama aplikasi penelusuran yang ingin Anda buat aplikasi webnya.

    Aplikasi penelusuran harus dikaitkan dengan setidaknya satu sumber data dengan kontrol akses. Untuk informasi selengkapnya, lihat Mengonfigurasi sumber data dengan kontrol akses.

  3. Buka tab Integrasi > UI.

  4. Klik Aktifkan aplikasi web.

  5. Jika Anda menggunakan workforce identity federation, pilih penyedia kumpulan tenaga kerja.

  6. Klik link ke aplikasi web Anda.

  7. Masukkan kredensial penyedia dan organisasi workforce pool Anda.

  8. Melihat pratinjau hasil untuk aplikasi Anda.

  9. Untuk mengonfigurasi hasil untuk aplikasi web, buka Mengonfigurasi hasil untuk widget penelusuran. Semua konfigurasi untuk widget juga diterapkan ke aplikasi web.

  10. Opsional: Untuk menyediakan aplikasi penelusuran kepada pengguna melalui aplikasi web khusus ini, salin URL dan kirimkan kepada pengguna yang memiliki kredensial login. Mereka dapat mem-bookmark URL aplikasi web dan membukanya untuk menggunakan aplikasi penelusuran Anda.

Untuk informasi selengkapnya tentang cara mendapatkan hasil penelusuran, lihat Mendapatkan hasil penelusuran.