Mendaftarkan dan memanggil model AI jarak jauh di AlloyDB Omni

Pratinjau — Model endpoint management

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dalam Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Untuk memanggil prediksi atau membuat penyematan menggunakan model, daftarkan endpoint model dengan pengelolaan endpoint model.

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

Sebelum mendaftarkan endpoint model dengan pengelolaan endpoint model, Anda harus mengaktifkan ekstensi google_ml_integration dan menyiapkan autentikasi berdasarkan penyedia model, jika endpoint model Anda memerlukan autentikasi.

Pastikan Anda mengakses database dengan nama pengguna default postgres.

Mengaktifkan ekstensi

Anda harus menambahkan dan mengaktifkan ekstensi google_ml_integration sebelum dapat mulai menggunakan fungsi terkait. Pengelolaan endpoint model memerlukan penginstalan ekstensi google_ml_integration.

1. Hubungkan ke database Anda menggunakan psql.

2. Opsional: Jika ekstensi google_ml_integration sudah diinstal, ubah untuk mengupdate ke versi terbaru:

       ALTER EXTENSION google_ml_integration UPDATE;
   

3. Tambahkan ekstensi google_ml_integration menggunakan psql:

     CREATE EXTENSION google_ml_integration;
   

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

5. Aktifkan pengelolaan endpoint model di database Anda:

     ALTER SYSTEM SET google_ml_integration.enable_model_support=on;
     SELECT pg_reload_conf();
   

Menyiapkan autentikasi

Bagian berikut menunjukkan cara menyiapkan autentikasi sebelum menambahkan endpoint model Vertex AI atau endpoint model oleh penyedia lain.

Menyiapkan autentikasi untuk Vertex AI

Untuk menggunakan endpoint model Google Vertex AI, Anda harus menambahkan izin Vertex AI ke akun layanan yang digunakan saat menginstal AlloyDB Omni. Untuk informasi selengkapnya, lihat Mengonfigurasi penginstalan AlloyDB Omni untuk membuat kueri model berbasis cloud.

Menyiapkan autentikasi untuk penyedia model lainnya

Untuk semua model kecuali model Vertex AI, Anda dapat menyimpan kunci API atau token pembawa di Secret Manager. Langkah ini bersifat opsional jika endpoint model Anda tidak menangani autentikasi melalui Secret Manager—misalnya, jika endpoint model Anda menggunakan header HTTP untuk meneruskan informasi autentikasi atau tidak menggunakan autentikasi sama sekali.

Bagian ini menjelaskan cara menyiapkan autentikasi jika Anda menggunakan Pengelola Secret.

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 google_ml.create_sm_secret().

2. Berikan izin ke cluster AlloyDB untuk mengakses secret.

     gcloud secrets add-iam-policy-binding 'SECRET_ID' \
         --member="serviceAccount:SERVICE_ACCOUNT_ID" \
         --role="roles/secretmanager.secretAccessor"
   

   Ganti kode berikut:

   • SECRET_ID: ID secret di Secret Manager.

   • SERVICE_ACCOUNT_ID: ID akun layanan yang Anda buat di langkah sebelumnya. Pastikan akun ini sama dengan yang Anda gunakan selama penginstalan AlloyDB Omni. Ini termasuk akhiran PROJECT_ID. lengkap. Contoh: my-service@my-project.

     Anda juga dapat memberikan peran ini ke akun layanan di tingkat project. Untuk informasi selengkapnya, lihat Menambahkan binding kebijakan Identity and Access Management

Model penyematan teks dengan dukungan bawaan

Bagian ini menunjukkan cara mendaftarkan endpoint model yang didukung secara bawaan oleh pengelolaan endpoint model.

Model penyematan Vertex AI

Pengelolaan endpoint model menyediakan 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 langsung menggunakannya sebagai ID model. Untuk model ini, ekstensi akan otomatis menyiapkan fungsi transformasi default.

Untuk mendaftarkan versi endpoint model textembedding-gecko@002, selesaikan langkah-langkah berikut:

Untuk AlloyDB Omni, pastikan Anda menyiapkan AlloyDB Omni untuk membuat kueri model Vertex AI berbasis cloud.

1. Buat dan aktifkan ekstensi google_ml_integration.

2. Hubungkan ke database Anda menggunakan psql.

3. Buat dan aktifkan ekstensi google_ml_integration.

4. Panggil fungsi create model untuk menambahkan endpoint model textembedding-gecko@002:

   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 => 'alloydb_service_agent_iam');
   
     The request URL that the function generates refers to the project associated with the AlloyDB Omni service account. If you want to refer to another project, then ensure that you specify the `model_request_url` explicitly.
   

Membuka model penyematan teks AI

Pengelolaan endpoint model memberikan dukungan bawaan untuk model text-embedding-ada-002 oleh OpenAI.Ekstensi google_ml_integration otomatis menyiapkan fungsi transformasi default dan memanggil panggilan ke model jarak jauh.

Contoh berikut menambahkan endpoint model OpenAI text-embedding-ada-002.

1. Hubungkan ke database Anda menggunakan psql.
2. Buat dan aktifkan ekstensi google_ml_integration.
3. Tambahkan kunci API OpenAI sebagai secret ke Secret Manager untuk autentikasi.

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

5. Panggil fungsi create model untuk mendaftarkan endpoint model text-embedding-ada-002:

     CALL
       google_ml.create_model(
         model_id => 'MODEL_ID',
         model_provider => 'open_ai',
         model_type => 'text_embedding',
         model_qualified_name => 'text-embedding-ada-002',
         model_auth_type => 'secret_manager',
         model_auth_id => 'SECRET_ID');
   

   Ganti kode berikut:

   • MODEL_ID: ID unik untuk endpoint model yang Anda tentukan. ID model ini dirujuk untuk metadata yang diperlukan endpoint model untuk membuat penyematan atau memanggil prediksi.
   • SECRET_ID: ID secret yang Anda gunakan sebelumnya dalam prosedur google_ml.create_sm_secret().

Untuk membuat embedding, lihat cara membuat embedding untuk endpoint model dengan dukungan bawaan.

Model embedding teks lainnya

Bagian ini menunjukkan cara mendaftarkan endpoint model penyematan teks yang dihosting kustom atau endpoint model penyematan teks yang disediakan oleh penyedia hosting model. Berdasarkan metadata endpoint model, Anda mungkin perlu menambahkan fungsi transformasi, membuat header HTTP, atau menentukan endpoint.

Model penyematan teks yang dihosting secara kustom

Bagian ini menunjukkan cara mendaftarkan endpoint model yang dihosting kustom beserta membuat fungsi transformasi, dan secara opsional, header HTTP kustom. AlloyDB Omni mendukung semua endpoint model yang dihosting secara kustom, terlepas dari tempatnya dihosting.

Contoh berikut menambahkan endpoint model kustom custom-embedding-model yang dihosting oleh Cymbal. 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:

1. Hubungkan ke database Anda menggunakan psql.

2. Buat dan aktifkan ekstensi google_ml_integration.

3. Opsional: Tambahkan kunci API sebagai secret ke Secret Manager untuk autentikasi.

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

5. 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;
   $$;
   

6. 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.
   • 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 OpenAI Text Embedding 3 Kecil dan Besar

Anda dapat mendaftarkan endpoint model text-embedding-3-small dan text-embedding-3-large OpenAI menggunakan fungsi prediksi penyematan dan fungsi transformasi khusus untuk endpoint model. Contoh berikut menunjukkan cara mendaftarkan endpoint model text-embedding-3-small OpenAI.

Untuk mendaftarkan endpoint model penyematan text-embedding-3-small, lakukan tindakan berikut:

1. Hubungkan ke database Anda menggunakan psql.
2. Buat dan aktifkan ekstensi google_ml_integration.
3. Tambahkan kunci API OpenAI sebagai secret ke Secret Manager untuk autentikasi. Jika sudah membuat secret untuk model OpenAI lainnya, Anda dapat menggunakan kembali secret yang sama.

4. 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.
   • 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.

5. Buat fungsi transformasi input dan output berdasarkan tanda tangan berikut untuk fungsi prediksi untuk model penyematan teks. Untuk informasi selengkapnya tentang cara membuat fungsi transformasi, lihat Contoh fungsi transformasi. Untuk mempelajari format input dan output yang diharapkan endpoint model OpenAI, lihat Embedding.

   Berikut adalah contoh fungsi transformasi untuk endpoint model penyematan teks OpenAI text-embedding-ada-002, text-embedding-3-small, dan text-embedding-3-large.

   -- Input Transform Function corresponding to openai_text_embedding model endpoint family
   CREATE OR REPLACE FUNCTION openai_text_input_transform(model_id VARCHAR(100), input_text TEXT)
   RETURNS JSON
   LANGUAGE plpgsql
   AS $$
   #variable_conflict use_variable
   DECLARE
     transformed_input JSON;
     model_qualified_name TEXT;
   BEGIN
     SELECT google_ml.model_qualified_name_of(model_id) INTO model_qualified_name;
     SELECT json_build_object('input', input_text, 'model', model_qualified_name)::JSON INTO transformed_input;
     RETURN transformed_input;
   END;
   $$;
   
   -- Output Transform Function corresponding to openai_text_embedding model endpoint family
   CREATE OR REPLACE FUNCTION openai_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->'data'->0->'embedding')) INTO transformed_output;
     RETURN transformed_output;
   END;
   $$;
   

6. Panggil fungsi create model untuk mendaftarkan endpoint model penyematan text-embedding-3-small:

   CALL
     google_ml.create_model(
       model_id => 'MODEL_ID',
       model_provider => 'open_ai',
       model_type => 'text_embedding',
       model_auth_type => 'secret_manager',
       model_auth_id => 'SECRET_ID',
       model_qualified_name => 'text-embedding-3-small',
       model_in_transform_fn => 'openai_text_input_transform',
       model_out_transform_fn => 'openai_text_output_transform');
   

   Ganti kode berikut:

   • MODEL_ID: ID unik untuk endpoint model yang Anda tentukan—misalnya openai-te-3-small. ID model ini dirujuk untuk metadata yang diperlukan endpoint model untuk membuat penyematan atau memanggil prediksi.
   • SECRET_ID: ID secret yang Anda gunakan sebelumnya dalam prosedur google_ml.create_sm_secret().

Untuk informasi selengkapnya, lihat cara membuat penyematan untuk endpoint model penyematan teks lainnya.

Model generik

Bagian ini menunjukkan cara mendaftarkan endpoint model generik yang tersedia di penyedia model yang dihosting seperti Hugging Face, OpenAI, Vertex AI, atau penyedia lainnya. Bagian ini menunjukkan contoh untuk mendaftarkan endpoint model generik yang dihosting di Hugging Face dan model gemini-pro generik dari Vertex AI Model Garden, yang tidak memiliki dukungan bawaan.

Anda dapat mendaftarkan endpoint model generik apa pun selama input dan output dalam format JSON. Berdasarkan metadata endpoint model, Anda mungkin perlu membuat header HTTP atau menentukan endpoint.

Model generik di Hugging Face

Contoh berikut menambahkan endpoint model klasifikasi kustom facebook/bart-large-mnli yang dihosting di Hugging Face.

1. Hubungkan ke database Anda menggunakan psql.
2. Buat dan aktifkan ekstensi google_ml_integration.
3. Tambahkan token pembawa sebagai secret ke Secret Manager untuk autentikasi.

4. Panggil secret yang disimpan di Secret Manager:

   CALL
     google_ml.create_sm_secret(
       secret_id => 'SECRET_ID',
       secret_path => 'projects/project-id/secrets/SECRE_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
   

   Ganti kode berikut:

   • SECRET_ID: ID secret yang Anda tetapkan dan kemudian digunakan saat mendaftarkan endpoint model.
   • 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.

5. Panggil fungsi create model untuk mendaftarkan endpoint model facebook/bart-large-mnli:

   CALL
     google_ml.create_model(
       model_id => 'MODEL_ID',
       model_provider => 'custom',
       model_request_url => 'REQUEST_URL',
       model_qualified_name => 'MODEL_QUALIFIED_NAME',
       model_auth_type => 'secret_manager',
       model_auth_id => 'SECRET_ID');
   

   Ganti kode berikut:

   • MODEL_ID: ID unik untuk endpoint model yang Anda tentukan—misalnya, custom-classification-model. ID model ini dirujuk untuk metadata yang diperlukan endpoint model untuk membuat penyematan atau memanggil prediksi.
   • REQUEST_URL: endpoint khusus model saat menambahkan penyematan teks kustom dan endpoint model generik—misalnya, https://api-inference.huggingface.co/models/facebook/bart-large-mnli.
   • MODEL_QUALIFIED_NAME: nama yang sepenuhnya memenuhi syarat dari versi endpoint model-misalnya, facebook/bart-large-mnli.
   • SECRET_ID: ID secret yang Anda gunakan sebelumnya dalam prosedur google_ml.create_sm_secret().

Model Gemini

Pastikan Anda menyiapkan AlloyDB Omni untuk membuat kueri model Vertex AI berbasis cloud.

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

1. Hubungkan ke database Anda menggunakan psql.
2. Buat dan aktifkan ekstensi google_ml_integration.

3. Panggil fungsi create model untuk mendaftarkan model gemini-1.0-pro:

   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 => 'alloydb_service_agent_iam');
   

   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 penyematan atau memanggil prediksi.
   • PROJECT_ID: ID project Google Cloud Anda.

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

Langkah selanjutnya

• Pelajari referensi pengelolaan endpoint model.