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 Membangun aplikasi AI generatif menggunakan Cloud SQL.

Catatan: Sebelum dapat mulai menggunakan ekstensi untuk pengelolaan endpoint model, Anda harus menetapkan flag database google_ml_integration.enable_model_support ke on. Selain itu, untuk mengetahui informasi selengkapnya tentang pengelolaan endpoint model, lihat Ringkasan pengelolaan endpoint model.

Model

Gunakan referensi ini untuk memahami parameter 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	wajib 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 endpoint model generik dan embedding teks lainnya. URL permintaan yang dihasilkan fungsi untuk endpoint model bawaan merujuk ke project dan region atau lokasi cluster Anda. Jika ingin merujuk ke project lain, pastikan Anda menentukan model_request_url secara eksplisit. Untuk endpoint model yang dihosting kustom, pastikan endpoint model dapat diakses melalui internet.
PROVIDER_ID	wajib 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 kustom.
MODEL_TYPE	opsional untuk endpoint model generik	Jenis model. Anda dapat menetapkan nilai ini ke text_embedding untuk endpoint model embedding teks atau generic untuk semua endpoint model lainnya.
MODEL_QUALIFIED_NAME	wajib 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 dengan pengelolaan endpoint model, Anda dapat membuat embedding menggunakan textembedding-gecko@001 sebagai ID model.
AUTH_TYPE	opsional kecuali endpoint model memiliki persyaratan autentikasi tertentu	Jenis autentikasi yang digunakan oleh endpoint model. Anda dapat menetapkannya ke cloudsql_service_agent_iam untuk model Vertex AI atau secret_manager untuk penyedia lainnya.
AUTH_ID	jangan tetapkan untuk endpoint model Vertex AI; wajib untuk semua endpoint model lainnya yang menyimpan secret di Secret Manager	ID secret yang Anda tetapkan dan selanjutnya 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 embedding teks dengan dukungan bawaan; jangan tetapkan untuk endpoint model generik	Fungsi untuk mengubah input fungsi prediksi yang sesuai ke input khusus model. Lihat Fungsi transformasi.
OUTPUT_TRANSFORM_FUNCTION	opsional untuk endpoint model embedding teks dengan dukungan bawaan; jangan tetapkan untuk endpoint model generik	Fungsi untuk mengubah output khusus model ke output fungsi prediksi. Lihat Fungsi transformasi.

google_ml.alter_model()

Berikut ini cara memanggil fungsi SQL google_ml.alter_model() yang digunakan untuk memperbarui 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;

Secret

Gunakan referensi ini untuk memahami parameter 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 selanjutnya 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 secret.

google_ml.alter_sm_secret()

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

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

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 selanjutnya digunakan saat mendaftarkan endpoint model.

Fungsi prediksi

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

google_ml.embedding()

Berikut ini cara membuat embedding:

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 ke dalam embedding vektor.

Untuk contoh kueri SQL untuk membuat embedding 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 untuk memanggil prediksi, lihat Contoh.

Fungsi transformasi

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

Fungsi transformasi input

Berikut ini tanda tangan untuk fungsi prediksi untuk endpoint model embedding 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 tanda tangan untuk fungsi prediksi untuk endpoint model embedding 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 ke output fungsi prediksi.

Contoh fungsi transformasi

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

Contoh permintaan curl berikut membuat embedding 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 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 pada satu waktu. Oleh karena itu, Anda harus membuat fungsi transformasi input yang membuat array dengan satu elemen.

• Respons dari model adalah array embedding, satu untuk setiap input perintah ke model. Karena fungsi google_ml.embedding() adalah fungsi tingkat baris, fungsi ini menampilkan satu input pada satu waktu. Oleh karena itu, Anda harus membuat fungsi transformasi output yang dapat digunakan untuk mengekstrak embedding 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 tanda tangan untuk fungsi pembuatan header yang dapat di gunakan dengan google_ml.embedding() fungsi prediksi saat mendaftarkan endpoint model embedding 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 dibuat 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 embedding teks yang dihosting 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 embedding teks ini saat didaftarkan dengan pengelolaan endpoint model:

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

Pembuatan URL permintaan

Gunakan fungsi pembuatan URL permintaan untuk menyimpulkan URL permintaan untuk endpoint model dengan dukungan bawaan. Berikut ini 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 dibuat oleh ekstensi untuk endpoint model dengan dukungan bawaan.