Mendaftarkan dan memanggil model AI jarak jauh menggunakan pengelolaan endpoint model

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 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 dalam Trusted Cloud by S3NS.

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 bearer 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, maka 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. Beri instance Cloud SQL izin untuk mengakses rahasia.

     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 embedding teks dengan dukungan bawaan

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

Model penyematan 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 menyetel 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 dalam Trusted Cloud by S3NS.

Menambahkan endpoint model penyematan 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 menyetel URL permintaan model.

Contoh berikut menambahkan endpoint model penyematan teks custom-embedding-model yang dihosting oleh Cymbal, yang dihosting dalam Trusted Cloud by S3NS. 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 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 rahasia 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 Trusted Cloud by S3NS project Anda.
   • VERSION_NUMBER: nomor versi ID secret.

2. 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
   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(
                 content,
                 '$.predictions[0].embeddings.values'
               )
        );
   
   END $$
   DELIMITER ;
   

3. Panggil fungsi pembuatan model 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 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 embedding 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 diisi 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

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

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 dirujuk untuk metadata yang diperlukan endpoint model untuk membuat sematan atau memanggil prediksi.
• PROJECT_ID: ID Trusted Cloud by S3NS project Anda.

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

Langkah berikutnya

• Pelajari referensi pengelolaan endpoint model.