Panduan memulai Vector Search

Dalam panduan memulai Vector Search Platform Agen Gemini Enterprise, pelajari cara membuat indeks dari set data contoh dari situs pakaian ecommerce fiktif. Untuk tujuan panduan memulai ini, embedding telah dibuat. Panduan memulai ini dimaksudkan sebagai cara untuk mulai membuat dan men-deploy indeks dalam waktu kurang dari 30 menit.

Prasyarat

Tutorial ini memerlukan Google Cloud project yang ditautkan dengan akun penagihan. Untuk membuat project baru, lihat Menyiapkan project dan lingkungan pengembangan. Anda harus membuat project dan menyiapkan akun penagihan.

Memilih lingkungan runtime

Tutorial ini dapat dijalankan di Colab atau Workbench Platform Agen Gemini Enterprise.

  • Colab: Buka tutorial ini di Colab
  • Workbench Platform Agen Gemini Enterprise: Buka tutorial ini di Workbench Platform Agen Gemini Enterprise. Jika ini adalah pertama kalinya Anda menggunakan Workbench Platform Agen Gemini Enterprise di Google Cloud project Anda, buka bagian Workbench Platform Agen Gemini Enterprise di Google Cloud konsol dan klik Aktifkan untuk mengaktifkan Notebooks API.

Untuk melihat notebook ini di GitHub, lihat GitHub.

Biaya untuk menyelesaikan panduan memulai ini

Untuk menyelesaikan tutorial ini, biayanya kira-kira beberapa dolar AS. Harga layanan yang digunakan dalam tutorial ini tersedia di halaman berikut: Google Cloud

Anda juga dapat menggunakan kalkulator harga untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan.

Penyiapan

Sebelum memulai Platform Agen Gemini Enterprise, Anda harus menyiapkan hal berikut:

Menginstal Agent Platform SDK untuk Python

Gemini Enterprise Agent Platform dan Cloud Storage API dapat diakses dengan berbagai cara, termasuk REST API dan Agent Platform SDK untuk Python. Dalam tutorial ini, Agent Platform SDK untuk Python digunakan.

!pip install --upgrade --user google-cloud-aiplatform>=1.29.0 google-cloud-storage

Untuk menggunakan paket yang baru diinstal di runtime Jupyter ini, Anda harus memulai ulang runtime, seperti yang ditunjukkan dalam cuplikan kode berikut.

# Restart kernel after installs so that your environment can access the new packages
import IPython

app = IPython.Application.instance()
app.kernel.do_shutdown(True)

Variabel lingkungan

Tetapkan variabel lingkungan. Jika diminta, ganti your-project-id dengan project ID Anda dan jalankan sel.

# get project ID
PROJECT_ID = ! gcloud config get-value project
PROJECT_ID = PROJECT_ID[0]
LOCATION = "us-central1"
if PROJECT_ID == "(unset)":
    print(f"Please set the project ID manually below")

# define project information
if PROJECT_ID == "(unset)":
  PROJECT_ID = "[your-project-id]"

# generate a unique id for this session
from datetime import datetime
UID = datetime.now().strftime("%m%d%H%M")

Autentikasi (khusus Colab)

Jika menjalankan notebook ini di Colab, Anda harus menjalankan autentikasi sel berikut. Langkah ini tidak diperlukan jika Anda menggunakan Workbench Platform Agen Gemini Enterprise karena telah diautentikasi sebelumnya.

import sys

# if it's Colab runtime, authenticate the user with Google Cloud
if 'google.colab' in sys.modules:
    from google.colab import auth
    auth.authenticate_user()

Menetapkan izin IAM

Anda harus menambahkan izin akses ke akun layanan default untuk menggunakan layanan.

  1. Buka halaman IAM di Google Cloud konsol.
  2. Cari principal untuk akun layanan komputasi default. Tampilannya akan seperti: compute@developer.gserviceaccount.com
  3. Klik tombol edit dan berikan akun layanan komputasi default dengan peran berikut: Pengguna Platform Agen Gemini Enterprise dan Admin Penyimpanan serta Admin Penggunaan Layanan.

Mengaktifkan API

Jalankan perintah berikut untuk mengaktifkan API untuk Compute Engine, Platform Agen Gemini Enterprise, dan Cloud Storage dengan Google Cloud project ini.

! gcloud services enable compute.googleapis.com aiplatform.googleapis.com storage.googleapis.com --project {PROJECT_ID}

Menyiapkan data contoh

Dalam tutorial ini, kita menggunakan set data TheLook yang memiliki tabel produk dengan sekitar 5.000 baris data produk sintetis untuk situs pakaian ecommerce fiktif.

Set data sampel

Dari tabel ini, kami telah menyiapkan file product-embs.json.

Contoh penyematan produk

File ini dalam format JSONL dan setiap baris memiliki ID untuk ID produk, nama untuk nama produk, dan embedding untuk embedding nama produk dalam 768 dimensi yang sebelumnya dibuat dengan embedding Platform Agen Gemini Enterprise untuk teks.

Embedding teks mewakili arti nama produk pakaian. Dalam tutorial ini, kita menggunakan Vector Search untuk menyelesaikan penelusuran semantik item. Kode contoh ini dapat digunakan sebagai dasar untuk sistem rekomendasi cepat lainnya yang memungkinkan Anda menemukan "produk lain yang serupa dengan produk ini" dengan cepat.

Untuk mempelajari lebih lanjut cara membuat embedding dari data di tabel BigQuery dan menyimpannya dalam file JSON, lihat Memulai Embedding Teks + Vector Search Platform Agen Gemini Enterprise.

Menyiapkan data di Cloud Storage

Untuk membuat indeks dengan Platform Agen Gemini Enterprise, tempatkan file embedding di bucket Cloud Storage. Kode berikut menyelesaikan dua tugas:

  1. Membuat bucket Cloud Storage.
  2. Menyalin file contoh ke bucket Cloud Storage Anda.
BUCKET_URI = f"gs://{PROJECT_ID}-vs-quickstart-{UID}"

! gcloud storage buckets create $BUCKET_URI --location=$LOCATION --project=$PROJECT_ID
! gcloud storage cp "gs://github-repo/data/vs-quickstart/product-embs.json" $BUCKET_URI

Untuk menggunakan Vector Search guna menjalankan kueri, Anda juga perlu menyalin file embedding ke direktori lokal:

! gcloud storage cp "gs://github-repo/data/vs-quickstart/product-embs.json" . # for query tests

Membuat dan men-deploy indeks Vector Search

Pelajari cara membuat indeks, membuat endpoint indeks, lalu men-deploy indeks ke endpoint.

Membuat indeks

Sekarang saatnya memuat embedding ke Vector Search. API tersedia dalam paket aiplatform SDK.

# init the aiplatform package
from google.cloud import aiplatform
aiplatform.init(project=PROJECT_ID, location=LOCATION)

Buat MatchingEngineIndex dengan fungsi create_tree_ah_index (Matching Engine adalah nama sebelumnya dari Vector Search).

# create Index
my_index = aiplatform.MatchingEngineIndex.create_tree_ah_index(
    display_name = f"vs-quickstart-index-{UID}",
    contents_delta_uri = BUCKET_URI,
    dimensions = 768,
    approximate_neighbors_count = 100,
)

Metode MatchingEngineIndex.create_tree_ah_index() membuat indeks. Proses ini memerlukan waktu kurang dari 10 menit jika set datanya kecil, atau sekitar 60 menit atau lebih, bergantung pada ukuran set data. Anda dapat memeriksa status pembuatan indeks di konsol Vector Search Google Cloud

Lihat Indeks

Parameter untuk membuat indeks:

  • contents_delta_uri: URI direktori Cloud Storage tempat Anda menyimpan file JSON embedding
  • dimensions: ukuran dimensi setiap embedding. Dalam hal ini, ukurannya adalah 768 karena Anda menggunakan embedding dari text embeddings API.
  • approximate_neighbors_count: jumlah item serupa yang ingin Anda ambil dalam kasus umum

Untuk mempelajari lebih lanjut cara membuat indeks dan parameter yang tersedia, lihat Membuat dan mengelola indeks Anda

Membuat endpoint indeks dan men-deploy indeks

Untuk menggunakan indeks, Anda harus membuat endpoint indeks. Endpoint ini berfungsi sebagai instance server yang menerima permintaan kueri untuk indeks Anda.

## create `IndexEndpoint`
my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint.create(
    display_name = f"vs-quickstart-index-endpoint-{UID}",
    public_endpoint_enabled = True
)

Dengan endpoint indeks, deploy indeks dengan menentukan ID indeks yang di-deploy unik.

DEPLOYED_INDEX_ID = f"vs_quickstart_deployed_{UID}"

# deploy the Index to the Index Endpoint
my_index_endpoint.deploy_index(
    index = my_index, deployed_index_id = DEPLOYED_INDEX_ID
)

Jika ini adalah pertama kalinya Anda men-deploy indeks ini ke endpoint indeks, proses pembuatan dan inisiasi backend secara otomatis dapat memerlukan waktu sekitar 30 menit. Untuk melihat status deployment indeks, di bagian Platform Agen pada Google Cloud konsol, buka bagian Deploy dan Gunakan. Pilih Indeks.

Lihat Indeks

Menjalankan kueri dengan Vector Search

Dalam kode berikut, kode ini menemukan embedding untuk nama produk tertentu, dan menemukan nama produk serupa dengan Vector Search.

Mendapatkan embedding untuk menjalankan kueri

Pertama, muat file JSON embedding untuk membuat dict nama dan embedding produk.

import json

# build dicts for product names and embs
product_names = {}
product_embs = {}
with open('product-embs.json') as f:
    for l in f.readlines():
        p = json.loads(l)
        id = p['id']
        product_names[id] = p['name']
        product_embs[id] = p['embedding']

Dengan kamus product_embs, Anda dapat menentukan ID produk untuk mendapatkan embedding.

 # Get the embedding for ID 6523 "cloudveil women's excursion short"
 # You can also try with other IDs such as 12711, 18090, 19536 and 11863
query_emb = product_embs['6523']

Menjalankan kueri

Teruskan embedding ke metode Endpoint.find_neighbors() untuk menemukan nama produk serupa.

# run query
response = my_index_endpoint.find_neighbors(
    deployed_index_id = DEPLOYED_INDEX_ID,
    queries = [query_emb],
    num_neighbors = 10
)

# show the results
for idx, neighbor in enumerate(response[0]):
    print(f"{neighbor.distance:.2f} {product_names[neighbor.id]}")

Metode find_neighbors() hanya memerlukan waktu milidetik untuk mengambil item serupa bahkan jika Anda memiliki miliaran item di indeks, berkat algoritma ScaNN. Vector Search juga mendukung penskalaan otomatis yang dapat secara otomatis mengubah ukuran jumlah node berdasarkan permintaan workload Anda.

Pembersihan

Jika Anda menggunakan project Cloud Anda sendiri, bukan project sementara di Qwiklabs, pastikan untuk menghapus semua indeks, endpoint indeks, dan bucket Cloud Storage setelah menyelesaikan tutorial ini. Jika tidak, Anda mungkin akan dikenai biaya yang tidak terduga dari resource yang tersisa.

Jika menggunakan Workbench, Anda mungkin juga perlu menghapus notebook dari konsol.


# wait for a confirmation
input("Press Enter to delete Index Endpoint, Index and Cloud Storage bucket:")

# delete Index Endpoint
my_index_endpoint.undeploy_all()
my_index_endpoint.delete(force = True)

# delete Index
my_index.delete()

# delete Cloud Storage bucket
! gcloud storage rm {BUCKET_URI} --recursive

Utilitas

Pembuatan atau deployment indeks dapat memerlukan waktu beberapa saat, dan selama waktu tersebut, Anda mungkin kehilangan koneksi dengan runtime Colab. Jika kehilangan koneksi, Anda dapat memeriksa konsol Vector Search Google Cloud dan menggunakan indeks yang ada untuk melanjutkan, bukan membuat atau men-deploy indeks baru lagi.

Mendapatkan indeks yang ada

Untuk mendapatkan objek indeks yang sudah ada, ganti your-index-id berikut dengan ID indeks dan jalankan sel. Anda bisa mendapatkan ID indeks dengan memeriksa konsol Vector Search Google Cloud . Di bagian Platform Agen pada Google Cloud konsol, buka bagian Deploy dan Gunakan. Pilih Indeks.

Lihat Indeks

my_index_id = "[your-index-id]"
my_index = aiplatform.MatchingEngineIndex(my_index_id)

Mendapatkan endpoint indeks yang ada

Untuk mendapatkan objek endpoint indeks yang sudah ada, ganti your-index-endpoint-id berikut dengan ID endpoint indeks dan jalankan sel. Anda bisa mendapatkan endpoint indeks dengan memeriksa konsol Vector Search Google Cloud . Di bagian Platform Agen pada Google Cloud konsol, buka bagian Deploy dan Gunakan. Pilih Endpoint Indeks.

Lihat Endpoint Indeks

my_index_endpoint_id = "[your-index-endpoint-id]"
my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(my_index_endpoint_id)