Melakukan penelusuran kemiripan vektor dengan Vertex AI

Selamat datang di Firebase SQL Connect penelusuran kemiripan vektor — penerapan penelusuran semantik Firebase yang terintegrasi dengan Google Vertex AI.

Inti dari fitur ini adalah embedding vektor, yang merupakan array bilangan floating point yang merepresentasikan makna semantik teks atau media. Dengan menjalankan penelusuran tetangga terdekat menggunakan embedding vektor input, Anda dapat menemukan semua konten yang secara semantik serupa. SQL Connect menggunakan ekstensi pgvector PostgreSQL untuk kemampuan ini.

Penelusuran semantik yang canggih ini dapat mendorong kasus penggunaan seperti mesin pemberi saran dan mesin telusur. Fitur ini juga merupakan komponen utama dalam pembuatan yang didukung pengambilan generasi dalam alur AI generatif. Dokumentasi Vertex AI adalah tempat yang tepat untuk mempelajari lebih lanjut.

Anda dapat mengandalkan dukungan bawaan SQL Connect untuk membuat embedding vektor secara otomatis menggunakan Embeddings API Vertex AI, atau menggunakan API tersebut untuk membuatnya secara manual.

Prasyarat

Siapkan SQL Connect untuk project Anda.

Catatan: Saat Anda menggunakan alur penyiapan, perlu diketahui bahwa integrasi Vertex AI SQL Connect hanya didukung untuk lokasi Cloud SQL for PostgreSQL tertentu. Lihat daftar lokasi.
Aktifkan Vertex AI API.

Catatan: Anda tidak perlu membuat project Google Cloud terpisah atau menginstal Google Cloud CLI.

Penyiapan

Anda dapat memilih antara alur pengembangan lokal (jika Anda adalah developer web, Kotlin Android, atau iOS) atau alur IDX (untuk developer web). Anda dapat menggunakan database lokal atau project SQL Connect produksi dan instance Cloud SQL for PostgreSQL untuk pengembangan.

Petunjuk ini mengasumsikan bahwa Anda telah membuat project SQL Connect Anda dengan mengikuti panduan memulai cepat.

Berintegrasi dengan PostgreSQL lokal

Siapkan instance PostgreSQL lokal.
Berikan peran IAM pengguna Vertex AI kepada Anda.
Siapkan Kredensial Default Aplikasi Google Cloud di lingkungan Anda.
Instal ekstensi pgvector di instance PostgreSQL lokal Anda.
Aktifkan ekstensi menggunakan CREATE EXTENSION vector sesuai petunjuk repositori pgvector.

Berintegrasi dengan IDX

Siapkan ruang kerja IDX menggunakan template SQL Connect.
Berikan peran IAM pengguna Vertex AI kepada Anda.
Aktifkan ekstensi menggunakan CREATE EXTENSION vector sesuai petunjuk repositori pgvector.

Mendesain skema

Untuk melakukan penelusuran vektor, tambahkan kolom baru berjenis Vector dalam skema Anda. Misalnya, jika Anda ingin melakukan penelusuran semantik menggunakan deskripsi film, tambahkan kolom untuk menyimpan embedding vektor yang terkait dengan deskripsi film. Dalam skema ini, descriptionEmbedding ditambahkan untuk menyimpan embedding vektor untuk kolom description

type Movie @table {
 id: ID! @col(name: "movie_id") @default(id: ID! @col(name: "movie_id") @default(expr: "uuidV4()")
 title: String!
 description: String
 descriptionEmbedding: Vector! @col(size:768)
 // ...
}

Membuat dan mengambil embedding

SQL Connect menyediakan dukungan terintegrasi untuk embedding vektor dengan nilai server _embed. Hal ini mengarahkan SQL Connect untuk membuat embedding vektor dengan memanggil Embedding API Vertex AI secara internal. Nilai server _embed dapat digunakan dalam mutasi dan kueri.

Mutasi

Membuat dan menyimpan embedding melalui SQL Connect

Di aplikasi penelusuran vektor, Anda mungkin ingin meminta agar embedding dibuat segera setelah Anda menambahkan data ke database. Berikut adalah createMovie mutasi yang menambahkan data film ke tabel Movie dan juga meneruskan deskripsi film dengan embedding model yang ditentukan.

mutation createMovie($title: String!, $description: String!) {
  movie_insert(data: {
    title: $title,
    description: $description,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $description}
  })
}

Dalam beberapa kasus, Anda mungkin ingin memperbarui deskripsi dan embedding film.

mutation updateDescription($id: String!, $description: String!) {
  movie_update(id: $id, data: {
    description: $description,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $description}
  })
}

Untuk memanggil mutasi terakhir dari klien:

import { updateMovieDescription } from 'lib/dataconnect-sdk/';

await updateMovieDescription({ id: movieId, description: description});

// Use the response

Kueri

Ambil embedding vektor menggunakan kueri seperti berikut. Perhatikan bahwa descriptionEmbedding yang ditampilkan oleh kueri adalah array float, yang biasanya tidak dapat dibaca manusia. Oleh karena itu, SDK yang dibuat SQL Connect tidak mendukung pengembaliannya secara langsung.

Anda dapat menggunakan embedding vektor yang ditampilkan untuk melakukan penelusuran kemiripan, seperti yang dijelaskan di bagian berikutnya.

query getMovieDescription($id: String!) @auth(level: PUBLIC) {
 movie(id: $id)
   id
   description
   descriptionEmbedding
}

Melakukan penelusuran kemiripan

Sekarang kita dapat melakukan penelusuran kemiripan.

Untuk setiap kolom Vector, SQL Connect membuat fungsi GraphQL yang mengimplementasikan penelusuran kemiripan. Nama fungsi yang dibuat ini adalah ${pluralType}_${vectorFieldName}_similarity. Fungsi ini mendukung beberapa parameter seperti yang ditunjukkan dalam contoh berikut dan dalam daftar referensi.

Anda dapat menentukan fungsi GraphQL yang memanggil penelusuran kemiripan. Seperti yang disebutkan di atas, nilai server _embed mengarahkan SQL Connect untuk membuat embedding vektor menggunakan Embedding API Vertex AI, dalam hal ini untuk membuat embedding untuk string penelusuran yang digunakan untuk perbandingan dengan embedding deskripsi film.

Dalam contoh ini, penelusuran kemiripan akan menampilkan hingga 5 film yang deskripsinya secara semantik paling dekat dengan kueri input. Kumpulan hasil diurutkan dalam urutan jarak menaik - terdekat hingga terjauh.

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", text: $query},
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
      }
  }

Menyesuaikan kueri kemiripan

Nilai default untuk parameter penelusuran seperti method dan within berfungsi dengan baik untuk sebagian besar kasus penggunaan. Namun, jika Anda melihat bahwa kueri menampilkan hasil yang terlalu berbeda, atau tidak menemukan hasil yang ingin Anda sertakan, coba sesuaikan parameter ini.

Untuk menemukan nilai yang sesuai untuk within, kita dapat menambahkan _metadata.distance ke kolom yang dipilih untuk melihat seberapa jauh setiap hasil dari vektor kueri. Berdasarkan nilai distance yang ditampilkan, kita dapat menetapkan parameter within; hanya hasil dengan jarak kurang dari nilai within yang akan disertakan:

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", text: $query},
      within: 2,
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
        _metadata {
          distance
        }
      }
  }

Anda juga dapat bereksperimen dengan fungsi jarak yang berbeda dengan menetapkan parameter method.

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", text: $query},
      within: .5,
      method: COSINE,
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
        _metadata {
          distance
        }
      }
  }

Perhatikan bahwa metode yang berbeda menampilkan nilai jarak yang sangat berbeda: jika Anda telah menetapkan within, Anda harus menyesuaikan nilai tersebut lagi setelah mengubah method.

Memanggil kueri kemiripan

Untuk memanggil penelusuran kemiripan dari kode klien:

import { searchMovieDescriptionUsingL2similarity} from 'lib/dataconnect-sdk';

const response = await searchMovieDescriptionUsingL2similarity({ query });

// Use the response

Menggunakan penyematan kustom

SQL Connect juga memungkinkan Anda bekerja dengan embedding secara langsung sebagai Vectors dan tidak menggunakan nilai server _embed untuk membuatnya.

Menyimpan embedding kustom

Dengan menggunakan Vertex Embeddings API, tentukan model yang cocok dan minta hasil embedding dengan dimensi yang benar.

Kemudian, transmisikan array float yang ditampilkan ke Vector untuk diteruskan ke operasi pembaruan untuk penyimpanan.

mutation updateDescription($id: String!, $description: String!, $descriptionEmbedding: Vector!) {
  movie_update(id: $id, data: {
    // title, genre...
    description: $description,
    descriptionEmbedding: $descriptionEmbedding
  })
}

Melakukan penelusuran kemiripan menggunakan embedding kustom

Lakukan operasi yang sama untuk mengambil embedding untuk istilah penelusuran dan transmisikan ke Vectors.

Kemudian, panggil kueri _similarity untuk melakukan setiap penelusuran.

query searchMovieDescriptionUsingL2Similarity($compare: Vector!, $within: Float, $excludesContent: String, $limit: Int) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare: $compare,
      method: L2,
      within: $within,
      where: {content: {ne: $excludesContent}}, limit: $limit)
      {
        id
        title
        description
      }
  }

Men-deploy ke produksi

Men-deploy skema dan konektor

Langkah terakhir dalam iterasi SQL Connect yang umum adalah men-deploy aset Anda ke produksi.

Saat men-deploy skema yang berisi jenis Vector ke CloudSQL menggunakan perintah firebase deploy, Firebase CLI akan mengambil langkah-langkah yang diperlukan untuk mengaktifkan pembuatan embedding berbasis Vertex AI di instance CloudSQL Anda.

firebase deploy --only dataconnect

Jika Anda ingin mengaktifkan dukungan embedding di instance CloudSQL secara manual, atau mengalami error CLI, ikuti petunjuk ini.

Sintaksis penelusuran vektor

Ekstensi skema

SQL ConnectJenis data Vector dipetakan ke jenis vector PostgreSQL seperti yang ditentukan oleh ekstensi pgvector. Jenis vector pgvector disimpan sebagai array bilangan floating point presisi tunggal di PostgreSQL.

Di SQL Connect, jenis Vector direpresentasikan sebagai array bilangan JSON. Input dipaksa menjadi array nilai float32. Jika paksaan gagal, error akan muncul.

Gunakan parameter ukuran direktif @col untuk menetapkan dimensi vektor.

type Question @table {
    text: String!
    category: String!
    textEmbedding: Vector! @col(size: 768)
}

size hanya didukung untuk jenis Vector. Operasi Vector, seperti penelusuran kemiripan, mengharuskan semua Vector memiliki jumlah dimensi yang sama.

directive @col(
  # … existing args
  """
  Defines a fixed column size for certain scalar types.

  - For Vector, size is required.
  - For all other types, size is currently unsupported and hence supplying it will result in a schema error.
  """
  size: Int
) on FIELD_DEFINITION

Nilai server `_embed` untuk kueri dan mutasi

_embed

Nilai server ini mengarahkan layanan SQL Connect untuk membuat dan menyimpan embedding menggunakan Embedding API Vertex AI. Nilai server ini dapat digunakan pada kueri dan mutasi.

Parameter Untuk penelusuran kemiripan

method: COSINE|INNER_PRODUCT|L2

Fungsi jarak yang digunakan untuk menelusuri tetangga terdekat. Algoritma yang saat ini didukung adalah subset algoritma penelusuran pgvector.

within: float

Batasan jarak tempat penelusuran tetangga terdekat dilakukan.

where: FDC filter condition

Lihat panduan skema, kueri, dan mutasi.

limit: int

Jumlah hasil yang akan ditampilkan.