整合 Cloud SQL 與 Vertex AI

MySQL  |  PostgreSQL  |  SQL Server

預先發布版 — Cloud SQL for MySQL integration with Vertex AI

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 您可以按《Cloud 資料處理附加條款》規定的方式，處理這項功能會用到的個人資料，但須遵守您使用 Google Cloud 所簽訂協議中的義務與限制。 正式發布前的功能是依「原樣」提供，支援服務可能受限。 詳情請參閱「推出階段說明」。

本頁說明如何整合 Cloud SQL 與 Vertex AI。這項整合功能可讓您將 Vertex AI 中託管的大型語言模型 (LLM)，套用至 MySQL 適用的 Cloud SQL 資料庫 (8.0.36 以上版本)。

整合 Cloud SQL 與 Vertex AI，即可將機器學習 (ML) 模型的語意和預測功能套用至資料。這項整合作業會擴充 SQL 語法，提供兩個查詢模型的函式：

• 叫用預測：在交易中透過 SQL 呼叫模型。
• 生成嵌入項目：讓嵌入模型將文字提示轉換為數值向量。然後將這些向量嵌入項目做為 vector 函式的輸入內容。包括根據相對語意距離比較及排序文字樣本的方法。

因此，您可以在資料庫中直接進行即時預測並取得寶貴的洞察資訊，簡化工作流程並提升決策能力。

如要進一步瞭解 Vertex AI，請參閱「Vertex AI 簡介」。

事前準備

注意： 專案名稱長度必須介於 4 至 30 個字元之間。輸入名稱時，表單會建議專案 ID，您可以編輯。專案 ID 長度必須介於 6 到 30 個字元之間，第一個字元須為小寫英文字母，其餘字元可以是破折號、小寫英文字母或數字，但最後一個字元不得為破折號。

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

1. 啟用必要的 Google Cloud API。

   控制台

   1. 前往「APIs & Services」(API 和服務) 頁面。
   2. 從專案清單中選取您的專案。
   3. 如果「API 程式庫」尚未開啟，請從導覽選單選取「程式庫」。

   4. 按一下要啟用的 API。如要執行這項程序，請啟用 Cloud SQL Admin API 和 Vertex AI API。

      注意：如需尋找這些 API 的協助，請使用搜尋欄位。

   5. 選取各個 API 後，按一下「啟用」。

   gcloud

   1. 開啟 Cloud Shell，直接在瀏覽器中使用指令列存取資源。 Google Cloud
   2. 如要啟用必要的 API，請使用 gcloud services enable 指令：

      gcloud services enable sqladmin.googleapis.com \
      enable aiplatform.googleapis.com

   這個指令會啟用下列 API：
   • Cloud SQL Admin API
   • Vertex AI API

2. 授予 Cloud SQL 服務帳戶 Identity and Access Management (IAM) 權限，以便存取 Vertex AI。

   gcloud

   注意：如果您要建立已啟用 Vertex AI 的執行個體，請先建立執行個體，再完成這個步驟。

   如要將 Vertex AI 權限新增至 Cloud SQL 執行個體所在專案的 Cloud SQL 服務帳戶，請使用 gcloud projects add-iam-policy-binding 指令：

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
     --role="roles/aiplatform.user"

   進行下列替換：

   • PROJECT_ID：具有 Vertex AI 端點的專案 ID。Cloud SQL 會使用這個端點存取 Vertex AI 中託管的 LLM。

   • SERVICE_ACCOUNT_EMAIL：Cloud SQL 服務帳戶的電子郵件地址。

     如要找出這個電子郵件地址，請使用 gcloud sql instances describe INSTANCE_NAME 指令，並將 INSTANCE_NAME 替換為 Cloud SQL 執行個體的名稱。serviceAccountEmailAddress 參數旁邊顯示的值就是電子郵件地址。

   注意：一般而言，政策變更會在 2 分鐘內生效。 然而在某些情況下，這類變更可能需要長達 7 分鐘的時間，才能完全傳達至整個系統中。詳情請參閱「存取權變更傳播」。

啟用資料庫與 Vertex AI 的整合功能

如要啟用資料庫與 Vertex AI 的整合功能，請完成下列步驟：

1. 建立或更新 Cloud SQL 執行個體，以便與 Vertex AI 整合。

   gcloud

   建立執行個體

   如要建立 Cloud SQL 執行個體，請使用 gcloud sql instances create 指令。

   gcloud sql instances create INSTANCE_NAME \
   --database-version=DATABASE_VERSION \
   --tier=MACHINE_TYPE \
   --region=REGION_NAME \
   --edition=EDITION_NAME \
   --enable-google-ml-integration

   請將下列項目改為對應的值：

   • INSTANCE_NAME：執行個體名稱
   • DATABASE_VERSION：例項的資料庫版本
   • MACHINE_TYPE：執行個體的機器類型
   • REGION_NAME：執行個體的區域名稱
   • EDITION_NAME：執行個體的 Cloud SQL 版本

   注意： 如要進一步瞭解這些參數，請參閱「建立執行個體」。

   更新執行個體

   如要更新執行個體，請使用 gcloud sql instances patch 指令。

   gcloud sql instances patch INSTANCE_NAME \
   --enable-google-ml-integration \

   如果這項更新會修改需要重新啟動的值，系統會顯示提示，要求您繼續變更或取消。

   注意： 如要進一步瞭解如何更新執行個體，請參閱「編輯執行個體」一文。

   REST v1

   建立執行個體

   請使用這個範例建立執行個體。如需此呼叫的完整參數清單，請參閱「執行個體：插入」頁面。如要瞭解執行個體設定，包括有效區域值，請參閱執行個體設定。

   使用任何要求資料之前，請先替換以下項目：

   • PROJECT_ID：包含執行個體的專案 ID 或專案編號 Google Cloud
   • INSTANCE_NAME：執行個體名稱
   • REGION_NAME：執行個體的區域名稱
   • DATABASE_VERSION：資料庫版本的列舉字串 (例如：POSTGRES_13)
   • PASSWORD：root 使用者的密碼
   • MACHINE_TYPE：機器 (層級) 類型的列舉字串，如下所示： db-custom-[CPUS]-[MEMORY_MBS]
   • EDITION_TYPE：您的 Cloud SQL 版本

   注意： 如要進一步瞭解這些參數，請參閱「建立執行個體」。

   此外，您也必須在要求中加入 enableGoogleMlIntegration 物件。視需要設定下列參數：

   • enableGoogleMlIntegration：將這個參數設為 true 後，Cloud SQL 執行個體就能連線至 Vertex AI，將即時預測和深入分析要求傳遞給 AI
   • cloudsql.enable_google_ml_integration：將這個參數設為 on 時，Cloud SQL 就能與 Vertex AI 整合

   HTTP 方法和網址：

   POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

   JSON 要求主體：

   {
     "name": "INSTANCE_NAME",
     "region": "REGION_NAME",
     "databaseVersion": "DATABASE_VERSION",
     "rootPassword": "PASSWORD",
     "settings": {
       "tier": "MACHINE_TYPE",
       "edition": "EDITION_TYPE",
       "enableGoogleMlIntegration": "true" | "false"
       "databaseFlags":
         {
           "name": "cloudsql.enable_google_ml_integration",
           "value": "on" | "off"
         }
     }
   }
   

   如要傳送要求，請展開以下其中一個選項：

   curl (Linux、macOS 或 Cloud Shell)

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances"

   PowerShell (Windows)

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances" | Select-Object -Expand Content

   您應該會收到如下的 JSON 回應：

   {
     "kind": "sql#operation",
     "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
     "status": "PENDING",
     "user": "[e-mail]",
     "insertTime": "2019-09-25T22:19:33.735Z",
     "operationType": "CREATE",
     "name": "OPERATION_ID",
     "targetId": "INSTANCE_ID",
     "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
     "targetProject": "PROJECT_ID"
   }
   

   更新執行個體

   請使用這個範例更新執行個體。如需這項呼叫的完整參數清單，請參閱 instances.patch 頁面。

   如果這項更新會修改需要重新啟動的值，系統會提示您繼續變更或取消。

   使用任何要求資料之前，請先替換以下項目：

   • PROJECT_ID：包含執行個體的專案 ID 或專案編號 Google Cloud
   • INSTANCE_NAME：執行個體名稱

   HTTP 方法和網址：

   PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

   JSON 要求主體：

   {
     "settings": {
       "enableGoogleMlIntegration": true,
       "databaseFlags":
         {
           "name": "cloudsql.enable_google_ml_integration",
           "value": "on"
         }
      }
   }

   如要傳送要求，請展開以下其中一個選項：

   curl (Linux、macOS 或 Cloud Shell)

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   curl -X PATCH \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell (Windows)

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method PATCH `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   您應該會收到如下的 JSON 回應：

   {
     "kind": "sql#operation",
     "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
     "status": "PENDING",
     "user": "[e-mail]",
     "insertTime": "2020-01-16T02:32:12.281Z",
     "operationType": "UPDATE",
     "name": "OPERATION_ID",
     "targetId": "INSTANCE_NAME",
     "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
     "targetProject": "PROJECT_ID"
   }
   

   注意： 如要進一步瞭解如何更新執行個體，請參閱「編輯執行個體」。

   REST v1beta4

   建立執行個體

   請使用這個範例建立執行個體。如需此呼叫的完整參數清單，請參閱「執行個體：插入」頁面。如要瞭解執行個體設定，包括有效區域值，請參閱執行個體設定。

   使用任何要求資料之前，請先替換以下項目：

   • PROJECT_ID：包含執行個體的專案 ID 或專案編號 Google Cloud
   • INSTANCE_NAME：執行個體名稱
   • REGION_NAME：執行個體的區域名稱
   • DATABASE_VERSION：資料庫版本的列舉字串 (例如：POSTGRES_13)
   • PASSWORD：root 使用者的密碼
   • MACHINE_TYPE：機器 (層級) 類型的列舉字串，如下所示： db-custom-[CPUS]-[MEMORY_MBS]
   • EDITION_TYPE：您的 Cloud SQL 版本

   注意： 如要進一步瞭解這些參數，請參閱「建立執行個體」。

   此外，您也必須在要求中加入 enableGoogleMlIntegration 物件。視需要設定下列參數：

   • enableGoogleMlIntegration：將這個參數設為 true 後，Cloud SQL 執行個體就能連線至 Vertex AI，將即時預測和深入分析要求傳遞給 AI
   • cloudsql.enable_google_ml_integration：將這個參數設為 on 時，Cloud SQL 就能與 Vertex AI 整合

   HTTP 方法和網址：

   POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances

   JSON 要求主體：

   {
     "name": "INSTANCE_NAME",
     "region": "REGION_NAME",
     "databaseVersion": "DATABASE_VERSION",
     "rootPassword": "PASSWORD",
     "settings": {
       "tier": "MACHINE_TYPE",
       "edition": "EDITION_TYPE",
       "enableGoogleMlIntegration": "true" | "false"
       "databaseFlags":
         {
           "name": "cloudsql.enable_google_ml_integration",
           "value": "on" | "off"
         }
     }
   }
   

   如要傳送要求，請展開以下其中一個選項：

   curl (Linux、macOS 或 Cloud Shell)

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances"

   PowerShell (Windows)

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances" | Select-Object -Expand Content

   您應該會收到如下的 JSON 回應：

   {
     "kind": "sql#operation",
     "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
     "status": "PENDING",
     "user": "[e-mail]",
     "insertTime": "2019-09-25T22:19:33.735Z",
     "operationType": "CREATE",
     "name": "OPERATION_ID",
     "targetId": "INSTANCE_ID",
     "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
     "targetProject": "PROJECT_ID"
   }
   

   更新執行個體

   請使用這個範例更新執行個體。如需這項呼叫的完整參數清單，請參閱 instances.patch 頁面。

   如果這項更新會修改需要重新啟動的值，系統會提示您繼續變更或取消。

   使用任何要求資料之前，請先替換以下項目：

   • PROJECT_ID：包含執行個體的專案 ID 或專案編號 Google Cloud
   • INSTANCE_NAME：執行個體名稱

   HTTP 方法和網址：

   PATCH https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

   JSON 要求主體：

   {
     "settings": {
       "enableGoogleMlIntegration": true,
       "databaseFlags":
         {
           "name": "cloudsql.enable_google_ml_integration",
           "value": "on"
         }
      }
   }

   如要傳送要求，請展開以下其中一個選項：

   curl (Linux、macOS 或 Cloud Shell)

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   curl -X PATCH \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell (Windows)

   注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method PATCH `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   您應該會收到如下的 JSON 回應：

   {
     "kind": "sql#operation",
     "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
     "status": "PENDING",
     "user": "[e-mail]",
     "insertTime": "2020-01-16T02:32:12.281Z",
     "operationType": "UPDATE",
     "name": "OPERATION_ID",
     "targetId": "INSTANCE_NAME",
     "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
     "targetProject": "PROJECT_ID"
   }
   

   注意： 如要進一步瞭解如何更新執行個體，請參閱「編輯執行個體」。

疑難排解

本節提供有關整合 Cloud SQL 與 Vertex AI 時發生的問題，以及排解問題的步驟。

問題	疑難排解
錯誤訊息：Google ML integration API is supported only on MySQL version 8.0.36 or above.	如要在 Cloud SQL 中啟用 Vertex AI 整合功能，您必須擁有 MySQL 適用的 Cloud SQL 資料庫，且版本為 8.0.36 以上。如要將資料庫升級至這個版本，請參閱「升級資料庫次要版本」。
錯誤訊息：Google ML Integration API is not supported on shared core instance. Please upsize your machine type.	如果您為執行個體的機器類型選取共用核心，就無法在 Cloud SQL 中啟用 Vertex AI 整合功能。將機器類型升級為專用核心。詳情請參閱「機器類型」。
錯誤訊息：Google ML Integration is unsupported for this maintenance version. Please follow https://cloud.google.com/sql/docs/mysql/self-service-maintenance to update the maintenance version of the instance.	如要在 Cloud SQL 中啟用 Vertex AI 整合功能，執行個體的維護版本必須為 R20240130 以上。如要將執行個體升級至這個版本，請參閱自助式維護。
錯誤訊息：Cannot invoke ml_predict_row if 'cloudsql.enable_google_ml_integration' is off.	cloudsql.enable_google_ml_integration 資料庫旗標已關閉。Cloud SQL 無法與 Vertex AI 整合。 如要開啟這個旗標，請使用 gcloud sql instances patch 指令： gcloud sql instances patch INSTANCE_NAME --database-flags cloudsql.enable_google_ml_integration=on 將 INSTANCE_NAME 替換為主要 Cloud SQL 執行個體的名稱。
錯誤訊息：Failed to connect to remote host: Connection refused.	Cloud SQL 與 Vertex AI 之間的整合功能未啟用。如要啟用這項整合功能，請使用 gcloud sql instances patch 指令： gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration 將 INSTANCE_NAME 替換為主要 Cloud SQL 執行個體的名稱。
錯誤訊息：Vertex AI API has not been used in project PROJECT_ID before or it is disabled. Enable it by visiting /apis/api/aiplatform.googleapis.com/overview?project=PROJECT_ID then retry.	Vertex AI API 未啟用。如要進一步瞭解如何啟用這項 API，請參閱「啟用資料庫與 Vertex AI 的整合功能」。
錯誤訊息：Permission 'aiplatform.endpoints.predict' denied on resource.	系統未將 Vertex AI 權限新增至 Cloud SQL 執行個體所在專案的 Cloud SQL 服務帳戶。如要進一步瞭解如何將這些權限新增至服務帳戶，請參閱「啟用資料庫與 Vertex AI 的整合」。
錯誤訊息：Publisher Model `projects/PROJECT_ID/locations/REGION_NAME/publishers/google/models/MODEL_NAME` not found.	機器學習模型或 LLM 不存在於 Vertex AI。
錯誤訊息：Resource exhausted: grpc: received message larger than max.	Cloud SQL 傳遞至 Vertex AI 的要求大小超過 gRPC 的要求上限 (每個要求 4 MB)。
錯誤訊息：Cloud SQL attempts to send a request to Vertex AI. However, the instance is in the %s region, but the Vertex AI endpoint is in the %s region. Make sure the instance and endpoint are in the same region.	Cloud SQL 會嘗試向 Vertex AI 傳送要求。不過，執行個體位於某個地區，但 Vertex AI 端點位於不同地區。如要解決這個問題，執行個體和端點必須位於相同區域。
錯誤訊息：The Vertex AI endpoint isn't formatted properly.	Vertex AI 端點格式不正確。詳情請參閱「使用私人端點進行線上預測」。
錯誤訊息：Quota exceeded for aiplatform.googleapis.com/online_prediction_requests_per_base_model with base model: textembedding-gecko.	Cloud SQL 傳送至 Vertex AI 的要求數超出限制，也就是每個專案的每個模型在每個地區每分鐘最多可傳送 1,500 個要求。

後續步驟

• 使用 LangChain 建構採用 LLM 的應用程式

• 向量嵌入使用訣竅

• 從 Cloud SQL 執行個體叫用線上預測

• 瞭解嵌入工作流程範例

• 使用 LangChain 建構採用 LLM 的應用程式