Referensi fungsi bantuan vektor

Pilih versi dokumentasi: 18.1.0

• Saat ini (18.1.0)
• 18.1.0

Lihat fungsi bantuan vektor mendetail berikut untuk menyederhanakan workload vektor AlloyDB Omni Anda.

vector_assist.define_spec

Mendefinisikan spesifikasi vektor baru, atau spesifikasi vektor, dan menampilkan rekomendasi yang diperlukan untuk meningkatkan workload vektor. Fungsi ini menerapkan spesifikasi yang disediakan pengguna untuk membuat rekomendasi.

Catatan: Fungsi ini adalah operasi yang berjalan lama (LRO). Jika Anda menggunakan klien dengan waktu tunggu (seperti studio AlloyDB Omni dengan waktu tunggu 5 menit), panggilan fungsi dapat dihentikan. Untuk memitigasi masalah ini, Anda dapat meningkatkan nilai minimum waktu tunggu, atau membuat salinan tabel yang Anda gunakan dengan hanya sebagian kecil data untuk memenuhi persyaratan waktu tunggu.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.define_spec(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT,
    schema_name TEXT DEFAULT NULL,
    vector_column_name TEXT DEFAULT NULL,
    text_column_name TEXT DEFAULT NULL,
    vector_index_type TEXT DEFAULT NULL, -- Allowed: 'hnsw', 'ivfflat'
    embeddings_available BOOL DEFAULT NULL,
    embedding_model TEXT DEFAULT NULL,
    num_vectors INT DEFAULT NULL,
    dimensionality INT DEFAULT NULL,
    distance_func TEXT DEFAULT NULL, -- Allowed: 'cosine', 'ip', 'l2', 'l1'
    quantization TEXT DEFAULT NULL, -- Allowed: 'none', 'halfvec', 'bit'
    prefilter_column_names TEXT[] DEFAULT NULL,
    memory_budget_kb INT DEFAULT NULL, -- In KB
    target_recall FLOAT DEFAULT NULL,
    target_top_k INT DEFAULT NULL,
    tune_vector_index BOOL DEFAULT FALSE, -- Set to true if target_recall is set
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Parameter

Parameter	Wajib?	Deskripsi
spec_id	Opsional, dibuat otomatis jika tidak diberikan	ID unik untuk spesifikasi vektor yang Anda tentukan.
table_name	Wajib	Nama tabel yang akan digunakan dalam penyiapan beban kerja vektor.
schema_name	Opsional	Skema yang berisi tabel yang akan digunakan dalam workload vektor. Skema disimpulkan secara otomatis berdasarkan jalur penelusuran skema.
vector_column_name	Lihat deskripsi	Nama kolom untuk kolom yang berisi penyematan vektor. Kolom ini wajib diisi jika Anda menggunakan lebih dari satu kolom vektor dan text_column_name tidak dideklarasikan. Jika Anda hanya menggunakan satu kolom vektor, parameter ini bersifat opsional.
text_column_name	Lihat deskripsi	Nama kolom untuk kolom teks. Jika workload vektor Anda memerlukan pembuatan embedding dari kolom teks, parameter ini diperlukan. Kolom ini wajib diisi jika parameter vector_column_name adalah NULL dan tidak ada kolom vektor lainnya. Parameter ini menggunakan ekstensi google_ml_integration untuk membuat embedding dari kolom teks yang diberikan.
vector_index_type	Opsional	Jenis indeks vektor. Nilai yang dapat diterima mencakup: (Default) HNSW IVFFlat
embeddings_available	Opsional	Boolean yang memeriksa apakah ada penyematan vektor dalam tabel yang dipilih. Kolom ini ditetapkan ke FALSE jika tidak ada kolom vektor yang terdeteksi dan parameter text_column_name ditetapkan.
embedding_model	Lihat deskripsi	ID model yang digunakan untuk membuat embedding. Kolom ini bersifat opsional, kecuali jika parameter embeddings_available adalah FALSE atau NULL. Nilai defaultnya adalah text-embedding-005.
num_vectors	Opsional	Jumlah vektor dalam tabel.
dismensionality	Opsional	Dimensi vektor yang diberikan.
distance_func	Opsional	Fungsi jarak yang akan digunakan untuk membandingkan vektor. Nilai yang dapat diterima mencakup: cosine: default jika quantization tidak ditetapkan ke bit ip l2 l1 jaccard hamming: default saat quantization disetel ke bit
quantization	Opsional	Kuantisasi untuk indeks vektor. Nilai yang dapat diterima mencakup: none: default saat dimensionality lebih kecil dari 2000 halfvec: default saat dimensionality berada di antara 2000 dan 4000 bit: default saat dimensionality lebih besar dari 4,000
prefilter_column_names	Opsional	Merekomendasikan indeks untuk kolom tertentu untuk prapenyaringan. Hal ini dapat membantu meningkatkan performa kueri dengan filter selektivitas tinggi pada kolom.
memory_budget_kb	Opsional	Memori maksimum (dalam KB) untuk pembuatan indeks. Nilai defaultnya adalah 60% dari memori instance.
target_recall	Opsional	Target perolehan untuk kueri vektor standar.
target_top_k	Opsional	Nilai yang cocok dengan K teratas untuk diambil untuk perhitungan recall. Nilai ini digunakan jika parameter target_recall ditentukan.
tune_vector_index	Opsional	Menyesuaikan indeks vektor dalam workload Anda. Jika diaktifkan, bantuan vektor akan otomatis menyesuaikan indeks vektor dan kueri penelusuran untuk sasaran perolehan kembali target menggunakan spesifikasi vektor, serta menghitung parameter indeks dan database yang optimal. Nilai yang dapat diterima mencakup: (Default)FALSE: hanya menyetel parameter penelusuran (ef_search). Nilai parameter waktu pembuatan indeks default (m, ef_construction) digunakan. TRUE: sesuaikan parameter waktu pembuatan penelusuran dan indeks.

Nilai yang ditampilkan

Menampilkan tabel rekomendasi, yang mencakup ID spesifikasi vektor yang baru dibuat.

vector_assist.list_specs

Menampilkan spesifikasi vektor saat ini untuk tabel dan kolom tertentu.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.list_specs(
  table_name      TEXT,
  column_name     TEXT DEFAULT NULL
)
RETURNS SETOF vector_assist.VECTOR_SPECS

Parameter

Parameter	Wajib?	Deskripsi
table_name	Wajib	Nama tabel yang spesifikasi vektornya diambil.
column_name	Opsional	Nama kolom untuk memfilter tabel sebelum menampilkan spesifikasi. Jika nama kolom ditentukan, spesifikasi yang berisi nama kolom teks atau vektor yang cocok dengan nama kolom ini akan ditampilkan.

Nilai yang ditampilkan

Menampilkan tabel spesifikasi untuk tabel tertentu dan secara opsional, nama kolom.

vector_assist.modify_spec

Mengubah spesifikasi vektor yang ada. Saat spesifikasi vektor diubah, rekomendasi terkait akan dibuat ulang berdasarkan spesifikasi baru.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.modify_spec(
  spec_id                TEXT,
  table_name             TEXT DEFAULT NULL,
  schema_name            TEXT DEFAULT NULL,
  vector_column_name     TEXT DEFAULT NULL,
  text_column_name       TEXT DEFAULT NULL,
  vector_index_type      TEXT DEFAULT NULL,
  embeddings_available   BOOL DEFAULT NULL,
  num_vectors            INT DEFAULT NULL,
  dimensionality         INT DEFAULT NULL,
  embedding_model        TEXT DEFAULT NULL,
  prefilter_column_names TEXT[] DEFAULT NULL,
  distance_func          TEXT DEFAULT NULL,
  quantization           TEXT DEFAULT NULL,
  memory_budget_kb       INT DEFAULT NULL,
  target_recall          FLOAT DEFAULT NULL,
  target_top_k           INT DEFAULT NULL,
  tune_vector_index      BOOL DEFAULT NULL
)
RETURNS SETOF vector_assist.RECOMMENDATIONS

Parameter

Parameter	Wajib?	Deskripsi
spec_id	Wajib	ID unik untuk spesifikasi vektor yang Anda tentukan.
table_name	Wajib	Nama tabel yang akan digunakan dalam penyiapan beban kerja vektor.
schema_name	Opsional	Skema yang berisi tabel yang akan digunakan dalam workload vektor. Skema disimpulkan secara otomatis berdasarkan jalur penelusuran skema.
vector_column_name	Lihat deskripsi	Nama kolom untuk kolom yang berisi penyematan vektor. Kolom ini wajib diisi jika Anda menggunakan lebih dari satu kolom vektor dan text_column_name tidak dideklarasikan. Jika Anda hanya menggunakan satu kolom vektor, parameter ini bersifat opsional.
text_column_name	Lihat deskripsi	Nama kolom untuk kolom teks. Jika workload vektor Anda memerlukan pembuatan embedding dari kolom teks, parameter ini diperlukan. Kolom ini wajib diisi jika parameter vector_column_name adalah NULL dan tidak ada kolom vektor lainnya. Parameter ini menggunakan ekstensi google_ml_integration untuk membuat embedding dari kolom teks yang diberikan.
vector_index_type	Opsional	Jenis indeks vektor. Nilai yang dapat diterima mencakup: HNSW IVFFlat
embeddings_available	Opsional	Boolean yang memeriksa apakah ada penyematan vektor dalam tabel yang dipilih. Kolom ini ditetapkan ke FALSE jika tidak ada kolom vektor yang terdeteksi dan parameter text_column_name ditetapkan.
embedding_model	Lihat deskripsi	ID model yang digunakan untuk membuat embedding. Kolom ini bersifat opsional, kecuali jika parameter embeddings_available adalah FALSE atau NULL. Nilai defaultnya adalah text-embedding-005.
num_vectors	Opsional	Jumlah vektor dalam tabel.
dismensionality	Opsional	Dimensi vektor yang diberikan.
distance_func	Opsional	Fungsi jarak yang akan digunakan untuk membandingkan vektor. Nilai yang dapat diterima mencakup cosine, ip, l2, atau l1.
quantization	Opsional	Kuantisasi untuk indeks vektor. Nilai yang dapat diterima mencakup none, halfvec, atau bit.
prefilter_column_names	Opsional	Mengidentifikasi kolom yang tersedia untuk prapenyaringan dalam kueri penelusuran vektor.
memory_budget_kb	Opsional	Memori maksimum (dalam KB) untuk pembuatan indeks.
target_recall	Opsional	Target perolehan untuk kueri vektor standar.
target_top_k	Opsional	Nilai yang cocok dengan K teratas untuk diambil untuk perhitungan recall. Nilai ini digunakan jika parameter target_recall ditentukan.
tune_vector_index	Opsional	Menyesuaikan indeks vektor dalam workload Anda. Jika diaktifkan, bantuan vektor menyesuaikan indeks vektor atau kueri penelusuran secara otomatis menggunakan spesifikasi vektor, dan menghitung parameter database dan indeks yang optimal. Nilai yang dapat diterima mencakup TRUE atau FALSE.

Nilai yang ditampilkan

Menampilkan tabel yang diperbarui berisi rekomendasi.

vector_assist.get_recommendations

Menampilkan rekomendasi yang terkait dengan vektor spec_id tertentu.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
    spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Parameter

Parameter	Wajib?	Deskripsi
spec_id	Wajib	Mendapatkan rekomendasi untuk vektor spec_id yang ditentukan.

Nilai yang ditampilkan

Menampilkan tabel rekomendasi yang harus diterapkan untuk menyiapkan workload vektor yang diminta. Setiap baris adalah satu rekomendasi yang berisi kueri SQL yang dapat dieksekusi dan penjelasan mendetail tentang alasan penerapan rekomendasi. Rekomendasi dapat diterapkan menggunakan fungsi apply_recommendation().

Tabel rekomendasi berisi kolom berikut:

Nama kolom	Jenis	Deskripsi
recommendation_id	Teks	ID rekomendasi. Rekomendasi diterapkan menggunakan ID ini.
vector_spec_id	Teks	ID spesifikasi vektor yang terkait dengan rekomendasi.
table_name	Teks	Nama tabel yang terkait dengan rekomendasi.
schema_name	Teks	Nama skema yang berisi tabel tertentu.
query	Teks	Kueri SQL yang dapat dieksekusi untuk mencapai hasil rekomendasi.
recommendation	Teks	Penjelasan untuk rekomendasi, termasuk perkiraan hasil setelah rekomendasi diterapkan. Kolom ini juga berisi alasan dan rasionalisasi rekomendasi. Anda dapat menggunakan konteks ini untuk menyesuaikan kueri sesuai kebutuhan dan membuat ulang rekomendasi.
applied	Boolean	Menunjukkan apakah rekomendasi telah diterapkan.
modified	Boolean	Menunjukkan apakah rekomendasi telah diubah oleh pengguna.
created_at	Stempel waktu dengan zona waktu	Waktu saat rekomendasi dibuat.

vector_assist.apply_recommendation

Menerapkan satu rekomendasi menggunakan recommendation_id.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.apply_recommendation (
    recommendation_id TEXT
)
RETURNS BOOLEAN;

Parameter

Parameter	Wajib?	Deskripsi
recommenation_id	Wajib	ID rekomendasi vektor yang akan diterapkan.

Nilai yang ditampilkan

Menampilkan boolean yang mengonfirmasi apakah rekomendasi berhasil diterapkan dan memperbarui kolom tabel vector_assist.RECOMMENDATIONS applied menjadi TRUE.

Jika bantuan vektor tidak dapat menerapkan rekomendasi, pesan error akan muncul jika terjadi kegagalan.

vector_assist.apply_spec

Menerapkan semua rekomendasi yang terkait dengan vektor spec_id atau nama tabel tertentu. Fungsi ini akan memeriksa semua rekomendasi dan menjalankan fungsi vector_assist.apply_recommendation pada setiap rekomendasi.

Catatan: Fungsi ini adalah operasi yang berjalan lama (LRO). Jika Anda menggunakan klien dengan waktu tunggu (seperti studio AlloyDB Omni dengan waktu tunggu 5 menit), panggilan fungsi dapat dihentikan. Untuk memitigasi masalah ini, Anda dapat meningkatkan nilai minimum waktu tunggu, atau membuat salinan tabel yang Anda gunakan dengan hanya sebagian kecil data untuk memenuhi persyaratan waktu tunggu.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.apply_spec(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT DEFAULT NULL,
    schema_name TEXT DEFAULT NULL,
    column_name TEXT DEFAULT NULL -- text_column_name or vector_column_name
)
RETURNS BOOLEAN;

Parameter

Anda harus menentukan spec_id atau table_name untuk menjalankan fungsi.

Parameter	Wajib?	Deskripsi
spec_id	Opsional	Menerapkan semua rekomendasi untuk vektor spec_id tertentu.
table_name	Opsional	Menerapkan semua rekomendasi untuk tabel tertentu.
schema_name	Opsional	Skema yang berisi tabel yang ditentukan.
column_name	Opsional	Mengidentifikasi text_column_name atau vector_column_name yang akan digunakan jika tabel berisi beberapa spesifikasi vektor.

Nilai yang ditampilkan

Menampilkan boolean yang mengonfirmasi apakah semua rekomendasi berhasil diterapkan dan menetapkan nilai di kolom tabel vector_assist.RECOMMENDATIONS applied ke TRUE untuk semua rekomendasi.

Jika bantuan vektor tidak dapat menerapkan rekomendasi, pesan error akan muncul jika terjadi kegagalan.

vector_assist.modify_recommendation

Mengubah kueri untuk rekomendasi tertentu dan menetapkan kolom modified dalam tabel vector_assist.RECOMMENDATIONS untuk rekomendasi terkait ke TRUE.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.modify_recommendation(
    recommendation_id TEXT,
    modified_query TEXT
)
RETURNS BOOLEAN;

Parameter

Parameter	Wajib?	Deskripsi
recommendation_id	Wajib	ID rekomendasi yang akan diubah.
modified_query	Wajib	Kueri SQL yang diubah pengguna untuk rekomendasi.

Nilai yang ditampilkan

Menampilkan boolean yang mengonfirmasi apakah rekomendasi berhasil diperbarui dan menetapkan kolom tabel vector_assist.RECOMMENDATIONS modified ke TRUE.

Jika bantuan vektor tidak dapat memperbarui rekomendasi, pesan error akan muncul jika terjadi kegagalan.

vector_assist.generate_query

Membuat kueri penelusuran vektor yang dioptimalkan berdasarkan spesifikasi vektor dan parameter penelusuran yang ditentukan. Fungsi ini dapat menyesuaikan nilai ef_search untuk memenuhi target_recall yang ditetapkan jika berlaku.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.generate_query(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT DEFAULT NULL,
    schema_name TEXT DEFAULT NULL,
    column_name TEXT DEFAULT NULL, -- text_column_name or vector_column_name of the spec
    search_text TEXT DEFAULT NULL,
    search_vector VECTOR DEFAULT NULL, -- e.g. '[1.0,2.0,3.0]'::vector
    output_column_names TEXT[] DEFAULT NULL, -- Columns to retrieve, NULL for SELECT *
    top_k INT DEFAULT NULL,
    filter_expressions TEXT[] DEFAULT NULL,
    target_recall FLOAT DEFAULT NULL, -- Inherited from spec, can be overridden
    iterative_index_search BOOL DEFAULT NULL
)
RETURNS TEXT; -- Returns the text representing the search query

Parameter

Anda harus menentukan spec_id atau table_name untuk menjalankan fungsi.

Parameter	Wajib?	Deskripsi
spec_id	Opsional	Menentukan spec_id untuk membuat kueri.
table_name	Opsional	Menentukan nama tabel untuk membuat kueri penelusuran jika spec_id tidak diberikan. Jika tabel berisi beberapa spesifikasi, parameter akan menampilkan error.
column_name	Opsional	Menentukan nama kolom untuk membuat kueri penelusuran jika spec_id tidak diberikan. Jika kolom berisi beberapa spesifikasi, maka parameter akan menampilkan error. column_name mungkin berupa text_column_name atau vector_column_name.
output_column_name	Opsional	Nama kolom yang akan diambil dalam kueri output. Untuk mengambil semua kolom, tetapkan parameter ini ke NULL.
search_text	Opsional	Teks penelusuran untuk membuat embedding. Penyematan dibuat menggunakan embedding_model dari spesifikasi. Anda hanya dapat menetapkan parameter search_text atau search_vector.
search_vector	Opsional	Vektor untuk kueri penelusuran. Anda hanya dapat menetapkan parameter search_text atau search_vector
top_k	Opsional	Jumlah tetangga terdekat yang akan ditampilkan.
filter_expressions	Opsional	Ekspresi filter yang akan diterapkan dalam kueri penelusuran. Filter dapat diterapkan ke kolom dalam tabel, seperti harga < 100.
iterative_index_search	Opsional	Menetapkan apakah akan melakukan penelusuran indeks iteratif untuk kueri yang difilter.
target_recall	Opsional	Target perolehan untuk kueri penelusuran saja. Jika ditetapkan, fungsi dapat menampilkan rekomendasi untuk ef_search jika menemukan nilai yang lebih baik.

Nilai yang ditampilkan

Menampilkan teks yang berisi kueri penelusuran vektor untuk parameter tertentu. Jika target_recall ditentukan, rekomendasi untuk ef_search juga dapat disertakan jika nilai yang lebih baik ditemukan. Kueri ini dapat dieksekusi atau disimpan untuk dijalankan nanti.

vector_assist.evaluate_query_recall

Mengevaluasi recall indeks vektor untuk kueri tertentu. Fungsi ini menggunakan konfigurasi database dan indeks dalam string JSON sebagai input.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.evaluate_query_recall(
  ann_query text,
  vector_search_configurations json DEFAULT NULL,
  recall float,
  ann_execution_time float,
  ground_truth_execution_time float,
  index_type text)
RETURNS RECORD

Parameter

Parameter	Wajib?	Deskripsi
ann_query	Wajib	Kueri SQL yang perlu dievaluasi perolehan kembali informasinya. Kueri ini harus berupa kueri ANN pgvector.
vector_search_configurations	Opsional	Konfigurasi yang dapat ditetapkan untuk kueri ANN. Parameter ini harus dalam format JSON.

Nilai yang ditampilkan

Menampilkan tabel yang mengevaluasi perolehan indeks vektor untuk kueri yang diberikan.

Tabel berisi kolom berikut:

Nama kolom	Jenis	Deskripsi
recall	Float	Persentase vektor yang ditampilkan indeks, yang merupakan tetangga terdekat sebenarnya. Metrik ini digunakan untuk mengukur kualitas penelusuran. Fungsi ini memungkinkan Anda menyesuaikan parameter untuk menampilkan hasil pencarian vektor yang diharapkan.
ann_execution_time	Float	Waktu yang diperlukan kueri vektor untuk dieksekusi menggunakan pemindaian indeks.
ground_truth_execution_time	Float	Waktu yang diperlukan kueri untuk dijalankan menggunakan pemindaian berurutan.
index_type	Teks	Jenis indeks vektor, seperti HNSW.

Contoh

Contoh berikut mengevaluasi recall untuk indeks HNSW dan menggantikan parameter konfigurasi HNSW.ef_search:

SELECT * FROM vector_assist.evaluate_query_recall(
  ann_query => 'SELECT id FROM items ORDER BY embedding <=> ''[1,2,3]'' LIMIT 10',
  vector_search_configurations => '{"hnsw.ef_search": 30}'
);