Mendaftarkan dan memanggil model AI jarak jauh di AlloyDB Omni

Pilih versi dokumentasi:

Untuk memanggil prediksi atau membuat embedding menggunakan model, daftarkan endpoint model dengan 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 mengharuskan penginstalan ekstensi google_ml_integration.

  1. Pastikan flag database google_ml_integration.enable_model_support disetel ke on untuk instance. Untuk mengetahui informasi selengkapnya tentang menyetel flag database, lihat Mengonfigurasi flag database.

  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 IF NOT EXISTS google_ml_integration;

  4. Opsional: Beri 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();

  6. Pastikan konektivitas keluar diaktifkan.

Menyiapkan autentikasi

Bagian berikut menunjukkan cara menyiapkan autentikasi sebelum mendaftarkan endpoint model.

Menyiapkan autentikasi untuk Vertex AI

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

Menyiapkan autentikasi menggunakan 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.

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.

    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_NAME' \
      --member="serviceAccount:SERVICE_ACCOUNT_ID" \
      --role="roles/secretmanager.secretAccessor"

    Ganti kode berikut:

    • SECRET_NAME: nama secret di Secret Manager.

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

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

Menyiapkan autentikasi menggunakan header

Contoh berikut menunjukkan cara menyiapkan autentikasi menggunakan fungsi yang menampilkan objek JSON yang berisi header yang diperlukan untuk membuat permintaan ke model penyematan.

  CREATE OR REPLACE FUNCTION HEADER_GEN_FUNCTION(
    model_id VARCHAR(100),
    input_text TEXT
  )
  RETURNS JSON
  LANGUAGE plpgsql
  AS $$
  #variable_conflict use_variable
  DECLARE
    api_key VARCHAR(255) := 'API_KEY';
    header_json JSON;
  BEGIN
    header_json := json_build_object(
      'Content-Type', 'application/json',
      'Authorization', 'Bearer ' || api_key
    );
    RETURN header_json;
  END;
  $$;

Ganti kode berikut:

  • HEADER_GEN_FUNCTION: nama fungsi pembuatan header yang dapat Anda gunakan saat mendaftarkan model.
  • API_KEY: kunci API penyedia model.

Model embedding teks

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

Pengelolaan endpoint model mendukung beberapa model penyematan teks dan Vertex AI generik sebagai endpoint model yang telah didaftarkan sebelumnya. Anda dapat langsung menggunakan ID model untuk membuat embedding atau memanggil prediksi, berdasarkan jenis model. Untuk mengetahui informasi selengkapnya tentang model pra-terdaftar yang didukung, lihat Model Vertex AI pra-terdaftar.

Misalnya, untuk memanggil model textembedding-gecko yang telah terdaftar sebelumnya, Anda dapat langsung memanggil model menggunakan fungsi embedding:

SELECT
      google_ml.embedding(
        model_id => 'textembedding-gecko',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');

Demikian pula, untuk memanggil model gemini-1.5-pro:generateContent yang telah didaftarkan sebelumnya, Anda dapat memanggil model secara langsung menggunakan fungsi prediksi:

 SELECT
        json_array_elements(
        google_ml.predict_row(
            model_id => 'gemini-1.5-pro:generateContent',
            request_body => '{
        "contents": [
            {
                "role": "user",
                "parts": [
                    {
                        "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
                    }
                ]
            }
        ]
        }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

Untuk membuat embedding, lihat cara membuat embedding untuk endpoint model yang telah terdaftar sebelumnya. Untuk memanggil prediksi, lihat cara memanggil prediksi untuk endpoint model yang telah terdaftar sebelumnya.

Model embedding teks dengan dukungan bawaan

Pengelolaan endpoint model menyediakan dukungan bawaan untuk beberapa model dari Vertex AI dan OpenAI. Untuk mengetahui daftar model dengan dukungan bawaan, lihat Model dengan dukungan bawaan.

Untuk model dengan dukungan bawaan, Anda dapat menetapkan nama yang memenuhi syarat sebagai nama yang memenuhi syarat model dan menentukan URL permintaan. Pengelolaan endpoint model secara otomatis mengidentifikasi model dan menyiapkan fungsi transformasi default.

Model penyematan Vertex AI

Langkah-langkah berikut menunjukkan cara mendaftarkan model Vertex AI dengan dukungan bawaan. Endpoint model text-embedding-005 dan text-multilingual-embedding-002 digunakan sebagai contoh.

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. Panggil fungsi pembuatan model untuk menambahkan endpoint model:

    text-embedding-005 

      CALL
    google_ml.create_model(
      model_id => 'text-embedding-005',
      model_request_url => 'publishers/google/models/text-embedding-005',
      model_provider => 'google',
      model_qualified_name => 'text-embedding-005',
      model_type => 'text_embedding',
      model_auth_type => 'alloydb_service_agent_iam');

    text-multilingual-embedding-002 

      CALL
    google_ml.create_model(
      model_id => 'text-multilingual-embedding-002',
      model_request_url => 'publishers/google/models/text-multilingual-embedding-002',
      model_provider => 'google',
      model_qualified_name => 'text-multilingual-embedding-002',
      model_type => 'text_embedding',
      model_auth_type => 'alloydb_service_agent_iam'
      model_in_transform_fn => 'google_ml.vertexai_text_embedding_input_transform',
      model_out_transform_fn => 'google_ml.vertexai_text_embedding_output_transform');

URL permintaan yang dihasilkan fungsi merujuk ke project yang terkait dengan akun layanan AlloyDB Omni. Jika Anda ingin merujuk ke project lain, pastikan Anda menentukan model_request_url secara eksplisit.

Jika model disimpan di project dan region lain selain cluster AlloyDB Anda, tetapkan URL permintaan ke projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID, dengan REGION_ID adalah region tempat model Anda dihosting, dan MODEL_ID adalah nama model yang memenuhi syarat.

Selain itu, berikan peran Vertex AI User (roles/aiplatform.user) ke akun layanan project tempat AlloyDB Omni diinstal agar model yang dihosting di project lain dapat diakses.

Model embedding teks Open AI

Ekstensi google_ml_integration otomatis menyiapkan fungsi transformasi default dan memanggil model OpenAI jarak jauh. Untuk mengetahui daftar model OpenAI dengan dukungan bawaan, lihat Model dengan dukungan bawaan.

Contoh berikut menambahkan endpoint model OpenAI text-embedding-ada-002. Anda dapat mendaftarkan endpoint model text-embedding-3-small dan text-embedding-3-large OpenAI menggunakan langkah-langkah yang sama dan menetapkan nama lengkap model yang khusus untuk model tersebut.

  1. Hubungkan ke database Anda menggunakan psql.
  2. Buat dan aktifkan ekstensi google_ml_integration.
  3. Tambahkan kunci API OpenAI sebagai rahasia 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 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 Google Cloud project Anda.
    • VERSION_NUMBER: nomor versi ID secret.

  5. Panggil fungsi pembuatan 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 guna membuat embedding 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 yang dihosting kustom

Bagian ini menunjukkan cara mendaftarkan endpoint model yang dihosting kustom beserta pembuatan fungsi transformasi, dan secara opsional, header HTTP kustom. Semua endpoint model yang dihosting kustom didukung, terlepas dari tempat dihostingnya.

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 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 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 Google Cloud project Anda.
    • VERSION_NUMBER: nomor versi ID secret.

  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 pembuatan model untuk mendaftarkan endpoint model embedding 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 guna 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.
    • MODEL_QUALIFIED_NAME: diperlukan 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 generik apa pun yang tersedia di penyedia model yang dihosting seperti Hugging Face, OpenAI, Vertex AI, Anthropic, atau penyedia lainnya. Bagian ini menunjukkan contoh untuk mendaftarkan endpoint model generik yang dihosting di Hugging Face, model gemini-pro generik dari Vertex AI Model Garden, dan endpoint model claude-haiku.

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

Untuk mengetahui informasi selengkapnya tentang model generik yang telah didaftarkan sebelumnya dan model dengan dukungan bawaan, lihat Model yang didukung.

Model Gemini

Karena beberapa model gemini-pro telah didaftarkan sebelumnya, Anda dapat langsung memanggil ID model untuk memanggil prediksi. Pastikan Anda telah menyiapkan AlloyDB Omni untuk membuat kueri model Vertex AI berbasis cloud.

Contoh berikut menggunakan endpoint model gemini-1.5-pro:generateContent dari Vertex AI Model Garden.

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

  3. Memanggil prediksi menggunakan ID model yang telah didaftarkan sebelumnya:

    SELECT
    json_array_elements(
    google_ml.predict_row(
        model_id => 'gemini-1.5-pro:generateContent',
        request_body => '{
    "contents": [
        {
            "role": "user",
            "parts": [
                {
                    "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
                }
            ]
        }
    ]
    }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

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 kunci API OpenAI sebagai rahasia ke Secret Manager untuk autentikasi. Jika Anda telah 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 rahasia yang Anda tetapkan dan selanjutnya digunakan saat mendaftarkan endpoint model.
    • SECRET_MANAGER_SECRET_ID: ID secret yang ditetapkan di Secret Manager saat Anda membuat secret.
    • PROJECT_ID: ID Google Cloud project Anda.
    • VERSION_NUMBER: nomor versi ID secret.

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

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'hugging_face',
    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 guna membuat embedding atau memanggil prediksi.
    • REQUEST_URL: endpoint khusus model saat menambahkan embedding 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 generik Anthropic

Contoh berikut menambahkan endpoint model claude-3-opus-20240229. Pengelolaan endpoint model menyediakan fungsi header yang diperlukan untuk mendaftarkan model Anthropic.

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

  1. Hubungkan ke database Anda menggunakan psql.

  2. Buat dan aktifkan ekstensi google_ml_integration.

    Secret Manager

    1. Tambahkan token pembawa sebagai secret ke Secret Manager untuk autentikasi.

    2. 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 rahasia yang Anda tetapkan dan selanjutnya digunakan saat mendaftarkan endpoint model.
      • SECRET_MANAGER_SECRET_ID: ID secret yang ditetapkan di Secret Manager saat Anda membuat secret.
      • PROJECT_ID: ID Google Cloud project Anda.
      • VERSION_NUMBER: nomor versi ID secret.

    3. Panggil fungsi pembuatan model untuk mendaftarkan endpoint model claude-3-opus-20240229.

      CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'anthropic',
    model_request_url => 'REQUEST_URL',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');

      Ganti kode berikut:

      • MODEL_ID: ID unik untuk endpoint model yang Anda tentukan—misalnya, anthropic-opus. ID model ini dirujuk untuk metadata yang diperlukan endpoint model guna membuat embedding atau memanggil prediksi.
      • REQUEST_URL: endpoint khusus model saat menambahkan embedding teks kustom dan endpoint model generik—misalnya, https://api.anthropic.com/v1/messages.

    Header Auth

    1. Gunakan fungsi pembuatan header default google_ml.anthropic_claude_header_gen_fn atau buat fungsi pembuatan header.

        CREATE OR REPLACE FUNCTION anthropic_sample_header_gen_fn(model_id VARCHAR(100), request_body JSON)
  RETURNS JSON
  LANGUAGE plpgsql
  AS $$
  #variable_conflict use_variable
  BEGIN
        RETURN json_build_object('x-api-key', 'ANTHROPIC_API_KEY', 'anthropic-version', 'ANTHROPIC_VERSION')::JSON;
  END;
  $$;

      Ganti kode berikut:

      • ANTHROPIC_API_KEY: kunci API anthropic.
      • ANTHROPIC_VERSION (Opsional): versi model tertentu yang ingin Anda gunakan—misalnya, 2023-06-01.

    2. Panggil fungsi pembuatan model untuk mendaftarkan endpoint model claude-3-opus-20240229.

      CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'anthropic',
    model_request_url => 'REQUEST_URL',
    generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');

      Ganti kode berikut:

      • MODEL_ID: ID unik untuk endpoint model yang Anda tentukan—misalnya, anthropic-opus. ID model ini dirujuk untuk metadata yang diperlukan endpoint model guna membuat embedding atau memanggil prediksi.
      • REQUEST_URL: endpoint khusus model saat menambahkan embedding teks kustom dan endpoint model generik—misalnya, https://api.anthropic.com/v1/messages.

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

Langkah berikutnya