Mengelola indeks vektor

Untuk memberikan masukan atau meminta dukungan terkait fitur ini, kirim email ke bq-vector-search@google.com.

Dokumen ini menjelaskan cara membuat dan mengelola indeks vektor.

Indeks vektor adalah struktur data yang dirancang untuk memungkinkan fungsi VECTOR_SEARCH melakukan penelusuran vektor yang lebih efisien untuk embedding. Jika VECTOR_SEARCH dapat menggunakan indeks vektor, fungsi tersebut akan menggunakan teknik penelusuran Perkiraan Nearest Neighbor untuk membantu meningkatkan performa penelusuran, dengan kompromi dari pengurangan penarikan sehingga menampilkan lebih banyak hasil perkiraan.

Peran dan izin

Untuk membuat indeks vektor, Anda memerlukan izin IAM bigquery.tables.createIndex pada tabel tempat Anda membuat indeks. Untuk melepas indeks vektor, Anda memerlukan izin bigquery.tables.deleteIndex. Setiap peran IAM yang telah ditetapkan berikut mencakup izin yang Anda perlukan untuk menggunakan indeks vektor:

BigQuery Data Owner (roles/bigquery.dataOwner)
BigQuery Data Editor (roles/bigquery.dataEditor)

Membuat indeks vektor

Untuk membuat indeks vektor, gunakan pernyataan bahasa definisi data (DDL) CREATE VECTOR INDEX:

Buka halaman BigQuery.

Buka BigQuery
Di editor kueri, jalankan pernyataan SQL berikut:
```
CREATE [ OR REPLACE ] VECTOR INDEX [ IF NOT EXISTS ] INDEX_NAME
ON DATASET_NAME.TABLE_NAME(COLUMN_NAME)
OPTIONS(index_type = INDEX_TYPE,
  distance_type = DISTANCE_TYPE,
  ivf_options = '{"num_lists":NUM_LISTS}')
```
Ganti kode berikut:
- INDEX_NAME: nama indeks vektor yang Anda buat. Karena indeks selalu dibuat dalam project dan set data yang sama sebagai tabel dasar, Anda tidak perlu menentukannya dalam nama.
- DATASET_NAME: nama set data yang berisi tabel.
- TABLE_NAME: nama tabel yang berisi kolom dengan data embedding.
- COLUMN_NAME: nama kolom yang berisi data embedding. Kolom harus memiliki jenis ARRAY<FLOAT64>. Kolom tidak boleh memiliki kolom turunan. Semua elemen dalam array harus berupa non-NULL, dan semua nilai dalam kolom harus memiliki dimensi array yang sama.
- INDEX_TYPE: algoritma yang akan digunakan untuk membuat indeks vektor. IVF adalah satu-satunya nilai yang didukung. Menentukan IVF akan membuat indeks vektor sebagai indeks file terbalik (IVF). IVF menggunakan algoritma k-means untuk mengelompokkan data vektor, lalu mempartisi data vektor berdasarkan cluster tersebut. Saat Anda menggunakan fungsi VECTOR_SEARCH untuk menelusuri data vektor, fungsi tersebut dapat menggunakan partisi ini untuk mengurangi jumlah data yang perlu dibaca untuk menentukan hasil.
- DISTANCE_TYPE: menentukan jenis jarak default yang akan digunakan saat melakukan penelusuran vektor menggunakan indeks ini. Nilai yang didukung adalah EUCLIDEAN dan COSINE. EUCLIDEAN adalah defaultnya.
  
  Pembuatan indeks itu sendiri selalu menggunakan jarak EUCLIDEAN untuk pelatihan, tetapi jarak yang digunakan dalam fungsi VECTOR_SEARCH dapat berbeda.
  
  Jika Anda menentukan nilai untuk argumen distance_type dari fungsi VECTOR_SEARCH, nilai tersebut akan digunakan, bukan nilai DISTANCE_TYPE.
- NUM_LISTS: nilai INT64 kurang dari atau sama dengan 5.000 yang menentukan jumlah daftar yang dibuat oleh algoritma IVF. Algoritma IVF membagi seluruh ruang data menjadi sejumlah daftar yang sama dengan NUM_LISTS, dengan titik data yang lebih dekat satu sama lain lebih mungkin ditempatkan dalam daftar yang sama. Jika NUM_LISTS kecil, Anda memiliki lebih sedikit daftar dengan lebih banyak titik data, sedangkan nilai yang lebih besar akan membuat lebih banyak daftar dengan titik data yang lebih sedikit.
  
  Anda dapat menggunakan NUM_LISTS yang dikombinasikan dengan argumen fraction_lists_to_search dalam fungsi VECTOR_SEARCH untuk membuat penelusuran vektor yang efisien. Jika Anda memiliki data yang didistribusikan dalam banyak grup kecil di ruang embedding, tentukan NUM_LISTS tinggi untuk membuat indeks dengan lebih banyak daftar dan tentukan nilai fraction_lists_to_search yang lebih rendah untuk memindai daftar yang lebih sedikit dalam penelusuran vektor. Gunakan NUM_LISTS yang lebih rendah dan nilai fraction_lists_to_search yang lebih tinggi saat data Anda didistribusikan dalam kelompok yang lebih sedikit dan lebih besar. Menggunakan nilai num_lists yang tinggi dapat membuat indeks vektor membutuhkan waktu pembuatan yang lebih lama.
  
  Jika Anda tidak menentukan NUM_LISTS, BigQuery akan menghitung nilai yang sesuai.

Contoh berikut membuat indeks vektor pada kolom embedding pada my_table:

CREATE TABLE my_dataset.my_table(embedding ARRAY<FLOAT64>);

CREATE VECTOR INDEX my_index ON my_dataset.my_table(embedding)
OPTIONS(index_type = 'IVF');

Contoh berikut membuat indeks vektor pada kolom embedding dari my_table, dan menentukan jenis jarak yang akan digunakan serta opsi IVF:

CREATE TABLE my_dataset.my_table(embedding ARRAY<FLOAT64>);

CREATE VECTOR INDEX my_index ON my_dataset.my_table(embedding)
OPTIONS(index_type = 'IVF', distance_type = 'COSINE',
ivf_options = '{"num_lists": 2500}')

Memahami pemuatan ulang indeks

Indeks vektor dikelola sepenuhnya oleh BigQuery dan otomatis diperbarui saat tabel yang diindeks berubah. Jika Anda menghapus kolom yang diindeks dalam tabel atau mengganti nama tabel itu sendiri, indeks vektor akan dihapus secara otomatis.

Jika Anda membuat indeks vektor pada tabel yang berukuran lebih kecil dari 10 MB, indeks vektor tidak akan diisi. Demikian pula, jika Anda menghapus data dari tabel yang diindeks dan ukuran tabel di bawah 10 MB, indeks vektor akan dinonaktifkan untuk sementara. Dalam hal ini, kueri penelusuran vektor tidak menggunakan indeks dan kode indexUnusedReasons di bagian vectorSearchStatistics dari resource Job adalah BASE_TABLE_TOO_SMALL. Tanpa indeks, VECTOR_SEARCH secara otomatis akan kembali menggunakan brute force untuk menemukan tetangga terdekat embedding.

Kueri yang menggunakan fungsi VECTOR_SEARCH selalu menampilkan hasil yang benar, meskipun beberapa bagian data belum diindeks.

Mendapatkan informasi tentang indeks vektor

Anda dapat memverifikasi keberadaan dan kesiapan indeks vektor dengan membuat kueri INFORMATION_SCHEMA. Tampilan berikut berisi metadata pada indeks vektor:

Tampilan INFORMATION_SCHEMA.VECTOR_INDEXES memiliki informasi tentang indeks vektor dalam set data.

Setelah pernyataan CREATE VECTOR INDEX selesai, indeks harus tetap diisi sebelum Anda dapat menggunakannya. Anda dapat menggunakan kolom last_refresh_time dan coverage_percentage untuk memverifikasi kesiapan indeks vektor. Jika indeks vektor belum siap, Anda masih dapat menggunakan fungsi VECTOR_SEARCH pada tabel. Fungsi tersebut mungkin berjalan lebih lambat tanpa indeks.
Tampilan INFORMATION_SCHEMA.VECTOR_INDEX_COLUMNS memiliki informasi tentang kolom yang diindeks vektor untuk semua tabel dalam set data.
Tampilan INFORMATION_SCHEMA.VECTOR_INDEX_OPTIONS memiliki informasi tentang opsi yang digunakan oleh indeks vektor dalam set data.

Contoh indeks vektor

Contoh berikut menunjukkan semua indeks vektor aktif pada tabel dalam set data my_dataset, yang terletak di project my_project. Pernyataan ini mencakup nama, pernyataan DDL yang digunakan untuk membuatnya, dan persentase cakupannya. Jika tabel dasar yang diindeks kurang dari 10 MB, indeksnya tidak akan diisi, dan dalam hal ini nilai coverage_percentage adalah 0.

SELECT table_name, index_name, ddl, coverage_percentage
FROM my_project.my_dataset.INFORMATION_SCHEMA.VECTOR_INDEXES
WHERE index_status = 'ACTIVE';

Hasilnya akan mirip dengan berikut ini:

+-------------+-------------+-----------------------------------------------------------------------------------------------+---------------------+
| table_name  | index_name  | ddl                                                                                           | coverage_percentage |
+-------------+-------------+-----------------------------------------------------------------------------------------------+---------------------+
| small_table | myindex1    | CREATE VECTOR INDEX `myindex1` ON `my_project.my_dataset.small_table`(embeddings)             | 100                 |
|             |             | OPTIONS (distance_type = 'EUCLIDEAN', index_type = 'IVF', ivf_options = '{"numLists": 3}')    |                     |
+-------------+-------------+-----------------------------------------------------------------------------------------------+---------------------+
| large_table | myindex2    | CREATE VECTOR INDEX `myindex2` ON `my_project.my_dataset.large_table`(vectors)                |  42                 |
|             |             | OPTIONS (distance_type = 'EUCLIDEAN', index_type = 'IVF', ivf_options = '{"numLists": 12}')   |                     |
+-------------+-------------+-----------------------------------------------------------------------------------------------+---------------------+

Contoh kolom indeks vektor

Kueri berikut mengekstrak informasi tentang kolom yang memiliki indeks vektor:

SELECT table_name, index_name, index_column_name, index_field_path
FROM my_project.dataset.INFORMATION_SCHEMA.VECTOR_INDEX_COLUMNS;

Hasilnya akan mirip dengan berikut ini:

+------------+------------+-------------------+------------------+
| table_name | index_name | index_column_name | index_field_path |
+------------+------------+-------------------+------------------+
| table1     | indexa     | a                 | a                |
| table2     | indexb     | b                 | b                |
| table3     | indexc     | c                 | c                |
+------------+------------+-------------------+------------------+

Contoh opsi indeks vektor

Kueri berikut mengekstrak informasi tentang opsi indeks vektor:

SELECT table_name, index_name, option_name, option_type, option_value
FROM my_project.dataset.INFORMATION_SCHEMA.VECTOR_INDEX_OPTIONS;

Hasilnya akan mirip dengan berikut ini:

+------------+------------+------------------+------------------+--------------------+
| table_name | index_name | option_name      | option_type      | option_value       |
+------------+------------+------------------+------------------+--------------------+
| table1     | indexa     | distance_type    | STRING           | EUCLIDEAN          |
| table1     | indexa     | index_type       | STRING           | IVF                |
| table2     | indexb     | ivf_options      | STRING           | {"num_lists": 100} |
| table2     | indexb     | index_type       | STRING           | IVF                |
+------------+------------+------------------+------------------+--------------------+

Penggunaan indeks vektor

Informasi tentang penggunaan indeks vektor tersedia dalam metadata tugas dari tugas yang menjalankan kueri penelusuran vektor. Anda dapat melihat metadata tugas menggunakan Konsol Google Cloud, alat command line bq, BigQuery API, atau library klien.

Saat menggunakan konsol Google Cloud, Anda dapat menemukan informasi penggunaan indeks vektor di kolom Vector Index Usage Mode dan Vector Index Unused Basics.

Saat menggunakan alat bq atau BigQuery API, Anda dapat menemukan informasi penggunaan indeks vektor di bagian VectorSearchStatistics dari resource Job.

Mode penggunaan indeks menunjukkan apakah indeks vektor digunakan dengan memberikan salah satu dari nilai berikut:

UNUSED: Tidak ada indeks vektor yang digunakan.
PARTIALLY_USED: Beberapa fungsi VECTOR_SEARCH dalam kueri menggunakan indeks vektor dan beberapa tidak.
FULLY_USED: Setiap fungsi VECTOR_SEARCH dalam kueri menggunakan indeks vektor.

Jika nilai mode penggunaan indeks adalah UNUSED atau PARTIALLY_USED, alasan indeks yang tidak digunakan menunjukkan alasan indeks vektor tidak digunakan dalam kueri.

Misalnya, hasil yang ditampilkan oleh bq show --format=prettyjson -j my_job_id berikut menunjukkan bahwa indeks tidak digunakan karena opsi use_brute_force ditentukan dalam fungsi VECTOR_SEARCH:

"vectorSearchStatistics": {
  "indexUnusedReasons": [
    {
      "baseTable": {
        "datasetId": "my_dataset",
        "projectId": "my_project",
        "tableId": "my_table"
      },
      "code": "INDEX_SUPPRESSED_BY_FUNCTION_OPTION",
      "message": "No vector index was used for the base table `my_project:my_dataset.my_table` because use_brute_force option has been specified."
    }
  ],
  "indexUsageMode": "UNUSED"
}

Opsi pengelolaan indeks

Untuk membuat indeks dan meminta BigQuery mengelolanya, Anda memiliki dua opsi:

Menggunakan gabungan slot bersama default: Jika data yang ingin diindeks di bawah batas per organisasi, Anda dapat menggunakan gabungan slot bersama untuk pengelolaan indeks.
Menggunakan pemesanan Anda sendiri: Untuk mencapai progres pengindeksan yang lebih dapat diprediksi dan konsisten pada workload produksi yang lebih besar, Anda dapat menggunakan pemesanan sendiri untuk pengelolaan indeks.

Menggunakan slot bersama

Jika Anda belum mengonfigurasi project agar menggunakan pemesanan khusus untuk pengindeksan, pengelolaan indeks akan ditangani dalam gabungan slot bersama yang gratis dan tunduk pada batasan berikut.

Jika Anda menambahkan data ke tabel yang menyebabkan ukuran total tabel yang diindeks melebihi batas organisasi Anda, BigQuery akan menjeda pengelolaan indeks untuk semua tabel yang diindeks. Jika hal ini terjadi, kolom index_status di tampilan INFORMATION_SCHEMA.VECTOR_INDEXES akan menampilkan PENDING DISABLEMENT dan indeks diantrekan untuk dihapus. Meskipun dalam proses penonaktifan indeks, indeks masih digunakan dalam kueri dan Anda akan dikenai biaya untuk penyimpanan indeks. Setelah indeks dihapus, kolom index_status akan menunjukkan indeks sebagai TEMPORARILY DISABLED. Dalam status ini, kueri tidak menggunakan indeks, dan Anda tidak akan dikenai biaya untuk penyimpanan indeks. Dalam hal ini, kode IndexUnusedReason adalah BASE_TABLE_TOO_LARGE.

Jika Anda menghapus data dari tabel dan ukuran total tabel yang diindeks di bawah batas per organisasi, pengelolaan indeks akan dilanjutkan untuk semua tabel yang diindeks. Kolom index_status di tampilan INFORMATION_SCHEMA.VECTOR_INDEXES adalah ACTIVE, kueri dapat menggunakan indeks, dan Anda akan dikenai biaya untuk penyimpanan indeks.

BigQuery tidak menjamin ketersediaan kapasitas dari gabungan slot bersama atau throughput pengindeksan yang Anda lihat. Untuk aplikasi produksi, Anda dapat menggunakan slot khusus untuk pemrosesan indeks.

Menggunakan pemesanan Anda sendiri

Alih-alih menggunakan gabungan slot bersama default, Anda dapat menetapkan pemesanan sendiri untuk mengindeks tabel. Menggunakan reservasi Anda sendiri memastikan performa tugas pengelolaan indeks yang dapat diprediksi dan konsisten, seperti pembuatan, refresh, dan pengoptimalan latar belakang.

Tidak ada batas ukuran tabel saat tugas pengindeksan berjalan di pemesanan Anda.
Menggunakan pemesanan Anda sendiri memberi Anda fleksibilitas dalam pengelolaan indeks. Jika perlu membuat indeks yang sangat besar atau membuat update besar pada tabel yang diindeks, Anda dapat menambahkan lebih banyak slot ke penetapan untuk sementara.

Untuk mengindeks tabel dalam project dengan reservasi yang ditetapkan, buat reservasi di region tempat tabel Anda berada. Kemudian, tetapkan project ke reservasi dengan job_type yang ditetapkan ke BACKGROUND:

SQL

Gunakan pernyataan DDL CREATE ASSIGNMENT.

Di konsol Google Cloud, buka halaman BigQuery.

Buka BigQuery
Di editor kueri, masukkan pernyataan berikut:
```
CREATE ASSIGNMENT
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`
OPTIONS (
  assignee = 'projects/PROJECT_ID',
  job_type = 'BACKGROUND');
```
Ganti kode berikut:
- ADMIN_PROJECT_ID: project ID dari project administrasi yang memiliki resource pemesanan
- LOCATION: lokasi pemesanan
- RESERVATION_NAME: nama pemesanan
- ASSIGNMENT_ID: ID tugas
  
  ID harus unik untuk project dan lokasi, diawali dan diakhiri dengan huruf kecil atau angka, dan hanya berisi huruf kecil, angka, dan tanda hubung.
- PROJECT_ID: ID project yang berisi tabel yang akan diindeks. Project ini ditetapkan ke pemesanan.
Klik Run.

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

bq

Gunakan perintah bq mk:

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=RESERVATION_NAME \
    --assignee_id=PROJECT_ID \
    --job_type=BACKGROUND \
    --assignee_type=PROJECT

Ganti kode berikut:

ADMIN_PROJECT_ID: project ID dari project administrasi yang memiliki resource pemesanan
LOCATION: lokasi pemesanan
RESERVATION_NAME: nama pemesanan
PROJECT_ID: ID project yang akan ditetapkan ke pemesanan ini

Melihat tugas pengindeksan

Tugas pengindeksan baru dibuat setiap kali indeks dibuat atau diperbarui pada satu tabel. Untuk melihat informasi tentang tugas, buat kueri tampilan INFORMATION_SCHEMA.JOBS*. Anda dapat memfilter tugas pengindeksan dengan menetapkan job_type IS NULL AND SEARCH(job_id, '`search_index`') dalam klausa WHERE kueri Anda. Contoh berikut mencantumkan lima tugas pengindeksan terbaru dalam project my_project:

SELECT *
FROM
 region-us.INFORMATION_SCHEMA.JOBS
WHERE
  project_id  = 'my_project'
  AND job_type IS NULL
  AND SEARCH(job_id, '`search_index`')
ORDER BY
 creation_time DESC
LIMIT 5;

Memilih ukuran pemesanan Anda

Untuk memilih jumlah slot yang tepat untuk pemesanan, Anda harus mempertimbangkan kapan tugas pengelolaan indeks dijalankan, jumlah slot yang digunakan, dan seperti apa penggunaan Anda dari waktu ke waktu. BigQuery memicu tugas pengelolaan indeks dalam situasi berikut:

Anda membuat indeks pada tabel.
Data diubah dalam tabel yang diindeks.
Skema tabel berubah dan hal ini memengaruhi kolom mana yang akan diindeks.
Data dan metadata indeks dioptimalkan atau diperbarui secara berkala.

Jumlah slot yang Anda perlukan untuk tugas pengelolaan indeks pada tabel bergantung pada faktor-faktor berikut:

Ukuran tabel
Laju penyerapan data ke tabel
Tingkat pernyataan DML yang diterapkan pada tabel
Penundaan yang dapat diterima untuk membangun dan mempertahankan indeks
Kompleksitas indeks, biasanya ditentukan oleh atribut data, seperti jumlah istilah duplikat

Memantau Penggunaan dan Progres

Cara terbaik untuk menilai jumlah slot yang Anda perlukan untuk menjalankan tugas pengelolaan indeks secara efisien adalah dengan memantau penggunaan slot dan menyesuaikan ukuran pemesanan sebagaimana mestinya. Kueri berikut menghasilkan penggunaan slot harian untuk tugas pengelolaan indeks. Hanya 30 hari terakhir yang disertakan dalam region us-west1:

SELECT
  TIMESTAMP_TRUNC(job.creation_time, DAY) AS usage_date,
  -- Aggregate total_slots_ms used for index-management jobs in a day and divide
  -- by the number of milliseconds in a day. This value is most accurate for
  -- days with consistent slot usage.
  SAFE_DIVIDE(SUM(job.total_slot_ms), (1000 * 60 * 60 * 24)) AS average_daily_slot_usage
FROM
  `region-us-west1`.INFORMATION_SCHEMA.JOBS job
WHERE
  project_id = 'my_project'
  AND job_type IS NULL
  AND SEARCH(job_id, '`search_index`')
GROUP BY
  usage_date
ORDER BY
  usage_date DESC
limit 30;

Jika slot tidak cukup untuk menjalankan tugas pengelolaan indeks, indeks mungkin menjadi tidak sinkron dengan tabelnya dan tugas pengindeksan mungkin gagal. Dalam hal ini, BigQuery membangun ulang indeks dari awal. Untuk menghindari indeks yang tidak sinkron, pastikan Anda memiliki slot yang cukup untuk mendukung pembaruan indeks dari penyerapan dan pengoptimalan data. Untuk informasi selengkapnya tentang pemantauan penggunaan slot, lihat diagram resource admin.

Menghapus indeks vektor

Jika tidak lagi memerlukan indeks vektor atau ingin mengubah kolom mana yang diindeks pada tabel, Anda dapat menghapus indeks pada tabel tersebut menggunakan Pernyataan DDL DROP VECTOR INDEX.

Contoh:

DROP VECTOR INDEX my_index ON my_dataset.indexed_table;

Jika tabel yang diindeks dihapus, indeksnya dihapus secara otomatis.

Langkah selanjutnya

Untuk ringkasan kasus penggunaan, harga, dan batasan indeks vektor, lihat Pengantar penelusuran vektor.
Coba tutorial Penelusuran embedding dengan penelusuran vektor.