Halaman ini diterjemahkan oleh Cloud Translation API.

Mendaftarkan dan memanggil model AI jarak jauh menggunakan pengelolaan endpoint model

MySQL | PostgreSQL | SQL Server

Halaman ini menjelaskan cara memanggil prediksi atau membuat penyematan menggunakan model, lalu mendaftarkan endpoint model dengan pengelolaan endpoint model.

Untuk mengetahui informasi selengkapnya tentang fungsi google_ml.create_model(), lihat Referensi pengelolaan endpoint model.

Sebelum memulai

Jika endpoint model Anda memerlukan autentikasi, aktifkan ekstensi google_ml_integration.
Berdasarkan penyedia model, siapkan autentikasi.
Pastikan Anda menggunakan nama pengguna default postgres untuk mengakses database.

Mengaktifkan ekstensi

Tetapkan flag database google_ml_integration.enable_model_support ke on untuk instance Anda. Untuk mengetahui informasi selengkapnya tentang cara menyetel flag database, lihat Mengonfigurasi flag database.
Hubungkan ke instance utama menggunakan klien psql atau Cloud SQL Studio.
Jalankan perintah berikut untuk memastikan ekstensi google_ml_integration diupdate ke versi 1.4.2:
```
    ALTER EXTENSION google_ml_integration UPDATE TO '1.4.2'
```
Tambahkan ekstensi google_ml_integration versi 1.4.2 menggunakan psql:
```
  CREATE EXTENSION google_ml_integration VERSION '1.4.2';
```
Opsional: Berikan izin kepada pengguna PostgreSQL non-super untuk mengelola metadata model:
```
  GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;
```
Ganti NON_SUPER_USER dengan nama pengguna PostgreSQL non-super.

Menyiapkan autentikasi

Bagian berikut menunjukkan cara menyiapkan autentikasi sebelum menambahkan endpoint model Vertex AI atau endpoint model yang dihosting dalam Google Cloud.

Menyiapkan autentikasi untuk Vertex AI

Untuk menggunakan endpoint model Google Vertex AI, Anda harus menambahkan izin Vertex AI ke akun layanan Cloud SQL berbasis IAM yang Anda gunakan untuk terhubung ke database. Untuk informasi selengkapnya tentang cara mengintegrasikan dengan Vertex AI, lihat Mengintegrasikan Cloud SQL dengan Vertex AI.

Menyiapkan autentikasi untuk model yang dihosting kustom

Bagian ini menjelaskan cara menyiapkan autentikasi jika Anda menggunakan Pengelola Secret. Untuk semua model kecuali endpoint model Vertex AI, Anda dapat menyimpan kunci API atau token pembawa di Secret Manager.

Jika endpoint model Anda tidak menangani autentikasi melalui Secret Manager, bagian ini bersifat opsional. Misalnya, jika endpoint model Anda menggunakan header HTTP untuk meneruskan informasi autentikasi atau tidak menggunakan autentikasi sama sekali, jangan selesaikan langkah-langkah di bagian ini.

Untuk membuat dan menggunakan kunci API atau token pembawa, selesaikan langkah-langkah berikut:

Buat secret di Secret Manager. Untuk mengetahui informasi selengkapnya, lihat Membuat secret dan mengakses versi secret.

Nama secret dan jalur secret digunakan dalam fungsi SQL google_ml.create_sm_secret().
Berikan izin ke instance Cloud SQL untuk mengakses secret.
```
  gcloud secrets add-iam-policy-binding SECRET_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
      --role="roles/secretmanager.secretAccessor"
```
Ganti kode berikut:
- SECRET_ID: ID secret di Secret Manager.
- SERVICE_ACCOUNT_EMAIL: alamat email akun layanan Cloud SQL berbasis IAM. Untuk menemukan alamat email ini, gunakan perintah gcloud sql instances describe INSTANCE_NAME dan ganti INSTANCE_NAME dengan nama instance. Nilai yang muncul di samping parameter serviceAccountEmailAddress adalah alamat email.

Model penyematan teks dengan dukungan bawaan

Bagian ini menunjukkan cara mendaftarkan endpoint model untuk pengelolaan endpoint model.

Model penyematan Vertex AI

Pengelolaan endpoint model memberikan dukungan bawaan untuk semua versi model text-embedding-gecko oleh Vertex AI. Gunakan nama yang memenuhi syarat untuk menetapkan versi model ke textembedding-gecko@001 atau textembedding-gecko@002.

Karena ID endpoint model textembedding-gecko dan textembedding-gecko@001 telah didaftarkan sebelumnya dengan pengelolaan endpoint model, Anda dapat menggunakan salah satunya secara langsung sebagai ID model. Untuk model ini, ekstensi akan otomatis menyiapkan fungsi transformasi default.

Pastikan instance Cloud SQL dan model Vertex AI yang Anda buat kueri berada di region yang sama.

Untuk mendaftarkan endpoint model textembedding-gecko@002, panggil fungsi create_model:

  CALL
    google_ml.create_model(
      model_id => 'textembedding-gecko@002',
      model_provider => 'google',
      model_qualified_name => 'textembedding-gecko@002',
      model_type => 'text_embedding',
      model_auth_type => 'cloudsql_service_agent_iam');

Model penyematan teks yang dihosting secara kustom

Bagian ini menunjukkan cara mendaftarkan endpoint model kustom yang dihosting di jaringan dalam Google Cloud.

Menambahkan endpoint model penyematan teks yang dihosting secara kustom melibatkan pembuatan fungsi transformasi, dan secara opsional, header HTTP kustom. Di sisi lain, menambahkan endpoint model generik yang dihosting secara kustom secara opsional melibatkan pembuatan header HTTP kustom dan menetapkan URL permintaan model.

Contoh berikut menambahkan endpoint model penyematan teks custom-embedding-model yang dihosting oleh Cymbal, yang dihosting dalam Google Cloud. Fungsi transformasi cymbal_text_input_transform dan cymbal_text_output_transform digunakan untuk mengubah format input dan output model menjadi format input dan output fungsi prediksi.

Untuk mendaftarkan endpoint model penyematan teks yang dihosting secara kustom, selesaikan langkah-langkah berikut:

Panggil secret yang disimpan di Secret Manager:
```
CALL
  google_ml.create_sm_secret(
    secret_id => 'SECRET_ID',
    secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
```
Ganti kode berikut:
- SECRET_ID: ID secret yang Anda tetapkan dan kemudian digunakan saat mendaftarkan endpoint model—misalnya, key1.
- SECRET_MANAGER_SECRET_ID: ID secret yang ditetapkan di Secret Manager saat Anda membuat secret.
- PROJECT_ID: ID project Google Cloud Anda.
- VERSION_NUMBER: nomor versi ID secret.
Catatan: Secret Manager membuat header Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER untuk autentikasi secara default. Jika format ini cocok dengan format token pembawa otorisasi endpoint model, Anda tidak perlu membuat header autentikasi menggunakan fungsi pembuatan header.

Buat fungsi transformasi input dan output berdasarkan tanda tangan berikut untuk fungsi prediksi untuk endpoint model penyematan teks. Untuk mengetahui informasi selengkapnya tentang cara membuat fungsi transformasi, lihat Contoh fungsi transformasi.

Berikut adalah contoh fungsi transformasi yang khusus untuk endpoint model penyematan teks custom-embedding-model:

-- Input Transform Function corresponding to the custom model endpoint
CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;
-- Output Transform Function corresponding to the custom model endpoint
CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS REAL[]
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_output REAL[];
BEGIN
  SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
  RETURN transformed_output;
END;
$$;

Panggil fungsi create model untuk mendaftarkan endpoint model penyematan kustom:
```
CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'REQUEST_URL',
    model_provider => 'custom',
    model_type => 'text_embedding',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    model_qualified_name => 'MODEL_QUALIFIED_NAME',
    model_in_transform_fn => 'cymbal_text_input_transform',
    model_out_transform_fn => 'cymbal_text_output_transform');
```
Ganti kode berikut:
- MODEL_ID: wajib diisi. ID unik untuk endpoint model yang Anda tentukan (misalnya, custom-embedding-model). ID model ini dirujuk untuk metadata yang diperlukan endpoint model untuk membuat penyematan atau memanggil prediksi.
- REQUEST_URL: wajib diisi. Endpoint khusus model saat menambahkan penyematan teks kustom dan endpoint model generik—misalnya, https://cymbal.com/models/text/embeddings/v1. Pastikan endpoint model dapat diakses melalui alamat IP internal. Pengelolaan endpoint model tidak mendukung alamat IP eksternal.
- MODEL_QUALIFIED_NAME: wajib jika endpoint model Anda menggunakan nama yang memenuhi syarat. Nama yang sepenuhnya memenuhi syarat jika endpoint model memiliki beberapa versi.
- SECRET_ID: ID secret yang Anda gunakan sebelumnya dalam prosedur google_ml.create_sm_secret().

Model generik

Bagian ini menunjukkan cara mendaftarkan endpoint model gemini-pro umum dari Vertex AI Model Garden, yang tidak memiliki dukungan bawaan. Anda dapat mendaftarkan endpoint model umum apa pun yang dihosting dalam Google Cloud.

Cloud SQL hanya mendukung endpoint model yang tersedia melalui Model Garden Vertex AI dan endpoint model yang dihosting di jaringan dalam Google Cloud.

Model Gemini

Contoh berikut menambahkan endpoint model gemini-1.0-pro dari Vertex AI Model Garden.

Untuk mendaftarkan endpoint model gemini-1.0-pro, panggil fungsi create model:

```sql
CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-1.0-pro:streamGenerateContent',
    model_provider => 'google',
    model_auth_type => 'cloudsql_service_agent_iam');
```

Replace the following:
* <code><var>MODEL_ID</var></code>: a unique ID for the model endpoint that you define (for example,<br> `gemini-1`). This model ID is referenced for metadata that the model endpoint needs to generate embeddings or invoke predictions.
* <code><var>PROJECT_ID</var></code>: the ID of your Google Cloud project.

Untuk informasi selengkapnya, lihat cara memanggil prediksi untuk endpoint model generik.

Langkah selanjutnya

Pelajari referensi pengelolaan endpoint model.