使用 Weaviate 資料庫搭配 Vertex AI RAG 引擎

本頁面說明如何將 RAG Engine 語料庫連結至 Weaviate 資料庫。

您也可以使用這個筆記本 RAG Engine with Weaviate 進行操作。

您可以使用 Weaviate 資料庫執行個體 (這是開放原始碼資料庫) 搭配 RAG Engine，建立索引並執行以向量為基礎的相似度搜尋。相似度搜尋可用來找出與所尋找文字相似的文字片段，但必須使用嵌入模型。嵌入模型會針對每個要比較的文字片段產生向量資料。相似度搜尋功能可用於擷取依據的語意上下文，從 LLM 中傳回最準確的內容。

有了 RAG Engine，您可以繼續使用自己負責佈建的全代管向量資料庫執行個體。RAG Engine 會使用向量資料庫進行儲存、索引管理和搜尋作業。

注意事項

使用 Weaviate 資料庫前，請考慮下列步驟：

  1. 您必須建立、設定及部署 Weaviate 資料庫執行個體和集合。請按照「建立 Weaviate 集合」一節的操作說明，根據結構定義設定集合。
  2. 您必須提供 Weaviate API 金鑰，讓 RAG Engine 與 Weaviate 資料庫互動。RAG Engine 支援以 API 金鑰為基礎的 AuthN 和 AuthZ，可連線至 Weaviate 資料庫，並支援 HTTPS 連線。
  3. RAG Engine 不會儲存及管理您的 Weaviate API 金鑰。請改為執行以下操作：
    1. 將金鑰儲存於 Google Cloud Secret Manager。
    2. 授予專案服務帳戶存取密鑰的權限。
    3. 請提供 RAG Engine 存取密鑰資源名稱的權限。
    4. 您與 Weaviate 資料庫互動時，RAG Engine 會使用服務帳戶存取密鑰資源。
  4. RAG 引擎語料庫和 Weaviate 集合之間有 1 對 1 的對應關係。RAG 檔案會儲存在 Weaviate 資料庫集合中。呼叫 CreateRagCorpus API 或 UpdateRagCorpus API 時，RAG 語料庫會與資料庫集合建立關聯。
  5. 除了以密集嵌入為基礎的語意搜尋，RAG Engine 也支援透過 Weaviate 資料庫執行混合搜尋。您也可以在混合搜尋中調整密集和稀疏向量相似度之間的權重。

佈建 Weaviate 資料庫

在 RAG Engine 中使用 Weaviate 資料庫前，您必須執行下列操作：

  1. 設定及部署 Weaviate 資料庫執行個體。
  2. 準備 HTTPS 端點。
  3. 建立 Weaviate 集合。
  4. 使用 API 金鑰，透過 AuthN 和 AuthZ 佈建 Weaviate。
  5. 佈建 RAG Engine 服務帳戶。

設定及部署 Weaviate 資料庫執行個體

您必須按照 Weaviate 官方指南快速入門操作。不過，您可以使用 Google Cloud 市集指南 (選用)。

只要 Weaviate 端點可供存取，您就可以在任何地方設定 Weaviate 例項，並在專案中進行設定及部署。接著，您就可以全面管理 Weaviate 資料庫執行個體。

由於 RAG Engine 不會參與 Weaviate 資料庫執行個體生命週期的任何階段，因此您必須授予 RAG Engine 權限，讓 RAG Engine 能夠在 Weaviate 資料庫中儲存及搜尋資料。此外，您也必須負責確保資料庫中的資料可供 RAG Engine 使用。舉例來說，如果您變更資料，RAG Engine 不會對因這些變更而導致的任何異常行為負責。

準備 HTTPS 端點

在 Weaviate 佈建期間，請務必建立 HTTPS 端點。雖然系統支援 HTTP 連線，但我們建議 RAG Engine 和 Weaviate 資料庫流量使用 HTTPS 連線。

建立 Weaviate 集合

由於 RAG Engine 語料庫和 Weaviate 集合有一對一的對應關係，因此您必須先在 Weaviate 資料庫中建立集合，再將集合與 RAG Engine 語料庫建立關聯。您呼叫 CreateRagCorpus API 或 UpdateRagCorpus API 時，系統會建立這項一次性關聯。

在 Weaviate 中建立集合時，請務必使用下列結構定義：

屬性名稱 資料類型
fileId text
corpusId text
chunkId text
chunkDataType text
chunkData text
fileOriginalUri text

使用 API 金鑰和 AuthN 及 AuthZ 為 Weaviate 進行佈建

如要設定 Weaviate API 金鑰，請完成下列步驟：

  1. 建立 Weaviate API 金鑰。
  2. 使用 Weaviate API 金鑰設定 Weaviate。
  3. 將 Weaviate API 金鑰儲存在 Secret Manager。

建立 API 金鑰

RAG Engine 只能使用 API 金鑰進行驗證和授權，才能連線至 Weaviate 資料庫執行個體。您必須按照 Weaviate 官方驗證指南設定 Weaviate 資料庫執行個體中的 API 金鑰驗證機制。

如果建立 Weaviate API 金鑰需要與 RAG 引擎提供的身分資訊建立關聯，則必須先建立第一個語料庫，並使用 RAG 引擎服務帳戶做為身分。

將 API 金鑰儲存在 Secret Manager 中

API 金鑰會儲存具敏感性的個人識別資訊 (SPII)，須遵守法律規定。如果 SPII 資料遭到盜用或濫用，使用者可能會面臨重大風險或傷害。為降低使用 RAG Engine 時對個人造成的風險，請勿儲存及管理 API 金鑰，並避免分享未加密的 API 金鑰。

如要保護 SPII，請採取下列做法：

  1. 將 API 金鑰儲存在 Secret Manager 中。
  2. 授予 RAG Engine 服務帳戶密鑰的權限，並在密鑰資源層級管理存取權。
    1. 前往專案的權限。
    2. 啟用「包含 Google 提供的角色授予項目」選項。
    3. 找出服務帳戶，格式為

      service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

    4. 編輯服務帳戶的使用者。
    5. 將 Secret Manager 密鑰存取者角色新增至服務帳戶。
  3. 在建立或更新 RAG 語料庫時，請將密鑰資源名稱傳遞至 RAG Engine，並儲存密鑰資源名稱。

當您向 Weaviate 資料庫執行個體提出 API 要求時，RAG Engine 會使用各個服務帳戶，從專案中讀取與 Secret Manager 中的密鑰資源相對應的 API 金鑰。

佈建 RAG Engine 服務帳戶

在專案中建立第一個資源時，RAG Engine 會建立專用服務帳戶。您可以在專案的「IAM」頁面中找到服務帳戶。服務帳戶的格式如下：

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

例如 service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com。

與 Weaviate 資料庫整合時，服務帳戶會在以下情況下使用：

  • 您可以使用服務帳戶產生 Weaviate API 金鑰，用於驗證。在某些情況下，產生 API 金鑰不需要任何使用者資訊，也就是說，產生 API 金鑰時不需要服務帳戶。
  • 您可以將服務帳戶與 Weaviate 資料庫中的 API 金鑰繫結，以便設定驗證 (AuthN) 和授權 (AuthZ)。不過，您不一定要使用服務帳戶。
  • 您可以在專案中儲存 API 金鑰 Secret Manager，並授予服務帳戶存取這些密鑰資源的權限。
  • RAG Engine 會使用服務帳戶，從專案中的 Secret Manager 存取 API 金鑰。

設定 Google Cloud 主控台環境

按一下即可瞭解如何設定環境

如要瞭解如何設定環境，請選取下列其中一個分頁：

Python 適用的 Vertex AI SDK

  1. 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.

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

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

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

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  8. 執行下列指令，安裝或更新 Python 適用的 Vertex AI SDK：

    pip3 install --upgrade "google-cloud-aiplatform>=1.38"

Node.js

  1. 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.

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

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

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

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  8. 執行下列指令，安裝或更新 Node.js 專用的 Vertex AI SDK：

    npm install @google-cloud/vertexai

Java

  1. 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.

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

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

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

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  8. 如要將 google-cloud-vertexai 新增為依附元件，請為環境新增適當的程式碼：

    Maven 與 BOM

    在 pom.xml 中加入以下 HTML：

    <dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.32.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-vertexai</artifactId>
  </dependency>
</dependencies>

    不使用 BOM 的 Maven

    在 pom.xml 中加入以下 HTML：

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-vertexai</artifactId>
  <version>0.4.0</version>
</dependency>

    Gradle without BOM

    Add the following to your build.gradle

    implementation 'com.google.cloud:google-cloud-vertexai:0.4.0'

Go

  1. 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.

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

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

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

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  8. 請查看可用的 Vertex AI API Go 套件，判斷哪個套件最符合專案需求：

    • 套件 cloud.google.com/go/vertexai (建議)

      vertexai 是人為編寫的套件，可提供常用功能和功能的存取權。

      對於大多數使用 Vertex AI API 建構的開發人員，建議從這個套件開始。如要存取這個套件尚未涵蓋的功能和特色，請改用自動產生的 aiplatform。

    • 套件 cloud.google.com/go/aiplatform

      aiplatform 是自動產生的套件。

      這個套件適用於需要存取 Vertex AI API 功能和人為編寫的 vertexai 套件尚未提供的功能的專案。

  9. 根據專案需求執行下列任一指令，安裝所需的 Go 套件：

    # Human authored package. Recommended for most developers.
go get cloud.google.com/go/vertexai
    
    
# Auto-generated package.
go get cloud.google.com/go/aiplatform

C#

  1. 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.

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

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

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

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

REST

  1. 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.

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

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

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

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. 輸入下列內容來設定環境變數。將 PROJECT_ID 替換為您的 Google Cloud 專案 ID。
    MODEL_ID="gemini-2.0-flash-001"
PROJECT_ID="PROJECT_ID"
  8. 佈建端點： 
    gcloud beta services identity create --service=aiplatform.googleapis.com --project=${PROJECT_ID}

  9. 選用步驟：如果您使用 Cloud Shell，系統會提示您授權 Cloud Shell，請按一下「授權」。

準備 RAG 語料庫

如要存取 Weaviate 資料庫中的資料，RAG 引擎必須能存取 RAG 字典。本節將說明如何建立單一 RAG 語料庫和其他 RAG 語料庫。

使用 CreateRagCorpus 和 UpdateRagCorpus API

呼叫 CreateRagCorpus 和 UpdateRagCorpus API 時，您必須指定下列欄位：

  • rag_vector_db_config.weaviate：呼叫 CreateRagCorpus API 後，系統會選擇向量資料庫設定。向量資料庫設定包含所有設定欄位。如果未設定 rag_vector_db_config.weaviate 欄位，系統會預設設定 rag_vector_db_config.rag_managed_db。
  • weaviate.http_endpoint：在 Weaviate 資料庫例項的佈建期間，會建立 HTTPS 或 HTTP Weaviate 端點。
  • weaviate.collection_name：在 Weaviate 執行個體佈建期間建立的集合名稱。名稱開頭必須為大寫英文字母。
  • api_auth.api_key_config：設定會指定使用 API 金鑰，授權您存取向量資料庫。
  • api_key_config.api_key_secret_version：儲存在 Secret Manager 中的密鑰資源名稱，其中包含 Weaviate API 金鑰。

您可以建立 RAG 語料庫，並將其與資料庫執行個體中的 Weaviate 集合建立關聯。不過，您可能需要服務帳戶才能產生 API 金鑰，並設定 Weaviate 資料庫執行個體。建立第一個 RAG 語料庫時，系統會產生服務帳戶。建立第一個 RAG 語料庫後，Weaviate 資料庫和 API 金鑰之間的關聯可能無法用於建立其他 RAG 語料庫。

為避免資料庫和鍵無法與 RAG 語料庫建立關聯，請對 RAG 語料庫執行下列操作：

  1. 在 rag_vector_db_config 中設定 weaviate 欄位。

    • 您無法變更相關的向量資料庫。
    • 將 http_endpoint 和 collection_name 欄位留空。您之後可以更新這兩個欄位。

  2. 如果您沒有將 API 金鑰儲存在 Secret Manager 中，可以將 api_auth 欄位留空。呼叫 UpdateRagCorpus API 時，您可以更新 api_auth 欄位。Weaviate 需要完成以下操作：

    1. 在 api_auth 欄位中設定 api_key_config。

    2. 在 Secret Manager 中設定 Weaviate API 金鑰的 api_key_secret_version。api_key_secret_version 欄位使用下列格式：

      projects/{project}/secrets/{secret}/versions/{version}

  3. 如果您指定的欄位只能設定一次 (例如 http_endpoint 或 collection_name)，您必須先刪除 RAG 字元集，然後重新建立 RAG 字元集，才能變更這些欄位。其他欄位 (例如 API 金鑰欄位 api_key_secret_version) 則可更新。

  4. 呼叫 UpdateRagCorpus 時，您可以設定 vector_db 欄位。vector_db 應由 CreateRagCorpus API 呼叫設為 weaviate。否則，系統會選擇預設的「RAG 管理資料庫」選項。您在呼叫 UpdateRagCorpus API 時無法變更這個選項。當您呼叫 UpdateRagCorpus 且 vector_db 欄位已部分設定時，您可以更新標示為「可變更」 (也稱為「可變動」) 的欄位。

下表列出程式碼中使用的 WeaviateConfig 可變動和不可變動欄位。

欄位名稱 可變更或不可變更
http_endpoint 設定後即無法變更
collection_name 設定後即無法變更
api_key_authentication 可以變更

建立第一個 RAG 語料庫

如果 RAG Engine 服務帳戶不存在，請執行下列操作：

  1. 在 RAG Engine 中使用空白的 Weaviate 設定建立 RAG 語料庫，這會啟動 RAG Engine 佈建作業，以建立服務帳戶。
  2. 請為 RAG Engine 服務帳戶選擇符合下列格式的名稱：

    service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

    例如 service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com。

  3. 使用服務帳戶存取儲存在專案 Secret Manager 中的密鑰，該密鑰包含 Weaviate API 金鑰。
  4. 在 Weaviate 佈建完成後取得下列資訊：
    • Weaviate HTTPS 或 HTTP 端點。
    • Weaviate 集合名稱。
  5. 呼叫 CreateRagCorpus API 以空白的 Weaviate 設定建立 RAG 語料庫，然後呼叫 UpdateRagCorpus API 以以下資訊更新 RAG 語料庫：
    • Weaviate HTTPS 或 HTTP 端點。
    • Weaviate 集合名稱。
    • API 金鑰資源名稱。

建立其他 RAG 語料庫

如果 RAG Engine 服務帳戶已存在，請執行下列操作：

  1. 從專案的權限取得 RAG Engine 服務帳戶。
  2. 啟用「包含 Google 提供的角色授權」選項
  3. 請為 RAG Engine 服務帳戶選擇符合下列格式的名稱：

    service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

  4. 使用服務帳戶存取儲存在專案 Secret Manager 中的密鑰，該密鑰包含 Weaviate API 金鑰。
  5. 在 Weaviate 佈建期間，取得下列資訊：
    • Weaviate HTTPS 或 HTTP 端點。
    • Weaviate 集合名稱。
  6. 在 RAG Engine 中建立 RAG 語料庫，然後執行下列任一操作，將語料庫連結至 Weaviate：
    1. 發出 CreateRagCorpus API 呼叫，建立 RAG 語料庫，並填入 Weaviate 設定 (這是建議做法)。
    2. 發出 CreateRagCorpus API 呼叫，使用空白的 Weaviate 設定建立 RAG 語料庫，然後發出 UpdateRagCorpus API 呼叫，使用下列資訊更新 RAG 語料庫：
      • Weaviate 資料庫 HTTP 端點
      • Weaviate 集合名稱
      • API 金鑰

範例

本節提供程式碼範例，說明如何設定 Weaviate 資料庫、Secret Manager、RAG 字典和 RAG 檔案。我們也提供程式碼範例，說明如何匯入檔案、擷取內容、產生內容，以及刪除 RAG 語料庫和 RAG 檔案。

如要使用 Model Garden RAG API 的 Notebook，請參閱「使用 Weaviate 搭配 Llama 3」一文。

設定 Weaviate 資料庫

此程式碼範例示範如何設定 Weaviate 資料和 Secret Manager。

REST

# TODO(developer): Update the variables.
# The HTTPS/HTTP Weaviate endpoint you created during provisioning.
HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

# Your Weaviate API Key.
WEAVIATE_API_KEY="example-api-key"

# Select your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
# For example, "MyCollectionName"
# Note that the first letter needs to be capitalized.
# Otherwise, Weavaite will capitalize it for you.
WEAVIATE_COLLECTION_NAME="MyCollectionName"

# Create a collection in Weaviate which includes the required schema fields shown below.
echo '{
  "class": "'${WEAVIATE_COLLECTION_NAME}'",
  "properties": [
    { "name": "fileId", "dataType": [ "string" ] },
    { "name": "corpusId", "dataType": [ "string" ] },
    { "name": "chunkId", "dataType": [ "string" ] },
    { "name": "chunkDataType", "dataType": [ "string" ] },
    { "name": "chunkData", "dataType": [ "string" ] },
    { "name": "fileOriginalUri", "dataType": [ "string" ] }
  ]
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer "${WEAVIATE_API_KEY} \
    -d @- \
    ${HTTP_ENDPOINT_NAME}/v1/schema

設定 Secret Manager

如要設定 Secret Manager，您必須啟用 Secret Manager 並設定權限。

建立密鑰

如要啟用 Secret Manager，請按照下列步驟操作：

控制台

  1. 前往「Secret Manager」頁面。

    前往 Secret Manager

  2. 按一下「+ 建立密鑰」。

  3. 輸入密鑰的名稱。密鑰名稱只能由英文字母 (A 至 Z)、數字 (0 至 9)、破折號 (-) 和底線 (_) 組成。

  4. 您可以選擇是否指定下列欄位：

    1. 如要上傳包含機密資料的檔案，請按一下「瀏覽」。
    2. 詳閱複製政策。
    3. 如要手動管理密鑰的位置，請勾選「手動管理此密鑰的位置」。至少須選取一個區域。
    4. 選取加密選項。
    5. 如果您想手動設定輪播期間，請勾選「設定輪播期間」。
    6. 如要指定發布或訂閱主題，以便接收事件通知，請按一下「新增主題」。
    7. 根據預設，密鑰不會過期。如要設定到期日，請勾選「設定到期日」。
    8. 根據預設，系統會在收到要求後刪除密鑰版本。如要延遲刪除密鑰版本，請勾選「設定延遲刪除時長」。
    9. 如果您想使用標籤來整理密鑰並加以分類，請按一下「+ 新增標籤」。
    10. 如果您想使用註解將非識別中繼資料附加到密鑰，請按一下「+ 新增註解」。

  5. 按一下「Create secret」。

REST

# Create a secret in SecretManager.
curl "https://secretmanager.googleapis.com/v1/projects/${PROJECT_ID}/secrets?secretId=${SECRET_NAME}" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"replication\": {\"automatic\": {}}}"

Python

在試用這個範例之前，請先按照 Vertex AI 快速入門：使用用戶端程式庫中的操作說明設定 Python。詳情請參閱 Vertex AI Python API 參考說明文件。

如要向 Vertex AI 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

# Import the Secret Manager client library.
from google.cloud import secretmanager


def create_secret(
    project_id: str, secret_id: str, ttl: Optional[str] = None
) -> secretmanager.Secret:
    """
    Create a new secret with the given name. A secret is a logical wrapper
    around a collection of secret versions. Secret versions hold the actual
    secret material.

     Args:
        project_id (str): The project ID where the secret is to be created.
        secret_id (str): The ID to assign to the new secret. This ID must be unique within the project.
        ttl (Optional[str]): An optional string that specifies the secret's time-to-live in seconds with
                             format (e.g., "900s" for 15 minutes). If specified, the secret
                             versions will be automatically deleted upon reaching the end of the TTL period.

    Returns:
        secretmanager.Secret: An object representing the newly created secret, containing details like the
                              secret's name, replication settings, and optionally its TTL.

    Example:
        # Create a secret with automatic replication and no TTL
        new_secret = create_secret("my-project", "my-new-secret")

        # Create a secret with a TTL of 30 days
        new_secret_with_ttl = create_secret("my-project", "my-timed-secret", "7776000s")
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent project.
    parent = f"projects/{project_id}"

    # Create the secret.
    response = client.create_secret(
        request={
            "parent": parent,
            "secret_id": secret_id,
            "secret": {"replication": {"automatic": {}}, "ttl": ttl},
        }
    )

    # Print the new secret name.
    print(f"Created secret: {response.name}")

設定權限

您必須為服務帳戶授予 Secret Manager 權限。

控制台

  1. 在 Google Cloud 控制台的「IAM 與管理」部分中找出服務帳戶，然後按一下鉛筆圖示進行編輯。

  2. 在「Role」欄位中，選取「Secret Manager Secret Accessor」。

Python

在試用這個範例之前，請先按照 Vertex AI 快速入門：使用用戶端程式庫中的操作說明設定 Python。詳情請參閱 Vertex AI Python API 參考說明文件。

如要向 Vertex AI 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

def iam_grant_access(
    project_id: str, secret_id: str, member: str
) -> iam_policy_pb2.SetIamPolicyRequest:
    """
    Grant the given member access to a secret.
    """

    # Import the Secret Manager client library.
    from google.cloud import secretmanager

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the secret.
    name = client.secret_path(project_id, secret_id)

    # Get the current IAM policy.
    policy = client.get_iam_policy(request={"resource": name})

    # Add the given member with access permissions.
    policy.bindings.add(role="roles/secretmanager.secretAccessor", members=[member])

    # Update the IAM Policy.
    new_policy = client.set_iam_policy(request={"resource": name, "policy": policy})

    # Print data about the secret.
    print(f"Updated IAM policy on {secret_id}")

新增密鑰版本

REST

# TODO(developer): Update the variables.
# Select a resource name for your Secret, which contains your API Key.
SECRET_NAME="MyWeaviateApiKeySecret"

# Your Weaviate API Key.
WEAVIATE_API_KEY="example-api-key"
# Encode your WEAVIATE_API_KEY using base 64.
SECRET_DATA=$(echo ${WEAVIATE_API_KEY} | base64)

# Create a new version of your secret which uses SECRET_DATA as payload
curl "https://secretmanager.googleapis.com/v1/projects/${PROJECT_ID}/secrets/${SECRET_NAME}:addVersion" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"payload\": {\"data\": \"${SECRET_DATA}\"}}"

Python

在試用這個範例之前，請先按照 Vertex AI 快速入門：使用用戶端程式庫中的操作說明設定 Python。詳情請參閱 Vertex AI Python API 參考說明文件。

如要向 Vertex AI 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

from google.cloud import secretmanager
import google_crc32c  # type: ignore


def add_secret_version(
    project_id: str, secret_id: str, payload: str
) -> secretmanager.SecretVersion:
    """
    Add a new secret version to the given secret with the provided payload.
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent secret.
    parent = client.secret_path(project_id, secret_id)

    # Convert the string payload into a bytes. This step can be omitted if you
    # pass in bytes instead of a str for the payload argument.
    payload_bytes = payload.encode("UTF-8")

    # Calculate payload checksum. Passing a checksum in add-version request
    # is optional.
    crc32c = google_crc32c.Checksum()
    crc32c.update(payload_bytes)

    # Add the secret version.
    response = client.add_secret_version(
        request={
            "parent": parent,
            "payload": {
                "data": payload_bytes,
                "data_crc32c": int(crc32c.hexdigest(), 16),
            },
        }
    )

    # Print the new secret version name.
    print(f"Added secret version: {response.name}")

搭配使用 Weaviate 和 Llama 3

模型花園 RAG API 筆記本示範如何搭配使用 Python 適用的 Vertex AI SDK、Weaviate 語料庫和 Llama 3 模型。如要使用筆記本，您必須執行下列操作：

  1. 設定 Weaviate 資料庫。

  2. 設定 Secret Manager。

  3. 使用 Model Garden RAG API 筆記本。

如需更多範例，請參閱「範例」。

建立 RAG 語料庫

這個程式碼範例示範如何建立 RAG 字體庫，並將 Weaviate 例項設為向量資料庫。

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora \
  -d '{
        "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
        "rag_vector_db_config" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python

在試用這個範例之前，請先按照 Vertex AI 快速入門：使用用戶端程式庫中的操作說明設定 Python。詳情請參閱 Vertex AI Python API 參考說明文件。

如要向 Vertex AI 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# weaviate_http_endpoint = "weaviate-http-endpoint"
# weaviate_collection_name = "weaviate-collection-name"
# weaviate_api_key_secret_manager_version = "projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/latest"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = rag.EmbeddingModelConfig(
    publisher_model="publishers/google/models/text-embedding-004"
)

# Configure Vector DB
vector_db = rag.Weaviate(
    weaviate_http_endpoint=weaviate_http_endpoint,
    collection_name=weaviate_collection_name,
    api_key=weaviate_api_key_secret_manager_version,
)

corpus = rag.create_corpus(
    display_name=display_name,
    description=description,
    embedding_model_config=embedding_model_config,
    vector_db=vector_db,
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

使用 RAG 檔案

RAG API 可處理檔案上傳、匯入、列出和刪除作業。

REST

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

  • PROJECT_ID：您的專案 ID。
  • LOCATION：處理要求的區域。
  • RAG_CORPUS_ID：RagCorpus 資源的 ID。
  • INPUT_FILE：本機檔案的路徑。
  • FILE_DISPLAY_NAME：RagFile 的顯示名稱。
  • RAG_FILE_DESCRIPTION：RagFile 的說明。

HTTP 方法和網址：

POST https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload

JSON 要求主體：

{
 "rag_file": {
  "display_name": "FILE_DISPLAY_NAME",
  "description": "RAG_FILE_DESCRIPTION"
 }
}

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

curl

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

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @INPUT_FILE \
     "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload"

PowerShell

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

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile INPUT_FILE `
    -Uri "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload" | Select-Object -Expand Content
成功的回應會傳回 RagFile 資源。RagFile.name 欄位的最後一個元件是伺服器產生的 rag_file_id。

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"
# path = "path/to/local/file.txt"
# display_name = "file_display_name"
# description = "file description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_file = rag.upload_file(
    corpus_name=corpus_name,
    path=path,
    display_name=display_name,
    description=description,
)
print(rag_file)
# RagFile(name='projects/[PROJECT_ID]/locations/us-central1/ragCorpora/1234567890/ragFiles/09876543',
#  display_name='file_display_name', description='file description')

匯入 RAG 檔案

檔案和資料夾可從雲端硬碟或 Cloud Storage 匯入。

REST

使用 response.metadata 查看 SDK response 物件中的部分失敗、要求時間和回應時間。

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

  • PROJECT_ID：您的專案 ID。
  • LOCATION：處理要求的區域。
  • RAG_CORPUS_ID：RagCorpus 資源的 ID。
  • GCS_URIS：Cloud Storage 位置清單。範例：gs://my-bucket1, gs://my-bucket2。
  • DRIVE_RESOURCE_ID：雲端硬碟資源的 ID。範例：
    • https://drive.google.com/file/d/ABCDE
    • https://drive.google.com/corp/drive/u/0/folders/ABCDEFG
  • DRIVE_RESOURCE_TYPE：雲端硬碟資源的類型。選項：
    • RESOURCE_TYPE_FILE - 檔案
    • RESOURCE_TYPE_FOLDER - 資料夾
  • CHUNK_SIZE：選用：每個區塊應有的符記數。
  • CHUNK_OVERLAP：選用：區塊之間重疊的符記數量。

HTTP 方法和網址：

POST https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import

JSON 要求主體：

{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": GCS_URIS
    },
    "google_drive_source": {
      "resource_ids": {
        "resource_id": DRIVE_RESOURCE_ID,
        "resource_type": DRIVE_RESOURCE_TYPE
      },
    }
  }
}

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

curl

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

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import"

PowerShell

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

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import" | Select-Object -Expand Content
成功的回應會傳回 ImportRagFilesOperationMetadata 資源。

以下範例示範如何從 Cloud Storage 匯入檔案。使用 max_embedding_requests_per_min 控制欄位，限制 RAG Engine 在 ImportRagFiles 索引程序中呼叫嵌入模型的頻率。這個欄位的預設值為每分鐘 1000 通話。

// Cloud Storage bucket/file location.
// Such as "gs://rag-e2e-test/"
GCS_URIS=YOUR_GCS_LOCATION

// Enter the QPM rate to limit RAG's access to your embedding model
// Example: 1000
EMBEDDING_MODEL_QPM_RATE=MAX_EMBEDDING_REQUESTS_PER_MIN_LIMIT

// ImportRagFiles
// Import a single Cloud Storage file or all files in a Cloud Storage bucket.
// Input: ENDPOINT, PROJECT_ID, RAG_CORPUS_ID, GCS_URIS
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ENDPOINT}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URIS}"\"'
    },
    "rag_file_chunking_config": {
      "chunk_size": 512
    },
    "max_embedding_requests_per_min": '"${EMBEDDING_MODEL_QPM_RATE}"'
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID=OPERATION_ID
poll_op_wait ${OPERATION_ID}

以下範例說明如何從 Google 雲端硬碟匯入檔案。使用 max_embedding_requests_per_min 控制欄位，限制 RAG 引擎在 ImportRagFiles 索引程序中呼叫嵌入模型的頻率。這個欄位的預設值為每分鐘 1000 通話。

// Google Drive folder location.
FOLDER_RESOURCE_ID=YOUR_GOOGLE_DRIVE_FOLDER_RESOURCE_ID

// Enter the QPM rate to limit RAG's access to your embedding model
// Example: 1000
EMBEDDING_MODEL_QPM_RATE=MAX_EMBEDDING_REQUESTS_PER_MIN_LIMIT

// ImportRagFiles
// Import all files in a Google Drive folder.
// Input: ENDPOINT, PROJECT_ID, RAG_CORPUS_ID, FOLDER_RESOURCE_ID
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ENDPOINT}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "google_drive_source": {
      "resource_ids": {
        "resource_id": '\""${FOLDER_RESOURCE_ID}"\"',
        "resource_type": "RESOURCE_TYPE_FOLDER"
      }
    },
    "max_embedding_requests_per_min": '"${EMBEDDING_MODEL_QPM_RATE}"'
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID=OPERATION_ID
poll_op_wait ${OPERATION_ID}

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"
# paths = ["https://drive.google.com/file/123", "gs://my_bucket/my_files_dir"]  # Supports Google Cloud Storage and Google Drive Links

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.import_files(
    corpus_name=corpus_name,
    paths=paths,
    transformation_config=rag.TransformationConfig(
        rag.ChunkingConfig(chunk_size=512, chunk_overlap=100)
    ),
    import_result_sink="gs://sample-existing-folder/sample_import_result_unique.ndjson",  # Optional, this has to be an existing storage bucket folder, and file name has to be unique (non-existent).
    max_embedding_requests_per_min=900,  # Optional
)
print(f"Imported {response.imported_rag_files_count} files.")
# Example response:
# Imported 2 files.

取得 RAG 檔案

REST

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

  • PROJECT_ID：您的專案 ID。
  • LOCATION：處理要求的區域。
  • RAG_CORPUS_ID：RagCorpus 資源的 ID。
  • RAG_FILE_ID：RagFile 資源的 ID。

HTTP 方法和網址：

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

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

curl

執行下列指令：

curl -X GET \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

執行下列指令：

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content
成功的回應會傳回 RagFile 資源。

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# file_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_file = rag.get_file(name=file_name)
print(rag_file)
# Example response:
# RagFile(name='projects/1234567890/locations/us-central1/ragCorpora/11111111111/ragFiles/22222222222',
# display_name='file_display_name', description='file description')

列出 RAG 檔案

REST

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

  • PROJECT_ID：您的專案 ID。
  • LOCATION：處理要求的區域。
  • RAG_CORPUS_ID：RagCorpus 資源的 ID。
  • PAGE_SIZE：標準清單頁面大小。您可以更新 page_size 參數，調整每頁傳回的 RagFiles 數量。
  • PAGE_TOKEN：標準清單頁面符記。通常會使用先前 VertexRagDataService.ListRagFiles 呼叫的 ListRagFilesResponse.next_page_token 取得。

HTTP 方法和網址：

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN

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

curl

執行下列指令：

curl -X GET \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

PowerShell

執行下列指令：

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" | Select-Object -Expand Content
您應該會收到成功的狀態碼 (2xx)，以及指定的 RAG_CORPUS_ID 底下的 RagFiles 清單。

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

files = rag.list_files(corpus_name=corpus_name)
for file in files:
    print(file.display_name)
    print(file.name)
# Example response:
# g-drive_file.txt
# projects/1234567890/locations/us-central1/ragCorpora/111111111111/ragFiles/222222222222
# g_cloud_file.txt
# projects/1234567890/locations/us-central1/ragCorpora/111111111111/ragFiles/333333333333

刪除 RAG 檔案

REST

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

  • PROJECT_ID：您的專案 ID。
  • LOCATION：處理要求的區域。
  • RAG_CORPUS_ID：RagCorpus 資源的 ID。
  • RAG_FILE_ID：RagFile 資源的 ID。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}/ragFiles/{rag_file_id}。

HTTP 方法和網址：

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

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

curl

執行下列指令：

curl -X DELETE \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

執行下列指令：

$headers = @{  }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content
成功的回應會傳回 DeleteOperationMetadata 資源。

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# file_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag.delete_file(name=file_name)
print(f"File {file_name} deleted.")
# Example response:
# Successfully deleted the RagFile.
# File projects/1234567890/locations/us-central1/ragCorpora/1111111111/ragFiles/2222222222 deleted.

擷取背景資訊

使用者提出問題或提供提示時，RAG 中的擷取元件會搜尋知識庫，找出與查詢相關的資訊。

REST

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

  • LOCATION：處理要求的區域。
  • PROJECT_ID：您的專案 ID。
  • RAG_CORPUS_RESOURCE：RagCorpus 資源的名稱。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}。
  • VECTOR_DISTANCE_THRESHOLD：只傳回向量距離小於閾值的上下文。
  • TEXT：用於取得相關內容的查詢文字。
  • SIMILARITY_TOP_K：要擷取的重要上下文數量。

HTTP 方法和網址：

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts

JSON 要求主體：

{
 "vertex_rag_store": {
    "rag_resources": {
      "rag_corpus": "RAG_CORPUS_RESOURCE",
    },
    "vector_distance_threshold": 0.8
  },
  "query": {
   "text": "TEXT",
   "similarity_top_k": SIMILARITY_TOP_K
  }
 }

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

curl

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

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts"

PowerShell

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

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts" | Select-Object -Expand Content
您應該會收到成功的狀態碼 (2xx) 和相關的 RagFiles 清單。

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-central1/ragCorpora/[rag_corpus_id]"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.retrieval_query(
    rag_resources=[
        rag.RagResource(
            rag_corpus=corpus_name,
            # Optional: supply IDs from `rag.list_files()`.
            # rag_file_ids=["rag-file-1", "rag-file-2", ...],
        )
    ],
    text="Hello World!",
    rag_retrieval_config=rag.RagRetrievalConfig(
        top_k=10,
        filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
    ),
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

生成內容

預測會控制產生內容的 LLM 方法。

REST

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

  • PROJECT_ID：您的專案 ID。
  • LOCATION：處理要求的區域。
  • MODEL_ID：用於產生內容的 LLM 模型。範例：gemini-2.0-flash-001
  • GENERATION_METHOD：用於產生內容的 LLM 方法。選項：generateContent、streamGenerateContent
  • INPUT_PROMPT：傳送至 LLM 的文字，用於產生內容。請嘗試使用與上傳的 rag 檔案相關的提示。
  • RAG_CORPUS_RESOURCE：RagCorpus 資源的名稱。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}。
  • SIMILARITY_TOP_K：選用：要擷取的重要上下文數量。
  • VECTOR_DISTANCE_THRESHOLD：選用：傳回向量距離小於閾值的上下文。

HTTP 方法和網址：

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD

JSON 要求主體：

{
 "contents": {
  "role": "user",
  "parts": {
    "text": "INPUT_PROMPT"
  }
 },
 "tools": {
  "retrieval": {
   "disable_attribution": false,
   "vertex_rag_store": {
    "rag_resources": {
      "rag_corpus": "RAG_CORPUS_RESOURCE",
    },
    "similarity_top_k": SIMILARITY_TOP_K,
    "vector_distance_threshold": VECTOR_DISTANCE_THRESHOLD
   }
  }
 }
}

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

curl

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

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD"

PowerShell

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

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD" | Select-Object -Expand Content
如果回應成功，系統會傳回含有引用資訊的生成內容。

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。


from vertexai import rag
from vertexai.generative_models import GenerativeModel, Tool
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_retrieval_tool = Tool.from_retrieval(
    retrieval=rag.Retrieval(
        source=rag.VertexRagStore(
            rag_resources=[
                rag.RagResource(
                    rag_corpus=corpus_name,
                    # Optional: supply IDs from `rag.list_files()`.
                    # rag_file_ids=["rag-file-1", "rag-file-2", ...],
                )
            ],
            rag_retrieval_config=rag.RagRetrievalConfig(
                top_k=10,
                filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
            ),
        ),
    )
)

rag_model = GenerativeModel(
    model_name="gemini-2.0-flash-001", tools=[rag_retrieval_tool]
)
response = rag_model.generate_content("Why is the sky blue?")
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

Weaviate 資料庫支援混合搜尋，可同時進行語意和關鍵字搜尋，以改善搜尋結果的關聯性。在擷取搜尋結果時，系統會結合語意相似度分數 (密集向量) 和關鍵字比對 (稀疏向量)，產生最終排名結果。

使用 RAG Engine 檢索 API 進行混合搜尋

以下範例說明如何使用 RAG Engine 檢索 API 啟用混合搜尋。

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora \
  -d '{
        "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
        "rag_vector_db_config" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-central1/ragCorpora/[rag_corpus_id]"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.retrieval_query(
    rag_resources=[
        rag.RagResource(
            rag_corpus=corpus_name,
            # Optional: supply IDs from `rag.list_files()`.
            # rag_file_ids=["rag-file-1", "rag-file-2", ...],
        )
    ],
    text="Hello World!",
    rag_retrieval_config=rag.RagRetrievalConfig(
        top_k=10,
        filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
    ),
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

使用混合搜尋和 RAG 引擎進行有根據的生成

以下範例說明如何使用混合搜尋和 RAG 引擎進行根基生成。

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora \
  -d '{
        "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
        "rag_vector_db_config" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。


from vertexai import rag
from vertexai.generative_models import GenerativeModel, Tool
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_retrieval_tool = Tool.from_retrieval(
    retrieval=rag.Retrieval(
        source=rag.VertexRagStore(
            rag_resources=[
                rag.RagResource(
                    rag_corpus=corpus_name,
                    # Optional: supply IDs from `rag.list_files()`.
                    # rag_file_ids=["rag-file-1", "rag-file-2", ...],
                )
            ],
            rag_retrieval_config=rag.RagRetrievalConfig(
                top_k=10,
                filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
            ),
        ),
    )
)

rag_model = GenerativeModel(
    model_name="gemini-2.0-flash-001", tools=[rag_retrieval_tool]
)
response = rag_model.generate_content("Why is the sky blue?")
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

後續步驟