在 Gemini Enterprise Agent Platform 上，搭配 RAG Engine 使用 RagManagedDb

Agent Platform RAG Engine 支援 VPC-SC 安全控管機制和 CMEK。不支援資料落地和 AXT 安全控管機制。

RAG Engine 代管的 Spanner 執行個體會做為向量資料庫使用，且已正式發布並啟用計費功能。詳情請參閱「Gemini Enterprise Agent Platform 的 RAG Engine 計費方式」。

本頁面說明 Gemini Enterprise Agent Platform 的 RAG Engine 如何使用 RagManagedDb，這是企業級向量資料庫，用於儲存及管理文件的向量表示法。接著，系統會根據文件與指定查詢的語意相似度，使用向量資料庫擷取相關文件。

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

重要事項： 系統預設會使用 RagManagedDb，並採用 Spanner。客戶使用 Google 代管的 Spanner 執行個體時，系統會依據標準 Spanner SKU 收費。該執行個體是在 Google 租戶專案中佈建。

管理檢索策略

RagManagedDb 提供下列檢索策略，支援 RAG 用途：

檢索策略	說明
k-最近鄰 (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.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Agent Platform 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": {}
        }
      }
    }'

預覽

部分 RAG 功能為預先發布版產品，使用時須遵守《Google Cloud 服務專屬條款》的《正式發布前產品條款》。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。此外，這類產品和功能的變更可能與其他正式發布前版本不相容。詳情請參閱 推出階段說明。使用 Gemini Enterprise Agent Platform 的 Gemini API，即表示您同意生成式 AI 預先發布版 條款及細則 (下稱「預先發布版條款」)。

使用 ANN RagManagedDb 建立 RAG 語料庫

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

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

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

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

• 建議值為 10 * sqrt(num of RAG files in your RAG corpus)。

• 如未指定，RAG Engine 會為這個參數指派預設值 500。

Python

from vertexai.preview 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 Agent Platform 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}"'
          }
        }
      }
    }'

預覽

部分 RAG 功能為預先發布版產品，使用時須遵守《Google Cloud 服務專屬條款》的《正式發布前產品條款》。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。此外，這類產品和功能的變更可能與其他正式發布前版本不相容。詳情請參閱 推出階段說明。使用 Gemini Enterprise Agent Platform 的 Gemini API，即表示您同意生成式 AI 預先發布版 條款及細則 (下稱「預先發布版條款」)。

將資料匯入 ANN RagManagedDb

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

請注意下列事項：

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

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

Python

from vertexai.preview 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 Agent Platform 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}'
  }
}'

管理加密設定

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

如需進一步控管用於加密的金鑰，RAG Engine 支援客戶自行管理的加密金鑰 (CMEK)。有了 CMEK，您就能使用在 Cloud Key Management Service (Cloud KMS) 中管理的加密編譯金鑰，保護 RAG 語料庫資料。

如要瞭解 RAG 語料庫的 CMEK 限制，請參閱「Gemini Enterprise Agent Platform 的 RAG Engine CMEK 限制」。

設定 Cloud KMS 金鑰並授予權限

您必須先在 Google Cloud KMS 設定加密編譯金鑰，並授予 RAG Engine 服務帳戶使用這組金鑰的必要權限，才能建立以 CMEK 加密的 RAG 語料庫。

必要條件

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

啟用 API

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

1. 前往 Google Cloud 控制台。
2. 選取要管理金鑰的專案，並建立 RAG 語料庫。
3. 在搜尋列中輸入「Key Management」，然後選取「Key Management」服務。
4. 如果 API 尚未啟用，請點選「啟用」。API 可能需要幾分鐘才能完全佈建。

建立 Cloud KMS 金鑰環和金鑰

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

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

   輸入下列指令：

   • 金鑰環名稱：輸入金鑰環的專屬名稱，例如 rag-engine-cmek-keys。
   • 位置類型：選取「區域」。使用 CMEK 加密 RAG 語料庫時，Cloud KMS 金鑰環必須與您使用的 RAG Engine 端點位於相同區域。
   • 位置：選擇所選區域，例如 us-central1。這個區域最好與 RAG Engine 資源所在的區域相同。

2. 點選「建立」。

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

1. 金鑰環建立後，系統會提示您，或者您也可以前往「Create Key」(建立金鑰)。

   輸入下列指令：

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

2. 點選「建立」。

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

1. 建立金鑰後，前往詳細資料頁面。

2. 找出資源名稱。格式為 projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME/cryptoKeyVersions/1。

   重要事項： 針對 RAG 語料庫中的 EncryptionSpec，您必須使用不含版本號碼的金鑰資源名稱。

3. 複製資源名稱，並移除 /cryptoKeyVersions/VERSION_NUMBER 部分。正確格式的資源名稱為 projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME。

將權限授予 RAG Engine 服務代理

如要讓 RAG Engine 使用 Cloud KMS 金鑰加密及解密資料，服務代理必須具備該金鑰的適當權限。

如要找出 RAG Engine 服務代理，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往專案的「IAM & Admin」>「IAM」頁面。

2. 在「Identity and Access Management」頁面，勾選「Include Google-provided role grants」(包含 Google 提供的角色授予項目) 核取方塊。

3. 在主體清單的篩選器或搜尋列中，搜尋 RAG Engine 服務代理。格式為 [e-mail]。

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

如果 RAG Engine 服務代理尚未建立，請按照下列步驟觸發服務代理建立作業：

1. 啟用 Resource Manager API。

2. 在 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"
   

3. 確認 RAG Engine 服務代理已建立。

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

1. 返回 Google Cloud 控制台中的 Cloud KMS 服務。

2. 選取包含您所建立金鑰的金鑰環。

3. 選取您建立的特定金鑰。

4. 在金鑰詳細資料頁面中，前往「Permissions」(權限) 分頁標籤。

5. 按一下「新增主體」。

6. 在「New principals」(新增主體) 欄位中，輸入 RAG Engine 服務代理的電子郵件地址。

7. 在「Select a role」(選取角色) 下拉式選單中，選取 Cloud KMS CryptoKey 加密者/解密者角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)。這個角色會授予服務代理必要權限，讓服務代理能使用金鑰執行加密和解密作業。

8. 按一下 [儲存]。

使用客戶自行管理的加密金鑰建立 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}"\"'
      }
    }'

配額

搭配使用 CMEK 與 Gemini Enterprise Agent Platform 服務 (例如 Gemini Enterprise Agent Platform 的 RAG Engine) 時，每個專案在各區域可使用的不重複 Cloud KMS 金鑰數量有配額限制。這項配額是由 aiplatform.googleapis.com/in_use_customer_managed_encryption_keys 指標追蹤。

每次在專案和區域內，使用新的專屬 Cloud KMS 金鑰建立資源 (例如 RAG 語料庫) 時，Cloud KMS 金鑰就會消耗一個單位的配額。即使刪除使用該特定金鑰的資源，系統也不會釋出這個配額單位。

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

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

後續步驟

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