Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

整合 Cloud SQL 與 Vertex AI

MySQL | PostgreSQL | SQL Server

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

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

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

您可以使用生成嵌入函式，讓嵌入模型將文字提示詞轉譯為數值向量。接著，您可以將這些向量嵌入做為向量資料類型的輸入內容。詳情請參閱 Microsoft 說明文件，瞭解 SQL 資料庫引擎中的向量搜尋和向量索引。

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

支援的版本和資料庫版本

Cloud SQL Enterprise Plus 版和 Cloud SQL Enterprise 版，以及 SQL Server 2025 的所有資料庫版本，都支援 Vertex AI 整合功能。

支援的模型類型

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

Vertex AI
Hugging Face
OpenAI

事前準備

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.
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
Verify that billing is enabled for your Google Cloud project.
啟用必要的 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。
  注意：如果找不到這些 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

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

gcloud

如要將 Vertex AI 權限新增至 Cloud SQL 執行個體所在專案的 Cloud SQL 服務帳戶，請建立具備最低必要權限的自訂 IAM 角色，然後將該角色授予服務帳戶。

如要建立具有 aiplatform.endpoints.predict 權限的自訂角色，請使用 gcloud iam roles create 指令：

gcloud iam roles create ROLE_NAME \
  --project=PROJECT_ID \
  --title="Cloud SQL Vertex AI Predictor" \
  --description="Allows Cloud SQL to invoke Vertex AI predictions" \
  --permissions="aiplatform.endpoints.predict"

如要將自訂角色授予 Cloud SQL 服務帳戶，請使用 gcloud projects add-iam-policy-binding 指令：

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

請進行下列替換：

ROLE_NAME：要建立的自訂 IAM 角色名稱，例如 CloudSQLMLPredictor。
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 執行個體名稱。

請確認使用嵌入模型的 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
如要使用第三方外部模型，您必須具備有效的模型 API 金鑰，並儲存在 Cloud SQL 執行個體可存取的 Secret Manager 位置。
如果使用第三方外部模型，Cloud SQL 執行個體必須使用公開 IP 位址。私人 IP 執行個體無法存取第三方外部模型。私人服務存取權和 Private Service Connect 僅支援 Vertex AI 整合。

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

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

建立或更新 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

建立執行個體

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

使用任何要求資料之前，請先修改下列項目的值：
- 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" } }
請展開以下其中一個選項，以傳送要求：
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": "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, } }
請展開以下其中一個選項，以傳送要求：
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": "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

建立執行個體

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

使用任何要求資料之前，請先修改下列項目的值：
- 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" } }
請展開以下其中一個選項，以傳送要求：
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": "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, } }
請展開以下其中一個選項，以傳送要求：
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": "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。

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


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 中使用的 Secret 名稱。

外部模型物件

如要從外部來源存取模型，您必須建立模型物件，供 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：模型端點的網址。
範例使用下列格式：
```
    https://region-aiplatform.googleapis.com/v1/projects/project-id/locations/region/publishers/google/models/model:predict
    
```
更改下列內容：
- REGION：模型端點所在的區域。
- PROJECT_ID：模型端點所在的專案 ID。
- MODEL：模型名稱。
MODEL：叫用的 AI 模型。例如：text-embedding-005。
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 中使用的 Secret 名稱。
- VERSION：Secret 的版本號碼。

調整外部模型

如要修改外部模型物件，請執行 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：模型端點的網址。
範例使用下列格式：
```
    https://region-aiplatform.googleapis.com/v1/projects/project-id/locations/region/publishers/google/models/model:predict
    
```
更改下列內容：
- REGION：模型端點所在的區域。
- PROJECT_ID：模型端點所在的專案 ID。
- MODEL：模型名稱。
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 中使用的 Secret 名稱。
- VERSION：Secret 的版本號碼。

停用 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 卸除外部模型，請執行 msdb 資料庫中的 gcloudsql_ml_drop_external_model 預存程序：

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` 程序	「指定的 Secret 網址不適用於這個模型供應商。」	如果是 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` 項電話素材資源	「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`	模型供應商傳回「Exhausted」錯誤。
`500 Internal Server Error`	模型供應商發生不明錯誤。模型供應商傳回非預期的回覆。

後續步驟

使用向量嵌入

整合 Cloud SQL 與 Vertex AI 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

支援的版本和資料庫版本

支援的模型類型

事前準備

控制台

gcloud

gcloud

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

gcloud

建立執行個體

更新執行個體

REST v1

建立執行個體

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

更新執行個體

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

REST v1beta4

建立執行個體

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

更新執行個體

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

新增 Secret Manager 權限

外部模型物件

建立外部模型

調整外部模型

停用 Vertex AI 整合功能

在 SQL Server 中捨棄外部模型

叫用外部模型

模型大小限制

疑難排解

錯誤代碼

後續步驟

整合 Cloud SQL 與 Vertex AI