Mendaftarkan dan memanggil model AI jarak jauh menggunakan pengelolaan endpoint model

MySQL   |  PostgreSQL   |  SQL Server

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

Untuk mengetahui informasi selengkapnya tentang fungsi mysql.ml_create_model_registration(), lihat Referensi pengelolaan endpoint model.

Sebelum memulai

• Berdasarkan penyedia model, siapkan autentikasi.

• Hubungkan ke instance utama Anda menggunakan klien mysql atau Cloud SQL Studio.

• Pastikan Anda terhubung ke database sebagai pengguna database MySQL dengan hak istimewa database yang dijelaskan dalam Hak istimewa pengguna database yang diperlukan.

Menyiapkan autentikasi

Bagian berikut menunjukkan cara menyiapkan autentikasi sebelum menambahkan endpoint model Vertex AI atau endpoint model yang dihosting di 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 mengetahui informasi selengkapnya tentang integrasi 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 Secret Manager. 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:

1. 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 mysql.ml_create_sm_secret_registration().

2. 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 gcloud sql instances describe INSTANCE_NAME perintah dan ganti INSTANCE_NAME dengan nama instance. Nilai yang muncul di samping parameter serviceAccountEmailAddress adalah alamat email.

Model embedding teks dengan dukungan bawaan

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

Model embedding Vertex AI

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

Karena ID endpoint model embedding Vertex AI didukung secara default dengan pengelolaan endpoint model, Anda dapat menggunakan salah satunya secara langsung sebagai ID model. Untuk model ini, fungsi embedding secara otomatis melakukan transformasi input dan output.

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

Untuk mendaftarkan endpoint model gemini-embedding-001, panggil fungsi ml_create_model_registration:

  CALL
    mysql.ml_create_model_registration(
      'gemini-embedding-001',
      'publishers/google/models/gemini-embedding-001',
      'google','text_embedding', 'gemini-embedding-001',
      'AUTH_TYPE_CLOUDSQL_SERVICE_AGENT_IAM',
       NULL,
      'mysql.cloudsql_ml_text_embedding_input_transform',
      'mysql.cloudsql_ml_text_embedding_output_transform', NULL);

Model embedding teks yang dihosting kustom

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

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

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

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

1. Panggil secret yang disimpan di Secret Manager:

   CALL
     mysql.ml_create_sm_secret_registration(
       'SECRET_ID',
       'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
   

   Ganti kode berikut:

   • SECRET_ID: ID secret yang Anda tetapkan dan selanjutnya 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, Anda tidak perlu membuat header autentikasi menggunakan fungsi pembuatan header.

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

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

   Catatan: Jika Anda mengurai vektor dari objek JSON dalam transformasi output di Cloud SQL untuk MySQL 9.7 atau yang lebih baru, pastikan Anda menggunakan JSON_UNQUOTE atau JSON_VALUE untuk mengekstrak nilai sebagai string. string_to_vector di MySQL 9.7 dan yang lebih baru tidak akan menerima input JSON.

   -- Input Transform Function corresponding to the custom model endpoint
   DELIMITER $$
   CREATE FUNCTION IF NOT EXISTS cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
   RETURNS JSON
   DETERMINISTIC
   
   BEGIN
     RETURN JSON_OBJECT('prompt', JSON_ARRAY(input_text));
   END $$
   
   -- Output Transform Function corresponding to the custom model endpoint
   CREATE FUNCTION IF NOT EXISTS cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
   RETURNS BLOB
   DETERMINISTIC
   
   BEGIN
     RETURN STRING_TO_VECTOR(
            JSON_EXTRACT(JSON_UNQUOTE(
                 content,
                 '$.predictions[0].embeddings.values'
               ))
        );
   
   END $$
   DELIMITER ;
   

3. Panggil fungsi model pembuatan untuk mendaftarkan endpoint model embedding kustom:

   CALL
      mysql.ml_create_model_registration(
        'MODEL_ID',
        'REQUEST_URL',
        'custom',
        'text_embedding',
        'MODEL_QUALIFIED_NAME',
        'auth_type_secret_manager',
        'SECRET_ID'
        'database_name.cymbal_text_input_transform',
        'database_name.cymbal_text_output_transform', NULL);

Ganti kode berikut:

• MODEL_ID: wajib. ID unik untuk endpoint model yang Anda tentukan (misalnya, custom-embedding-model). ID model ini direferensikan untuk metadata yang diperlukan endpoint model untuk membuat embedding atau memanggil prediksi.
• REQUEST_URL: wajib. Endpoint khusus model saat menambahkan endpoint model generik dan embedding teks kustom—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 mysql.ml_create_sm_secret_registration().

Model generik

Bagian ini menunjukkan cara mendaftarkan endpoint model gemini-flash generik dari Vertex AI Model Garden, yang telah terdaftar dalam katalog secara default. Anda dapat mendaftarkan endpoint model generik apa pun yang dihosting di dalam Google Cloud.

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

Model Gemini

Contoh berikut menggunakan endpoint model gemini-2.5-flash dari Vertex AI Model Garden.

Untuk mendaftarkan endpoint model gemini-2.5-flash, panggil fungsi mysql.ml_create_model_registration:

    CALL
      mysql.ml_create_model_registration(
        'MODEL_ID',
        'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.5-flash:streamGenerateContent',
        'google',
        'auth_type_cloudsql_service_agent_iam',
        NULL, NULL, NULL, NULL);

Ganti kode berikut:

• MODEL_ID: ID unik untuk endpoint model yang Anda tentukan (misalnya,
  gemini-1). ID model ini direferensikan untuk metadata yang diperlukan endpoint model untuk membuat embedding atau memanggil prediksi.
• PROJECT_ID: ID project Google Cloud Anda.

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

Langkah berikutnya

• Pelajari tentang referensi pengelolaan endpoint model.