模型端點管理參考資料

本頁列出 google_ml_integration 擴充功能提供的不同函式參數,用於註冊及管理模型端點。此外,該頁面也會列出可透過模型端點管理服務管理的密鑰。如要在正式環境中使用 AI 模型,請參閱「使用 Cloud SQL 建構生成式 AI 應用程式」。

模型

請參閱這份參考資料,瞭解可管理模型端點的函式參數。

google_ml.create_model()

以下說明如何呼叫用於註冊模型端點中繼資料的 google_ml.create_model() SQL 函式:

  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');
參數 必填 說明
MODEL_ID 所有模型端點都必須提供這項資訊 您定義的模型端點專屬 ID。
REQUEST_URL

內建支援的文字嵌入模型端點可選用

新增其他文字嵌入和通用模型端點時,模型專屬的端點。

函式為內建模型端點產生的要求網址,是指叢集的專案和區域或位置。如要參照其他專案,請務必明確指定 model_request_url

如果是自訂模型端點,請確保模型端點可透過網際網路存取。

PROVIDER_ID 內建支援的文字嵌入模型端點必須提供這項資訊 模型端點的供應商。預設值為 custom。如果是 Cloud SQL,請將供應商設為 google (Vertex AI 模型端點)、open_ai (OpenAI 模型端點)、anthropic (Anthropic 模型端點)、hugging_face (Hugging Face 模型端點) 或 custom (自訂代管模型端點)。
MODEL_TYPE 通用模型端點為選用項目 模型類型。您可以將這個值設為文字嵌入模型端點的 text_embedding,或是所有其他模型端點的 generic
MODEL_QUALIFIED_NAME OpenAI 模型端點為必填,其他模型端點則為選填 如果模型端點有多個版本,或模型端點定義了完整名稱,則為完整名稱,例如 textembedding-gecko@001textembedding-gecko@002。由於 textembedding-gecko@001 模型已預先向模型端點管理服務註冊,因此您可以使用 textembedding-gecko@001 做為模型 ID,產生嵌入內容。
AUTH_TYPE 選用,除非模型端點有特定驗證要求 模型端點使用的驗證類型。您可以將其設為 cloudsql_service_agent_iam (適用於 Vertex AI 模型) 或 secret_manager (適用於其他供應商)。
AUTH_ID 請勿為 Vertex AI 模型端點設定;所有其他模型端點都必須設定,這些端點會將密鑰儲存在 Secret Manager 中 您設定的密碼 ID,用於註冊模型端點。
GENERATE_HEADER_FUNCTION 選用 您設定的函式名稱,用於產生自訂標頭。這個函式的簽章取決於 google_ml.predict_row() 函式。請參閱 HTTP 標頭產生函式
INPUT_TRANSFORM_FUNCTION 內建支援的文字嵌入模型端點可選用,通用模型端點則不適用 這個函式會將相應預測函式的輸入內容轉換為模型專屬的輸入內容。請參閱轉換函式
OUTPUT_TRANSFORM_FUNCTION 內建支援的文字嵌入模型端點可選用,通用模型端點則不適用 此函式可將模型專屬輸出內容轉換為預測函式輸出內容。請參閱轉換函式

google_ml.alter_model()

以下說明如何呼叫 google_ml.alter_model() SQL 函式,用來更新模型端點中繼資料:

    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()

以下說明如何呼叫用於捨棄模型端點的 google_ml.drop_model() SQL 函式:

  CALL google_ml.drop_model('MODEL_ID');
參數 說明
MODEL_ID 您定義的模型端點專屬 ID。

google_ml.list_model()

以下說明如何呼叫 google_ml.list_model() SQL 函式,列出模型端點資訊:

  SELECT google_ml.list_model('MODEL_ID');
參數 說明
MODEL_ID 您定義的模型端點專屬 ID。

google_ml.model_info_view

下列範例說明如何呼叫 google_ml.model_info_view 檢視畫面,列出所有模型端點的模型端點資訊:

  SELECT * FROM google_ml.model_info_view;

密鑰

請參閱這份參考資料,瞭解可管理密鑰的函式參數。

google_ml.create_sm_secret()

以下說明如何呼叫 google_ml.create_sm_secret() SQL 函式,用於新增在 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');
參數 說明
SECRET_ID 您設定的密碼 ID,用於註冊模型端點。
PROJECT_ID 包含密鑰的 Google Cloud 專案 ID。這個專案可以與包含 Cloud SQL 執行個體的專案不同。
SECRET_MANAGER_SECRET_ID 您建立密鑰時,在 Secret Manager 中設定的密鑰 ID。
VERSION_NUMBER 密鑰 ID 的版本號碼。

google_ml.alter_sm_secret()

以下說明如何呼叫用於更新密鑰資訊的 google_ml.alter_sm_secret() SQL 函式:

  CALL
    google_ml.alter_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
參數 說明
SECRET_ID 您設定的密碼 ID,用於註冊模型端點。
PROJECT_ID 包含密鑰的 Google Cloud 專案 ID。這個專案可以與包含 Cloud SQL 執行個體的專案不同。
SECRET_MANAGER_SECRET_ID 您建立密鑰時,在 Secret Manager 中設定的密鑰 ID。
VERSION_NUMBER 密鑰 ID 的版本號碼。

google_ml.drop_sm_secret()

以下說明如何呼叫 google_ml.drop_sm_secret() SQL 函式,用來捨棄密鑰:

  CALL google_ml.drop_sm_secret('SECRET_ID');
參數 說明
SECRET_ID 您設定的密碼 ID,用於註冊模型端點。

預測函式

請參閱這份參考資料,瞭解可產生嵌入內容或叫用預測結果的函式參數。

google_ml.embedding()

以下說明如何產生嵌入:

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    contents => 'CONTENT');
參數 說明
MODEL_ID 您定義的模型端點專屬 ID。
CONTENT 要轉換為向量嵌入的文字。

如需產生文字嵌入的 SQL 查詢範例,請參閱「範例」。

google_ml.predict_row()

以下說明如何叫用預測:

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');
參數 說明
MODEL_ID 您定義的模型端點專屬 ID。
REQUEST_BODY 預測函式的參數 (JSON 格式)。

如需叫用預測的 SQL 查詢範例,請參閱「範例」。

轉換函式

請參閱這份參考資料,瞭解輸入和輸出轉換函式的參數。

輸入轉換函式

以下是文字嵌入模型端點的預測函式簽章:

  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;
參數 說明
INPUT_TRANSFORM_FUNCTION 這個函式會將相應預測函式的輸入內容,轉換為模型端點專屬的輸入內容。

輸出轉換函式

以下是文字嵌入模型端點的預測函式簽章:

  CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];
參數 說明
OUTPUT_TRANSFORM_FUNCTION 這個函式會將模型端點專屬輸出內容轉換為預測函式輸出內容。

轉換函式範例

如要進一步瞭解如何為模型端點建立轉換函式,請考慮需要 JSON 輸入和輸出的自訂代管文字嵌入模型端點。

以下 cURL 要求範例會根據提示和模型端點建立嵌入內容:

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

系統會傳回下列範例回應:

[[ 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]]

根據這項輸入內容和回覆,您可以推斷出以下資訊:

  • 模型預期透過 prompt 欄位輸入 JSON。這個欄位接受輸入陣列。由於 google_ml.embedding() 函式是列層級函式,因此一次只能輸入一個文字。因此,您需要建立輸入轉換函式,建構含有單一元素的陣列。

  • 模型的回覆是嵌入陣列,每個提示輸入內容對應一個嵌入。由於 google_ml.embedding() 函式是資料列層級函式,因此一次只會傳回單一輸入內容。因此,您需要建立輸出轉換函式,從陣列中擷取嵌入。

以下範例顯示註冊模型端點管理服務時,用於這個模型端點的輸入和輸出轉換函式:

輸入轉換函式

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

輸出轉換函式

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

HTTP 標頭產生函式

以下顯示標頭生成函式的簽章,註冊其他文字嵌入模型端點時,可與 google_ml.embedding() 預測函式搭配使用。

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

google_ml.predict_row() 預測函式的簽章如下:

CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON;
參數 說明
GENERATE_HEADERS 用於產生自訂標頭的函式。註冊模型端點時,您也可以傳遞標頭產生函式產生的授權標頭。

標頭產生函式範例

如要進一步瞭解如何建立函式,以產生 JSON 鍵值對做為 HTTP 標頭,請考慮使用自訂代管的文字嵌入模型端點。

下列範例 cURL 要求會傳遞 version HTTP 標頭,模型端點會使用這個標頭:

  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"]}'

模型會透過 version 欄位接收文字輸入內容,並以 JSON 格式傳回版本值。以下範例顯示向模型端點管理服務註冊時,用於這個文字嵌入模型端點的標頭產生函式:

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

產生要求網址

使用要求網址產生函式,推斷內建支援的模型端點要求網址。這個函式的簽名如下:

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)
參數 說明
GENERATE_REQUEST_URL 這項函式會產生擴充功能的要求網址,適用於內建支援功能的模型端點。