自 2025 年 4 月 29 日起，Gemini 1.5 Pro 和 Gemini 1.5 Flash 模型將無法用於先前未使用這些模型的專案，包括新專案。詳情請參閱「模型版本和生命週期」。

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

搭配 Vertex AI RAG 引擎使用 RagManagedDb

本頁面說明 Vertex AI RAG Engine 如何使用 RagManagedDb，這是一種企業級向量資料庫，用於儲存及管理文件的向量表示法。然後根據文件與指定查詢的語意相似度，使用向量資料庫擷取相關文件。

此外，本頁面也會說明如何實作 CMEK。

管理擷取策略

RagManagedDb 提供下列擷取策略，支援 RAG 用途：

擷取策略	說明
k-Nearest Neighbors (KNN) (預設)	比較 RAG 語料庫中的所有資料點，找出最鄰近的項目。如果您在建立 RAG 語料庫時未指定策略，系統會預設使用 KNN 擷取策略。	在擷取期間驗證完美召回 (1.0)。非常適合需要高召回率的應用程式。非常適合中小型 RAG 語料庫，最多可儲存 10,000 個 RAG 檔案。需要搜尋每個資料點，因此延遲時間會隨著語料庫中的 RAG 檔案數量增加而變長。
最鄰近搜尋 (ANN)	使用近似技術，比 KNN 技術更快找到類似鄰點。	大幅縮短大型 RAG 語料庫的查詢延遲時間。由於採用近似技術，召回率略有下降。如果 RAG 語料庫很大 (大約超過 10,000 個 RAG 檔案)，這項功能就非常實用。可接受的喚回度損失量取決於使用案例，但在大多數大規模案例中，為了提升查詢效能而損失少許喚回度，是可接受的取捨。

使用 KNN `RagManagedDb` 建立 RAG 語料庫

這份程式碼範例說明如何使用 KNN RagManagedDb 建立 RAG 語料庫。

Python

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

vector_db = rag.RagManagedDb(retrieval_strategy=rag.KNN())
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

REST

請替換下列變數：

PROJECT_ID：您的專案 ID。
LOCATION：處理要求的區域。
CORPUS_DISPLAY_NAME：RAG 語料庫的顯示名稱。

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora \
-d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "vector_db_config": {
        "ragManagedDb": {
          "knn": {}
        }
      }
    }'

使用 ANN `RagManagedDb` 建立 RAG 語料庫

為提供 ANN 功能，RagManagedDb 會使用樹狀結構分割資料，加快搜尋速度。為獲得最佳的召回率和延遲時間，應透過實驗設定這個樹狀結構，以符合資料大小和分布情形。RagManagedDb 可讓您設定樹狀結構的 tree_depth 和 leaf_count。

tree_depth 可決定樹狀結構中的層數或層級數。請遵守下列規範：

如果 RAG 語料庫中約有 10,000 個 RAG 檔案，請將值設為 2。
如果 RAG 檔案超過這個數量，請將此值設為 3。
如未指定 tree_depth，Vertex AI RAG 引擎會為這個參數指派預設值 2。

leaf_count 會決定樹狀結構中的葉節點數量。每個葉節點都包含一組密切相關的向量，以及對應的質心。請遵守下列規範：

建議值為 10 * sqrt(num of RAG files in your RAG corpus)。
如未指定，Vertex AI RAG 引擎會為這個參數指派 500 的預設值。

Python

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
TREE_DEPTH = YOUR_TREE_DEPTH # Optional: Acceptable values are 2 or 3. Default is 2.
LEAF_COUNT = YOUR_LEAF_COUNT # Optional: Default is 500.

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

ann_config = rag.ANN(tree_depth=TREE_DEPTH, leaf_count=LEAF_COUNT)
vector_db = rag.RagManagedDb(retrieval_strategy=ann_config)
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

REST

請替換下列變數：

PROJECT_ID：您的專案 ID。
LOCATION：處理要求的區域。
CORPUS_DISPLAY_NAME：RAG 語料庫的顯示名稱。
TREE_DEPTH：樹狀結構深度。
LEAF_COUNT：你的節能綠葉數量。

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME
TREE_DEPTH=TREE_DEPTH
LEAF_COUNT=LEAF_COUNT

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora \
-d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "vector_db_config": {
        "ragManagedDb": {
          "ann": {
            "tree_depth": '"${TREE_DEPTH}"',
            "leaf_count": '"${LEAF_COUNT}"'
          }
        }
      }
    }'

將資料匯入 ANN `RagManagedDb`

您可以使用 ImportRagFiles API 或 UploadRagFile API，將資料匯入 ANN RagManagedDb。不過，與 KNN 擷取策略不同，ANN 方法需要重建至少一次基礎樹狀結構索引，並視需要於匯入大量資料後重建，才能達到最佳擷取率。如要讓 Vertex AI RAG 引擎重建 ANN 索引，請在 ImportRagFiles API 要求中將 rebuild_ann_index 設為 true。

請注意下列事項：

查詢 RAG 語料庫前，您必須重建 ANN 索引至少一次。
每個位置的專案只能同時重建一個索引。

如要將本機檔案上傳至 RAG 語料庫，請參閱「上傳 RAG 檔案」。如要將資料匯入 RAG 語料庫並觸發 ANN 索引重建，請參閱下列程式碼範例，瞭解如何從 Cloud Storage 匯入資料。如要瞭解支援的資料來源，請參閱「支援 RAG 的資料來源」。

Python

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
CORPUS_ID = YOUR_CORPUS_ID
PATHS = ["gs://my_bucket/my_files_dir"]
REBUILD_ANN_INDEX = REBUILD_ANN_INDEX # Choose true or false.

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

corpus_name = f"projects/{PROJECT_ID}/locations/{LOCATION}/ragCorpora/{CORPUS_ID}"
# This is a non blocking call.
response = await rag.import_files_async(
    corpus_name=corpus_name,
    paths=PATHS,
    rebuild_ann_index=REBUILD_ANN_INDEX
)

# Wait for the import to complete.
await response.result()

REST

GCS_URI=GCS_URI
REBUILD_ANN_INDEX=<true/false>

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URI}"\"',
      },
    "rebuild_ann_index": '${REBUILD_ANN_INDEX}'
  }
}'

管理加密

Vertex AI RAG 引擎提供多種選項，可管理靜態資料的加密方式。根據預設，RagManagedDb 中的所有使用者資料都會使用 Google-owned and Google-managed encryption key加密，這是預設設定。這項預設設定可協助您確認資料安全無虞，不必進行任何特定設定。

如果您需要進一步控管用於加密的金鑰，Vertex AI RAG 引擎支援客戶管理的加密金鑰 (CMEK)。使用 CMEK 時，您可以透過 Cloud Key Management Service (KMS) 管理加密金鑰，保護 RAG 語料庫資料。

如要瞭解 RAG 語料庫的 CMEK 限制，請參閱 Vertex AI RAG 引擎的 CMEK 限制。

設定 KMS 金鑰並授予權限

如要建立以 CMEK 加密的 RAG 語料庫，請先在 Google Cloud KMS 中設定加密金鑰，並授予 Vertex AI RAG Engine 服務帳戶使用該金鑰的必要權限。

必要條件

如要執行下列設定步驟，請確認您的使用者帳戶在 Google Cloud 專案中具備適當的身分與存取權管理 (IAM) 權限，您打算在該專案中建立 KMS 金鑰和 RAG 語料庫。通常需要 Cloud KMS 管理員角色 (roles/cloudkms.admin) 等角色。

啟用 API

如要啟用 Cloud KMS API，請按照下列步驟操作：

前往 Google Cloud 控制台。
選取要管理金鑰的專案，然後建立 RAG 語料庫。
在搜尋列中輸入「金鑰管理」，然後選取「金鑰管理」服務。
如果 API 尚未啟用，請按一下「啟用」。API 可能需要幾分鐘才能完成佈建。

建立 KMS 金鑰環和金鑰

如要建立金鑰環，請按照下列步驟操作：

在「金鑰管理」部分，按一下「建立金鑰環」。

輸入下列指令：
- 金鑰環名稱：輸入金鑰環的專屬名稱，例如 rag-engine-cmek-keys。
- 位置類型：選取「區域」。使用 CMEK 加密 RAG 語料庫時，Cloud Key Management Service 金鑰環必須與您使用的 Vertex AI RAG 引擎端點位於相同區域。
- 位置：選擇所選區域，例如 us-central1。這個區域最好與 RAG Engine 資源所在的區域相符。
點選「建立」。

如要在金鑰環中建立金鑰，請執行下列操作：

建立金鑰環後，系統會提示您建立金鑰，您也可以前往「建立金鑰」。

輸入下列指令：
- 金鑰名稱：輸入金鑰的專屬名稱，例如 my-rag-corpus-key。
- 防護等級：選擇防護等級 (「軟體」或「HSM」)。如需硬體支援的金鑰，請選取「HSM」HSM。
- 用途：選取「對稱式加密/解密」。這是 CMEK 的必要資訊。
- 金鑰內容來源：選取「產生的金鑰」。
- 輪替週期：選用。(建議使用) 根據貴機構的安全政策 (例如每 90 天一次)，設定金鑰輪替排程。
點選「建立」。

如要複製金鑰資源名稱，請按照下列步驟操作：

建立金鑰後，請前往金鑰詳細資料頁面。
找出資源名稱。格式為 projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME/cryptoKeyVersions/1。

重要事項： 在 RAG 語料庫中，您必須使用不含版本號碼的資源名稱做為 EncryptionSpec 的鍵。
複製資源名稱，並移除 /cryptoKeyVersions/VERSION_NUMBER 部分。格式正確的資源名稱為 projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME。

授予 Vertex AI RAG 引擎服務代理權限

如要讓 Vertex AI RAG 引擎使用 KMS 金鑰加密及解密資料，服務代理程式必須具備該特定金鑰的適當權限。

如要找出 Vertex AI RAG 引擎服務代理，請執行下列操作：

在專案的 Google Cloud 控制台中，前往「IAM 與管理」>「IAM」頁面。
在「身分與存取權管理」頁面中，勾選「包含 Google 提供的角色授予項目」核取方塊。
在主體清單的篩選或搜尋列中，搜尋 Vertex AI RAG Engine 服務代理程式。格式為 service-YOUR_PROJECT_NUMBER@gcp-sa-vertex-rag.iam.gserviceaccount.com。

將 YOUR_PROJECT_NUMBER 替換為您的 Google Cloud 專案編號。

如果 Vertex AI RAG 引擎服務代理程式尚未存在，請按照下列步驟觸發服務代理程式建立作業：

啟用 Resource Manager API。

在 Cloud Shell 或指令列中執行下列指令：

gcloud beta services identity create --service=aiplatform.googleapis.com \
    --projects=PROJECT_ID

或者，也可以傳送 REST API 呼叫：

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json; charset=utf-8" -d "" "https://serviceusage.googleapis.com/v1beta1/projects/PROJECT_ID/services/aiplatform.googleapis.com:generateServiceIdentity"

確認 Vertex AI RAG 引擎服務代理是否已建立。

如要授予 KMS 金鑰的權限，請按照下列步驟操作：

返回 Google Cloud 控制台中的 Key Management 服務。
選取包含您建立金鑰的金鑰環。
選取您建立的特定金鑰。
在金鑰的詳細資料頁面中，前往「權限」分頁標籤。
按一下「新增主體」。
在「New principals」(新增主體) 欄位中，輸入 Vertex AI RAG Engine 服務代理的電子郵件地址。
在「Select a role」(選取角色) 下拉式選單中，選取「Cloud KMS CryptoKey Encrypter/Decrypter」(Cloud KMS CryptoKey 加密者/解密者) 角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)。這個角色會授予服務代理人必要權限，以便使用金鑰進行加密和解密作業。
按一下 [儲存]。

使用客戶管理的加密功能建立 RAG 語料庫

這個程式碼範例說明如何建立以客戶管理加密金鑰 (CMEK) 加密的 RAG 語料庫。

請替換下列程式碼範例中的變數：

Python

import vertexai
from google.cloud import aiplatform
from vertexai import rag
from google.cloud.aiplatform_v1.types.encryption_spec import EncryptionSpec

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME

vertexai.init(project=PROJECT_ID)

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, encryption_spec=EncryptionSpec(kms_key_name=KMS_KEY_NAME))

REST

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora \
-d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "encryption_spec" : {
        "kms_key_name" : '\""${KMS_KEY_NAME}"\"'
      }
    }'

配額

搭配 Vertex AI 服務 (例如 Vertex AI RAG Engine) 使用 CMEK 時，每個專案在每個區域可使用的不重複 Cloud KMS 金鑰數量設有配額。這項配額會透過 aiplatform.googleapis.com/in_use_customer_managed_encryption_keys 指標追蹤。

每次使用新的專屬 KMS 金鑰，在專案和區域中建立 RAG 語料庫等資源時，KMS 金鑰都會消耗一單位的配額。即使刪除使用該特定金鑰的資源，也不會釋出這項配額單位。

如果需要的專屬金鑰數量超出目前上限，請為所選區域的 aiplatform.googleapis.com/in_use_customer_managed_encryption_keys 申請提高配額。

如要進一步瞭解如何申請提高配額，請參閱「在 Google Cloud 控制台中查看及編輯配額」。

後續步驟

如要進一步瞭解 RagManagedDb，請參閱「瞭解 RagManagedDb」。
如要從 Google 雲端硬碟或 Cloud Storage 匯入檔案和資料夾，請參閱匯入 RAG 檔案範例。
如要列出 RAG 檔案，請參閱列出 RAG 檔案的範例。

搭配 Vertex AI RAG 引擎使用 RagManagedDb 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

管理擷取策略

使用 KNN RagManagedDb 建立 RAG 語料庫

Python

REST

使用 ANN RagManagedDb 建立 RAG 語料庫

Python

REST

將資料匯入 ANN RagManagedDb

Python

REST

管理加密

設定 KMS 金鑰並授予權限

必要條件

啟用 API

建立 KMS 金鑰環和金鑰

授予 Vertex AI RAG 引擎服務代理權限

使用客戶管理的加密功能建立 RAG 語料庫

Python

REST

配額

後續步驟

搭配 Vertex AI RAG 引擎使用 RagManagedDb

使用 KNN `RagManagedDb` 建立 RAG 語料庫

使用 ANN `RagManagedDb` 建立 RAG 語料庫

將資料匯入 ANN `RagManagedDb`