模型端點管理參考資料

預先發布版

這項產品適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 正式發布前的產品是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

MySQL  |  PostgreSQL  |  SQL Server

本頁列出 Cloud SQL 提供的不同函式參數，用於註冊及管理模型端點。此外，該頁面也會列出可透過模型端點管理功能管理的密鑰。

注意： 如要進一步瞭解模型端點管理，請參閱「在 Cloud SQL 中註冊及呼叫遠端 AI 模型」。

模型

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

mysql.ml_create_model_registration()

以下說明如何使用 mysql.ml_create_model_registration() 函式註冊模型端點中繼資料：

  CALL
    mysql.ml_create_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

參數	必填	說明
MODEL_ID	所有模型端點的必填屬性	您定義的模型端點專屬 ID。
REQUEST_URL	Vertex AI 模型可為 NULL	新增其他文字嵌入和通用模型端點時，模型專屬的端點。 函式為內建模型端點產生的要求網址，是指叢集的專案和區域或位置。如要參照其他專案，請務必明確指定 model_request_url。 如果是自訂模型端點，請確保模型端點可透過網際網路存取。
PROVIDER_ID	內建支援的文字嵌入模型端點必須提供這項資訊	模型端點的供應商。預設值為 custom。如果是 Cloud SQL，請將供應商設為 google (Vertex AI 模型端點)、open_ai (OpenAI 模型端點)、anthropic (Anthropic 模型端點)、hugging_face (Hugging Face 模型端點) 或 custom (自訂代管模型端點)。
MODEL_TYPE	一般模型端點可為 NULL	模型類型。您可以將這個值設為文字嵌入模型端點的 text_embedding，或是所有其他模型端點的 generic。
MODEL_QUALIFIED_NAME	OpenAI 模型端點必須提供此值，其他模型端點則可為 NULL	如果模型端點有多個版本，或模型端點定義了完整名稱，則為完整名稱，例如 textembedding-gecko@001 或 textembedding-gecko@002。由於 textembedding-gecko@001 模型已預先向模型端點管理服務註冊，因此您可以使用 textembedding-gecko@001 做為模型 ID，產生嵌入內容。
AUTH_TYPE	除非模型端點有特定驗證需求，否則可以為 NULL	模型端點使用的驗證類型。您可以將其設為 auth_type_cloudsql_service_agent_iam (適用於 Vertex AI 模型) 或 auth_type_secret_manager (適用於其他供應商)。
AUTH_ID	如果是 Vertex AI 端點，請傳遞為 NULL；如果是將密鑰儲存在 Secret Manager 中的所有其他模型端點，則必須傳遞	您設定的密碼 ID，用於註冊模型端點。
GENERATE_HEADER_FUNCTION	可為空值	您設定的函式名稱，用於產生自訂標頭。這個函式的簽章取決於 mysql.ml_predict_row() 函式。請參閱 HTTP 標頭產生函式。
INPUT_TRANSFORM_FUNCTION	內建支援的文字嵌入模型端點可選用，通用模型端點則不適用	這個函式會將相應預測函式的輸入內容轉換為模型專屬的輸入內容。請參閱轉換函式。
OUTPUT_TRANSFORM_FUNCTION	內建支援的文字嵌入模型端點可選用，通用模型端點則不適用	這個函式可將模型專屬輸出內容轉換為預測函式輸出內容。請參閱轉換函式。

mysql.ml_alter_model_registration()

以下說明如何呼叫 mysql.ml_alter_model_registration() SQL 函式，用來更新模型端點中繼資料：

    CALL
    mysql.ml_alter_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

mysql.ml_drop_model_registration()

以下說明如何呼叫用於捨棄模型端點的 mysql.ml_drop_model_registration() SQL 函式：

  CALL mysql.ml_drop_model_registration('MODEL_ID');

參數	說明
MODEL_ID	您定義的模型端點專屬 ID。

mysql.ml_list_registered_model()

以下說明如何呼叫 mysql.ml_list_registered_model() SQL 函式，列出模型端點資訊：

  SELECT mysql.ml_list_registered_model('MODEL_ID');

參數	說明
MODEL_ID	您定義的模型端點專屬 ID。

mysql.cloudsql_ml_models

以下說明如何查詢 mysql.cloudsql_ml_models 資料表，該資料表用於列出所有模型端點的模型端點資訊：

  SELECT * FROM mysql.cloudsql_ml_models;

密鑰

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

mysql.ml_create_sm_secret_registration()

以下說明如何呼叫 mysql.ml_create_sm_secret_registration() SQL 函式，用於新增在 Secret Manager 中建立的密鑰：

    CALL
    mysql.ml_create_sm_secret_registration(
      'SECRET_ID',
      '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 的版本號碼。

mysql.ml_alter_sm_secret_registration()

以下說明如何呼叫用於更新密鑰資訊的 mysql.ml_alter_sm_secret_registration() SQL 函式：

  CALL
    mysql.ml_alter_sm_secret_registration(
      'SECRET_ID',
      '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 的版本號碼。

mysql.ml_drop_sm_secret_registration()

以下說明如何呼叫 mysql.ml_drop_sm_secret_registration() SQL 函式，用來捨棄密鑰：

  CALL mysql.ml_drop_sm_secret_registration('SECRET_ID');

參數	說明
SECRET_ID	您設定的密碼 ID，用於註冊模型端點。

預測函式

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

mysql.ml_embedding()

以下說明如何產生嵌入：

SELECT
  mysql.ml_embedding(
    'MODEL_ID',
    'CONTENT');

參數	說明
MODEL_ID	您定義的模型端點專屬 ID。
CONTENT	要轉換為向量嵌入的文字。

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

mysql.ml_predict_row()

以下說明如何叫用預測：

SELECT
  mysql.ml_predict_row(
    'MODEL_ID',
    'REQUEST_BODY');

參數	說明
MODEL_ID	您定義的模型端點專屬 ID。
REQUEST_BODY	預測函式的參數 (JSON 格式)。

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

轉換函式

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

輸入轉換函式

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

  CREATE FUNCTION IF NOT EXISTS
  INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

參數	說明
INPUT_TRANSFORM_FUNCTION	這個函式會將相應預測函式的輸入內容，轉換為模型端點專屬的輸入內容。

輸出轉換函式

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

  CREATE FUNCTION IF NOT EXISTS
  OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;

參數	說明
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。這個欄位接受輸入陣列。由於 mysql.ml_embedding() 函式是列層級函式，因此一次只能輸入一個文字。因此，您需要建立輸入轉換函式，建構含有單一元素的陣列。

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

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

輸入轉換函式

DELIMITER $$
CREATE FUNCTION IF NOT EXISTS cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC

BEGIN
  RETURN JSON_OBJECT('prompt', JSON_ARRAY(input_text));
END $$

輸出轉換函式

CREATE FUNCTION IF NOT EXISTS cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS BLOB
DETERMINISTIC

BEGIN
  RETURN STRING_TO_VECTOR(
         JSON_EXTRACT(
              content,
              '$.predictions[0].embeddings.values'
            )
    );

END $$
DELIMITER ;

HTTP header generation function

The following shows signature for the header generation function that can be used with the `mysql.ml_embedding()` prediction function when registering other text embedding model endpoints.

  CREATE FUNCTION IF NOT EXISTS GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

For the mysql.ml_predict_row() prediction function, the signature is as follows:

CREATE FUNCTION IF NOT EXISTS GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON DETERMINISTIC;

Parameter	Description
GENERATE_HEADERS	The function to generate custom headers. You can also pass the authorization header generated by the header generation function while registering the model endpoint.

Header generation function example

To better understand how to create a function that generates output in JSON key value pairs that are used as HTTP headers, consider a custom-hosted text embedding model endpoint.

The following example curl request passes the version HTTP header, which is used by the model endpoint:

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

The model expects text input through the version field and returns the version value in JSON format. The following example shows the header generation function that is used for this text embedding model endpoint when it is registered with model endpoint management:

DELIMITER $$
CREATE FUNCTION IF NOT EXISTS header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC
BEGIN
  RETURN JSON_OBJECT('version', '2024-01-01');
END;
$$
DELIMITER ;