Menangani error kuota dengan memanggil ML.GENERATE_EMBEDDING secara iteratif

Tutorial ini menunjukkan cara menggunakan prosedur tersimpan publik bqutil.procedure.bqml_generate_embeddings BigQuery untuk melakukan iterasi melalui panggilan ke fungsi ML.GENERATE_EMBEDDING. Memanggil fungsi secara iteratif memungkinkan Anda mengatasi error yang dapat dicoba ulang yang terjadi karena melebihi kuota dan batas yang berlaku untuk fungsi.

Untuk meninjau kode sumber untuk prosedur tersimpan bqutil.procedure.bqml_generate_embeddings di GitHub, lihat bqml_generate_embeddings.sqlx. Untuk mengetahui informasi selengkapnya tentang parameter dan penggunaan prosedur tersimpan, lihat file README.

Tutorial ini memandu Anda melalui tugas-tugas berikut:

  • Membuat model jarak jauh melalui model text-embedding-004.
  • Melakukan iterasi melalui panggilan ke fungsi ML.GENERATE_EMBEDDING, menggunakan model jarak jauh dan tabel data publik bigquery-public-data.bbc_news.fulltext dengan prosedur tersimpan bqutil.procedure.bqml_generate_embeddings.

Izin yang diperlukan

  • Untuk membuat set data, Anda memerlukan izin Identity and Access Management (IAM) bigquery.datasets.create.
  • Untuk membuat resource koneksi, Anda memerlukan izin IAM berikut:

    • bigquery.connections.create
    • bigquery.connections.get
  • Untuk memberikan izin ke akun layanan koneksi, Anda memerlukan izin berikut:

    • resourcemanager.projects.setIamPolicy
  • Untuk membuat model, Anda memerlukan izin berikut:

    • bigquery.jobs.create
    • bigquery.models.create
    • bigquery.models.getData
    • bigquery.models.updateData
    • bigquery.connections.delegate
  • Untuk menjalankan inferensi, Anda memerlukan izin berikut:

    • bigquery.models.getData
    • bigquery.jobs.create

Biaya

Dalam dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih berikut:

  • BigQuery ML: You incur costs for the data that you process in BigQuery.
  • Vertex AI: You incur costs for calls to the Vertex AI model.

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga. Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Untuk mengetahui informasi selengkapnya tentang harga BigQuery, lihat harga BigQuery.

Untuk mengetahui informasi selengkapnya tentang harga Vertex AI, lihat harga Vertex AI.

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, and Vertex AI APIs.

    Enable the APIs

Membuat set data

Buat set data BigQuery untuk menyimpan model dan data sampel Anda:

  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:

    1. Untuk Dataset ID, masukkan target_dataset.

    2. Untuk Location type, pilih Multi-region, lalu pilih US (multiple regions in United States).

    3. Jangan ubah setelan default yang tersisa, lalu klik Create dataset.

Membuat koneksi

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

Pilih salah satu opsi berikut:

Konsol

  1. Buka halaman BigQuery.

    Buka BigQuery

  2. Untuk membuat koneksi, klik Tambahkan, lalu klik Koneksi ke sumber data eksternal.

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

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

  5. Klik Create connection.

  6. Klik Go to connection.

  7. 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 izin ke akun layanan koneksi

Untuk memberikan peran yang sesuai kepada akun layanan koneksi agar dapat mengakses layanan Cloud Storage dan Vertex AI, ikuti langkah-langkah berikut:

  1. Buka halaman IAM & Admin.

    Buka IAM & Admin

  2. Klik Berikan akses.

  3. Di kolom New principals, masukkan ID akun layanan yang Anda salin sebelumnya.

  4. Di menu Select a role, pilih Vertex AI > Vertex AI User.

  5. Klik Simpan.

Membuat model pembuatan embedding teks

Buat model jarak jauh yang merepresentasikan model text-embedding-004 Vertex AI yang dihosting:

  1. Di Konsol Google Cloud, buka halaman BigQuery.

    Buka BigQuery

  2. Di editor kueri, jalankan pernyataan berikut:

    CREATE OR REPLACE MODEL `target_dataset.embedding_model`
      REMOTE WITH CONNECTION `LOCATION.CONNECTION_ID`
      OPTIONS (ENDPOINT = 'text-embedding-004');

    Ganti kode berikut:

    • LOCATION: lokasi koneksi.
    • CONNECTION_ID: ID koneksi BigQuery Anda.

      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.

    Kueri memerlukan waktu beberapa detik untuk diselesaikan, setelah itu model embedding akan muncul di set data sample di panel Explorer. Karena kueri menggunakan pernyataan CREATE MODEL untuk membuat model, tidak akan ada hasil kueri.

Menjalankan prosedur tersimpan

Jalankan prosedur tersimpan bqutil.procedure.bqml_generate_embeddings, yang mengulangi panggilan ke fungsi ML.GENERATE_EMBEDDING menggunakan model target_dataset.embedding_model dan tabel data publik bigquery-public-data.bbc_news.fulltext:

  1. Di Konsol Google Cloud, buka halaman BigQuery.

    Buka BigQuery

  2. Di editor kueri, jalankan pernyataan berikut:

    CALL `bqutil.procedure.bqml_generate_embeddings`(
        "bigquery-public-data.bbc_news.fulltext",            -- source table
        "PROJECT_ID.target_dataset.news_body_embeddings",  -- destination table
        "PROJECT_ID.target_dataset.embedding_model",       -- model
        "body",                                              -- content column
        ["filename"],                                        -- key columns
        '{}'                                                 -- optional arguments encoded as a JSON string
    );

    Ganti PROJECT_ID dengan project ID project yang Anda gunakan untuk tutorial ini.

    Prosedur tersimpan membuat tabel target_dataset.news_body_embeddings untuk berisi output fungsi ML.GENERATE_EMBEDDING.

  3. Setelah kueri selesai berjalan, pastikan tidak ada baris di tabel target_dataset.news_body_embeddings yang berisi error yang dapat dicoba ulang. Di editor kueri, jalankan pernyataan berikut:

    SELECT *
    FROM `target_dataset.news_body_embeddings`
    WHERE ml_generate_embedding_status LIKE '%A retryable error occurred%';

    Kueri menampilkan pesan No data to display.

Pembersihan

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.