執行語意搜尋和檢索增強生成

本教學課程將逐步說明如何建立及使用文字嵌入項目，以進行語意搜尋和檢索增強生成 (RAG)。

本教學課程涵蓋下列工作：

• 透過 Vertex AI 嵌入模型建立 BigQuery ML 遠端模型。
• 使用 ML.GENERATE_EMBEDDING 函式搭配遠端模型，從 BigQuery 資料表中的文字生成嵌入。
• 建立向量索引，為嵌入建立索引，以提升搜尋效能。
• 使用 VECTOR_SEARCH 函式搭配嵌入項目，搜尋相似文字。
• 使用 ML.GENERATE_TEXT 函式生成文字，並運用向量搜尋結果擴增提示輸入內容，藉此執行 RAG，提升結果品質。

本教學課程使用 BigQuery 公開資料表 patents-public-data.google_patents_research.publications。

必要角色和權限

• 如要建立連結，您必須具備下列身分與存取權管理 (IAM) 角色：

  • roles/bigquery.connectionAdmin

• 如要將權限授予連線的服務帳戶，您必須具備下列權限：

  • resourcemanager.projects.setIamPolicy

• 本教學課程中其餘 BigQuery 作業所需的 IAM 權限，包含在下列兩個角色中：

  • BigQuery 資料編輯者 (roles/bigquery.dataEditor) 建立模型、資料表和索引。
  • BigQuery 使用者 (roles/bigquery.user) 執行 BigQuery 工作。

費用

在本文件中，您會使用 Google Cloud的下列計費元件：

• BigQuery ML: You incur costs for the data that you process in BigQuery.
• Vertex AI: You incur costs for calls to the Vertex AI service that's represented by the remote model.

如要根據預測用量估算費用，請使用 Pricing Calculator。 初次使用 Google Cloud 的使用者可能符合免費試用資格。

如要進一步瞭解 BigQuery 定價，請參閱 BigQuery 說明文件中的「BigQuery 定價」一文。

如要進一步瞭解 Vertex AI 定價，請參閱 Vertex AI 定價頁面。

事前準備

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

   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

2. Make sure that billing is enabled for your Google Cloud project.

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Enable the APIs

建立資料集

建立 BigQuery 資料集來儲存機器學習模型。

控制台

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery 頁面

2. 在「Explorer」窗格中，按一下專案名稱。

3. 依序點按 「View actions」(查看動作) >「Create dataset」(建立資料集)。

   

4. 在「建立資料集」頁面中，執行下列操作：

   • 在「Dataset ID」(資料集 ID) 中輸入 bqml_tutorial。

   • 針對「Location type」(位置類型) 選取「Multi-region」(多區域)，然後選取「US (multiple regions in United States)」(us (多個美國區域))。

   • 其餘設定請保留預設狀態，然後按一下「Create dataset」(建立資料集)。

bq

如要建立新的資料集，請使用 bq mk 指令搭配 --location 旗標。如需可能的完整參數清單，請參閱 bq mk --dataset 指令參考資料。

1. 建立名為「bqml_tutorial」的資料集，並將資料位置設為「US」，以及說明設為「BigQuery ML tutorial dataset」：

   bq --location=US mk -d \
    --description "BigQuery ML tutorial dataset." \
    bqml_tutorial

   這個指令採用 -d 捷徑，而不是使用 --dataset 旗標。如果您省略 -d 和 --dataset，該指令預設會建立資料集。

2. 確認資料集已建立完成：

   bq ls

API

請呼叫 datasets.insert 方法，搭配已定義的資料集資源。

{
  "datasetReference": {
     "datasetId": "bqml_tutorial"
  }
}

BigQuery DataFrames

在嘗試這個範例之前，請按照使用 BigQuery DataFrames 的 BigQuery 快速入門導覽課程中的 BigQuery DataFrames 設定說明操作。 詳情請參閱 BigQuery DataFrames 參考說明文件。

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

import google.cloud.bigquery

bqclient = google.cloud.bigquery.Client()
bqclient.create_dataset("bqml_tutorial", exists_ok=True)

建立連線

建立 Cloud 資源連線，並取得連線的服務帳戶。在與上一步建立的資料集相同的位置中建立連線。

如果已設定預設連線，或您具備 BigQuery 管理員角色，則可略過這個步驟。

建立供遠端模型使用的Cloud 資源連線，並取得連線的服務帳戶。在與上一步建立的資料集相同的位置中建立連線。

選取下列選項之一：

主控台

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 在「Explorer」窗格中，按一下 「新增資料」：

   

   「新增資料」對話方塊隨即開啟。

3. 在「依條件篩選」窗格的「資料來源類型」部分，選取「商務應用程式」。

   或者，您也可以在「Search for data sources」(搜尋資料來源) 欄位中輸入 Vertex AI。

4. 在「精選資料來源」部分，按一下「Vertex AI」。

5. 按一下「Vertex AI Models: BigQuery Federation」解決方案資訊卡。

6. 在「連線類型」清單中，選取「Vertex AI 遠端模型、遠端函式和 BigLake (Cloud 資源)」。

7. 在「連線 ID」欄位中，輸入連線名稱。

8. 點選「建立連線」。

9. 按一下「前往連線」。

10. 在「連線資訊」窗格中，複製服務帳戶 ID，以供後續步驟使用。

bq

1. 在指令列環境中建立連線：

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   --project_id 參數會覆寫預設專案。

   更改下列內容：

   • REGION：您的連線區域
   • PROJECT_ID：您的 Google Cloud 專案 ID
   • CONNECTION_ID：連線的 ID

   建立連線資源時，BigQuery 會建立專屬的系統服務帳戶，並將其與連線建立關聯。

   疑難排解：如果收到下列連線錯誤訊息，請更新 Google Cloud SDK：

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. 擷取並複製服務帳戶 ID，以供後續步驟使用：

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   輸出結果會與下列內容相似：

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

使用 google_bigquery_connection 資源。

注意： 如要使用 Terraform 建立 BigQuery 物件，請務必啟用 Cloud Resource Manager API。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會在 US 地區中建立名為 my_cloud_resource_connection 的 Cloud 資源連線：

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   每項專案只需要執行一次這個指令，且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在學習教學課程，可以複製每個章節或步驟中的範例程式碼。

   將範例程式碼複製到新建立的 main.tf。

   視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您使用這個方法。

3. 查看並修改範例參數，套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 檢查設定，確認 Terraform 即將建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，並在提示中輸入 yes，即可套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

注意：Terraform 範例通常會假設您已在 Google Cloud 專案中啟用必要的 API。

授予服務帳戶存取權

為連線的服務帳戶授予 Vertex AI 使用者角色。您必須在「事前準備」一節中建立或選取的專案中，授予這項角色。在其他專案中授予角色會導致 [e-mail] does not have the permission to access resource 錯誤。

如要授予角色，請按照下列步驟操作：

1. 前往「IAM & Admin」(IAM 與管理) 頁面。

   前往「IAM & Admin」(IAM 與管理)

2. 按一下 「授予存取權」。

3. 在「新增主體」欄位，輸入先前複製的服務帳戶 ID。

4. 在「請選擇角色」欄位中，選擇「Vertex AI」，然後選取「Vertex AI 使用者」角色。

5. 按一下 [儲存]。

建立遠端模型，用於生成文字嵌入

建立代表代管 Vertex AI 文字嵌入生成模型的遠端模型：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在查詢編輯器中執行下列陳述式：

   CREATE OR REPLACE MODEL `bqml_tutorial.embedding_model`
     REMOTE WITH CONNECTION `us.CONNECTION_ID`
     OPTIONS (ENDPOINT = 'text-embedding-005');

   將 CONNECTION_ID 替換為 BigQuery 連線的 ID。

   在 Google Cloud 控制台中查看連線詳細資料時，CONNECTION_ID 是「連線 ID」中顯示的完整連線 ID 最後一個區段的值，例如 projects/myproject/locations/connection_location/connections/myconnection。

   查詢作業會在幾秒內完成，完成後，模型 embedding_model 會顯示在「Explorer」(探索工具) 窗格的 bqml_tutorial 資料集中。由於查詢是使用 CREATE MODEL 陳述式建立模型，因此不會有查詢結果。

生成文字嵌入

使用 ML.GENERATE_EMBEDDING 函式從專利摘要生成文字嵌入，然後將這些嵌入寫入 BigQuery 資料表，以便進行搜尋。

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在查詢編輯器中執行下列陳述式：

   CREATE OR REPLACE TABLE `bqml_tutorial.embeddings` AS
   SELECT * FROM ML.GENERATE_EMBEDDING(
     MODEL `bqml_tutorial.embedding_model`,
     (
       SELECT *, abstract AS content
       FROM `patents-public-data.google_patents_research.publications`
       WHERE LENGTH(abstract) > 0 AND LENGTH(title) > 0 AND country = 'Singapore'
     )
   )
   WHERE LENGTH(ml_generate_embedding_status) = 0;

這項查詢大約需要 5 分鐘才能完成。

使用 ML.GENERATE_EMBEDDING 函式產生嵌入可能會失敗，原因可能是 Vertex AI LLM 配額或服務無法使用。錯誤詳細資料會傳回至 ml_generate_embedding_status 欄。如果資料欄為空白，表示成功產生嵌入內容。ml_generate_embedding_status

如要瞭解 BigQuery 中其他產生文字嵌入的方法，請參閱使用預先訓練的 TensorFlow 模型嵌入文字教學課程。

建立向量索引

如果您在嵌入欄上建立向量索引，對該欄執行的向量搜尋會使用近似最鄰近搜尋技術。這項技術可提升向量搜尋效能，但會降低召回率，因此傳回的結果會更近似。

如要建立向量索引，請使用 CREATE VECTOR INDEX 資料定義語言 (DDL) 陳述式：

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 在查詢編輯器中執行下列 SQL 陳述式：

   CREATE OR REPLACE VECTOR INDEX my_index
   ON `bqml_tutorial.embeddings`(ml_generate_embedding_result)
   OPTIONS(index_type = 'IVF',
     distance_type = 'COSINE',
     ivf_options = '{"num_lists":500}')

建立向量索引通常只需要幾秒鐘的時間。向量索引需要再 2 到 3 分鐘才能填入資料並供您使用。

確認向量索引是否準備就緒

系統會以非同步方式填入向量索引。您可以查詢 INFORMATION_SCHEMA.VECTOR_INDEXES 檢視區塊，並確認 coverage_percentage 欄值大於 0，且 last_refresh_time 欄值不是 NULL，藉此檢查索引是否已可供使用。

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 在查詢編輯器中執行下列 SQL 陳述式：

   SELECT table_name, index_name, index_status,
   coverage_percentage, last_refresh_time, disable_reason
   FROM `PROJECT_ID.bqml_tutorial.INFORMATION_SCHEMA.VECTOR_INDEXES`

   將 PROJECT_ID 替換為您的專案 ID。

使用向量索引執行文字相似度搜尋

使用 VECTOR_SEARCH 函式，搜尋與文字查詢產生的嵌入項目相符的相關專利。

top_k 引數會決定要傳回的相符項目數量，在本例中為五個。fraction_lists_to_search 選項會決定要搜尋的向量索引清單百分比。您建立的向量索引有 500 個清單，因此 .01 的 fraction_lists_to_search 值表示這項向量搜尋會掃描其中五個清單。如這裡所示，fraction_lists_to_search 值越低，召回率就越低，但效能會越快。如要進一步瞭解向量索引清單，請參閱num_lists 向量索引選項。

您必須使用與要比較資料表相同的模型，才能在查詢中生成嵌入，否則搜尋結果不會準確。

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 在查詢編輯器中執行下列 SQL 陳述式：

   SELECT query.query, base.publication_number, base.title, base.abstract
   FROM VECTOR_SEARCH(
     TABLE `bqml_tutorial.embeddings`, 'ml_generate_embedding_result',
     (
     SELECT ml_generate_embedding_result, content AS query
     FROM ML.GENERATE_EMBEDDING(
     MODEL `bqml_tutorial.embedding_model`,
     (SELECT 'improving password security' AS content))
     ),
     top_k => 5, options => '{"fraction_lists_to_search": 0.01}')

   輸出結果會與下列內容相似：

   +-----------------------------+--------------------+-------------------------------------------------+-------------------------------------------------+
   |            query            | publication_number |                       title                     |                      abstract                   |
   +-----------------------------+--------------------+-------------------------------------------------+-------------------------------------------------+
   | improving password security | SG-120868-A1       | Data storage device security method and a...    | Methods for improving security in data stora... |
   | improving password security | SG-10201610585W-A  | Passsword management system and process...      | PASSSWORD MANAGEMENT SYSTEM AND PROCESS ...     |
   | improving password security | SG-148888-A1       | Improved system and method for...               | IMPROVED SYSTEM AND METHOD FOR RANDOM...        |
   | improving password security | SG-194267-A1       | Method and system for protecting a password...  | A system for providing security for a...        |
   | improving password security | SG-120868-A1       | Data storage device security...                 | Methods for improving security in data...       |
   +-----------------------------+--------------------+-------------------------------------------------+-------------------------------------------------+
   

建立文字生成遠端模型

建立代表代管 Vertex AI 文字生成模型的遠端模型：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在查詢編輯器中執行下列陳述式：

   CREATE OR REPLACE MODEL `bqml_tutorial.text_model`
     REMOTE WITH CONNECTION `us.CONNECTION_ID`
     OPTIONS (ENDPOINT = 'gemini-1.5-flash-002');

   將 CONNECTION_ID 替換為 BigQuery 連線的 ID。

   在 Google Cloud 控制台中查看連線詳細資料時，CONNECTION_ID 是「連線 ID」中顯示的完整連線 ID 最後一個區段的值，例如 projects/myproject/locations/connection_location/connections/myconnection。

   查詢作業會在幾秒內完成，完成後，模型 text_model 會顯示在「Explorer」(探索工具) 窗格的 bqml_tutorial 資料集中。由於查詢是使用 CREATE MODEL 陳述式建立模型，因此不會有查詢結果。

根據向量搜尋結果生成文字

將搜尋結果做為提示，使用 ML.GENERATE_TEXT 函式生成文字

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在查詢編輯器中執行下列陳述式：

   SELECT ml_generate_text_llm_result AS generated, prompt
   FROM ML.GENERATE_TEXT(
     MODEL `bqml_tutorial.text_model`,
     (
       SELECT CONCAT(
         'Propose some project ideas to improve user password security using the context below: ',
         STRING_AGG(
           FORMAT("patent title: %s, patent abstract: %s", base.title, base.abstract),
           ',\n')
         ) AS prompt,
       FROM VECTOR_SEARCH(
         TABLE `bqml_tutorial.embeddings`, 'ml_generate_embedding_result',
         (
           SELECT ml_generate_embedding_result, content AS query
           FROM ML.GENERATE_EMBEDDING(
             MODEL `bqml_tutorial.embedding_model`,
            (SELECT 'improving password security' AS content)
           )
         ),
       top_k => 5, options => '{"fraction_lists_to_search": 0.01}')
     ),
     STRUCT(600 AS max_output_tokens, TRUE AS flatten_json_output));

   輸出結果會與下列內容相似：

   +------------------------------------------------+------------------------------------------------------------+
   |            generated                           | prompt                                                     |
   +------------------------------------------------+------------------------------------------------------------+
   | These patents suggest several project ideas to | Propose some project ideas to improve user password        |
   | improve user password security.  Here are      | security using the context below: patent title: Active     |
   | some, categorized by the patent they build     | new password entry dialog with compact visual indication   |
   | upon:                                          | of adherence to password policy, patent abstract:          |
   |                                                | An active new password entry dialog provides a compact     |
   | **I. Projects based on "Active new password    | visual indication of adherence to password policies. A     |
   | entry dialog with compact visual indication of | visual indication of progress towards meeting all          |
   | adherence to password policy":**               | applicable password policies is included in the display    |
   |                                                | and updated as new password characters are being...        |
   +------------------------------------------------+------------------------------------------------------------+
    

清除所用資源

注意：刪除專案會造成以下結果：

• 專案中的所有內容都會遭到刪除。 如果您使用現有專案來進行本文中的工作，刪除專案將一併刪除其中已完成的所有工作。
• 自訂的專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。

如果打算探索多種架構、教學課程或快速入門導覽課程，重複使用專案有助於避免超出專案配額限制。

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

後續步驟

• 請參閱「在檢索增強生成 pipeline 中剖析 PDF」教學課程，瞭解如何根據剖析的 PDF 內容建立 RAG pipeline。