Pembuatan embedding otomatis

Dokumen ini menjelaskan cara menggunakan pembuatan embedding otomatis untuk data Anda, yang memungkinkan BigQuery mempertahankan kolom embedding pada tabel berdasarkan kolom sumber. Kolom sumber harus memiliki jenis data STRING atau ObjectRef. Saat Anda menambahkan atau mengubah data di kolom sumber, BigQuery akan otomatis membuat atau memperbarui kolom embedding untuk data tersebut menggunakan model embedding Agent Platform. Hal ini berguna jika Anda ingin BigQuery mempertahankan embedding saat data sumber Anda diperbarui secara rutin.

Embedding berguna untuk aplikasi AI generatif modern seperti Retrieval Augmented Generation (RAG), tetapi dapat menjadi rumit untuk dibuat, dikelola, dan dikueri. Anda dapat menggunakan pembuatan embedding otomatis untuk menyederhanakan proses pembuatan, pemeliharaan, dan pengiriman kueri embedding untuk digunakan dalam penelusuran kemiripan dan aplikasi AI generatif lainnya.

Misalnya, Anda dapat menggunakan kueri yang mirip dengan berikut ini untuk membuat tabel dengan pembuatan embedding otomatis yang diaktifkan, menyisipkan data, lalu melakukan penelusuran semantik:

CREATE TABLE mydataset.products (
  name STRING,
  description STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(description, connection_id => 'us.example_connection',
        endpoint => 'text-embedding-005')
      # Alternatively, you can use the syntax for a built-in model.
      # AI.EMBED(description, model => 'embeddinggemma-300m')
    ) STORED OPTIONS( asynchronous = TRUE ));

# Values in the description_embedding column are automatically generated.
INSERT INTO mydataset.products (name, description) VALUES
  ('Super slingers', 'An exciting board game for the whole family'), ...;

SELECT * FROM AI.SEARCH(TABLE mydataset.products, 'description', 'A really fun toy');

Sebelum memulai

Untuk mengaktifkan pembuatan embedding otomatis pada tabel, Anda harus memiliki izin dan koneksi yang diperlukan, serta mengaktifkan Vertex AI API untuk project Anda.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengaktifkan pembuatan embedding otomatis, minta administrator untuk memberi Anda peran IAM berikut:

• Untuk menggunakan resource koneksi: BigQuery Connections User (roles/bigquery.connectionUser) pada koneksi
• Untuk membuat atau mengubah tabel: BigQuery Data Editor (roles/bigquery.dataEditor) pada tabel
• Berikan peran berikut ke akun layanan koneksi agar dapat mengakses model yang dihosting di endpoint Agent Platform: Agent Platform User (roles/aiplatform.user) di project yang memiliki koneksi

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Membuat koneksi dan memberikan izin ke akun layanan

Untuk mengaktifkan pembuatan embedding otomatis pada tabel, Anda harus membuat koneksi resource Cloud. Kemudian, berikan peran Agent Platform User (roles/aiplatform.user) ke akun layanan yang dibuat saat Anda membuat koneksi.

Membuat kolom embedding yang dibuat secara otomatis

Anda dapat membuat kolom embedding yang dibuat secara otomatis dalam tabel baru atau menambahkannya ke tabel yang sudah ada.

Membuat tabel dengan kolom embedding yang dibuat secara otomatis

Anda dapat menggunakan pembuatan embedding otomatis untuk membuat embedding menggunakan fungsi AI.EMBED dalam CREATE TABLE pernyataan.

Ganti kode berikut:

• DATASET_ID: Nama set data tempat Anda ingin membuat tabel.
• TABLE: Nama tabel tempat pembuatan embedding otomatis akan dibuat.
• COLUMN, ...: Kolom apa pun yang harus ada dalam tabel Anda selain kolom yang ingin Anda sematkan secara otomatis.
• STRING_COL: Nama kolom STRING yang ingin Anda sematkan secara otomatis.
• EMBEDDING_COL_NAME: Nama kolom embedding yang dibuat secara otomatis.
• CONNECTION_ID: Nilai STRING yang berisi nama koneksi yang akan digunakan, seperti my_project.us.example_connection. Anda harus memberikan peran Agent Platform User ke akun layanan koneksi di project tempat Anda membuat tabel.
• ENDPOINT: nilai STRING yang menentukan endpoint model embedding teks Agent Platform yang didukung untuk digunakan untuk model embedding teks. Nilai endpoint yang Anda tentukan harus menyertakan versi model, misalnya text-embedding-005. Jika Anda menentukan nama model, bukan URL, BigQuery ML akan otomatis mengidentifikasi model dan menggunakan endpoint lengkap model.

• MODEL (Pratinjau): nilai STRING yang menentukan model embedding teks bawaan. Satu-satunya nilai yang didukung adalah embeddinggemma-300m model. Jika Anda menentukan parameter ini, Anda tidak dapat menentukan parameter endpoint atau connection_id.

  Saat Anda menentukan parameter MODEL, data Anda akan tetap berada di BigQuery dan slot Anda akan digunakan untuk membuat embedding; tidak ada data yang dikirim ke Agent Platform dan tidak ada biaya yang dikenakan di Agent Platform.

Menambahkan kolom embedding yang dibuat secara otomatis ke tabel yang sudah ada

Anda juga dapat menambahkan kolom embedding yang dibuat secara otomatis ke tabel yang sudah ada dengan menggunakan pernyataan ALTER TABLE ADD COLUMN.

Tugas pembuatan embedding latar belakang akan dimulai segera setelah tabel Anda dibuat atau diubah, atau setelah Anda memperbarui data di kolom sumber.

Untuk melacak progres pembuatan embedding, Anda dapat menggunakan kueri yang mirip dengan berikut ini:

SELECT
  COUNT(*) AS total_num_rows,
  COUNTIF(description_embedding IS NOT NULL
          AND description_embedding.status = '') AS total_num_generated_embeddings
FROM
  PROJECT_ID.DATASET_ID.TABLE;

Setelah memiliki tabel dengan embedding, Anda dapat membuat indeks vektor pada kolom STRUCT yang berisi embedding yang dibuat secara otomatis.

Contoh

Misalkan Anda adalah peritel besar yang menjual berbagai produk. Anda memiliki tabel nama dan deskripsi produk dan ingin membantu pelanggan menemukan produk yang mereka cari. Kueri berikut menunjukkan cara menyiapkan pembuatan embedding otomatis untuk membantu penelusuran semantik deskripsi produk Anda.

Pertama, buat set data:

CREATE SCHEMA mydataset;

Selanjutnya, buat tabel dengan pembuatan embedding otomatis yang diaktifkan untuk menyimpan informasi produk Anda. Kolom yang dibuat secara otomatis disebut description_embedding dan didasarkan pada kolom description.

# Create a table of products and descriptions with a generated embedding column.
CREATE TABLE mydataset.products (
  name STRING,
  description STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(description, connection_id => 'us.example_connection',
        endpoint => 'text-embedding-005')
      # Alternatively, you can use the syntax for a built-in model.
      # AI.EMBED(description, model => 'embeddinggemma-300m')
    ) STORED OPTIONS( asynchronous = TRUE )
);

Kueri berikut menyisipkan beberapa nama dan deskripsi produk ke dalam tabel. Anda tidak menentukan nilai untuk description_embedding karena dibuat secara otomatis.

# Insert product descriptions into the table.
# The description_embedding column is automatically updated.
INSERT INTO mydataset.products (name, description) VALUES
  ("Lounger chair", "A comfortable chair for relaxing in."),
  ("Super slingers", "An exciting board game for the whole family."),
  ("Encyclopedia set", "A collection of informational books.");

Anda dapat secara opsional membuat indeks vektor pada tabel untuk mempercepat penelusuran. Indeks vektor memerlukan lebih dari tiga baris, sehingga kueri berikut mengasumsikan bahwa Anda telah menyisipkan data tambahan. Setiap kali Anda menyisipkan data, kolom description_embedding akan otomatis diperbarui.

CREATE VECTOR INDEX my_index
ON mydataset.products(description_embedding)
OPTIONS(index_type = 'IVF');

Terakhir, Anda dapat menggunakan fungsi AI.SEARCHuntuk melakukan penelusuran semantik pada produk Anda untuk mainan yang menyenangkan:

# Search for products that are fun to play with.
SELECT base.name, base.description, distance
FROM AI.SEARCH(TABLE mydataset.products, 'description', "A really fun toy");

/*------------------+----------------------------------------------+----------------------+
 | name             | description                                  | distance             |
 +------------------+----------------------------------------------+----------------------+
 | Super slingers   | An exciting board game for the whole family. | 0.80954913893618929  |
 | Lounger chair    | A comfortable chair for relaxing in.         | 0.938933930620146    |
 | Encyclopedia set | A collection of informational books.         | 1.1119297739353384   |
 +------------------+----------------------------------------------+----------------------*/

Embedding yang dibuat dari kolom ObjectRef

Anda dapat menambahkan kolom embedding yang dibuat untuk kolom ObjectRef dalam tabel.

Contoh berikut menunjukkan cara membuat tabel dengan kolom ObjectRef, lalu menambahkan kolom embedding yang dibuat untuk kolom tersebut:

# Create a table with ObjectRef columns.
CREATE TABLE mydataset.images AS
SELECT
  REGEXP_EXTRACT(ref.uri, r'.*/(.*).jpg$') AS name,
  ref
FROM mydataset.object_table;

# Add a generated embedding column for the ObjectRef column.
ALTER TABLE mydataset.images
ADD COLUMN image_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
GENERATED ALWAYS AS (
  AI.EMBED(
    ref,
    connection_id => "us.my_connection",
    endpoint => "multimodalembedding@001")
)
STORED OPTIONS (asynchronous = true);

Mendapatkan informasi tentang kolom embedding yang dibuat secara otomatis

Untuk memverifikasi bahwa kolom adalah kolom embedding yang dibuat secara otomatis, kueri tampilan INFORMATION_SCHEMA.COLUMNS.

Kueri berikut menunjukkan informasi tentang semua kolom embedding yang dibuat secara otomatis:

SELECT *
FROM PROJECT_ID.DATASET_ID.INFORMATION_SCHEMA.COLUMNS
WHERE is_generated = 'ALWAYS';

Kolom generation_expression menunjukkan panggilan ke fungsi AI.EMBED yang digunakan untuk membuat embedding di kolom.

Menggunakan pemesanan Anda sendiri

Secara default, BigQuery menggunakan slot on demand untuk menangani pemrosesan yang diperlukan untuk mempertahankan kolom embedding yang dibuat. Untuk memastikan performa yang dapat diprediksi dan konsisten, Anda dapat secara opsional membuat pemesanan dan menetapkan job_type ke BACKGROUND. Jika ada pemesanan latar belakang, BigQuery akan menggunakannya untuk mempertahankan kolom embedding yang dibuat.

Kuota

Saat Anda menggunakan endpoint Agent Platform untuk pembuatan embedding dengan menentukan parameter endpoint dalam fungsi AI.EMBED, BigQuery akan mengirimkan permintaan ke Agent Platform untuk membuat embedding. Permintaan ini tunduk pada kuota untuk Agent Platform. Kuota untuk permintaan per menit untuk model embedding Anda secara langsung memengaruhi throughput tugas pembuatan embedding latar belakang. Jika pembuatan embedding lambat, minta batas kuota yang lebih tinggi untuk Agent Platform dengan mengikuti petunjuk di Meminta kuota yang lebih tinggi. Jika Anda menentukan parameter model dalam fungsi AI.EMBED, embedding akan dibuat dalam BigQuery dan tidak ada permintaan yang dikirim ke Agent Platform, sehingga kuota Agent Platform tidak berlaku.

Pemecahan masalah

Kolom embedding yang dibuat berisi dua kolom: result dan status. Jika terjadi error saat BigQuery mencoba membuat embedding untuk baris tertentu dalam tabel Anda, kolom result akan menjadi NULL dan kolom status akan menjelaskan error tersebut. Misalnya, jika kolom sumber adalah NULL maka embedding result juga NULL dan statusnya adalah NULL value is not supported for embedding generation.

Error yang lebih parah dapat menghentikan pembuatan embedding. Dalam hal ini, Anda dapat mengkueri kolom async_generation_status dalam INFORMATION_SCHEMA.COLUMNS tampilan untuk mengidentifikasi error pemblokiran.

Error pemblokiran dapat mencakup hal berikut:

• Error izin ditolak
• Error tidak ditemukan
• Error endpoint model embedding yang tidak didukung
• Error Vertex AI API tidak diaktifkan

Setelah tugas pembuatan embedding berikutnya berhasil, kolom async_generation_status akan dihapus.

Kueri berikut menunjukkan cara memeriksa error pemblokiran:

SELECT
  column_name,
  async_generation_status
FROM
  mydataset.INFORMATION_SCHEMA.COLUMNS
WHERE
  table_name = 'images';

Jika kolom image_embedding memiliki error pemblokiran, hasilnya akan mirip dengan berikut ini:

[
  {
    "column_name": "image_embedding",
    "async_generation_status": {
      "blocking_error": {
        "message": "<service_account> does not have the permission to access resources used by AI.EMBED. Please follow https://cloud.google.com/bigquery/docs/permissions-for-ai-functions to set up permissions.",
        ...
      }
    }
  }
]

Anda juga dapat mengkueri tampilan INFORMATION_SCHEMA.JOBS untuk tugas latar belakang dan melihat informasi di kolom error_result. ID tugas dari tugas embedding latar belakang diawali dengan gc_. Misalnya, kueri berikut mengekstrak semua tugas latar belakang yang hasil errornya bukan NULL:

SELECT * FROM `region-REGION.INFORMATION_SCHEMA.JOBS` j
WHERE EXISTS (
  SELECT 1
  FROM unnest(j.referenced_tables) t
  WHERE
    j.project_id = 'PROJECT_ID'
    AND t.dataset_id = 'DATASET_ID'
    AND t.table_id = 'TABLE'
)
AND starts_with(job_id, 'gc')
AND error_result IS NOT NULL
ORDER BY j.creation_time DESC;

Catat biaya

Biaya pembuatan embedding otomatis termasuk dalam kategori berikut.

Biaya DML latar belakang BigQuery

Embedding yang dibuat ditulis ke tabel Anda menggunakan tugas DML latar belakang. Secara default, BigQuery menggunakan slot on demand untuk menangani tugas ini. Project tabel ditagih mengikuti model penagihan on demand DML.

Atau, untuk memastikan performa yang dapat diprediksi dan konsisten, Anda dapat membuat pemesanan dan menetapkan job_type ke BACKGROUND. Jika ada pemesanan latar belakang, BigQuery akan menggunakannya untuk menjalankan tugas DML latar belakang. Dan pemesanan latar belakang akan ditagih untuk penggunaan waktu slot dari tugas DML latar belakang.

Biaya Gemini Enterprise Agent Platform

Pembuatan embedding otomatis mengirimkan permintaan ke Gemini Enterprise Agent Platform, yang dapat menimbulkan biaya. Untuk melacak biaya Agent Platform yang dikeluarkan oleh tugas embedding latar belakang, ikuti langkah-langkah berikut:

1. Lihat laporan penagihan Anda di Penagihan Cloud.

2. Gunakan filter untuk mempersempit hasil.

   Untuk layanan, pilih Vertex AI.

3. Untuk melihat biaya tugas tertentu, filter berdasarkan label.

   Tetapkan kunci ke bigquery_ml_job dan nilai ke ID tugas dari tugas embedding. Semua tugas embedding latar belakang memiliki awalan gc_.

Diperlukan waktu hingga 24 jam agar beberapa biaya muncul di Penagihan Cloud.

Batasan

• Setiap tabel mendukung maksimal satu kolom embedding yang dibuat secara otomatis.
• Operasi DML serentak dapat menyebabkan penundaan dan kegagalan sementara dalam pembuatan embedding. Untuk performa yang lebih baik dan mengurangi biaya, sebaiknya masukkan data dalam batch dan hindari pembaruan DML yang sering.
• Jika Anda menggunakan streaming API lama untuk memasukkan data, mungkin ada penundaan sebelum pembuatan embedding dimulai.
• Saat menggunakan BigQuery Storage Write API, tugas pembuatan embedding latar belakang dapat gagal jika tugas penulisan streaming berjalan secara serentak. Jika hal ini terjadi, kuota Agent Platform dan biaya DML latar belakang akan terbuang. Penggunaan Storage Write API juga menyebabkan tugas pembuatan embedding serentak pada tabel, tetapi hal ini ditangani oleh BigQuery dan tidak ada kuota Agent Platform atau biaya DML latar belakang yang terbuang.
• Untuk throughput yang lebih tinggi di endpoint jarak jauh Agent Platform, sebaiknya gunakan model embedding teks, bukan model Gemini. Untuk mengetahui informasi selengkapnya, lihat Kuota.
• Tidak ada indikasi bahwa kolom dibuat secara otomatis saat Anda melihat skema tabel menggunakan Cloud de Confiance konsol atau kolom ddl dari tampilan INFORMATION_SCHEMA.TABLES.
• Jika Anda membuat salinan, clone, atau snapshot tabel yang memiliki kolom embedding yang dibuat, hanya data yang akan disalin. Konfigurasi pembuatan tidak berlaku untuk tabel baru, dan pembaruan pada kolom sumber tabel baru tidak akan menghasilkan embedding baru.
• Jika Anda memulihkan tabel yang mengaktifkan pembuatan embedding otomatis dari snapshot, konfigurasi pembuatan embedding tidak akan dipulihkan.
• Saat menggunakan BigQuery API, Anda hanya dapat menentukan properti generatedColumn saat membuat kolom baru. Anda tidak dapat menambahkan, memperbarui, atau menghapus properti generatedColumn pada kolom yang sudah ada.

• Setelah Anda membuat kolom embedding yang dibuat, batasan berikut akan berlaku:

  • Anda tidak dapat menghapus atau mengganti nama kolom sumber, tetapi Anda masih dapat menghapus atau mengganti nama kolom embedding yang dibuat. Jika Anda menghapus kolom embedding, Anda dapat menghapus atau mengganti nama kolom sumber.
  • Anda tidak dapat mengubah jenis data kolom sumber atau kolom embedding yang dibuat.

• Anda tidak dapat menentukan nilai default untuk kolom embedding yang dibuat secara otomatis.

• Anda tidak dapat menulis langsung ke kolom embedding yang dibuat menggunakan metode berikut:

  • DML
  • Penulisan streaming
  • bq insert
  • bq load
  • bq copy -a

• Tabel dengan kolom embedding yang dibuat tidak mendukung kebijakan keamanan tingkat kolom apa pun, seperti tag kebijakan.

• Saat Anda memanggil fungsi penelusuran, seperti VECTOR_SEARCH atau AI.SEARCH, baris dengan embedding yang tidak ada di tabel dasar akan dilewati selama penelusuran.

• Anda tidak dapat membuat indeks vektor berpartisi pada tabel yang mengaktifkan pembuatan embedding otomatis.

• Jika Anda membuat indeks vektor pada kolom embedding yang dibuat secara otomatis, pelatihan indeks akan dimulai setelah setidaknya 80% baris memiliki embedding yang dibuat. Anda dapat memeriksa progres pembuatan embedding dengan mengikuti langkah-langkah berikut:

  Kueri persentase embedding pada tabel Anda yang telah dibuat:

  SELECT
    COUNTIF(description_embedding IS NOT NULL
    AND description_embedding.status = '') * 100.0 / COUNT(*) AS percent
  FROM PROJECT_ID.DATASET_ID.TABLE;
  

Langkah berikutnya

• Pelajari lebih lanjut cara membuat dan mengelola indeks vektor.
• Lihat Pengantar penelusuran vektor.