Membuat embedding teks menggunakan fungsi ML.GENERATE_EMBEDDING

Dokumen ini menunjukkan cara membuat model jarak jauh BigQuery ML yang merujuk pada model penyematan. Kemudian, Anda menggunakan model tersebut dengan fungsi ML.GENERATE_EMBEDDING untuk membuat penyematan teks dengan menggunakan data dari tabel standar BigQuery.

Jenis model jarak jauh berikut didukung:

• Model jarak jauh dibandingkan model sematan Vertex AI.
• Model jarak jauh melalui model terbuka yang didukung (Pratinjau).

Peran yang diperlukan

Untuk membuat model jarak jauh dan menggunakan fungsi ML.GENERATE_EMBEDDING, Anda memerlukan peran Identity and Access Management (IAM) berikut:

• Buat dan gunakan set data, tabel, dan model BigQuery: Editor Data BigQuery (roles/bigquery.dataEditor) di project Anda.

• Membuat, mendelegasikan, dan menggunakan koneksi BigQuery: BigQuery Connections Admin (roles/bigquery.connectionsAdmin) di project Anda.

  Jika Anda belum mengonfigurasi koneksi default, Anda dapat membuat dan menyetelnya sebagai bagian dari menjalankan pernyataan CREATE MODEL. Untuk melakukannya, Anda harus memiliki peran Admin BigQuery (roles/bigquery.admin) di project Anda. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi koneksi default.

• Memberikan izin ke akun layanan koneksi: Admin IAM Project (roles/resourcemanager.projectIamAdmin) di project yang berisi endpoint Vertex AI. Ini adalah project saat ini untuk model jarak jauh yang Anda buat dengan menentukan nama model sebagai endpoint. Ini adalah project yang diidentifikasi dalam URL untuk model jarak jauh yang Anda buat dengan menentukan URL sebagai endpoint.

• Membuat tugas BigQuery: Pengguna Tugas BigQuery (roles/bigquery.jobUser) di project Anda.

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk melakukan tugas dalam dokumen ini. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

• Buat set data: bigquery.datasets.create
• Membuat, mendelegasikan, dan menggunakan koneksi: bigquery.connections.*
• Tetapkan izin akun layanan: resourcemanager.projects.getIamPolicy dan resourcemanager.projects.setIamPolicy
• Buat model dan jalankan inferensi:
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata
• Membuat kueri data tabel: bigquery.tables.getData

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Sebelum memulai

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Enable the APIs

Membuat set data

Buat set data BigQuery untuk memuat resource Anda:

Konsol

1. Di konsol Google Cloud , buka halaman BigQuery.

   Buka halaman BigQuery

2. Di panel Explorer, klik nama project Anda.

3. Klik View actions > Create dataset.

4. Di halaman Create dataset, lakukan hal berikut:

   • Untuk ID Set Data, ketik nama untuk set data.

   • Untuk Location type, pilih lokasi untuk set data.

   • Klik Create dataset.

bq

1. Untuk membuat set data baru, gunakan perintah bq mk dengan flag --location:

   bq --location=LOCATION mk -d DATASET_ID

   Ganti kode berikut:

   • LOCATION: lokasi set data.
   • DATASET_ID: ID set data yang Anda buat.

2. Pastikan set data telah dibuat:

   bq ls

Membuat koneksi

Anda dapat melewati langkah ini jika telah mengonfigurasi koneksi default, atau memiliki peran Admin BigQuery.

Buat koneksi resource Cloud untuk digunakan model jarak jauh, lalu dapatkan akun layanan koneksi. Buat koneksi di lokasi yang sama dengan set data yang Anda buat di langkah sebelumnya.

Pilih salah satu opsi berikut:

Konsol

1. Buka halaman BigQuery.

   Buka BigQuery

2. Di panel Penjelajah, klik Tambahkan data:

   

   Dialog Tambahkan data akan terbuka.

3. Di panel Filter Menurut, di bagian Jenis Sumber Data, pilih Aplikasi Bisnis.

   Atau, di kolom Telusuri sumber data, Anda dapat memasukkan Vertex AI.

4. Di bagian Sumber data unggulan, klik Vertex AI.

5. Klik kartu solusi Vertex AI Models: BigQuery Federation.

6. Dalam daftar Connection type, pilih Vertex AI remote models, remote functions and BigLake (Cloud Resource).

7. Di kolom Connection ID, masukkan nama untuk koneksi Anda.

8. Klik Create connection.

9. Klik Go to connection.

10. Di panel Connection info, salin ID akun layanan untuk digunakan di langkah berikutnya.

bq

1. Di lingkungan command line, buat koneksi:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   Parameter --project_id akan mengganti project default.

   Ganti kode berikut:

   • REGION: region koneksi Anda
   • PROJECT_ID: Google Cloud project ID Anda
   • CONNECTION_ID: ID untuk koneksi Anda

   Saat Anda membuat resource koneksi, BigQuery akan membuat akun layanan sistem unik dan mengaitkannya dengan koneksi.

   Pemecahan masalah: Jika Anda mendapatkan error koneksi berikut, update Google Cloud SDK:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Ambil dan salin ID akun layanan untuk digunakan pada langkah berikutnya:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   Outputnya mirip dengan hal berikut ini:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel."}
   

Terraform

Gunakan resource google_bigquery_connection.

Catatan: Untuk membuat objek BigQuery menggunakan Terraform, Anda harus mengaktifkan Cloud Resource Manager API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut membuat koneksi resource Cloud bernama my_cloud_resource_connection di region US:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Untuk menerapkan konfigurasi Terraform di project Google Cloud , selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

1. Luncurkan Cloud Shell.

2. Tetapkan project default Google Cloud tempat Anda ingin menerapkan konfigurasi Terraform.

   Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root).

1. Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus memiliki ekstensi .tf—misalnya main.tf. Dalam tutorial ini, file ini disebut sebagai main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Jika mengikuti tutorial, Anda dapat menyalin kode contoh di setiap bagian atau langkah.

   Salin kode contoh ke dalam main.tf yang baru dibuat.

   Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.

3. Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
4. Simpan perubahan Anda.
5. Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori.

   terraform init

   Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade:

   terraform init -upgrade

Menerapkan perubahan

1. Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan:

   terraform plan

   Koreksi konfigurasi jika diperlukan.

2. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt:

   terraform apply

   Tunggu hingga Terraform menampilkan pesan "Apply complete!".

3. Buka Google Cloud project Anda untuk melihat hasilnya. Di konsol Google Cloud , buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

Catatan: Contoh Terraform biasanya mengasumsikan bahwa API yang diperlukan sudah diaktifkan di project Google Cloud Anda.

Memberikan akses pada akun layanan

Berikan peran Vertex AI User ke akun layanan koneksi.

Jika Anda berencana menentukan endpoint sebagai URL saat membuat model jarak jauh, misalnya endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-005', berikan peran ini di project yang sama dengan yang Anda tentukan di URL.

Jika Anda berencana menentukan endpoint menggunakan nama model saat membuat model jarak jauh, misalnya endpoint = 'text-embedding-005', berikan peran ini di project yang sama tempat Anda berencana membuat model jarak jauh.

Pemberian peran dalam project lain akan menyebabkan error bqcx-1234567890-wxyz@gcp-sa-bigquery-condel. does not have the permission to access resource.

Untuk memberikan peran, ikuti langkah-langkah berikut:

Konsol

1. Buka halaman IAM & Admin.

   Buka IAM & Admin

2. Klik Grant access.

   Dialog Add principals akan terbuka.

3. Di kolom Akun utama baru, masukkan ID akun layanan yang Anda salin sebelumnya.

4. Di kolom Pilih peran, pilih Vertex AI, lalu pilih Pengguna Vertex AI.

5. Klik Simpan.

gcloud

Gunakan perintah gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None

Ganti kode berikut:

• PROJECT_NUMBER: nomor project Anda
• MEMBER: ID akun layanan yang Anda salin sebelumnya

Men-deploy model terbuka

Jika ingin menggunakan model terbuka yang didukung, Anda harus men-deploy model tersebut ke Vertex AI terlebih dahulu. Untuk mengetahui informasi selengkapnya tentang cara melakukannya, lihat Men-deploy model terbuka.

Membuat model

1. Di konsol Google Cloud , buka halaman BigQuery.

   Buka BigQuery

2. Dengan menggunakan editor SQL, buat model jarak jauh:

   CREATE OR REPLACE MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`
   REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
   OPTIONS (ENDPOINT = 'ENDPOINT');

   Ganti kode berikut:

   • PROJECT_ID: project ID Anda
   • DATASET_ID: ID set data untuk menampung model
   • MODEL_NAME: nama model
   • REGION: region yang digunakan oleh koneksi.
   • CONNECTION_ID: ID koneksi BigQuery Anda

     Saat Anda melihat detail koneksi di konsol Google Cloud , ini adalah nilai di bagian terakhir ID koneksi yang sepenuhnya memenuhi syarat yang ditampilkan di ID Koneksi, misalnya projects/myproject/locations/connection_location/connections/myconnection

   • ENDPOINT: nama model embedding yang akan digunakan. Untuk mengetahui informasi selengkapnya tentang versi dan alias model Vertex AI, lihat ENDPOINT. Untuk mengetahui informasi selengkapnya tentang model terbuka, lihat model terbuka yang didukung.

     Model Vertex AI yang Anda tentukan harus tersedia di lokasi tempat Anda membuat model jarak jauh. Untuk mengetahui informasi selengkapnya, lihat Lokasi.

Membuat embedding teks

Buat embedding teks dengan fungsi ML.GENERATE_EMBEDDING menggunakan data teks dari kolom tabel atau kueri.

Biasanya, Anda akan menggunakan model embedding teks untuk kasus penggunaan khusus teks, dan model embedding multimodal untuk kasus penggunaan penelusuran lintas modalitas, dengan embedding untuk konten teks dan visual dibuat dalam ruang semantik yang sama.

Teks Vertex AI

Membuat embedding teks dengan menggunakan model jarak jauh melalui model embedding teks Vertex AI:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Ganti kode berikut:

• PROJECT_ID: project ID Anda.
• DATASET_ID: ID set data yang berisi model.
• MODEL_NAME: nama model jarak jauh di atas model penyematan.
• TABLE_NAME: nama tabel yang berisi teks yang akan disematkan. Tabel ini harus memiliki kolom yang bernama content, atau Anda dapat menggunakan alias untuk menggunakan kolom dengan nama yang berbeda.
• CONTENT_QUERY: kueri yang hasilnya berisi kolom STRING yang disebut content.
• FLATTEN_JSON: nilai BOOL yang menunjukkan apakah akan mengurai penyematan ke kolom terpisah atau tidak. Nilai default-nya adalah TRUE.
• TASK_TYPE: literal STRING yang menentukan aplikasi downstream yang dimaksudkan untuk membantu model menghasilkan embedding dengan kualitas yang lebih baik. TASK_TYPE menerima nilai berikut:
  • RETRIEVAL_QUERY: menentukan bahwa teks yang diberikan adalah kueri dalam setelan penelusuran atau pengambilan.
  • RETRIEVAL_DOCUMENT: menentukan bahwa teks yang diberikan adalah dokumen dalam setelan penelusuran atau pengambilan.

    Saat menggunakan jenis tugas ini, sebaiknya sertakan judul dokumen dalam pernyataan kueri untuk meningkatkan kualitas penyematan. Judul dokumen harus berada di kolom yang bernama title atau diberi alias sebagai title, misalnya:

          SELECT *
          FROM
            ML.GENERATE_EMBEDDING(
              MODEL mydataset.embedding_model,
              (SELECT abstract as content, header as title, publication_number
              FROM mydataset.publications),
              STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
          );
          

    Menentukan kolom judul dalam kueri input akan mengisi kolom title isi permintaan yang dikirim ke model. Jika Anda menentukan nilai title saat menggunakan jenis tugas lain, input tersebut akan diabaikan dan tidak berpengaruh pada hasil penyematan.

  • SEMANTIC_SIMILARITY: menentukan bahwa teks yang diberikan akan digunakan untuk Kemiripan Teks Semantik (STS).
  • CLASSIFICATION: menentukan bahwa embedding akan digunakan untuk klasifikasi.
  • CLUSTERING: menentukan bahwa embedding akan digunakan untuk pengelompokan.
  • QUESTION_ANSWERING: menentukan bahwa embedding akan digunakan untuk menjawab pertanyaan.
  • FACT_VERIFICATION: menentukan bahwa embedding akan digunakan untuk verifikasi fakta.
  • CODE_RETRIEVAL_QUERY: menentukan bahwa embedding akan digunakan untuk pengambilan kode.
• OUTPUT_DIMENSIONALITY: nilai INT64 yang menentukan jumlah dimensi yang akan digunakan saat membuat embedding. Misalnya, jika Anda menentukan 256 AS output_dimensionality, maka kolom output ml_generate_embedding_result berisi 256 sematan untuk setiap nilai input.

  Untuk model jarak jauh melalui model gemini-embedding-001, nilai OUTPUT_DIMENSIONALITY harus berada dalam rentang [1, 3072]. Nilai defaultnya adalah 3072. Untuk model jarak jauh di atas model text-embedding atau text-multilingual-embedding, nilai OUTPUT_DIMENSIONALITY harus berada dalam rentang [1, 768]. Nilai defaultnya adalah 768.

  Jika Anda menggunakan model jarak jauh melalui model text-embedding, versi model text-embedding harus text-embedding-004 atau yang lebih baru. Jika Anda menggunakan model jarak jauh melalui model text-multilingual-embedding, versi model text-multilingual-embedding harus text-multilingual-embedding-002 atau yang lebih baru.

Contoh: menyematkan teks dalam tabel

Contoh berikut menunjukkan permintaan untuk menyematkan kolom content dari tabel text_data:

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE mydataset.text_data,
    STRUCT(TRUE AS flatten_json_output, 'CLASSIFICATION' AS task_type)
  );

Teks bebas

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Catatan: Untuk memberikan masukan atau meminta dukungan terkait fitur ini, hubungi [e-mail].

Membuat embedding teks dengan menggunakan model jarak jauh melalui model embedding terbuka:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output)
);

Ganti kode berikut:

• PROJECT_ID: project ID Anda.
• DATASET_ID: ID set data yang berisi model.
• MODEL_NAME: nama model jarak jauh di atas model penyematan.
• TABLE_NAME: nama tabel yang berisi teks yang akan disematkan. Tabel ini harus memiliki kolom yang bernama content, atau Anda dapat menggunakan alias untuk menggunakan kolom dengan nama yang berbeda.
• CONTENT_QUERY: kueri yang hasilnya berisi kolom STRING yang disebut content.
• FLATTEN_JSON: nilai BOOL yang menunjukkan apakah akan mengurai penyematan ke kolom terpisah atau tidak. Nilai defaultnya adalah TRUE.

Multimodal Vertex AI

Membuat embedding teks dengan menggunakan model jarak jauh melalui model embedding multimodal Vertex AI:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output，
  OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Ganti kode berikut:

• PROJECT_ID: project ID Anda.
• DATASET_ID: ID set data yang berisi model.
• MODEL_NAME: nama model jarak jauh di atas model multimodalembedding@001.
• TABLE_NAME: nama tabel yang berisi teks yang akan disematkan. Tabel ini harus memiliki kolom yang bernama content, atau Anda dapat menggunakan alias untuk menggunakan kolom dengan nama yang berbeda.
• CONTENT_QUERY: kueri yang hasilnya berisi kolom STRING yang disebut content.
• FLATTEN_JSON: BOOL yang menunjukkan apakah akan mengurai penyematan ke kolom terpisah atau tidak. Nilai defaultnya adalah TRUE.
• OUTPUT_DIMENSIONALITY: nilai INT64 yang menentukan jumlah dimensi yang akan digunakan saat membuat embedding. Nilai yang valid adalah 128, 256, 512, dan 1408. Nilai defaultnya adalah 1408. Misalnya, jika Anda menentukan 256 AS output_dimensionality, maka ml_generate_embedding_result kolom output berisi 256 sematan untuk setiap nilai input.

Contoh: menggunakan embedding untuk mengurutkan kesamaan semantik

Contoh berikut menyematkan kumpulan ulasan film dan mengurutkannya berdasarkan jarak kosinus ke ulasan "This movie was average" menggunakan fungsi VECTOR_SEARCH. Jarak yang lebih kecil menunjukkan adanya lebih banyak kesamaan semantik.

Untuk mengetahui informasi selengkapnya tentang penelusuran vektor dan indeks vektor, lihat Pengantar penelusuran vektor.

CREATE TEMPORARY TABLE movie_review_embeddings AS (
  SELECT *
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "This movie was fantastic" AS content
        UNION ALL
        SELECT "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "This movie was just okay..." AS content
        UNION ALL
        SELECT "This movie was terrible." AS content
      ),
      STRUCT(TRUE AS flatten_json_output)
    )
);

WITH average_review_embedding AS (
  SELECT ml_generate_embedding_result
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (SELECT "This movie was average" AS content),
      STRUCT(TRUE AS flatten_json_output)
    )
)
SELECT
  base.content AS content,
  distance AS distance_to_average_review
FROM
  VECTOR_SEARCH(
    TABLE movie_review_embeddings,
    "ml_generate_embedding_result",
    (SELECT ml_generate_embedding_result FROM average_review_embedding),
    distance_type=>"COSINE",
    top_k=>-1
  )
ORDER BY distance_to_average_review;

Hasilnya adalah sebagai berikut:

+------------------------------------------+----------------------------+
| content                                  | distance_to_average_review |
+------------------------------------------+----------------------------+
| This movie was just okay...              | 0.062789813467745592       |
| This movie was fantastic                 |  0.18579561313064263       |
| This movie was terrible.                 |  0.35707466240930985       |
| This was the best movie I've ever seen!! |  0.41844932504542975       |
+------------------------------------------+----------------------------+

Langkah berikutnya

• Pelajari cara menggunakan embedding teks dan gambar untuk melakukan penelusuran semantik teks ke gambar.
• Pelajari cara menggunakan embedding teks untuk penelusuran semantik dan retrieval-augmented generation (RAG).