使用模型端點管理工具註冊及呼叫遠端 AI 模型

預先發布版

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

MySQL   |  PostgreSQL   |  SQL Server

本頁面說明如何使用模型叫用預測或產生嵌入，然後向模型端點管理服務註冊模型端點。

如要進一步瞭解 google_ml.create_model() 函式，請參閱模型端點管理參考資料。

事前準備

• 如果模型端點需要驗證，請啟用 google_ml_integration 擴充功能。

• 根據模型供應商設定驗證。

• 請務必使用postgres預設使用者名稱存取資料庫。

啟用擴充功能

1. 將執行個體的 google_ml_integration.enable_model_support 資料庫標記設為 on。如要進一步瞭解如何設定資料庫標記，請參閱「設定資料庫標記」。

2. 使用 psql 用戶端或 Cloud SQL Studio 連線至主要執行個體。

3. 執行下列指令，確認 google_ml_integration 擴充功能已更新至 1.4.2 版：

       ALTER EXTENSION google_ml_integration UPDATE TO '1.4.2'
   

4. 使用 psql 新增 google_ml_integration 1.4.2 版擴充功能：

     CREATE EXTENSION google_ml_integration VERSION '1.4.2';
   

5. 選用：將管理模型中繼資料的權限授予非超級 PostgreSQL 使用者：

     GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;
   

   將 NON_SUPER_USER 替換為非超級 PostgreSQL 使用者名稱。

設定驗證方法

以下各節說明如何設定驗證，然後新增 Vertex AI 模型端點或 Google Cloud代管的模型端點。

設定 Vertex AI 的驗證

如要使用 Google Vertex AI 模型端點，您必須將 Vertex AI 權限新增至用來連線至資料庫的 IAM 型 Cloud SQL 服務帳戶。如要進一步瞭解如何整合 Vertex AI，請參閱「整合 Cloud SQL 與 Vertex AI」。

為自訂代管模型設定驗證

本節說明如何在使用 Secret Manager 時設定驗證。除了 Vertex AI 模型端點以外，您可以在 Secret Manager 中儲存所有模型的 API 金鑰或不記名權杖。

如果模型端點並非透過 Secret Manager 處理驗證，則這個部分為選填。舉例來說，如果模型端點使用 HTTP 標頭傳遞驗證資訊，或完全不使用驗證，則不需要完成本節中的步驟。

如要建立及使用 API 金鑰或不記名權杖，請完成下列步驟：

1. 在 Secret Manager 中建立密鑰。詳情請參閱「建立密鑰及存取密鑰版本」。

   密碼名稱和密碼路徑會用於 google_ml.create_sm_secret() SQL 函式。

2. 授予 Cloud SQL 執行個體存取密碼的權限。

     gcloud secrets add-iam-policy-binding SECRET_ID \
         --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
         --role="roles/secretmanager.secretAccessor"
   

   更改下列內容：

   • SECRET_ID：Secret Manager 中的密鑰 ID。
   • SERVICE_ACCOUNT_EMAIL：以 IAM 為基礎的 Cloud SQL 服務帳戶電子郵件地址。如要找出這個電子郵件地址，請使用 gcloud sql instances describe INSTANCE_NAME 指令，並將 INSTANCE_NAME 替換為執行個體名稱。serviceAccountEmailAddress 參數旁邊顯示的值就是電子郵件地址。

內建支援的文字嵌入模型

本節說明如何註冊模型端點，以便管理模型端點。

Vertex AI 嵌入模型

模型端點管理功能內建支援所有版本的 text-embedding-gecko 模型 (由 Vertex AI 提供)。使用完整名稱將模型版本設為 textembedding-gecko@001 或 textembedding-gecko@002。

由於 textembedding-gecko 和 textembedding-gecko@001 模型端點 ID 都已預先向模型端點管理服務註冊，因此您可以直接使用其中一個做為模型 ID。對於這些模型，擴充功能會自動設定預設轉換函式。

請確認 Cloud SQL 執行個體和您查詢的 Vertex AI 模型位於相同區域。

如要註冊 textembedding-gecko@002 模型端點，請呼叫 create_model 函式：

  CALL
    google_ml.create_model(
      model_id => 'textembedding-gecko@002',
      model_provider => 'google',
      model_qualified_name => 'textembedding-gecko@002',
      model_type => 'text_embedding',
      model_auth_type => 'cloudsql_service_agent_iam');

自訂代管文字嵌入模型

本節說明如何註冊 Google Cloud網路中代管的自訂模型端點。

如要新增自訂代管的文字嵌入模型端點，請建立轉換函式，並視需要建立自訂 HTTP 標頭。另一方面，新增自訂代管的通用模型端點時，可選擇產生自訂 HTTP 標頭，並設定模型要求網址。

以下範例會新增 Cymbal 代管的 custom-embedding-model 文字嵌入模型端點，該端點代管於 Google Cloud內。cymbal_text_input_transform 和 cymbal_text_output_transform 轉換函式可用來將模型的輸入和輸出格式，轉換為預測函式的輸入和輸出格式。

如要註冊自訂主機代管的文字嵌入模型端點，請完成下列步驟：

1. 呼叫儲存在 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，後續註冊模型端點時會使用這個 ID，例如 key1。
   • SECRET_MANAGER_SECRET_ID：您建立密鑰時在 Secret Manager 中設定的密鑰 ID。
   • PROJECT_ID：您的 Google Cloud 專案 ID。
   • VERSION_NUMBER：密鑰 ID 的版本號碼。
   注意： Secret Manager 預設會產生 Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER 標頭以進行驗證。如果這個格式與模型端點的授權不記名權杖格式相符，您就不必使用標頭產生函式產生授權標頭。

2. 根據文字嵌入模型端點的預測函式，建立輸入和輸出轉換函式。如要進一步瞭解如何建立轉換函式，請參閱轉換函式範例。

   以下是專為 custom-embedding-model 文字嵌入模型端點設計的轉換函式範例：

   -- Input Transform Function corresponding to the custom model endpoint
   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;
   $$;
   -- Output Transform Function corresponding to the custom model endpoint
   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;
   $$;
   

3. 呼叫建立模型函式，註冊自訂嵌入模型端點：

   CALL
     google_ml.create_model(
       model_id => 'MODEL_ID',
       model_request_url => 'REQUEST_URL',
       model_provider => 'custom',
       model_type => 'text_embedding',
       model_auth_type => 'secret_manager',
       model_auth_id => 'SECRET_ID',
       model_qualified_name => 'MODEL_QUALIFIED_NAME',
       model_in_transform_fn => 'cymbal_text_input_transform',
       model_out_transform_fn => 'cymbal_text_output_transform');
   

   更改下列內容：

   • MODEL_ID：必要。您定義的模型端點專屬 ID (例如 custom-embedding-model)。模型端點需要參照這個模型 ID，才能產生嵌入或叫用預測。
   • REQUEST_URL：必要。新增自訂文字嵌入和一般模型端點時，模型專屬的端點 (例如 https://cymbal.com/models/text/embeddings/v1)。確認可透過內部 IP 位址存取模型端點。模型端點管理服務不支援外部 IP 位址。
   • MODEL_QUALIFIED_NAME：如果模型端點使用限定名稱，則為必要欄位。如果模型端點有多個版本，則為完整名稱。
   • SECRET_ID：您在先前的google_ml.create_sm_secret()程序中使用的密鑰 ID。

通用模型

本節說明如何從 Vertex AI Model Garden 註冊不支援內建功能的通用 gemini-pro 模型端點。您可以註冊在 Google Cloud內代管的任何通用模型端點。

Cloud SQL 僅支援透過 Vertex AI Model Garden 提供的模型端點，以及 Google Cloud網路中託管的模型端點。

Gemini 模型

以下範例會從 Vertex AI Model Garden 新增 gemini-1.0-pro 模型端點。

如要註冊 gemini-1.0-pro 模型端點，請呼叫 create model 函式：

```sql
CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-1.0-pro:streamGenerateContent',
    model_provider => 'google',
    model_auth_type => 'cloudsql_service_agent_iam');
```

Replace the following:
* <code><var>MODEL_ID</var></code>: a unique ID for the model endpoint that you define (for example,<br> `gemini-1`). This model ID is referenced for metadata that the model endpoint needs to generate embeddings or invoke predictions.
* <code><var>PROJECT_ID</var></code>: the ID of your Google Cloud project.

詳情請參閱如何叫用一般模型端點的預測結果。

後續步驟

• 瞭解模型端點管理參考資料。