Membuat penyematan gambar menggunakan fungsi ML.GENERATE_EMBEDDING

Dokumen ini menunjukkan cara membuat model jarak jauh BigQuery ML yang merujuk pada model penyematan Vertex AI. Kemudian, Anda menggunakan model tersebut dengan fungsi ML.GENERATE_EMBEDDING untuk membuat penyematan gambar menggunakan data dari tabel objek BigQuery.

Peran yang diperlukan

  • Untuk membuat koneksi, Anda memerlukan keanggotaan dalam peran Identity and Access Management (IAM) berikut:

    • roles/bigquery.connectionAdmin

  • Untuk memberikan izin ke akun layanan koneksi, Anda memerlukan izin berikut:

    • resourcemanager.projects.setIamPolicy

  • Untuk membuat tabel objek, Anda memerlukan izin berikut:

    • bigquery.tables.create
    • bigquery.tables.update
    • bigquery.connections.delegate

  • Untuk membuat model menggunakan BigQuery ML, Anda memerlukan izin IAM berikut:

    • bigquery.jobs.create
    • bigquery.models.create
    • bigquery.models.getData
    • bigquery.models.updateData
    • bigquery.models.updateMetadata

  • Untuk menjalankan inferensi, Anda memerlukan izin berikut:

    • bigquery.tables.getData pada tabel
    • bigquery.models.getData pada model
    • bigquery.jobs.create

Sebelum memulai

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

    Go to project selector

  2. Make sure that billing is enabled for your Google Cloud project.

  3. Enable the BigQuery, BigQuery Connection, Cloud Storage, and Vertex AI APIs.

    Enable the APIs

Membuat set data

Buat set data BigQuery untuk menyimpan tabel dan model objek Anda.

Konsol

  1. Di Konsol Google Cloud, buka halaman BigQuery.

    Buka halaman BigQuery

  2. Di panel Explorer, klik nama project Anda.

  3. Klik View actions > Create dataset.

  4. Di halaman Create dataset, lakukan hal berikut:

    • Untuk ID Set Data, ketik nama untuk set data.

    • Untuk Location type, pilih lokasi untuk set data.

    • Klik Create dataset.

bq

  1. Untuk membuat set data baru, gunakan perintah bq mk dengan flag --location:

    bq --location=LOCATION mk -d DATASET_ID

    Ganti kode berikut:

    • LOCATION: lokasi set data.
    • DATASET_ID: ID set data yang Anda buat.

  2. Pastikan set data telah dibuat:

    bq ls

Membuat koneksi

Buat koneksi resource Cloud dan dapatkan akun layanan koneksi. Buat koneksi di lokasi yang sama dengan set data yang Anda buat di langkah sebelumnya.

Pilih salah satu opsi berikut:

Konsol

  1. Buka halaman BigQuery.

    Buka BigQuery

  2. Di panel Penjelajah, klik Tambahkan data.

    Dialog Add data akan terbuka.

  3. Di panel Filter By, di bagian Data Source Type, pilih Databases.

    Atau, di kolom Search for data sources, Anda dapat memasukkan Vertex AI.

  4. Di bagian Sumber data unggulan, klik Vertex AI.

  5. Klik kartu solusi Vertex AI Models: BigQuery Federation.

  6. Dalam daftar Connection type, pilih Vertex AI remote models, remote functions and BigLake (Cloud Resource).

  7. Di kolom Connection ID, masukkan nama untuk koneksi Anda.

  8. Klik Create connection.

  9. Klik Go to connection.

  10. Di panel Connection info, salin ID akun layanan untuk digunakan di langkah berikutnya.

bq

  1. Di lingkungan command line, buat koneksi:

    bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID

    Parameter --project_id akan mengganti project default.

    Ganti kode berikut:

    • REGION: region koneksi Anda
    • PROJECT_ID: project ID Google Cloud Anda
    • CONNECTION_ID: ID untuk koneksi Anda

    Saat Anda membuat resource koneksi, BigQuery akan membuat akun layanan sistem unik dan mengaitkannya dengan koneksi.

    Pemecahan masalah: Jika Anda mendapatkan error koneksi berikut, update Google Cloud SDK:

    Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...

  2. Ambil dan salin ID akun layanan untuk digunakan di langkah berikutnya:

    bq show --connection PROJECT_ID.REGION.CONNECTION_ID

    Outputnya mirip dengan hal berikut ini:

    name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

Terraform

Gunakan resource google_bigquery_connection.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut membuat koneksi resource Cloud bernama my_cloud_resource_connection di region US:


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Untuk menerapkan konfigurasi Terraform di project Google Cloud, selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

  1. Luncurkan Cloud Shell.

  2. Tetapkan project Google Cloud default tempat Anda ingin menerapkan konfigurasi Terraform.

    Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root).

  1. Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus memiliki ekstensi .tf—misalnya main.tf. Dalam tutorial ini, file ini disebut sebagai main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Jika mengikuti tutorial, Anda dapat menyalin kode contoh di setiap bagian atau langkah.

    Salin kode contoh ke dalam main.tf yang baru dibuat.

    Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.

  3. Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
  4. Simpan perubahan Anda.
  5. Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori. 
    terraform init

    Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade: 

    terraform init -upgrade

Menerapkan perubahan

  1. Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan: 
    terraform plan

    Koreksi konfigurasi jika diperlukan.

  2. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt: 
    terraform apply

    Tunggu hingga Terraform menampilkan pesan "Apply complete!".

  3. Buka project Google Cloud Anda untuk melihat hasilnya. Di Konsol Google Cloud, buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

Memberikan akses pada akun layanan

Berikan peran Vertex AI User dan Storage Object Viewer ke akun layanan koneksi.

Untuk memberikan peran, ikuti langkah-langkah berikut:

Konsol

  1. Buka halaman IAM & Admin.

    Buka IAM & Admin

  2. Klik Add.

    Dialog Add principals akan terbuka.

  3. Di kolom Akun utama baru, masukkan ID akun layanan yang Anda salin sebelumnya.

  4. Di kolom Pilih peran, pilih Vertex AI, lalu pilih Pengguna Vertex AI.

  5. Klik Add another role.

  6. Di kolom Select a role, pilih Cloud Storage, lalu pilih Storage Object Viewer.

  7. Klik Simpan.

gcloud

Gunakan perintah gcloud projects add-iam-policy-binding.

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

Ganti kode berikut:

  • PROJECT_NUMBER: nomor project dari project tempat peran akan diberikan.
  • MEMBER: ID akun layanan yang Anda salin sebelumnya.

Membuat tabel objek

Untuk menganalisis gambar tanpa memindahkannya dari Cloud Storage, buat tabel objek.

Untuk membuat tabel objek:

SQL

Gunakan pernyataan CREATE EXTERNAL TABLE.

  1. Di konsol Google Cloud, buka halaman BigQuery Studio.

    Buka BigQuery Studio

  2. Di editor kueri, masukkan pernyataan berikut:

    CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['BUCKET_PATH'[,...]],
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE');

    Ganti kode berikut:

    • PROJECT_ID: project ID Anda.
    • DATASET_ID: ID set data yang Anda buat.
    • TABLE_NAME: nama tabel objek.
    • REGION: region atau multi-region yang berisi koneksi.
    • CONNECTION_ID: ID koneksi yang Anda buat.

      Saat Anda melihat detail koneksi di konsol Google Cloud, ini adalah nilai di bagian terakhir ID koneksi yang sepenuhnya memenuhi syarat yang ditampilkan di ID Koneksi, misalnya projects/myproject/locations/connection_location/connections/myconnection.

      Untuk menggunakan koneksi default, tentukan DEFAULT, bukan string koneksi yang berisi PROJECT_ID.REGION.CONNECTION_ID.

    • BUCKET_PATH: jalur ke bucket Cloud Storage yang berisi gambar, dalam format ['gs://bucket_name/[folder_name/]*'].

      Bucket Cloud Storage yang Anda gunakan harus berada di project yang sama tempat Anda berencana membuat model dan memanggil fungsi ML.GENERATE_EMBEDDING. Jika ingin memanggil fungsi ML.GENERATE_EMBEDDING dalam project yang berbeda dengan project yang berisi bucket Cloud Storage yang digunakan oleh tabel objek, Anda harus memberikan peran Storage Admin di tingkat bucket ke akun layanan service-A@gcp-sa-aiplatform.iam.gserviceaccount.com.

    • STALENESS_INTERVAL: menentukan apakah metadata yang di-cache digunakan oleh operasi terhadap tabel objek, dan seberapa baru metadata yang di-cache agar operasi dapat menggunakannya. Untuk informasi selengkapnya tentang pertimbangan penyimpanan metadata ke dalam cache, lihat Cache metadata untuk performa.

      Untuk menonaktifkan cache metadata, tentukan 0. Ini adalah setelan defaultnya.

      Untuk mengaktifkan caching metadata, tentukan nilai literal interval antara 30 menit dan 7 hari. Misalnya, tentukan INTERVAL 4 HOUR untuk interval penghentian 4 jam. Dengan nilai ini, operasi terhadap tabel akan menggunakan metadata yang di-cache jika metadata yang di-cache telah diperbarui dalam 4 jam terakhir. Jika metadata yang di-cache lebih usang, operasi akan mengambil metadata dari Cloud Storage.

    • CACHE_MODE: menentukan apakah cache metadata diperbarui secara otomatis atau manual. Untuk informasi selengkapnya terkait pertimbangan caching metadata, lihat Caching metadata untuk performa.

      Ubah ke AUTOMATIC agar cache metadata diperbarui sesuai dengan interval yang ditentukan sistem, biasanya antara 30 hingga 60 menit.

      Tetapkan ke MANUAL jika Anda ingin me-refresh cache metadata pada jadwal yang Anda tentukan. Dalam hal ini, Anda dapat memanggil prosedur sistem BQ.REFRESH_EXTERNAL_METADATA_CACHE untuk me-refresh cache.

      Anda harus menetapkan CACHE_MODE jika STALENESS_INTERVAL ditetapkan ke nilai yang lebih besar dari 0.

  3. Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

bq

Gunakan perintah bq mk.

bq mk --table \
--external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

Ganti kode berikut:

  • BUCKET_PATH: jalur ke bucket Cloud Storage yang berisi gambar, dalam format ['gs://bucket_name/[folder_name/]*'].

    Bucket Cloud Storage yang Anda gunakan harus berada di project yang sama tempat Anda berencana membuat model dan memanggil fungsi ML.GENERATE_EMBEDDING. Jika ingin memanggil fungsi ML.GENERATE_EMBEDDING dalam project yang berbeda dengan project yang berisi bucket Cloud Storage yang digunakan oleh tabel objek, Anda harus memberikan peran Storage Admin di tingkat bucket ke akun layanan service-A@gcp-sa-aiplatform.iam.gserviceaccount.com.

  • REGION: region atau multi-region yang berisi koneksi.
  • CONNECTION_ID: ID koneksi yang Anda buat.

    Saat Anda melihat detail koneksi di konsol Google Cloud, ini adalah nilai di bagian terakhir ID koneksi yang sepenuhnya memenuhi syarat yang ditampilkan di ID Koneksi, misalnya projects/myproject/locations/connection_location/connections/myconnection.

  • STALENESS_INTERVAL: menentukan apakah metadata yang di-cache digunakan oleh operasi terhadap tabel objek, dan seberapa baru metadata yang di-cache agar operasi dapat menggunakannya. Untuk informasi selengkapnya tentang pertimbangan penyimpanan metadata ke dalam cache, lihat Cache metadata untuk performa.

    Untuk menonaktifkan cache metadata, tentukan 0. Ini adalah setelan defaultnya.

    Untuk mengaktifkan caching metadata, tentukan nilai literal interval antara 30 menit dan 7 hari. Misalnya, tentukan INTERVAL 4 HOUR untuk interval penghentian 4 jam. Dengan nilai ini, operasi terhadap tabel akan menggunakan metadata yang di-cache jika metadata yang di-cache telah diperbarui dalam 4 jam terakhir. Jika metadata yang di-cache lebih usang, operasi akan mengambil metadata dari Cloud Storage.

  • CACHE_MODE: menentukan apakah cache metadata diperbarui secara otomatis atau manual. Untuk informasi selengkapnya terkait pertimbangan caching metadata, lihat Caching metadata untuk performa.

    Ubah ke AUTOMATIC agar cache metadata diperbarui sesuai dengan interval yang ditentukan sistem, biasanya antara 30 hingga 60 menit.

    Tetapkan ke MANUAL jika Anda ingin me-refresh cache metadata pada jadwal yang Anda tentukan. Dalam hal ini, Anda dapat memanggil prosedur sistem BQ.REFRESH_EXTERNAL_METADATA_CACHE untuk me-refresh cache.

    Anda harus menetapkan CACHE_MODE jika STALENESS_INTERVAL ditetapkan ke nilai yang lebih besar dari 0.

  • PROJECT_ID: project ID Anda.
  • DATASET_ID: ID set data yang Anda buat.
  • TABLE_NAME: nama tabel objek.

Membuat model

  1. Di konsol Google Cloud, buka halaman BigQuery.

    Buka BigQuery

  2. Dengan menggunakan editor SQL, buat model jarak jauh:

    CREATE OR REPLACE MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (ENDPOINT = 'ENDPOINT');

    Ganti kode berikut:

    • PROJECT_ID: project ID Anda.
    • DATASET_ID: ID set data yang Anda buat sebelumnya.
    • MODEL_NAME: nama model.
    • REGION: region atau multi-region yang berisi koneksi.
    • CONNECTION_ID: ID koneksi yang Anda buat.

      Saat Anda melihat detail koneksi di konsol Google Cloud, ini adalah nilai di bagian terakhir ID koneksi yang sepenuhnya memenuhi syarat yang ditampilkan di ID Koneksi, misalnya projects/myproject/locations/connection_location/connections/myconnection.

    • ENDPOINT: model penyematan yang akan digunakan, dalam hal ini multimodalembedding@001.

      Jika Anda menentukan URL sebagai endpoint saat membuat model jarak jauh, misalnya endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-004', pastikan project yang Anda tentukan di URL adalah project tempat Anda telah memberikan peran pengguna Vertex AI ke koneksi. akun layanan.

      Model multimodalembedding@001 harus tersedia di lokasi tempat Anda membuat model jarak jauh. Untuk mengetahui informasi selengkapnya, lihat Lokasi.

Membuat embedding gambar

Buat penyematan gambar dengan fungsi ML.GENERATE_EMBEDDING menggunakan data gambar dari tabel objek:

  SELECT *
  FROM ML.GENERATE_EMBEDDING(
    MODEL <var>PROJECT_ID</var>.<var>DATASET_ID</var>.<var>MODEL_NAME</var>,
    TABLE <var>PROJECT_ID</var>.<var>DATASET_ID</var>.<var>TABLE_NAME</var>,
    STRUCT(FLATTEN_JSON AS flatten_json_output,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
  );

Ganti kode berikut:

  • PROJECT_ID: project ID Anda.
  • DATASET_ID: ID set data yang berisi model.
  • MODEL_NAME: nama model jarak jauh di atas model multimodalembedding@001.
  • TABLE_NAME: nama tabel objek yang berisi gambar yang akan disematkan.
  • FLATTEN_JSON: nilai BOOL yang menunjukkan apakah akan mengurai penyematan ke kolom terpisah atau tidak. Nilai defaultnya adalah TRUE.
  • OUTPUT_DIMENSIONALITY: nilai INT64 yang menentukan jumlah dimensi yang akan digunakan saat membuat embeddings. Nilai yang valid adalah 128, 256, 512, dan 1408. Nilai defaultnya adalah 1408. Misalnya, jika Anda menentukan 256 AS output_dimensionality, kolom output ml_generate_embedding_result akan berisi 256 penyematan untuk setiap nilai input.

Contoh

Contoh berikut menunjukkan cara membuat penyematan untuk gambar di tabel objek images:

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE `mydataset.images`,
    STRUCT(TRUE AS flatten_json_output, 512 AS output_dimensionality)
  );