Membuat embedding vektor untuk data tekstual secara massal menggunakan DML yang dipartisi

Dokumen ini menjelaskan cara membuat dan mengisi ulang embedding vektor secara massal untuk data tekstual (STRING atau JSON) yang disimpan di Spanner menggunakan SQL dan model embedding teks Gemini Enterprise Agent Platform.

Prasyarat

Anda harus memiliki tabel di database Spanner yang berisi data tekstual (STRING atau JSON). Untuk mengetahui informasi selengkapnya tentang cara mengimpor data, lihat Ringkasan impor dan ekspor Spanner.

Contoh kasus penggunaan

Misalkan Anda memiliki tabel di Spanner dengan skema berikut. Tabel ini berisi jutaan data.

GoogleSQL 

CREATE TABLE Products (
  product_id INT64 NOT NULL,
  name STRING(MAX),
  description STRING(MAX)
) PRIMARY KEY(product_id);

PostgreSQL 

CREATE TABLE Products (
  product_id INT8 NOT NULL,
  name TEXT,
  description TEXT,
  PRIMARY KEY(product_id)
);

Sasaran Anda adalah membuat embedding vektor untuk kolom description dalam tabel ini guna menemukan item serupa yang akan direkomendasikan kepada pelanggan untuk meningkatkan pengalaman belanja mereka menggunakan penelusuran vektor.

Mendaftarkan model embedding

GoogleSQL

Daftarkan model embedding teks dengan endpoint model Agent Platform di database Spanner Anda:

CREATE MODEL MODEL_NAME
INPUT(
  content STRING(MAX)
)
OUTPUT(
  embeddings STRUCT<values ARRAY<FLOAT32>>
)
REMOTE OPTIONS(
    endpoint = '//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
  default_batch_size = 5
)

Ganti kode berikut:

  • MODEL_NAME: nama model embedding teks Agent Platform
  • PROJECT: project yang menghosting endpoint Agent Platform
  • LOCATION: lokasi endpoint Agent Platform

PostgreSQL

Dalam dialek PostgreSQL, Anda tidak perlu mendaftarkan model. Anda meneruskan nama endpoint langsung ke panggilan fungsi spanner.ML_PREDICT_ROW.

Untuk praktik terbaik, pertimbangkan hal berikut:

  • Untuk mempertahankan isolasi kuota, gunakan endpoint di project yang berbeda untuk membuat dan mengisi ulang embedding, bukan endpoint produksi. Cadangkan endpoint produksi untuk menyalurkan traffic produksi.
  • Pastikan endpoint model mendukung nilai default_batch_size. Anda dapat mengganti default_batch_size dengan petunjuk kueri @{remote_udf_max_rows_per_rpc=NEW_NUMBER}. Untuk mengetahui informasi tentang batas default_batch_size untuk setiap region, lihat Mendapatkan embedding teks untuk cuplikan teks.
  • Tentukan endpoint dengan versi model tertentu (misalnya, @003), bukan @latest. Hal ini karena vektor embedding yang dihasilkan untuk bagian teks yang sama mungkin berbeda, bergantung pada versi model yang Anda gunakan. Oleh karena itu, Anda sebaiknya menghindari penggunaan versi model yang berbeda untuk menghasilkan embedding dalam set data yang sama. Selain itu, memperbarui versi model dalam pernyataan definisi model tidak akan memperbarui embedding yang sudah dibuat dengan model ini. Salah satu cara untuk mengelola versi model untuk embedding adalah dengan membuat kolom tambahan dalam tabel yang menyimpan versi model.
  • Model embedding teks yang disesuaikan secara kustom tidak didukung dengan fungsi ML.PREDICT GoogleSQL dan spanner.ML_PREDICT_ROW PostgreSQL.

Menguji integrasi menyeluruh model embedding

Anda dapat menjalankan kueri untuk menguji apakah model embedding berhasil dikonfigurasi, dan embedding diambil. Misalnya, jalankan kueri berikut:

GoogleSQL 

SELECT embeddings.values
FROM SAFE.ML.PREDICT(
  MODEL MODEL_NAME,
  (SELECT description AS content FROM products LIMIT 10)
);

Ganti kode berikut:

  • MODEL_NAME: nama model embedding teks Agent Platform

PostgreSQL 

SELECT spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', description))))
FROM Products
LIMIT 10;

Ganti kode berikut:

  • PROJECT: project yang menghosting endpoint Agent Platform
  • LOCATION: lokasi endpoint Agent Platform
  • MODEL_NAME: nama model embedding teks Agent Platform

Memperbarui tabel sumber untuk menyertakan kolom tambahan guna menyimpan embedding

Selanjutnya, perbarui skema tabel sumber untuk menambahkan kolom embedding. Menentukan panjang vektor bersifat opsional untuk menyimpan embedding, direkomendasikan untuk performa penelusuran KNN, dan diperlukan untuk indeks vektor. Hilangkan panjang vektor jika kolom menyimpan vektor dengan berbagai dimensi:

GoogleSQL 

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME ARRAY<FLOAT32>(vector_length=>VECTOR_LENGTH);

Ganti kode berikut:

  • TABLE_NAME: nama tabel sumber
  • EMBEDDING_COLUMN_NAME: nama kolom tempat Anda ingin menambahkan embedding yang dihasilkan
  • VECTOR_LENGTH: dimensi output model embedding, seperti 768 atau 3072

PostgreSQL 

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME real[] VECTOR LENGTH VECTOR_LENGTH;

Ganti kode berikut:

  • TABLE_NAME: nama tabel sumber
  • EMBEDDING_COLUMN_NAME: nama kolom tempat Anda ingin menambahkan embedding yang dihasilkan
  • VECTOR_LENGTH: dimensi output model embedding, seperti 768 atau 3072

Misalnya, menggunakan contoh tabel products, jalankan:

GoogleSQL 

ALTER TABLE Products
ADD COLUMN desc_embed ARRAY<FLOAT32>(vector_length=>768);

PostgreSQL 

ALTER TABLE Products
ADD COLUMN desc_embed real[] VECTOR LENGTH 768;

Anda dapat menambahkan kolom lain untuk mengelola versi model embedding.

GoogleSQL 

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT64;

PostgreSQL 

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT8;

Meningkatkan kuota untuk Agent Platform

Anda mungkin perlu meningkatkan kuota Agent Platform API untuk region yang menggunakan model embedding teks. Untuk meminta penambahan, lihat Penambahan kuota Agent Platform.

Mengisi ulang embedding

Terakhir, jalankan pernyataan UPDATE berikut menggunakan DML berpartisi untuk membuat embedding untuk kolom data tekstual dan menyimpan embedding di database Anda. Anda dapat menyimpan versi model bersama dengan embedding. Sebaiknya jalankan kueri ini selama periode traffic rendah di database Anda.

GoogleSQL 

UPDATE TABLE_NAME
SET
  TABLE_NAME.EMBEDDING_COLUMN_NAME = (
    SELECT embeddings.values
    FROM SAFE.ML.PREDICT(
      MODEL MODEL_NAME,
      (SELECT TABLE_NAME.DATA_COLUMN_NAME AS content)
    ) @{remote_udf_max_rows_per_rpc=MAX_ROWS}
  ),
  TABLE_NAME.EMBEDDING_VERSION_COLUMN = MODEL_VERSION
WHERE FILTER_CONDITION;

Ganti kode berikut:

  • TABLE_NAME: nama tabel dengan data tekstual
  • EMBEDDING_COLUMN_NAME: nama kolom tempat Anda ingin menambahkan embedding yang dihasilkan
  • DATA_COLUMN_NAME: nama kolom dengan data tekstual
  • MODEL_NAME: nama model embedding Agent Platform
  • MAX_ROWS: jumlah maksimum baris per RPC
  • EMBEDDING_VERSION_COLUMN: kolom yang mengelola versi model embedding yang digunakan untuk mengisi ulang embedding Anda
  • MODEL_VERSION: versi model embedding teks
  • FILTER_CONDITION: kondisi filter yang dapat dipartisi yang ingin Anda terapkan

Penggunaan SAFE.ML.PREDICT akan menampilkan NULL untuk permintaan yang gagal. Anda juga dapat menggunakan SAFE.ML.PREDICT yang dikombinasikan dengan filter WHERE embedding_column IS NULL untuk menjalankan ulang kueri tanpa menghitung embedding untuk kolom yang sudah dihitung.

PostgreSQL 

UPDATE TABLE_NAME
SET
  EMBEDDING_COLUMN_NAME = spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', DATA_COLUMN_NAME)))
  ) /*@ remote_udf_max_rows_per_rpc=MAX_ROWS */ ->'predictions'->0->'embeddings'->'values'),
  EMBEDDING_VERSION_COLUMN = MODEL_VERSION
WHERE FILTER_CONDITION;

Ganti kode berikut:

  • TABLE_NAME: nama tabel dengan data tekstual
  • EMBEDDING_COLUMN_NAME: nama kolom tempat Anda ingin menambahkan embedding yang dihasilkan
  • DATA_COLUMN_NAME: nama kolom dengan data tekstual
  • PROJECT: project yang menghosting endpoint Agent Platform
  • LOCATION: lokasi endpoint Agent Platform
  • MODEL_NAME: nama model embedding Agent Platform
  • MODEL_VERSION: versi model embedding Agent Platform
  • MAX_ROWS: jumlah maksimum baris per RPC
  • EMBEDDING_VERSION_COLUMN: kolom yang mengelola versi model embedding teks yang digunakan untuk mengisi ulang embedding Anda
  • FILTER_CONDITION: kondisi filter yang dapat dipartisi yang ingin Anda terapkan

Contoh kueri pengisian ulang untuk tabel products:

GoogleSQL 

UPDATE products
SET
  products.desc_embed = (
    SELECT embeddings.values
    FROM SAFE.ML.PREDICT(
      MODEL embedding_model,
      (SELECT products.description AS content)
    ) @{remote_udf_max_rows_per_rpc=200}
  ),
  products.desc_embed_model_version = 3
WHERE products.desc_embed IS NULL;

PostgreSQL 

UPDATE products
SET
  desc_embed = spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', description)))
  ) /*@ remote_udf_max_rows_per_rpc=200 */ ->'predictions'->0->'embeddings'->'values'),
  desc_embed_model_version = 3
WHERE desc_embed IS NULL;

Untuk praktik terbaik, pertimbangkan hal berikut:

  • Waktu tunggu gRPC default untuk Spanner API adalah satu jam. Bergantung pada jumlah embedding yang Anda isi ulang, Anda mungkin perlu meningkatkan waktu tunggu ini untuk memastikan bahwa DML berpartisi UPDATE memiliki waktu yang cukup untuk diselesaikan. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi waktu tunggu dan percobaan ulang kustom.

Performa dan pertimbangan lainnya

Pertimbangkan hal berikut untuk mengoptimalkan performa saat melakukan pengisian ulang data embedding.

Jumlah node

DML yang dipartisi menjalankan pernyataan DML yang diberikan pada partisi yang berbeda secara paralel. Untuk instance dengan jumlah node yang tinggi, Anda mungkin mengamati error kuota selama eksekusi DML yang dipartisi. Jika permintaan Agent Platform API dibatasi karena batas kuota Agent Platform API, Spanner akan mencoba ulang kegagalan ini dalam mode transaksi DML yang dipartisi maksimum 20 kali. Jika Anda mengamati tingkat error kuota yang tinggi di Agent Platform, tingkatkan kuota untuk Agent Platform. Anda juga dapat menyesuaikan paralelisme menggunakan petunjuk tingkat pernyataan @{pdml_max_parallelism=DESIRED_NUMBER} saat menggunakan GoogleSQL. Contoh berikut menetapkan paralelisme ke '5':

GoogleSQL 

@{pdml_max_parallelism=5} UPDATE products
SET products.desc_embed =(
  SELECT embeddings.values
  FROM SAFE.ML.PREDICT(MODEL embedding_model, (
        SELECT products.value AS CONTENT
        )
  )
      @{remote_udf_max_rows_per_rpc=200}
),
products.desc_embed_model_version = MODEL_VERSION
WHERE products.desc_embed IS NULL;

Ukuran teks di kolom data

Model embedding Agent Platform memiliki batas jumlah maksimum token untuk setiap input teks. Versi model yang berbeda memiliki batas token yang berbeda. Setiap permintaan Agent Platform dapat memiliki beberapa kolom teks input, tetapi ada batas jumlah maksimum token yang ada dalam satu permintaan. Untuk database GoogleSQL, jika Anda mengalami error INVALID_ARGUMENT dengan pesan "Request is too large", coba kurangi ukuran batch untuk menghindari error tersebut. Untuk melakukannya, Anda dapat mengonfigurasi default_batch_size atau menggunakan petunjuk kueri @{remote_udf_max_outstanding_rpcs} saat mendaftarkan model.

Jumlah permintaan API yang dikirim ke Agent Platform

Anda dapat menggunakan petunjuk kueri @{remote_udf_max_outstanding_rpcs} untuk menambah atau mengurangi jumlah permintaan yang dikirim ke Agent Platform dari Spanner. Perlu diketahui bahwa meningkatkan batas ini dapat meningkatkan penggunaan CPU dan memori instance Spanner. Untuk database GoogleSQL, penggunaan petunjuk kueri ini akan menggantikan default_batch_size yang dikonfigurasi untuk model Anda.

Memantau progres pengisian ulang

Anda dapat memantau jumlah permintaan, latensi, dan byte jaringan yang dikirim ke Agent Platform dari Spanner menggunakan dasbor insight sistem.

Langkah berikutnya