Mengonfigurasi prasyarat untuk tugas pengayaan

Sebelum dapat membuat tugas pengayaan di Knowledge Studio, Anda mungkin perlu mengonfigurasi beberapa komponen infrastruktur yang mendasarinya, bergantung pada arsitektur keamanan dan sumber data target Anda.

Panduan ini menjelaskan cara mengonfigurasi akun layanan yang dikelola pelanggan, penyedia autentikasi pihak ketiga, bucket Cloud Storage, dan tampilan Cloud Logging.

Tabel berikut menjelaskan konfigurasi prasyarat dan kapan Anda perlu mengonfigurasinya:

Fitur konfigurasi Kapan harus mengonfigurasi
Google Cloud API Wajib. Anda harus mengaktifkan API Google Cloud yang mendasarinya untuk menjalankan alur kerja pengayaan.
Akun layanan yang dikelola pelanggan Anda ingin membatasi akses baca dan tulis pada set data target.
Peran Identity and Access Management (IAM) Pengguna Anda harus memberikan izin kepada pengelola dan peninjau alur kerja untuk membuat dan menyetujui metadata.
Penyedia autentikasi pihak ketiga Anda terhubung ke sumber pengetahuan pihak ketiga (seperti Microsoft SharePoint, Atlassian Confluence, atau GitHub).
Bucket Cloud Storage Anda menyerap konteks bisnis tidak terstruktur (seperti PDF, Markdown, dan CSV) serta set data evaluasi.
Set data evaluasi Anda ingin menyediakan kueri awal dan set data tolok ukur untuk melacak akurasi agen secara aktif.
Jejak Agen untuk pembelajaran mandiri Anda ingin agen pengayaan menganalisis interaksi agen Gemini Enterprise downstream secara otomatis.
Pembuatan profil data dan insight data Direkomendasikan. Anda ingin meningkatkan kualitas pengayaan dengan membuat profil statistik dan insight AI dasar pada tabel yang sering digunakan.

Sebelum memulai

  1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

Detail API yang diperlukan

Untuk mengonfigurasi dan menjalankan tugas pengayaan, API yang diaktifkan menjalankan fungsi berikut:

Nama API Pengenal Layanan Tujuan dalam alur kerja Pengayaan
Dataplex API dataplex.googleapis.com API bidang kontrol utama. Mengelola EnrichmentTask, EnrichmentRun, set konteks, Permintaan Perubahan, dan EnrichmentChatService.
BigQuery API bigquery.googleapis.com Diperlukan untuk memindai skema tabel, menyerap histori eksekusi SQL, dan membuat kueri tabel trace BigQuery Agent Analytics.
Cloud Storage API storage.googleapis.com Diperlukan untuk menyerap set evaluasi dan mengelola sampel set data evaluasi.
IAM Service Account Credentials API iamcredentials.googleapis.com Diperlukan untuk mengautentikasi agen eksekusi dengan aman dan memberikan Kredensial Jangka Pendek (SLC) selama tugas.

Mengonfigurasi akun layanan yang dikelola pelanggan

Tugas pengayaan menggunakan akun layanan yang dikelola pelanggan untuk menjalankan operasi. Dengan demikian, Anda dapat membatasi akses baca dan tulis pada set data target.

  1. Buat akun layanan.

    Untuk membuat akun layanan, Anda harus menjadi Project Owner (roles/owner) atau Editor (roles/editor), atau memiliki peran Service Account Admin (roles/iam.serviceAccountAdmin).

    Akun layanan khusus mengisolasi operasi pengayaan Anda, sehingga Anda hanya dapat memberikan izin baca dan izin tulis tertentu yang diperlukan untuk tugas ini tanpa memengaruhi workload lain.

    Untuk membuat akun layanan, ikuti langkah-langkah berikut:

    Google Cloud CLI

    Untuk membuat akun layanan, gunakan perintah gcloud iam service-accounts create:

    Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

    • SERVICE_ACCOUNT_NAME: nama akun layanan Anda

    Jalankan perintah berikut:

    Linux, macOS, atau Cloud Shell

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" \
    --display-name="Knowledge Catalog enrichment agent SA"

    Windows (PowerShell)

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME `
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" `
    --display-name="Knowledge Catalog enrichment agent SA"

    Windows (cmd.exe)

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME ^
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" ^
    --display-name="Knowledge Catalog enrichment agent SA"

    REST

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • SERVICE_ACCOUNT_NAME: nama akun layanan Anda
    • TARGET_PROJECT_ID: project ID Google Cloud Anda

    Metode HTTP dan URL: 

    POST https://iam.googleapis.com/v1/projects/TARGET_PROJECT_ID/serviceAccounts

    Meminta isi JSON: 

    {
   "accountId": "SERVICE_ACCOUNT_NAME",
   "serviceAccount": {
    "displayName": "Knowledge Catalog enrichment agent SA",
    "description": "Service Account for Dataplex Knowledge Catalog enrichment agent execution"
   }
  }

    Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

    Anda akan menerima kode status berhasil (2xx) dan respons kosong.

  2. Berikan peran IAM level resource yang diperlukan ke akun layanan eksekusi pada cakupan target Anda:

    • Dataplex Catalog Editor (roles/dataplex.catalogEditor) dan Dataplex Catalog Viewer (roles/dataplex.catalogViewer): Memungkinkan agen memeriksa metadata katalog, membuat entri kerja bertahap, dan memublikasikan pengayaan yang disetujui secara manual.
    • (Opsional) Dataplex Workflow Approver (roles/dataplex.workflowApprover): Hanya diperlukan jika Anda mengaktifkan Auto-publish pada tugas Anda. Memungkinkan agen menyetujui dan memublikasikan permintaan perubahan metadatanya sendiri secara otomatis.
    • BigQuery Data Viewer (roles/bigquery.dataViewer): Memungkinkan agen membaca skema tabel, metadata kolom, dan tabel trace analisis agen.

    Catatan: Contoh kode berikut memberikan peran ini di level project untuk memudahkan penyiapan. Untuk sistem produksi, sebaiknya berikan peran ini dengan aman di level resource pada set data target tertentu.

    Untuk memberikan peran standar ini, ikuti langkah-langkah berikut:

    Untuk menambahkan binding kebijakan IAM ke project, gunakan perintah gcloud projects add-iam-policy-binding:

    Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

    • SERVICE_ACCOUNT_NAME: nama akun layanan Anda
    • TARGET_PROJECT_ID: project ID Google Cloud Anda

    Jalankan perintah berikut:

    Linux, macOS, atau Cloud Shell

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/bigquery.dataViewer"

    Windows (PowerShell)

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/bigquery.dataViewer"

    Windows (cmd.exe)

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/bigquery.dataViewer"

  3. Beri pengguna izin untuk meniru akun layanan dengan memberi mereka peran Service Account User (roles/iam.serviceAccountUser):

    Pengguna yang membuat tugas pengayaan di konsol harus memiliki izin ini agar dapat menentukan dan melampirkan akun layanan ini ke tugas.

    Untuk memberikan peran Service Account User kepada pengguna, ikuti langkah-langkah berikut:

    Untuk menambahkan binding kebijakan IAM ke akun layanan, gunakan perintah gcloud iam service-accounts add-iam-policy-binding:

    Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

    • SERVICE_ACCOUNT_NAME: nama akun layanan Anda
    • TARGET_PROJECT_ID: project ID Google Cloud Anda
    • USER_EMAIL: alamat email pengguna

    Jalankan perintah berikut:

    Linux, macOS, atau Cloud Shell

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="user:USER_EMAIL@domain.com" \
    --role="roles/iam.serviceAccountUser"

    Windows (PowerShell)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="user:USER_EMAIL@domain.com" `
    --role="roles/iam.serviceAccountUser"

    Windows (cmd.exe)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="user:USER_EMAIL@domain.com" ^
    --role="roles/iam.serviceAccountUser"

  4. Izinkan agen layanan Knowledge Catalog internal untuk meniru identitas akun layanan ini dengan memberinya peran Token Akun Layanan Service Account Token Creator (roles/iam.serviceAccountTokenCreator):

    Hal ini memungkinkan layanan Knowledge Catalog yang mendasarinya mengasumsikan identitas akun layanan khusus ini dan izin terbatasnya saat menjalankan operasi pengayaan latar belakang atas nama Anda.

    Untuk mengizinkan agen mengasumsikan identitas akun layanan, ikuti langkah-langkah berikut:

    Untuk menambahkan binding kebijakan IAM ke akun layanan, gunakan perintah gcloud iam service-accounts add-iam-policy-binding:

    Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

    • SERVICE_ACCOUNT_NAME: nama akun layanan Anda
    • TARGET_PROJECT_ID: project ID Google Cloud Anda
    • TARGET_PROJECT_NUMBER: nomor project Google Cloud Anda

    Jalankan perintah berikut:

    Linux, macOS, atau Cloud Shell

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"

    Windows (PowerShell)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" `
    --role="roles/iam.serviceAccountTokenCreator"

    Windows (cmd.exe)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" ^
    --role="roles/iam.serviceAccountTokenCreator"

Memberikan peran IAM yang diperlukan kepada pengguna

Untuk memastikan tim Anda dapat mengelola alur kerja pengayaan dan meninjau proposal yang dihasilkan AI, berikan peran IAM yang sesuai kepada pengguna Anda. Untuk mengetahui petunjuk tentang cara memberikan peran ini, lihat Mengelola akses ke project, folder, dan organisasi.

Pengelola alur kerja (seperti data steward) yang membuat, mengonfigurasi, dan memantau tugas memerlukan peran berikut:

  • Dataplex DataScan Editor (roles/dataplex.dataScanEditor) atau Dataplex Editor (roles/dataplex.editor): memungkinkan pengguna membuat, mengubah, memicu, dan membatalkan tugas pengayaan.
  • Pengguna Akun Layanan (roles/iam.serviceAccountUser) di akun layanan yang dikelola pelanggan: diperlukan untuk melampirkan akun layanan sebagai identitas eksekusi tugas.

Peninjau perubahan (seperti pemilik domain atau pakar materi subjek) yang memeriksa, menyetujui, dan memublikasikan proposal metadata buatan AI ke katalog memerlukan peran berikut:

  • Dataplex Catalog Editor (roles/dataplex.catalogEditor) dan Dataplex Catalog Viewer (roles/dataplex.catalogViewer): diperlukan untuk membuka permintaan perubahan, memeriksa perbedaan proposal secara berdampingan, dan mengedit deskripsi secara inline.
  • Pemberi Persetujuan Alur Kerja Dataplex (roles/dataplex.workflowApprover): diperlukan untuk menyetujui dan memublikasikan permintaan perubahan ke katalog aktif.
  • Dataplex DataScan Viewer (roles/dataplex.dataScanViewer) atau Dataplex Viewer (roles/dataplex.viewer): diperlukan untuk meninjau skor keyakinan per proposal, diagnosis kegagalan pengujian, dan scorecard evaluasi downstream.

Mengonfigurasi penyedia autentikasi pihak ketiga

Saat menghubungkan agen pengayaan ke sumber pengetahuan pihak ketiga (seperti Microsoft SharePoint, Atlassian Confluence, atau GitHub), Anda harus mengonfigurasi Penyedia Autentikasi menggunakan layanan Agent Identity Google Cloud.

Agent Identity bertindak sebagai pengelola kredensial keamanan yang mengenkripsi token pihak ketiga Anda di dalam project, sehingga memastikan bahwa operator manusia tidak perlu menangani rahasia klien mentah selama eksekusi tugas.

Untuk mengetahui petunjuk langkah demi langkah tentang cara membuat token yang diperlukan dan mengonfigurasi penyedia autentikasi untuk platform eksternal tertentu, lihat Mengonfigurasi konektor eksternal untuk tugas pengayaan.

Menyiapkan izin IAM untuk penyedia autentikasi

Agar agen pengayaan dapat mengambil kredensial penyedia autentikasi Anda dengan aman secara dinamis selama operasi aktif, Anda harus memberikan peran Agent Identity Admin (roles/agentidentity.admin) kepada Knowledge Catalog Service Agent (service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com) terkelola. Anda dapat memberikan peran ini di tingkat resource penyedia autentikasi atau tingkat project.

Selain itu, pengguna manusia yang melampirkan penyedia autentikasi ke tugas di konsolGoogle Cloud harus memiliki izin agentidentity.authProviders.get (disertakan dalam Agent Identity Viewer (roles/agentidentity.viewer)) di penyedia autentikasi.

Menyiapkan bucket Cloud Storage

Cloud Storage berfungsi sebagai lapisan staging berbasis file, penyerapan konteks, dan ekspor artefak utama untuk alur kerja pengayaan pengetahuan.

Anda dapat mengonfigurasi agen untuk menyerap file dari satu atau beberapa bucket input untuk melakukan grounding penalarannya dalam pengetahuan domain perusahaan Anda. Jenis konteks yang didukung meliputi:

  • Dokumentasi domain dan kamus data: File Markdown, teks biasa, PDF, HTML, atau CSV yang berisi definisi tabel, glosarium bisnis, Prosedur Operasi Standar (SOP), arsitektur pipeline data, atau panduan penamaan kolom.

  • Set data evaluasi: File JSONL atau CSV yang menyimpan kueri seed dan set kueri validasi yang di-holdout. Untuk mengetahui informasi selengkapnya, lihat Memformat set data evaluasi.

  • Skrip SQL dan transformasi referensi: Skrip SQL yang disimpan, definisi model dbt, atau logika transformasi ETL yang memberikan sinyal kontekstual terkait pola gabungan tabel dan penghitungan bisnis.

Jika dikonfigurasi, agen pengayaan juga dapat mengekspor paket terstruktur dan menjalankan artefak ke bucket output. Artefak output yang didukung meliputi:

  • Laporan evaluasi mendetail: Kartu skor komprehensif yang menampilkan delta akurasi per kueri, diagnosis kegagalan pengujian, dan metrik distribusi keyakinan.

Untuk memastikan agen pengayaan dapat bekerja di luar bucket, pastikan akun layanan eksekusi Anda memiliki izin yang diperlukan.

  • Berikan peran Object Viewer (roles/storage.objectViewer) pada bucket input agar agen dapat membaca dokumen tahapan dan file konfigurasi.
  • (Opsional) Berikan peran Object Creator (roles/storage.objectCreator) pada bucket output jika Anda ingin agen menyimpan artefak eksekusi dan log validasi.

Untuk memberi akun layanan akses ke bucket Cloud Storage, ikuti langkah-langkah berikut:

Untuk menambahkan binding kebijakan IAM ke bucket penyimpanan, gunakan perintah gcloud storage buckets add-iam-policy-binding:

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • CUSTOMER_BUCKET: nama bucket Cloud Storage Anda
  • SERVICE_ACCOUNT_NAME: nama akun layanan Anda
  • TARGET_PROJECT_ID: project ID Google Cloud Anda

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Windows (PowerShell)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/storage.objectViewer"

Windows (cmd.exe)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/storage.objectViewer"

Memformat set data evaluasi

Alur kerja pengayaan dapat otomatis mengekstrak informasi tanpa contoh. Namun, menyediakan set data evaluasi memungkinkan agen menguji dirinya sendiri dan meningkatkan akurasinya.

Anda dapat menyediakan dua jenis set data:

  • Set seleksi: Daftar contoh pertanyaan pengguna dan kueri SQL yang diharapkan. Agen menggunakan daftar ini untuk berlatih dan menulis ringkasan tabel yang lebih baik.

  • Set evaluasi: Daftar pertanyaan terpisah yang digunakan untuk menilai performa agen. Jika agen berperforma buruk, set evaluasi ini mencegah update yang buruk dipublikasikan ke katalog Anda.

Atau, Anda dapat memberikan satu set data gabungan. Layanan pengayaan secara otomatis mempartisi data menjadi set seleksi dan set evaluasi.

Persyaratan skema set data

Set data evaluasi harus diformat sebagai file JSONL dan disimpan di Cloud Storage. Setiap baris dalam file harus berisi pertanyaan bahasa alami yang dipasangkan dengan kueri SQL kebenaran nyata yang diharapkan.

Pastikan file Anda cocok dengan skema set data evaluasi yang ditentukan oleh Gemini Enterprise Agent Platform. Tabel berikut menunjukkan kolom pemformatan yang diterima:

Nama kolom Jenis Deskripsi
display_name STRING Opsional. ID atau nama untuk permintaan evaluasi.
evaluation_request.prompt.text STRING Pertanyaan bahasa alami atau perintah pengguna.
evaluation_request.golden_response.candidate STRING Mengidentifikasi respons emas. Tetapkan ke golden.
evaluation_request.golden_response.text STRING Kebenaran nyata, kueri SQL yang divalidasi yang menjawab pertanyaan. Scorer menjalankan SQL ini terhadap data.

Cuplikan berikut menunjukkan file evaluasi .jsonl yang valid:

{"display_name": "revenue-2026", "evaluation_request": {"prompt": {"text": "What is total revenue for customer C100 in 2026?"}, "golden_response": {"candidate": "golden", "text": "SELECT SUM(amount) FROM `project.dataset.orders` WHERE customer_id = 'C100' AND EXTRACT(YEAR FROM order_date) = 2026;"}}}
{"display_name": "monthly-subscribers", "evaluation_request": {"prompt": {"text": "List active subscribers on monthly billing"}, "golden_response": {"candidate": "golden", "text": "SELECT user_id, email FROM `project.dataset.subscriptions` WHERE status = 'ACTIVE' AND plan_type = 'MONTHLY';"}}}

Untuk panduan mendetail tentang cara membuat set data evaluasi berkualitas tinggi, lihat dokumentasi Gemini Enterprise Agent Platform.

Mengonfigurasi trace agen untuk pembelajaran mandiri

Agar agen pengayaan dapat otomatis menganalisis interaksi agen Gemini Enterprise downstream (atau aplikasi Gemini Enterprise Agent Platform kustom), Anda dapat memberikan akses baca ke trace interaksi aplikasi Anda.

Penyerapan trace ini memungkinkan agen melakukan penggalian lintasan. Agen menemukan bagian yang menyulitkan agen downstream karena konteks yang tidak ada, mengelompokkan pertanyaan pengguna yang sering diajukan ke dalam class kueri berdampak tinggi, dan secara otomatis mengumpulkan ringkasan tabel, semantik kolom, dan istilah glosarium bisnis yang tepat yang diperlukan untuk mengatasi kesenjangan tersebut.

Bergantung pada arsitektur perusahaan Anda, pilih salah satu dari dua metode penyiapan berikut:

Logging Langsung menggunakan tampilan log tercakup (Direkomendasikan)

Jika logging interaksi diaktifkan untuk aplikasi, log eksekusi akan di-streaming langsung ke Logging. Untuk mengikuti prinsip hak istimewa terendah, buat Tampilan Log khusus yang dibatasi untuk aplikasi tertentu dan berikan akses baca akun layanan eksekusi secara eksklusif pada tampilan tersebut.

  1. Membuat tampilan log tercakup untuk mengisolasi log. Hal ini memastikan layanan pengayaan hanya membaca telemetri dari aplikasi tertentu yang dikonfigurasi (misalnya, dengan memfilter resource.type="aiplatform.googleapis.com/Agent"), sehingga mencegah akses yang tidak sah ke log Cloud Anda yang lebih luas.

    gcloud CLI

    Untuk membuat tampilan log tercakup, gunakan perintah gcloud logging views create:

    Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

    • LOG_VIEW_NAME: nama tampilan log Anda
    • YOUR_GEMINI_ENTERPRISE_APP_ID: ID aplikasi Gemini Enterprise Anda

    Jalankan perintah berikut:

    Linux, macOS, atau Cloud Shell

    gcloud logging views create LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    Windows (PowerShell)

    gcloud logging views create LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    Windows (cmd.exe)

    gcloud logging views create LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    REST

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • LOG_VIEW_NAME: nama tampilan log Anda
    • TARGET_PROJECT_ID: project ID Google Cloud Anda
    • YOUR_GEMINI_ENTERPRISE_APP_ID: ID aplikasi Gemini Enterprise Anda

    Metode HTTP dan URL: 

    POST https://logging.googleapis.com/v2/projects/TARGET_PROJECT_ID/locations/global/buckets/_Default/views?viewId=LOG_VIEW_NAME

    Meminta isi JSON: 

    {
 "filter": "resource.type=\"aiplatform.googleapis.com/Agent\" AND resource.labels.agent_id=\"YOUR_GEMINI_ENTERPRISE_APP_ID\""
}

    Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

    Anda akan menerima kode status berhasil (2xx) dan respons kosong.

  2. Setelah Anda membuat tampilan log, berikan akses baca ke akun layanan eksekusi. Tindakan ini akan memberikan otorisasi kepada tugas pengayaan untuk mengambil telemetri aplikasi yang diperlukan selama fase pembelajaran mandiri.

    Untuk menambahkan binding kebijakan IAM ke tampilan log, gunakan perintah gcloud logging views add-iam-policy-binding:

    Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

    • LOG_VIEW_NAME: nama tampilan log Anda
    • SERVICE_ACCOUNT_NAME: nama akun layanan Anda
    • TARGET_PROJECT_ID: project ID Google Cloud Anda

    Jalankan perintah berikut:

    Linux, macOS, atau Cloud Shell

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/logging.viewAccessor"

    Windows (PowerShell)

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/logging.viewAccessor"

    Windows (cmd.exe)

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/logging.viewAccessor"

Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi tampilan log di bucket log.

BigQuery Agent Analytics

Jika organisasi Anda melakukan streaming log interaksi ke BigQuery menggunakan sink log Logging atau menulis langsung ke tabel analisis agen BigQuery, Anda dapat memberikan akses ke set data tersebut.

Pastikan log interaksi dikonfigurasi untuk di-streaming ke set data BigQuery yang ditentukan, dan pastikan akun layanan eksekusi diberi peran BigQuery Data Viewer (roles/bigquery.dataViewer) pada set data tertentu tersebut. Hal ini memungkinkan agen membaca telemetri yang diekspor langsung dari BigQuery.

Untuk mengetahui informasi selengkapnya tentang cara mengekspor log, lihat Merutekan log ke tujuan yang didukung.

Mengaktifkan pembuatan profil data dan insight data

Sebelum menjalankan tugas pengayaan, sebaiknya aktifkan pembuatan profil data dan insight data AI pada tabel target yang sering Anda gunakan. Pembuatan profil data memberikan karakteristik statistik—seperti nilai umum, distribusi data, dan jumlah null—sementara insight data menghasilkan deskripsi tabel dasar dan contoh kueri. Dengan memberikan sinyal ini, agen pengayaan dapat menghasilkan proposal metadata yang lebih akurat.

Langkah berikutnya