整合 Cloud SQL 與 Vertex AI

本頁面說明如何整合 Cloud SQL 與 Vertex AI。

透過這項整合功能，您可以將託管於 Vertex AI 的大型語言模型 (LLM)，套用至 SQL Server 適用的 Cloud SQL 2025 資料庫。

整合 Cloud SQL 與 Vertex AI，以便將機器學習 (ML) 模型的語意和預測功能套用至資料。這項整合功能會透過 generate embeddings 函式擴充 SQL 語法，以便查詢模型。

您可以使用 generate embeddings 函式，讓嵌入模型將文字提示轉換為數值向量。然後將這些向量嵌入內容套用為向量資料類型的輸入內容。詳情請參閱 Microsoft 說明文件「SQL Database Engine 中的向量搜尋和向量索引」。

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

支援的版本和資料庫版本

Cloud SQL Enterprise Plus 版和 Cloud SQL Enterprise 版都支援 Vertex AI 整合功能，且所有 SQL Server 2025 資料庫版本也支援這項功能。

支援的模型類型

整合 Vertex AI 與 Cloud SQL 時，支援下列來源的模型端點：

  • Vertex AI
  • Hugging Face
  • OpenAI

事前準備

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. 啟用必要的 Google Cloud API。

    控制台

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

    4. 按一下要啟用的 API。如要執行這項程序，請啟用下列項目：

      • Cloud SQL Admin API
      • Vertex AI API
      • Compute Engine API
      • 選用：如果使用第三方模型，則必須啟用 Secret Manager API。
    5. 選取各個 API 後，按一下「啟用」。

    gcloud

    1. 開啟 Cloud Shell，直接在瀏覽器中使用指令列存取資源。 Google Cloud
    2. 如要啟用必要的 API，請使用 gcloud services enable 指令： 
      gcloud services enable sqladmin.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com \
  secretmanager.googleapis.com
      3. 這個指令會啟用下列 API：
      • Cloud SQL Admin API
      • Vertex AI API
      • Compute Engine API
      • 選用：如果使用第三方模型，則必須使用 Secret Manager API。

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

    8. gcloud

    如要將 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 指令：

      gcloud sql instances describe INSTANCE_NAME | grep EmailAddress

      將 INSTANCE_NAME 改成 Cloud SQL 執行個體的名稱。

  8. 請確認使用嵌入模型時，Cloud SQL 使用者已獲得下列資料庫權限：
    • 如要讓資料庫使用者建立或修改模型，您必須在下列預存程序中，授予 Cloud SQL 使用者 EXECUTE 權限：
      • [msdb].gcloudsql_ml_create_external_model：建立外部模型物件，其中包含 AI 模型推論端點的位置、驗證方法和用途。
      • [msdb].gcloudsql_ml_alter_external_model：可讓您修改外部模型物件。
      • [msdb].gcloudsql_ml_drop_external_model：從資料庫移除外部模型物件。
    • 如要呼叫先前列出的預存程序，您必須具備目標資料庫的下列權限：
      • CREATE EXTERNAL MODEL
      • ALTER EXTERNAL MODEL

      • 如要瞭解如何授予這些權限，請參閱 Microsoft 說明文件，瞭解「建立外部模型」指令和命名方式。

      如要瞭解 Cloud SQL 超級使用者權限，請參閱關於 SQL Server 使用者和預存程序。

  9. 如要使用第三方外部模型，您必須在 Cloud SQL 執行個體可存取的 Secret Manager 位置，儲存該模型的有效 API 金鑰。
  10. 如果使用第三方外部模型，Cloud SQL 執行個體必須使用公開 IP 位址。私人 IP 執行個體無法存取第三方外部模型。私人服務存取權和 Private Service Connect 僅支援 Vertex AI 整合。

啟用資料庫與 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 \
--enable-google-ml-integration

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

    • INSTANCE_NAME：執行個體的名稱。
    • DATABASE_VERSION：執行個體的資料庫版本，例如 SQLSERVER_2025_ENTERPRISE。
    • MACHINE_TYPE：執行個體的機型，例如 db-perf-optimized-N-8.。
    • REGION_NAME：執行個體所在的區域，例如 us-central1。

    更新執行個體

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

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

    REST v1

    建立執行個體

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

    使用任何要求資料之前，請先修改下列項目的值：

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

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

    • enableGoogleMlIntegration：將這個參數設為 true 後，Cloud SQL 執行個體就能連線至 Vertex AI，將即時預測和深入分析要求傳遞給 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"
    
  }
}

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

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

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "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：包含執行個體的 Google Cloud 專案 ID 或專案編號
    • INSTANCE_NAME：執行個體的名稱

    HTTP 方法和網址：

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

    JSON 要求主體：

    {
  "settings": {
    "enableGoogleMlIntegration": true,
    
   }
}

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

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

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "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：包含執行個體的 Google Cloud 專案 ID 或專案編號。
    • INSTANCE_NAME：執行個體的名稱。
    • REGION_NAME：執行個體的區域名稱。
    • DATABASE_VERSION：資料庫版本的列舉字串，例如 SQLSERVER_2025_ENTERPRISE。
    • PASSWORD：資料庫root使用者的密碼。
    • MACHINE_TYPE：機型 (層級) 類型的列舉字串，例如 db-custom-[CPUS]-[MEMORY_MBS]。詳情請參閱「機器層級」。
    • EDITION_TYPE：您的 Cloud SQL 版本，例如 ENTERPRISE。

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

    • enableGoogleMlIntegration：將這個參數設為 true 後，Cloud SQL 執行個體就能連線至 Vertex AI，將即時預測和深入分析要求傳遞給 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"
    
  }
}

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

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

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "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：包含執行個體的 Google Cloud 專案 ID 或專案編號
    • INSTANCE_NAME：執行個體的名稱

    HTTP 方法和網址：

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

    JSON 要求主體：

    {
  "settings": {
    "enableGoogleMlIntegration": true,
    
   }
}

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

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

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "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"
}

新增 Secret Manager 權限

如要使用外部來源 (例如 OpenAI 或 Hugging Face) 的模型，必須將模型來源的 API 金鑰儲存在 Secret Manager 中。

接著，您需要授予 Cloud SQL 執行個體存取權，以便存取 Secret Manager 中的模型來源 API 金鑰。如要取得存取權，請執行下列指令：


SA_NAME=$(gcloud sql instances describe INSTANCE_NAME --format="value(serviceAccountEmailAddress)");

gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member="serviceAccount:${SA_NAME}" \
    --role="roles/secretmanager.secretAccessor"

更改下列內容：

  • INSTANCE_NAME：Cloud SQL 執行個體的名稱。
  • SECRET_NAME：Secret Manager 中使用的密碼名稱。

外部模型物件

如要存取外部來源的模型，您需要建立供 SQL Server 使用的模型物件。Cloud SQL 提供三種預存程序，可讓您建立、變更及捨棄外部模型物件：

  • gcloudsql_ml_create_external_model
  • gcloudsql_ml_alter_external_model
  • gcloudsql_ml_drop_external_model

建立外部模型

如要建立模型，請執行 msdb 資料庫中的預存程序 gcloudsql_ml_create_external_model：

EXECUTE [msdb].[dbo].[gcloudsql_ml_create_external_model]
@db = [DB_NAME],
@model_name = MODEL_NAME,
@model_provider = 'MODEL_PROVIDER',
@model = 'MODEL',
@model_url = MODEL_URL,
@secret_url = SECRET_URL

更改下列內容：

  • DB_NAME：要建立外部模型的目標資料庫。
  • MODEL_NAME：新外部模型的名稱。
  • MODEL_PROVIDER：模型供應商名稱，例如下列其中一個：
    • Vertex AI
    • OpenAI
    • Hugging Face
  • MODEL_URL：模型端點的網址。
  • MODEL：要呼叫的 AI 模型。例如：gemini-embedding-002。
  • SECRET_URL：如果 Vertex AI 是模型供應商，這個參數必須為空白。如果使用外部模型，這個值必須參照 API 金鑰的 Secret Manager 位置。範例網址格式如下： 
        https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION

    更改下列內容：

    • PROJECT_ID：Secret 所在的專案 ID。
    • SECRET_NAME：Secret Manager 中使用的密鑰名稱。
    • VERSION：密鑰的版本號碼。

變更外部模型

如要變更外部模型物件，請執行 msdb 資料庫中的 gcloudsql_ml_alter_external_model 預存程序：

EXECUTE [msdb].[dbo].[gcloudsql_ml_alter_external_model]
@db = [DB_NAME],
@model_name = MODEL_NAME,
@model_provider = 'MODEL_PROVIDER',
@model = 'MODEL',
@model_url = MODEL_URL,
@secret_url = SECRET_URL

更改下列內容：

  • DB_NAME：要修改的模型所在的目標資料庫。
  • MODEL_NAME：現有模型的名稱。
  • MODEL_PROVIDER：模型供應商名稱，例如下列其中一個：
    • Vertex AI
    • OpenAI
    • Hugging Face
  • MODEL_URL：模型端點的網址。
  • MODEL：要呼叫的 AI 模型。例如：gemini-embedding-001。
  • SECRET_URL：如果 Vertex AI 是模型供應商，這個參數必須為空白。如果使用外部模型，這個值必須參照 API 金鑰的 Secret Manager 位置。網址範例的格式如下： 
        https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION

    更改下列內容：

    • PROJECT_ID：Secret 所在的專案 ID。
    • SECRET_NAME：Secret Manager 中使用的密鑰名稱。
    • VERSION：密鑰的版本號碼。

停用 Vertex AI 整合功能

如要停用 Cloud SQL 執行個體的 Vertex AI 整合功能，請執行下列指令：

gcloud sql instances patch [instance-name] --no-enable-google-ml-integration

將 INSTANCE_NAME 改成 Cloud SQL 執行個體的名稱。

在 SQL Server 中捨棄外部模型

如要從 SQL Server 捨棄外部模型，請執行 gcloudsql_ml_drop_external_model 資料庫中的 msdb 預存程序：

EXECUTE [msdb].[dbo].[gcloudsql_ml_drop_external_model]
@db = [DB_NAME],
@model_name = MODEL_NAME

更改下列內容：

  • DB_NAME：要捨棄的外部模型所在的目標資料庫。
  • MODEL_NAME：要捨棄的外部模型名稱。

叫用外部模型

在 Cloud SQL 執行個體上啟用 Vertex AI 整合功能，並為 SQL Server 建立模型物件後，即可叫用 SQL Server AI_GENERATE_EMBEDDINGS 函式，為資料建立向量嵌入。

如要使用外部模型建立向量嵌入，請執行下列指令：

SELECT AI_GENERATE_EMBEDDINGS(N'Test Text' USE MODEL MODEL_NAME)

將 MODEL_NAME 替換為要使用的模型名稱。

執行主體使用者必須已透過適當的角色或授權，獲授予 EXECUTE ON EXTERNAL MODEL 權限。

詳情請參閱 Microsoft 說明文件中的「外部模型授權」。

模型大小限制

部分模型 (例如 gemini-embedding-01) 的預設輸出維度高於 SQL Server 支援的 float32 向量，後者最多可有 1,998 個維度。如有必要，您必須使用float16 (Microsoft 預覽功能) 做為向量基本型別，最多可提供 3,996 個向量維度，或在 AI_GENERATE_EMBEDDINGS 要求中提供 dimensions 參數，以減少維度。

詳情請參閱「向量資料類型支援半精度浮點數」。

如需範例，請參閱下列內容：

DECLARE @params JSON = N'{"dimensions": "DIMENSIONS"}';
SELECT AI_GENERATE_EMBEDDINGS('This article introduces AI concepts.' USE MODEL MODEL_NAME PARAMETERS @params)

更改下列內容：

  • DIMENSIONS：要用於模型的維度，例如 1536。這個值會以字串形式接受。
  • MODEL_NAME：要使用的模型名稱。

疑難排解

你可能收到下列錯誤訊息：

背景資訊 收到錯誤或訊息 可能原因
CREATE/ALTER 程序 「指定的模型供應商無效。」 提供的模型供應商不受支援。
CREATE/ALTER 程序 「指定的密鑰網址不適用於這個模型供應商。」 如果是 Vertex AI，密碼網址必須留空。如果是其他模型供應商，則私密網址不得留空。
CREATE/ALTER/DROP 程序 「指定的模型名稱無效。」 模型名稱為必填欄位。
CREATE/ALTER 程序 「指定的模型網址無效。」 模型網址為必填欄位。
CREATE/ALTER/DROP 程序 「指定的資料庫名稱無效。」 請提供有效的資料庫名稱，這是必填欄位。
AI_GENERATE_EMBEDDINGS 通來電 各種錯誤代碼，包括 400、403、404、405、500。 如果嘗試執行 AI_GENERATE_EMBEDDINGS 函式時發生問題，系統只會傳回錯誤代碼。這是 Microsoft 已知的限制。
AI_GENERATE_EMBEDDINGS 通來電 「The HTTP response does not contain valid JSON.」(HTTP 回應不含有效的 JSON)。 機器學習代理程式傳回要求您重試的錯誤代碼，例如 429 或 500。不過，客戶收到的卻是這則簡訊。這是 Microsoft 已知的限制。

錯誤代碼

AI_GENERATE_EMBEDDINGS 函式只會提供錯誤代碼，不會提供訊息。下表列出部分錯誤代碼的可能原因：

錯誤代碼 可能原因
400 Bad Request
  • 不支援的型號類型。
  • JSON 酬載格式有誤。
  • 模型類型網址無效。
401 Unauthorized 第三方模型缺少有效的 API 金鑰。
403 Forbidden
  • Cloud SQL 執行個體沒有存取 Vertex AI 的適當權限。
  • Cloud SQL 執行個體缺少存取 Secret Manager 的適當權限。
  • API 金鑰未授予指定第三方模型的權限。
  • 專案未啟用 Vertex AI。
404 Not Found
  • 指定的 secret_url 不存在。
  • 指定的 model_url 不存在。
405 Method Not Allowed 提供的方法不是 POST。
413 Request Body Too Large 要求大小超過 1 MB 的上限。
429 Too Many Requests 模型供應商發生錯誤，導致配額用盡。
500 Internal Server Error
  • 模型供應商發生不明錯誤。
  • 模型供應商傳回非預期的回覆。

後續步驟