Mendaftarkan dan memanggil model AI jarak jauh menggunakan pengelolaan endpoint model

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

Sebelum memulai

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. Pastikan flag database google_ml_integration.enable_model_support ditetapkan ke on untuk instance. Untuk mengetahui informasi selengkapnya tentang cara menetapkan flag database, lihat Mengonfigurasi flag database instance.

  2. Hubungkan ke database Anda menggunakan psql atau AlloyDB untuk PostgreSQL Studio.

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

        ALTER EXTENSION google_ml_integration UPDATE;

  4. Tambahkan ekstensi google_ml_integration menggunakan psql:

      CREATE EXTENSION IF NOT EXISTS google_ml_integration;

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

  6. Pastikan IP keluar diaktifkan untuk mengakses model yang dihosting di luar VPC Anda, seperti model pihak ketiga. Untuk mengetahui informasi selengkapnya, lihat Menambahkan konektivitas keluar.

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 AlloyDB berbasis IAM yang Anda gunakan untuk terhubung ke database. Untuk mengetahui informasi selengkapnya tentang integrasi dengan Vertex AI, lihat Mengintegrasikan dengan Vertex AI.

Menyiapkan autentikasi menggunakan Secret Manager

Bagian ini menjelaskan cara menyiapkan autentikasi jika Anda menggunakan Secret Manager untuk menyimpan detail autentikasi bagi penyedia pihak ketiga.

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 berbasis IAM dalam format serviceAccount:service-PROJECT_ID@gcp-sa-alloydb.iam.gserviceaccount.com—misalnya, service-212340152456@gcp-sa-alloydb.iam.gserviceaccount.com.

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

Menyiapkan autentikasi menggunakan header

Contoh berikut menunjukkan cara menyiapkan autentikasi menggunakan fungsi. Fungsi ini 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 penyematan teks

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

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

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

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 langsung memanggil model 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 terdaftar sebelumnya. Untuk memanggil prediksi, lihat cara memanggil prediksi untuk endpoint model yang terdaftar sebelumnya.

Model penyematan teks dengan dukungan bawaan

Pengelolaan endpoint model menyediakan dukungan bawaan untuk beberapa model oleh 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.

Pastikan cluster AlloyDB dan model Vertex AI yang Anda buat kueri berada di region yang sama.

  1. Hubungkan ke database Anda menggunakan psql.

  2. Buat dan aktifkan ekstensi google_ml_integration.

  3. Panggil fungsi create 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');

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 AlloyDB dari project tempat instance AlloyDB berada sehingga AlloyDB dapat mengakses model yang dihosting di project lain.

Membuka model penyematan teks AI

Ekstensi google_ml_integration secara otomatis menyiapkan fungsi transformasi default dan memanggil panggilan ke 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 yang sama dan menetapkan nama yang memenuhi syarat model 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 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 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. Semua endpoint model yang dihosting secara kustom didukung, 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.

  5. Buat fungsi transformasi input dan output berdasarkan tanda tangan berikut untuk fungsi prediksi untuk endpoint model penyematan teks. Untuk 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. Pastikan endpoint model dapat diakses melalui alamat IP internal. Pengelolaan endpoint model tidak mendukung alamat IP publik.
    • 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 generik 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 output 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 terdaftar 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.

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

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

  3. Panggil 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 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. Panggil fungsi create 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 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 generik Anthropic

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

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

    3. Panggil fungsi create 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 untuk membuat penyematan atau memanggil prediksi.
      • REQUEST_URL: endpoint khusus model saat menambahkan penyematan 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 create 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 untuk membuat penyematan atau memanggil prediksi.
      • REQUEST_URL: endpoint khusus model saat menambahkan penyematan teks kustom dan endpoint model generik—misalnya, https://api.anthropic.com/v1/messages.

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

Langkah selanjutnya