本頁面由 Cloud Translation API 翻譯而成。

模型端點管理參考資料

選取說明文件版本：

本頁列出 google_ml_integration 擴充功能提供的不同函式參數，用於註冊及管理模型端點，以及使用模型端點管理服務管理密鑰。

您必須先將 google_ml_integration.enable_model_support 資料庫旗標設為 on，才能開始使用擴充功能。

詳情請參閱「使用模型端點管理服務搭配 AlloyDB Omni for 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`	內建支援的其他文字嵌入模型端點則為選用	新增其他文字嵌入和通用模型端點時，模型專屬的端點。如果是 AlloyDB for PostgreSQL，請提供 `https` URL。函式為內建模型端點產生的要求網址，是指叢集的專案和區域或位置。如要參照其他專案，請務必明確指定 `model_request_url`。如需 Vertex AI 模型端點的要求網址清單，請參閱「Vertex AI 模型端點要求網址」。如果是自訂代管模型端點，請確認模型端點可從 AlloyDB 所在的網路存取。
`PROVIDER_ID`	內建支援的文字嵌入模型端點必須提供這項資訊	模型端點的供應商。預設值為 `custom`。設為下列其中一個值： `google`，適用於 Vertex AI 模型端點 OpenAI 模型端點的 `open_ai` `hugging_face` 個 Hugging Face 模型端點 `anthropic` 個 Anthropic 模型端點 `custom` 其他供應商
`MODEL_TYPE`	通用模型端點為選用項目	模型類型。設為下列其中一項： `text_embedding` 個文字嵌入模型端點 `generic` (適用於所有其他模型端點)
`MODEL_QUALIFIED_NAME`	內建支援的文字嵌入模型必須提供這項資訊，其他模型端點則為選填	內建支援的文字嵌入模型完整名稱。如要瞭解預先註冊模型必須使用的 Vertex AI 完整名稱，請參閱「預先註冊的 Vertex AI 模型」。如要瞭解內建支援的 OpenAI 模型必須使用的完整名稱，請參閱「內建支援的模型」。
`AUTH_TYPE`	選用，除非模型端點有特定驗證要求	模型端點使用的驗證類型。如果其他供應商使用 Secret Manager 進行驗證，您可以將其設為 `alloydb_service_agent_iam` (適用於 Vertex AI 模型) 或 `secret_manager`。如果使用驗證標頭，則不需要設定這個值。
`AUTH_ID`	請勿為 Vertex AI 模型端點設定；對於在 Secret Manager 中儲存密碼的所有其他模型端點，則必須設定	您設定的密碼 ID，用於註冊模型端點。
`GENERATE_HEADER_FUNCTION`	選用	產生自訂標頭的函式名稱。對於 Anthropic 模型，模型端點管理功能提供 `google_ml.anthropic_claude_header_gen_fn` 函式，可用於預設版本。這個函式的簽章取決於您使用的預測函式。請參閱標題生成函式。
`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。
`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');

如要瞭解必須為每個參數設定的值，請參閱「建立密鑰」。

`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 查詢範例，請參閱 AlloyDB Omni 的轉換函式範例。

`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": ["AlloyDB 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`	用於產生自訂標頭的函式。註冊模型端點時，您也可以傳遞標頭產生函式產生的授權標頭。

標頭產生函式範例

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

下列 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": ["AlloyDB 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;
$$;

使用 API 金鑰產生標頭的函式

以下範例說明如何使用 API 金鑰設定驗證。

嵌入模型

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
BEGIN
  RETURN json_build_object('Authorization', 'API_KEY')::JSON;
END;
$$;

將 API_KEY 替換為模型供應商的 API 金鑰。

通用模型

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  response_json JSON
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
transformed_output REAL[];
BEGIN
  -- code to add Auth token to API request
RETURN json_build_object('x-api-key', 'API_KEY', 'anthropic-version', '2023-06-01')::JSON;
END;
$$;

將 API_KEY 替換為模型供應商的 API 金鑰。

要求產生網址

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

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

支援的模型

您可以使用模型端點管理功能，註冊任何文字嵌入或通用模型端點。模型端點管理也包括預先註冊的 Vertex AI 模型，以及內建支援的模型。如要進一步瞭解不同的模型類型，請參閱「模型類型」。

預先註冊的 Vertex AI 模型

模型類型	模型 ID	擴充功能版本
`generic`	`gemini-1.5-pro:streamGenerateContent` `gemini-1.5-pro:generateContent` `gemini-1.0-pro:generateContent`	1.4.2 以上版本
`text_embedding`	`textembedding-gecko` `text-embedding-gecko@001`	1.3 以上版本

內建支援的模型

Vertex AI

合格模型名稱	模型類型
`text-embedding-gecko@001`	`text-embedding`
`text-embedding-gecko@003`	`text-embedding`
`text-embedding-004`	`text-embedding`
`text-embedding-005`	`text-embedding`
`text-embedding-preview-0815`	`text-embedding`
`text-multilingual-embedding-002`	`text-embedding`

OpenAI

合格模型名稱	模型類型
`text-embedding-ada-002`	`text-embedding`
`text-embedding-3-small`	`text-embedding`
`text-embedding-3-large`	`text-embedding`

Anthropic

合格模型名稱	模型類型
`claude-3-opus-20240229`	`generic`
`claude-3-sonnet-20240229`	`generic`
`claude-3-haiku-20240307`	`generic`

模型端點管理參考資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

模型

google_ml.create_model() 個函式

google_ml.alter_model()

google_ml.drop_model() 個函式

google_ml.list_model() 個函式

google_ml.model_info_view 個檢視表

密鑰

google_ml.create_sm_secret() 個函式

google_ml.alter_sm_secret() 個函式

google_ml.drop_sm_secret() 個函式

預測函式

google_ml.embedding() 個函式

google_ml.predict_row() 個函式

轉換函式

輸入轉換函式

輸出轉換函式

轉換函式範例

輸入轉換函式

輸出轉換函式

HTTP 標頭產生函式

標頭產生函式範例

使用 API 金鑰產生標頭的函式

嵌入模型

通用模型

要求產生網址

支援的模型

預先註冊的 Vertex AI 模型

內建支援的模型

Vertex AI

OpenAI

Anthropic

模型端點管理參考資料

`google_ml.create_model()` 個函式

`google_ml.alter_model()`

`google_ml.drop_model()` 個函式

`google_ml.list_model()` 個函式

`google_ml.model_info_view` 個檢視表

`google_ml.create_sm_secret()` 個函式

`google_ml.alter_sm_secret()` 個函式

`google_ml.drop_sm_secret()` 個函式

`google_ml.embedding()` 個函式

`google_ml.predict_row()` 個函式