Menghasilkan embedding teks dengan menggunakan fungsi ML.GENERATE_ analisis .

Dokumen ini menunjukkan cara membuat model jarak jauh BigQuery ML yang mereferensikan model dasar penyematan Vertex AI. Anda kemudian menggunakan model tersebut dengan fungsi ML.GENERATE_EMBEDDING untuk membuat embedding teks menggunakan data dari tabel standar BigQuery.

Peran yang diperlukan

  • Untuk membuat koneksi, Anda memerlukan keanggotaan dalam peran Identity and Access Management (IAM) berikut:

    • roles/bigquery.connectionAdmin

  • Untuk memberikan izin ke akun layanan koneksi, Anda memerlukan izin berikut:

    • resourcemanager.projects.setIamPolicy

  • Untuk membuat model menggunakan BigQuery ML, Anda memerlukan izin IAM berikut:

    • bigquery.jobs.create
    • bigquery.models.create
    • bigquery.models.getData
    • bigquery.models.updateData
    • bigquery.models.updateMetadata

  • Untuk menjalankan inferensi, Anda memerlukan izin berikut:

    • bigquery.tables.getData pada tabel
    • bigquery.models.getData pada model
    • bigquery.jobs.create

Sebelum memulai

  1. Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

    Buka pemilih project

  2. Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

  3. Aktifkan API BigQuery, BigQuery Connection, and Vertex AI.

    Mengaktifkan API

Membuat set data

Buat set data BigQuery untuk menyimpan model ML Anda:

  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.

    Buat set data.

  4. Di halaman Create dataset, lakukan hal berikut:

    • Untuk Dataset ID, masukkan bqml_tutorial.

    • Untuk Location type, pilih Multi-region, lalu pilih US (multiple regions in United States).

      Set data publik disimpan di US multi-region. Untuk mempermudah, simpan set data Anda di lokasi yang sama.

    • Jangan ubah setelan default yang tersisa, lalu klik Create dataset.

      Halaman Create dataset.

Membuat koneksi

Buat koneksi resource Cloud dan dapatkan akun layanan koneksi. Buat koneksi di lokasi yang sama seperti set data yang Anda buat di langkah sebelumnya.

Pilih salah satu opsi berikut:

Konsol

  1. Buka halaman BigQuery.

    Buka BigQuery

  2. Untuk membuat koneksi, klik Add, lalu klik Connections to external data sources.

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

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

  5. Klik Create connection.

  6. Klik Go to connection.

  7. 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: project ID Google Cloud 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 di 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.iam.gserviceaccount.com"}

Terraform

Tambahkan bagian berikut ke dalam file main.tf Anda. 

 ## This creates a cloud resource connection.
 ## Note: The cloud resource nested object has only one output only field - serviceAccountId.
 resource "google_bigquery_connection" "connection" {
    connection_id = "CONNECTION_ID"
    project = "PROJECT_ID"
    location = "REGION"
    cloud_resource {}
}
Ganti kode berikut:

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

Memberikan akses pada akun layanan

Berikan izin pada akun layanan Anda untuk menggunakan koneksi ini. Kegagalan memberikan izin akan menyebabkan error. Pilih salah satu opsi 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 Save.

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

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 `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 dari ID koneksi yang sepenuhnya memenuhi syarat yang ditampilkan dalam Connection ID, misalnya projects/myproject/locations/connection_location/connections/myconnection

    • ENDPOINT: embedding LLM yang akan digunakan. Misalnya, ENDPOINT='multimodalembedding'.

      Untuk beberapa jenis model, Anda dapat menentukan versi model tertentu dengan menambahkan @version ke nama model. Misalnya, textembedding-gecko@001. Untuk mengetahui informasi tentang versi model yang didukung untuk berbagai jenis model, lihat ENDPOINT.

Membuat embedding teks menggunakan data dari tabel

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

Biasanya, Anda ingin menggunakan model textembedding-gecko atau textembedding-gecko-multilingual untuk kasus penggunaan khusus teks, dan menggunakan model multimodalembedding untuk kasus penggunaan penelusuran lintas-modal, dengan sematan untuk konten teks dan visual dihasilkan dalam ruang semantik yang sama.

textembedding-gecko*

Buat embedding teks menggunakan model jarak jauh melalui LLM textembedding-gecko atau textembedding-gecko-multilingual:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type)
);

Ganti kode berikut:

  • PROJECT_ID: project ID Anda.
  • DATASET_ID: ID set data yang berisi model.
  • MODEL_NAME: nama model jarak jauh pada model textembedding-gecko atau textembedding-gecko-multilingual.
  • 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.
  • FLATTEN_JSON: nilai BOOL yang menunjukkan apakah akan mengurai penyematan ke dalam kolom terpisah. Nilai defaultnya adalah TRUE.
  • TASK_TYPE: literal STRING yang menentukan aplikasi downstream yang dimaksudkan untuk membantu model menghasilkan embedding berkualitas yang lebih baik. TASK_TYPE menerima nilai berikut:
    • RETRIEVAL_QUERY: menentukan bahwa teks tertentu adalah kueri dalam setelan penelusuran atau pengambilan.
    • RETRIEVAL_DOCUMENT: menentukan bahwa teks tertentu adalah dokumen dalam setelan penelusuran atau pengambilan.

      Saat menggunakan jenis tugas ini, sebaiknya sertakan judul dokumen dalam pernyataan kueri untuk meningkatkan kualitas penyematan. Anda dapat menggunakan opsi title untuk menentukan nama kolom yang berisi judul dokumen. Jika tidak, judul dokumen harus berada dalam kolom 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)
      );
    • SEMANTIC_SIMILARITY: menentukan bahwa teks tertentu akan digunakan untuk Semantic Textual Similarity (STS).
    • CLASSIFICATION: menentukan bahwa embedding akan digunakan untuk klasifikasi.
    • CLUSTERING: menentukan bahwa embedding akan digunakan untuk pengelompokan.

multimodalembedding

Buat embedding teks dengan menggunakan model jarak jauh melalui LLM multimodalembedding:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  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 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.
  • FLATTEN_JSON: BOOL yang menunjukkan apakah akan mengurai penyematan ke kolom terpisah atau tidak. Nilai defaultnya adalah TRUE.

Membuat embedding teks dengan menggunakan data dari kueri

Buat embedding teks dengan fungsi ML.GENERATE_EMBEDDING menggunakan data teks yang disediakan oleh kueri dan model jarak jauh melalui LLM textembedding-gecko atau textembedding-gecko-multilingual:

Biasanya, Anda ingin menggunakan model textembedding-gecko atau textembedding-gecko-multilingual untuk kasus penggunaan khusus teks, dan menggunakan model multimodalembedding untuk kasus penggunaan penelusuran lintas-modal, dengan sematan untuk konten teks dan visual dihasilkan dalam ruang semantik yang sama.

textembedding-gecko*

Buat embedding teks menggunakan model jarak jauh melalui LLM textembedding-gecko atau textembedding-gecko-multilingual:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (CONTENT_QUERY),
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type
  );

Ganti kode berikut:

  • PROJECT_ID: project ID Anda.
  • DATASET_ID: ID set data yang berisi model.
  • MODEL_NAME: nama model jarak jauh pada model textembedding-gecko atau textembedding-gecko-multilingual.
  • CONTENT_QUERY: kueri yang hasilnya berisi kolom STRING yang disebut content.
  • FLATTEN_JSON: nilai BOOL yang menunjukkan apakah akan mengurai penyematan ke dalam kolom terpisah atau tidak. Nilai defaultnya adalah TRUE.
  • TASK_TYPE: literal STRING yang menentukan aplikasi downstream yang dimaksudkan untuk membantu model menghasilkan embedding berkualitas yang lebih baik. TASK_TYPE menerima nilai berikut:
    • RETRIEVAL_QUERY: menentukan bahwa teks tertentu adalah kueri dalam setelan penelusuran atau pengambilan.
    • RETRIEVAL_DOCUMENT: menentukan bahwa teks tertentu adalah dokumen dalam setelan penelusuran atau pengambilan.

      Saat menggunakan jenis tugas ini, sebaiknya sertakan judul dokumen dalam pernyataan kueri untuk meningkatkan kualitas penyematan. Anda dapat menggunakan opsi title untuk menentukan nama kolom yang berisi judul dokumen. Jika tidak, judul dokumen harus berada dalam kolom 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)
          );
    • SEMANTIC_SIMILARITY: menentukan bahwa teks tertentu akan digunakan untuk Semantic Textual Similarity (STS).
    • CLASSIFICATION: menentukan bahwa embedding akan digunakan untuk klasifikasi.
    • CLUSTERING: menentukan bahwa embedding akan digunakan untuk pengelompokan.

multimodalembedding

Buat embedding teks dengan menggunakan model jarak jauh melalui LLM multimodalembedding:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_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 multimodalembedding@001.
  • 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.

Contoh

Contoh berikut menunjukkan cara memanggil fungsi ML.GENERATE_EMBEDDING pada tabel dan kueri.

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)
  );

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 ML.DISTANCE. Jarak yang lebih kecil menunjukkan adanya lebih banyak kesamaan semantik.

WITH movie_review_embeddings AS (
  SELECT *
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "Movie 1" AS title, "This movie was fantastic" AS content
        UNION ALL
        SELECT "Movie 2" AS title, "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "Movie 3" AS title, "This movie was just okay..." AS content
        UNION ALL
        SELECT "Movie 4" AS title, "This movie was terrible." AS content
      ),
      STRUCT(TRUE AS flatten_json_output)
    )
),
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
  content,
  ML.DISTANCE(
    (SELECT ml_generate_embedding_result FROM average_review_embedding),
    ml_generate_embedding_result,
    'COSINE'
  ) AS distance_to_average_review
FROM
  movie_review_embeddings
ORDER BY distance_to_average_review;

Hasilnya adalah sebagai berikut:

+------------------------------------------+----------------------------+
| content                                  | distance_to_average_review |
+------------------------------------------+----------------------------+
| This movie was fantastic                 | 0.10028859431058901        |
| This movie was terrible.                 |   0.142427236973374        |
| This was the best movie I've ever seen!! | 0.46742391210381995        |
| This movie was just okay...              | 0.47399255715360622        |
+------------------------------------------+----------------------------+