Referensi pengelolaan endpoint model

Pratinjau

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

MySQL   |  PostgreSQL   |  SQL Server

Halaman ini mencantumkan parameter untuk berbagai fungsi yang disediakan oleh ekstensi google_ml_integration untuk mendaftarkan dan mengelola endpoint model. Halaman ini juga mencantumkan secret yang dapat Anda kelola menggunakan pengelolaan endpoint model. Untuk menggunakan model AI di lingkungan produksi, lihat Mem-build aplikasi AI generatif menggunakan Cloud SQL.

Catatan: Sebelum dapat mulai menggunakan ekstensi untuk pengelolaan endpoint model, Anda harus menetapkan tanda database google_ml_integration.enable_model_support ke on. Selain itu, untuk informasi selengkapnya tentang pengelolaan endpoint model, lihat Mendaftarkan dan memanggil model AI jarak jauh di Cloud SQL.

Model

Gunakan referensi ini untuk memahami parameter untuk fungsi yang memungkinkan Anda mengelola endpoint model.

google_ml.create_model()

Berikut ini cara memanggil fungsi SQL google_ml.create_model() yang digunakan untuk mendaftarkan metadata endpoint model:

  CALL
    google_ml.create_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');

Parameter	Wajib	Deskripsi
MODEL_ID	diperlukan untuk semua endpoint model	ID unik untuk endpoint model yang Anda tentukan.
REQUEST_URL	opsional untuk endpoint model embedding teks dengan dukungan bawaan	Endpoint khusus model saat menambahkan penyematan teks lain dan endpoint model generik. URL permintaan yang dihasilkan fungsi untuk endpoint model bawaan merujuk ke project dan wilayah atau lokasi cluster Anda. Jika Anda ingin merujuk ke project lain, pastikan Anda menentukan model_request_url secara eksplisit. Untuk endpoint model yang dihosting secara kustom, pastikan endpoint model dapat diakses melalui internet.
PROVIDER_ID	diperlukan untuk endpoint model embedding teks dengan dukungan bawaan	Penyedia endpoint model. Nilai defaultnya adalah custom. Untuk Cloud SQL, tetapkan penyedia ke google untuk endpoint model Vertex AI, open_ai untuk endpoint model OpenAI, anthropic untuk endpoint model Anthropic, hugging_face untuk endpoint model Hugging Face, atau custom untuk endpoint model yang dihosting secara kustom.
MODEL_TYPE	opsional untuk endpoint model generik	Jenis model. Anda dapat menetapkan nilai ini ke text_embedding untuk endpoint model penyematan teks atau generic untuk semua endpoint model lainnya.
MODEL_QUALIFIED_NAME	diperlukan untuk endpoint model OpenAI; opsional untuk endpoint model lainnya	Nama yang sepenuhnya memenuhi syarat jika endpoint model memiliki beberapa versi atau jika endpoint model menentukannya—misalnya, textembedding-gecko@001 atau textembedding-gecko@002. Karena model textembedding-gecko@001 telah terdaftar sebelumnya dengan pengelolaan endpoint model, Anda dapat membuat penyematan menggunakan textembedding-gecko@001 sebagai ID model.
AUTH_TYPE	opsional kecuali jika endpoint model memiliki persyaratan autentikasi tertentu	Jenis autentikasi yang digunakan oleh endpoint model. Anda dapat menyetelnya ke cloudsql_service_agent_iam untuk model Vertex AI atau secret_manager untuk penyedia lain.
AUTH_ID	jangan ditetapkan untuk endpoint model Vertex AI; diperlukan untuk semua endpoint model lainnya yang menyimpan secret di Secret Manager	ID secret yang Anda tetapkan dan kemudian digunakan saat mendaftarkan endpoint model.
GENERATE_HEADER_FUNCTION	opsional	Nama fungsi yang Anda tetapkan untuk membuat header kustom. Tanda tangan fungsi ini bergantung pada fungsi google_ml.predict_row(). Lihat Fungsi pembuatan Header HTTP.
INPUT_TRANSFORM_FUNCTION	opsional untuk endpoint model penyematan teks dengan dukungan bawaan; jangan tetapkan untuk endpoint model generik	Fungsi untuk mengubah input fungsi prediksi yang sesuai menjadi input khusus model. Lihat Fungsi transformasi.
OUTPUT_TRANSFORM_FUNCTION	opsional untuk endpoint model penyematan teks dengan dukungan bawaan; jangan tetapkan untuk endpoint model generik	Fungsi untuk mengubah output khusus model menjadi output fungsi prediksi. Lihat Fungsi transformasi.

google_ml.alter_model()

Berikut ini cara memanggil fungsi SQL google_ml.alter_model() yang digunakan untuk mengupdate metadata endpoint model:

    CALL
    google_ml.alter_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');

google_ml.drop_model()

Berikut ini cara memanggil fungsi SQL google_ml.drop_model() yang digunakan untuk menghapus endpoint model:

  CALL google_ml.drop_model('MODEL_ID');

Parameter	Deskripsi
MODEL_ID	ID unik untuk endpoint model yang Anda tentukan.

google_ml.list_model()

Berikut ini cara memanggil fungsi SQL google_ml.list_model() yang digunakan untuk mencantumkan informasi endpoint model:

  SELECT google_ml.list_model('MODEL_ID');

Parameter	Deskripsi
MODEL_ID	ID unik untuk endpoint model yang Anda tentukan.

google_ml.model_info_view

Berikut ini cara memanggil tampilan google_ml.model_info_view yang digunakan untuk mencantumkan informasi endpoint model untuk semua endpoint model:

  SELECT * FROM google_ml.model_info_view;

Rahasia

Gunakan referensi ini untuk memahami parameter untuk fungsi yang memungkinkan Anda mengelola secret.

google_ml.create_sm_secret()

Berikut ini cara memanggil fungsi SQL google_ml.create_sm_secret() yang digunakan untuk menambahkan secret yang dibuat 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');

Parameter	Deskripsi
SECRET_ID	ID secret yang Anda tetapkan dan kemudian digunakan saat mendaftarkan endpoint model.
PROJECT_ID	ID project Google Cloud Anda yang berisi secret. Project ini dapat berbeda dengan project yang berisi instance Cloud SQL Anda.
SECRET_MANAGER_SECRET_ID	ID secret yang ditetapkan di Secret Manager saat Anda membuat secret.
VERSION_NUMBER	Nomor versi ID rahasia.

google_ml.alter_sm_secret()

Berikut ini cara memanggil fungsi SQL google_ml.alter_sm_secret() yang digunakan untuk memperbarui informasi rahasia:

  CALL
    google_ml.alter_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

Parameter	Deskripsi
SECRET_ID	ID secret yang Anda tetapkan dan kemudian digunakan saat mendaftarkan endpoint model.
PROJECT_ID	ID project Google Cloud Anda yang berisi secret. Project ini dapat berbeda dengan project yang berisi instance Cloud SQL Anda.
SECRET_MANAGER_SECRET_ID	ID secret yang ditetapkan di Secret Manager saat Anda membuat secret.
VERSION_NUMBER	Nomor versi ID rahasia.

google_ml.drop_sm_secret()

Berikut ini cara memanggil fungsi SQL google_ml.drop_sm_secret() yang digunakan untuk menghapus secret:

  CALL google_ml.drop_sm_secret('SECRET_ID');

Parameter	Deskripsi
SECRET_ID	ID secret yang Anda tetapkan dan kemudian digunakan saat mendaftarkan endpoint model.

Fungsi prediksi

Gunakan referensi ini untuk memahami parameter untuk fungsi yang memungkinkan Anda membuat penyematan atau memanggil prediksi.

google_ml.embedding()

Berikut ini cara membuat penyematan:

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    contents => 'CONTENT');

Parameter	Deskripsi
MODEL_ID	ID unik untuk endpoint model yang Anda tentukan.
CONTENT	teks yang akan diterjemahkan menjadi penyematan vektor.

Untuk contoh kueri SQL guna membuat penyematan teks, lihat Contoh.

google_ml.predict_row()

Berikut ini cara memanggil prediksi:

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');

Parameter	Deskripsi
MODEL_ID	ID unik untuk endpoint model yang Anda tentukan.
REQUEST_BODY	parameter ke fungsi prediksi, dalam format JSON.

Untuk contoh kueri SQL guna memanggil prediksi, lihat Contoh.

Fungsi transformasi

Gunakan referensi ini untuk memahami parameter untuk fungsi transformasi input dan output.

Fungsi transformasi input

Berikut ini menunjukkan tanda tangan untuk fungsi prediksi untuk endpoint model penyematan teks:

  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

Parameter	Deskripsi
INPUT_TRANSFORM_FUNCTION	Fungsi untuk mengubah input fungsi prediksi yang sesuai ke input khusus endpoint model.

Fungsi transformasi output

Berikut ini menunjukkan tanda tangan untuk fungsi prediksi untuk endpoint model penyematan teks:

  CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];

Parameter	Deskripsi
OUTPUT_TRANSFORM_FUNCTION	Fungsi untuk mengubah output khusus endpoint model menjadi output fungsi prediksi.

Contoh fungsi transformasi

Untuk lebih memahami cara membuat fungsi transformasi untuk endpoint model Anda, pertimbangkan endpoint model penyematan teks yang dihosting secara kustom yang memerlukan input dan output JSON.

Contoh permintaan cURL berikut membuat penyematan berdasarkan perintah dan endpoint model:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json"
    -d '{"prompt": ["Cloud SQL Embeddings"]}'

Contoh respons berikut akan ditampilkan:

[[ 0.3522231  -0.35932037  0.10156056  0.17734447 -0.11606089 -0.17266059
   0.02509351  0.20305622 -0.09787305 -0.12154685 -0.17313677 -0.08075467
   0.06821183 -0.06896557  0.1171584  -0.00931572  0.11875633 -0.00077482
   0.25604948  0.0519384   0.2034983  -0.09952664  0.10347155 -0.11935943
  -0.17872004 -0.08706985 -0.07056875 -0.05929353  0.4177883  -0.14381726
   0.07934926  0.31368294  0.12543282  0.10758053 -0.30210832 -0.02951015
   0.3908268  -0.03091059  0.05302926 -0.00114946 -0.16233777  0.1117468
  -0.1315904   0.13947351 -0.29569918 -0.12330773 -0.04354299 -0.18068913
   0.14445548  0.19481727]]

Berdasarkan input dan respons ini, Anda dapat menyimpulkan hal berikut:

• Model mengharapkan input JSON melalui kolom prompt. Kolom ini menerima array input. Karena fungsi google_ml.embedding() adalah fungsi tingkat baris, fungsi ini mengharapkan satu input teks dalam satu waktu. Oleh karena itu, Anda perlu membuat fungsi transformasi input yang membuat array dengan satu elemen.

• Respons dari model adalah array penyematan, satu untuk setiap input perintah ke model. Karena fungsi google_ml.embedding() adalah fungsi tingkat baris, fungsi ini menampilkan satu input dalam satu waktu. Oleh karena itu, Anda perlu membuat fungsi transformasi output yang dapat digunakan untuk mengekstrak penyematan dari array.

Contoh berikut menunjukkan fungsi transformasi input dan output yang digunakan untuk endpoint model ini saat didaftarkan dengan pengelolaan endpoint model:

fungsi transformasi input

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

fungsi transformasi output

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

Fungsi pembuatan header HTTP

Berikut ini menunjukkan tanda tangan untuk fungsi pembuatan header yang dapat digunakan dengan fungsi prediksi google_ml.embedding() saat mendaftarkan endpoint model penyematan teks lainnya.

  CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

Untuk fungsi prediksi google_ml.predict_row(), tanda tangannya adalah sebagai berikut:

CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON;

Parameter	Deskripsi
GENERATE_HEADERS	Fungsi untuk membuat header kustom. Anda juga dapat meneruskan header otorisasi yang dihasilkan oleh fungsi pembuatan header saat mendaftarkan endpoint model.

Contoh fungsi pembuatan header

Untuk lebih memahami cara membuat fungsi yang menghasilkan output dalam key-value pair JSON yang digunakan sebagai header HTTP, pertimbangkan endpoint model penyematan teks yang dihosting secara kustom.

Contoh permintaan cURL berikut meneruskan header HTTP version, yang digunakan oleh endpoint model:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
      -H "Content-Type: application/json" \
      -H "version: 2024-01-01" \
      -d '{"prompt": ["Cloud SQL Embeddings"]}'

Model mengharapkan input teks melalui kolom version dan menampilkan nilai versi dalam format JSON. Contoh berikut menunjukkan fungsi pembuatan header yang digunakan untuk endpoint model penyematan teks ini saat didaftarkan dengan pengelolaan endpoint model:

CREATE OR REPLACE FUNCTION header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN json_build_object('version', '2024-01-01')::JSON;
END;
$$;

Membuat URL permintaan

Gunakan fungsi pembuatan URL permintaan untuk menyimpulkan URL permintaan untuk endpoint model dengan dukungan bawaan. Berikut ini menunjukkan tanda tangan untuk fungsi ini:

CREATE OR REPLACE FUNCTION GENERATE_REQUEST_URL(provider google_ml.model_provider, model_type google_ml.MODEL_TYPE, model_qualified_name VARCHAR(100), model_region VARCHAR(100) DEFAULT NULL)

Parameter	Deskripsi
GENERATE_REQUEST_URL	Fungsi untuk membuat URL permintaan yang dihasilkan oleh ekstensi untuk endpoint model dengan dukungan bawaan.