本頁列出 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 |
內建支援的文字嵌入模型端點可選用 |
新增其他文字嵌入和通用模型端點時，模型專屬的端點。 函式為內建模型端點產生的要求網址，是指叢集的專案和區域或位置。如要參照其他專案，請務必明確指定 如果是自訂模型端點，請確保模型端點可透過網際網路存取。 |
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@001 或 textembedding-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 |
這項函式會產生擴充功能的要求網址，適用於內建支援功能的模型端點。 |