Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat penyematan teks menggunakan fungsi ML.GENERATE_EMBEDDING

Dokumen ini menunjukkan cara membuat model jarak jauh BigQuery ML yang merujuk pada model penyematan Vertex AI. Kemudian, Anda menggunakan model tersebut dengan fungsi ML.GENERATE_EMBEDDING untuk membuat penyematan 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

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
Make sure that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.
Enable the APIs

Membuat set data

Buat set data BigQuery untuk menyimpan model ML Anda:

Di konsol Google Cloud, buka halaman BigQuery.

Buka halaman BigQuery
Di panel Explorer, klik nama project Anda.
Klik View actions > Create dataset.
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.

Membuat koneksi

Buat koneksi resource Cloud dan 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

Buka halaman BigQuery.

Buka BigQuery
Untuk membuat koneksi, klik Tambahkan, lalu klik Koneksi ke sumber data eksternal.
Dalam daftar Connection type, pilih Vertex AI remote models, remote functions and BigLake (Cloud Resource).
Di kolom Connection ID, masukkan nama untuk koneksi Anda.
Klik Create connection.
Klik Go to connection.
Di panel Connection info, salin ID akun layanan untuk digunakan di langkah berikutnya.

bq

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...
```

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

Gunakan resource google_bigquery_connection.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk 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

Luncurkan Cloud Shell.
Tetapkan project Google Cloud default 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).

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
```
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.
Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
Simpan perubahan Anda.
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

Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan:
```
terraform plan
```
Koreksi konfigurasi jika diperlukan.
Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt:
```
terraform apply
```
Tunggu hingga Terraform menampilkan pesan "Apply complete!".
Buka project Google Cloud Anda untuk melihat hasilnya. Di Konsol Google Cloud, buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

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-004', 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-004', berikan peran ini di project yang sama dengan tempat Anda berencana membuat model jarak jauh.

Memberikan peran di project lain akan menyebabkan error bqcx-1234567890-xxxx@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

Untuk memberikan peran, ikuti langkah-langkah berikut:

Konsol

Buka halaman IAM & Admin.

Buka IAM & Admin
Klik Grant access.

Dialog Add principals akan terbuka.
Di kolom Akun utama baru, masukkan ID akun layanan yang Anda salin sebelumnya.
Di kolom Pilih peran, pilih Vertex AI, lalu pilih Pengguna Vertex AI.
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

Membuat model

Di konsol Google Cloud, buka halaman BigQuery.

Buka BigQuery
Dengan menggunakan editor SQL, buat model jarak jauh:
```
CREATE OR REPLACE MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION `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
- 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 penyematan yang akan digunakan. Model ini harus berupa text-embedding, text-multilingual-embedding, atau multimodalembedding. Untuk mengetahui informasi selengkapnya tentang versi dan alias model yang didukung, lihat ENDPOINT.
Penting: Dukungan BigQuery ML untuk model textembedding-gecko@002 akan dihentikan secara bertahap. Jika Anda memiliki model jarak jauh yang menggunakan model ini, bermigrasilah ke model text-embedding-004 atau versi model yang didukung lain sesegera mungkin.

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 text-embedding atau text-multilingual-embedding untuk kasus penggunaan khusus teks, dan menggunakan model multimodalembedding untuk kasus penggunaan penelusuran lintas modal, dengan penyematan untuk konten teks dan visual dihasilkan di ruang semantik yang sama.

text embedding

Buat embedding teks menggunakan model jarak jauh melalui model penyematan:

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,
    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 melalui 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.
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. Anda dapat menggunakan opsi title untuk menentukan nama kolom yang berisi judul dokumen. Jika tidak, judul dokumen harus berada di kolom yang bernama title atau memiliki alias 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 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.
OUTPUT_DIMENSIONALITY: nilai INT64 yang menentukan jumlah dimensi yang akan digunakan saat membuat embedding. Misalnya, jika Anda menentukan 256 AS output_dimensionality, kolom output ml_generate_embedding_result akan berisi 256 penyematan untuk setiap nilai input.
Anda hanya dapat menggunakan argumen ini jika model jarak jauh yang Anda tentukan dalam argumen model menggunakan salah satu model berikut sebagai endpoint:
- text-embedding-004 atau yang lebih baru
- text-multilingual-embedding-002 atau yang lebih baru

penyematan multimodal

Buat embedding teks menggunakan model jarak jauh melalui model 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，
  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.
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 penyematan. Nilai yang valid adalah 128, 256, 512, dan 1408. Nilai defaultnya adalah 1408. Misalnya, jika Anda menentukan 256 AS output_dimensionality, kolom output ml_generate_embedding_result akan berisi 256 penyematan untuk setiap nilai input.

Membuat embedding teks menggunakan data dari kueri

Buat penyematan teks dengan fungsi ML.GENERATE_EMBEDDING menggunakan data teks yang disediakan oleh kueri dan model jarak jauh melalui model penyematan.

Biasanya, Anda ingin menggunakan model text-embedding atau text-multilingual-embedding untuk kasus penggunaan khusus teks, dan menggunakan model multimodalembedding untuk kasus penggunaan penelusuran lintas-modal, dengan penyematan untuk konten teks dan visual dihasilkan di ruang semantik yang sama.

text embedding

Buat embedding teks menggunakan model jarak jauh melalui model penyematan:

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,
    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 melalui model penyematan.
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.
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. Anda dapat menggunakan opsi title untuk menentukan nama kolom yang berisi judul dokumen. Jika tidak, judul dokumen harus berada di kolom yang bernama title atau memiliki alias 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 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.
OUTPUT_DIMENSIONALITY: nilai INT64 yang menentukan jumlah dimensi yang akan digunakan saat membuat penyematan. Misalnya, jika Anda menentukan 256 AS output_dimensionality, kolom output ml_generate_embedding_result akan berisi 256 penyematan untuk setiap nilai input.
Anda hanya dapat menggunakan argumen ini jika model jarak jauh yang Anda tentukan dalam argumen model menggunakan salah satu model berikut sebagai endpoint:
- text-embedding-004 atau yang lebih baru
- text-multilingual-embedding-002 atau yang lebih baru

penyematan multimodal

Buat embedding teks menggunakan model jarak jauh melalui model multimodalembedding:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_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.
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 penyematan. Nilai yang valid adalah 128, 256, 512, dan 1408. Nilai defaultnya adalah 1408. Misalnya, jika Anda menentukan 256 AS output_dimensionality, kolom output ml_generate_embedding_result akan berisi 256 penyematan untuk setiap nilai input.

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, 'CLASSIFICATION' AS task_type)
  );

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 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       |
+------------------------------------------+----------------------------+