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

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

MySQL | PostgreSQL | SQL Server

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

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

事前準備

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

使用 mysql 用戶端或 Cloud SQL Studio 連線至主要執行個體。
請務必以 MySQL 資料庫使用者身分連線至資料庫，並具備「必要資料庫使用者權限」一文所述的資料庫權限。

設定驗證方法

以下各節說明如何設定驗證，然後新增 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 金鑰或不記名權杖，請完成下列步驟：

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

密碼名稱和密碼路徑會用於 mysql.ml_create_sm_secret_registration() SQL 函式。
授予 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、text-embedding 和 gemini-embedding 模型，使用完整名稱將模型版本設為 textembedding-gecko@001 或 textembedding-gecko@002。

由於模型端點管理功能預設支援 Vertex AI 嵌入模型端點 ID，因此您可以直接將任何 ID 做為模型 ID 使用。對於這些模型，嵌入函式會自動執行輸入和輸出轉換。

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

如要註冊 gemini-embedding-001 模型端點，請呼叫 ml_create_model_registration 函式：

  CALL
    mysql.ml_create_model_registration(
      'gemini-embedding-001',
      'publishers/google/models/gemini-embedding-001',
      'google','text_embedding', 'gemini-embedding-001',
      'AUTH_TYPE_CLOUDSQL_SERVICE_AGENT_IAM',
       NULL,
      'mysql.cloudsql_ml_text_embedding_input_transform',
      'mysql.cloudsql_ml_text_embedding_output_transform', NULL);

自訂代管文字嵌入模型

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

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

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

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

呼叫儲存在 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，後續註冊模型端點時會使用這個 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 標頭以進行驗證。如果這個格式與模型端點的授權不記名權杖格式相符，您就不必使用標頭產生函式產生授權標頭。

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

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

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

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

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

   CALL
      mysql.ml_create_model_registration(
        'MODEL_ID',
        'REQUEST_URL',
        'custom',
        'text_embedding',
        'MODEL_QUALIFIED_NAME',
        'auth_type_secret_manager',
        'SECRET_ID'
        'database_name.cymbal_text_input_transform',
        'database_name.cymbal_text_output_transform', NULL);

更改下列內容：

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

通用模型

本節說明如何從 Vertex AI Model Garden 註冊一般gemini-flash模型端點，該端點預設已在目錄中註冊。您可以註冊在 Google Cloud內代管的任何通用模型端點。

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

Gemini 模型

下列範例使用 Vertex AI Model Garden 中的 gemini-2.5-flash 模型端點。

如要註冊 gemini-2.5-flash 模型端點，請呼叫 mysql.ml_create_model_registration 函式：

    CALL
      mysql.ml_create_model_registration(
        'MODEL_ID',
        'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.5-flash:streamGenerateContent',
        'google',
        'auth_type_cloudsql_service_agent_iam',
        NULL, NULL, NULL, NULL);