Melakukan penelusuran kemiripan vektor dengan Vertex AI

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

Inti dari fitur ini adalah penyematan 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 mirip secara semantik. Data Connect menggunakan ekstensi pgvector PostgreSQL untuk kemampuan ini.

Penelusuran semantik yang canggih ini dapat mendorong kasus penggunaan seperti mesin pemberi saran dan mesin telusur. Vektor ini juga merupakan komponen utama dalam Retrieval-Augmented Generation dalam alur AI generatif. Dokumentasi Vertex AI adalah tempat yang tepat untuk mempelajari lebih lanjut.

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

Prasyarat

• Siapkan Data Connect untuk project Anda.

  Catatan: Saat Anda menyelesaikan alur penyiapan, perlu diketahui bahwa integrasi Vertex AI Data 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 Data Connect produksi dan instance Cloud SQL untuk PostgreSQL-nya untuk pengembangan.

Catatan: Baik Anda bekerja secara lokal maupun dengan project produksi, Anda menggunakan Vertex AI, dan Anda akan dikenai biaya penggunaan Vertex AI.

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

Berintegrasi dengan PostgreSQL lokal

1. Siapkan instance PostgreSQL lokal.
2. Berikan peran IAM pengguna Vertex AI kepada diri Anda.
3. Siapkan Kredensial Default Aplikasi Google Cloud di lingkungan Anda.
4. Instal ekstensi pgvector di instance PostgreSQL lokal Anda.
5. Aktifkan ekstensi menggunakan CREATE EXTENSION vector per petunjuk repositori pgvector.

Mengintegrasikan dengan IDX

1. Siapkan ruang kerja IDX Anda menggunakan template Data Connect.
2. Berikan peran IAM pengguna Vertex AI kepada diri Anda.
3. Aktifkan ekstensi menggunakan CREATE EXTENSION vector per 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)
 // ...
}

Catatan: Pastikan dimensi penyematan vektor diberikan menggunakan direktif skema @col(size: X), karena penelusuran penyematan vektor hanya dapat membandingkan vektor dengan dimensi yang sama. Embedding vektor yang dihasilkan menggunakan Vertex AI berukuran 768.

Membuat dan mengambil embedding

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

Catatan: Embedding vektor yang dihasilkan dari versi model yang berbeda umumnya dianggap tidak kompatibel. Oleh karena itu, untuk semua operasi pada kolom (kueri atau mutasi), praktik terbaiknya adalah menggunakan embedding vektor yang dihasilkan menggunakan model yang sama. Daftar model Vertex AI yang didukung tersedia di dokumentasi.

Mutasi

Membuat dan menyimpan embedding melalui Data Connect

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

mutation createMovie($movieData: Movie_Data! @pick(fields: ["title", "genre", "description"])) {
  movie_insert(data: {
    ...movieData,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $movieData.description}
  })
}

Dalam beberapa kasus, Anda mungkin ingin memperbarui deskripsi dan penyematan 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 { updateMovieDescriptionWithEmbed } from 'lib/dataconnect-sdk/';

await updateMovieDescriptionWithEmbed({ 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 dihasilkan Data Connect tidak mendukung pengembaliannya secara langsung.

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

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

Melakukan penelusuran kemiripan

Sekarang kita dapat melakukan penelusuran kemiripan.

Untuk setiap kolom Vector, Data Connect menghasilkan fungsi GraphQL yang menerapkan penelusuran kesamaan. Nama fungsi yang dihasilkan 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 kesamaan. Seperti yang disebutkan di atas, nilai server _embed mengarahkan Data Connect untuk membuat embedding vektor menggunakan API Embedding Vertex AI, dalam hal ini untuk membuat embedding untuk string penelusuran yang digunakan untuk perbandingan dengan embedding deskripsi film.

Dalam contoh ini, penelusuran kesamaan akan menampilkan hingga 5 film yang deskripsinya paling mirip secara semantik dengan kueri input. Kumpulan hasil diurutkan dalam urutan menaik jarak - 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 Anda menampilkan hasil yang terlalu berbeda, atau tidak menampilkan 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 berbagai fungsi jarak 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.

Panggil kueri kemiripan

Untuk memanggil penelusuran kesamaan dari kode klien:

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

const response = await searchMovieDescriptionUsingL2similarity({ query });

// Use the response

Menggunakan penyematan kustom

Data Connect juga memungkinkan Anda bekerja dengan penyematan secara langsung sebagai Vector daripada menggunakan nilai server _embed untuk membuatnya.

Menyimpan penyematan 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 update untuk penyimpanan.

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

Melakukan penelusuran kesamaan menggunakan penyematan kustom

Lakukan operasi yang sama untuk mengambil embedding untuk istilah penelusuran dan mentransformasikannya 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

Deploy skema dan konektor Anda

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

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

firebase deploy --only dataconnect

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

Sintaksis penelusuran vektor

Ekstensi skema

Jenis data Vector Data Connect dipetakan ke jenis vector PostgreSQL seperti yang ditentukan oleh ekstensi pgvector. Jenis vector pgvector disimpan sebagai array angka floating point presisi tunggal di PostgreSQL.

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

Catatan: Numerik JavaScript kompatibel dengan paksaan float.

Gunakan parameter ukuran pada direktif @col untuk menetapkan dimensi vektor.

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

size hanya didukung untuk jenis Vector. Vector, seperti penelusuran kesamaan, 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 Data Connect untuk membuat dan menyimpan embedding menggunakan Vertex AI Embedding API. 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 subkumpulan algoritma penelusuran pgvector.

within: float

Batasan pada jarak di mana penelusuran tetangga terdekat dilakukan.

where: FDC filter condition

Lihat panduan skema, kueri, dan mutasi.

limit: int

Jumlah hasil yang akan ditampilkan.