透過 Cloud Run 服務，在 Cloud Storage 中的 PDF (非結構化資料) 使用 Vertex AI Search

1. 簡介

總覽

Vertex AI Search and Conversation (舊稱 Generative AI App Builder)，可讓開發人員運用 Google 基礎模型、搜尋專業知識和對話式 AI 技術，打造企業級的生成式 AI 應用程式。本程式碼研究室著重於使用 Vertex AI Search，讓您運用自己的資料建構品質媲美 Google 的搜尋應用程式，並在網頁或應用程式中嵌入搜尋列。

Cloud Run 是代管運算平台，可讓您在 Google 的可擴充基礎架構上直接執行容器。您可以使用「以原始碼為基礎的部署」選項，在 Cloud Run 中部署以任何程式設計語言編寫的程式碼 (能夠將程式碼放入容器中)。

在本程式碼研究室中，您將使用以原始碼為基礎的部署方式建立 Cloud Run 服務，以便擷取 Cloud Storage 值區中 PDF 檔案非結構化內容的搜尋結果。您可以進一步瞭解如何擷取非結構化內容。

課程內容

  • 如何針對從 Cloud Storage 值區擷取的非結構化資料 (以 PDF 格式擷取) 建立 Vertex AI Search 應用程式
  • 如何在 Cloud Run 中使用以來源為基礎的部署建立 HTTP 端點
  • 如何按照最低權限原則建立服務帳戶，讓 Cloud Run 服務查詢 Vertex AI Search 應用程式
  • 如何叫用 Cloud Run 服務來查詢 Vertex AI Search 應用程式

2. 設定和需求

必要條件

啟用 Cloud Shell

  1. 在 Cloud 控制台中，按一下「啟用 Cloud Shell」圖示 d1264ca30785e435.png。

cb81e7c8e34bc8d.png

如果您是第一次啟動 Cloud Shell，系統會顯示中繼畫面，說明這項服務的內容。如果系統顯示中繼畫面，請按一下「繼續」。

d95252b003979716.png

佈建並連線至 Cloud Shell 只需幾分鐘的時間。

7833d5e1c5d18f54.png

這個虛擬機器已載入所有必要的開發工具。提供永久的 5 GB 主目錄，而且在 Google Cloud 中運作，大幅提高網路效能和驗證能力。在本程式碼研究室中，您的大部分作業都可透過瀏覽器完成。

連線至 Cloud Shell 後，您應會發現自己通過驗證，且專案已設為您的專案 ID。

  1. 在 Cloud Shell 中執行下列指令，確認您已通過驗證：
gcloud auth list

指令輸出

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`
  1. 在 Cloud Shell 中執行下列指令，確認 gcloud 指令知道您的專案：
gcloud config list project

指令輸出

[core]
project = <PROJECT_ID>

如果尚未設定，請使用下列指令進行設定：

gcloud config set project <PROJECT_ID>

指令輸出

Updated property [core/project].

3. 啟用 API

您必須先啟用多個 API，才能開始使用 Vertex AI Search。

本程式碼研究室需要使用 Vertex AI Search and Conversation、BigQuery 和 Cloud Storage API。您可以在這裡啟用這些 API。

接著，請按照下列步驟啟用 Vertex AI Search and Conversation API：

  1. 前往 Google Cloud 控制台中的 Vertex AI Search and Conversation 控制台。
  2. 閱讀並同意《服務條款》，然後按一下「繼續」並啟用 API。

4. 針對 Cloud Storage 中的非結構化資料建立搜尋應用程式

  1. 在 Google Cloud 控制台中，前往搜尋和會話群組頁面。按一下「新增應用程式」。
  2. 在「Select app type」(選取應用程式類型) 窗格中，選取「Search」(搜尋)。
  3. 請確定已啟用 Enterprise 功能，以便接收系統從文件中逐字擷取的答案。
  4. 確認「進階 LLM 功能」選項已啟用，才能接收搜尋摘要。
  5. 在「應用程式名稱」欄位中，輸入應用程式名稱。您的應用程式 ID 會顯示在應用程式名稱下方。
  6. 選取「全球 (全球)」做為應用程式的位置，然後按一下「繼續」。
  7. 在「Data stores」(資料儲存庫) 窗格中，點選「Create new data store」(建立新的資料儲存庫)。
  8. 在「Select a data source」(選取資料來源) 窗格中，選取「Cloud Storage」。
  9. 在「Import data from GCS」(從 GCS 匯入資料) 窗格中，確認已選取「Folder」(資料夾)。
  10. 在 gs:// 欄位中輸入以下值：cloud-samples-data/gen-app-builder/search/stanford-cs-224 這個 Cloud Storage 值區內含公開 Cloud Storage 資料夾中的 PDF 檔案，以供測試之用。
  11. 選取「Unstructured documents」(非結構化文件)，然後按一下「Continue」(繼續)。
  12. 在「設定資料儲存庫」窗格中，選取「全域 (全球)」做為資料儲存庫的位置。
  13. 輸入資料儲存庫的名稱。您稍後在本程式碼研究室中部署 Cloud Run 服務時，會使用這個名稱。點選「Create」(建立)。
  14. 在「Data stores」(資料儲存庫) 窗格中，選取新的資料儲存庫，然後按一下「Create」(建立)。
  15. 在資料儲存庫的「資料」頁面中，按一下「活動」分頁標籤，即可查看資料擷取狀態。匯入程序完成後，「狀態」欄會顯示「匯入完成」。
  16. 按一下「Documents」(文件) 分頁標籤，即可查看匯入的文件數量。
  17. 在導覽選單中，按一下「Preview」，測試搜尋應用程式。
  18. 在搜尋列中輸入 final lab due date，然後按下 Enter 鍵，即可查看相關結果。

5. 建立 Cloud Run 服務

在本節中，您將建立 Cloud Run 服務，以便接受搜尋字詞的查詢字串。這項服務會使用 Discovery Engine API 的 Python 用戶端程式庫。如要查看其他支援的執行階段，請按這裡查看清單。

建立函式的原始碼

首先，建立目錄並以 cd 放入該目錄。

mkdir docs-search-service-python && cd $_

接著，建立含有以下內容的 requirements.txt 檔案：

blinker==1.6.3
cachetools==5.3.1
certifi==2023.7.22
charset-normalizer==3.3.0
click==8.1.7
Flask==3.0.0
google-api-core==2.12.0
google-auth==2.23.3
google-cloud-discoveryengine==0.11.2
googleapis-common-protos==1.61.0
grpcio==1.59.0
grpcio-status==1.59.0
idna==3.4
importlib-metadata==6.8.0
itsdangerous==2.1.2
Jinja2==3.1.2
MarkupSafe==2.1.3
numpy==1.26.1
proto-plus==1.22.3
protobuf==4.24.4
pyasn1==0.5.0
pyasn1-modules==0.3.0
requests==2.31.0
rsa==4.9
urllib3==2.0.7
Werkzeug==3.0.1
zipp==3.17.0

接著，建立含有以下內容的 main.py 來源檔案：

from typing import List
import json
import os
from flask import Flask
from flask import request

app = Flask(__name__)

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

project_id = os.environ.get('PROJECT_ID')
location = "global"  # Values: "global", "us", "eu"
data_store_id = os.environ.get('SEARCH_ENGINE_ID')

print(project_id)
print(data_store_id)

@app.route("/")
def search_storage():

    search_query = request.args.get("searchQuery")

    result = search_sample(project_id, location, data_store_id, search_query)
    return result

def search_sample(
    project_id: str,
    location: str,
    data_store_id: str,
    search_query: str,
) -> str:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.SearchServiceClient(client_options=client_options)

    # The full resource name of the search engine serving config
    # e.g. projects/{project_id}/locations/{location}/dataStores/{data_store_id}/servingConfigs/{serving_config_id}
    serving_config = client.serving_config_path(
        project=project_id,
        location=location,
        data_store=data_store_id,
        serving_config="default_config",
    )

    # Optional: Configuration options for search
    # Refer to the `ContentSearchSpec` reference for all supported fields:
    # https://cloud.google.com/python/docs/reference/discoveryengine/latest/google.cloud.discoveryengine_v1.types.SearchRequest.ContentSearchSpec
    content_search_spec = discoveryengine.SearchRequest.ContentSearchSpec(
        # For information about snippets, refer to:
        # https://cloud.google.com/generative-ai-app-builder/docs/snippets
        snippet_spec=discoveryengine.SearchRequest.ContentSearchSpec.SnippetSpec(
            return_snippet=True
        ),
        # For information about search summaries, refer to:
        # https://cloud.google.com/generative-ai-app-builder/docs/get-search-summaries
        summary_spec=discoveryengine.SearchRequest.ContentSearchSpec.SummarySpec(
            summary_result_count=5,
            include_citations=True,
            ignore_adversarial_query=True,
            ignore_non_summary_seeking_query=True,
        ),
    )


    # Refer to the `SearchRequest` reference for all supported fields:
    # https://cloud.google.com/python/docs/reference/discoveryengine/latest/google.cloud.discoveryengine_v1.types.SearchRequest
    request = discoveryengine.SearchRequest(
        serving_config=serving_config,
        query=search_query,
        page_size=10,
        content_search_spec=content_search_spec,
        query_expansion_spec=discoveryengine.SearchRequest.QueryExpansionSpec(
            condition=discoveryengine.SearchRequest.QueryExpansionSpec.Condition.AUTO,
        ),
        spell_correction_spec=discoveryengine.SearchRequest.SpellCorrectionSpec(
            mode=discoveryengine.SearchRequest.SpellCorrectionSpec.Mode.AUTO
        ),
    )

    response = client.search(request)

    return response.summary.summary_text

if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

設定環境變數

在這個程式碼中，您將建立幾個環境變數，以提高這個程式碼研究室中使用的 gcloud 指令可讀性。

PROJECT_ID=$(gcloud config get-value project)

SERVICE_NAME="search-storage-pdfs-python"
SERVICE_REGION="us-central1"

# update with your data store name
SEARCH_ENGINE_ID=<your-data-store-name>

建立服務帳戶

本程式碼研究室將說明如何建立 Cloud Run 服務的服務帳戶，以便存取 Vertex AI Search API。

SERVICE_ACCOUNT="cloud-run-vertex-ai-search"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com

gcloud iam service-accounts create $SERVICE_ACCOUNT \
  --display-name="Cloud Run Vertex AI Search service account"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role='roles/discoveryengine.editor'

部署 Cloud Run 服務

您現在可以使用以來源為基礎的部署，自動將 Cloud Run 服務容器化。

gcloud run deploy $SERVICE_NAME \
--region=$SERVICE_REGION \
--source=. \
--service-account $SERVICE_ACCOUNT \
--update-env-vars SEARCH_ENGINE_ID=$SEARCH_ENGINE_ID,PROJECT_ID=$PROJECT_ID \
--no-allow-unauthenticated

然後將 Cloud Run 網址儲存為環境變數，方便日後使用。

ENDPOINT_URL="$(gcloud run services describe $SERVICE_NAME --region=$SERVICE_REGION --format='value(status.url)')"

6. 呼叫 Cloud Run 服務

您現在可以使用查詢字串呼叫 Cloud Run 服務，要求 What is the final lab due date?。

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" "$ENDPOINT_URL?searchQuery=what+is+the+final+lab+due+date"

結果應該會與下方的範例輸出內容類似：

The final lab is due on Tuesday, March 21 at 4:30 PM [1].

7. 恭喜！

恭喜您完成本程式碼研究室！

建議您詳閱 Vertex AI Search 和 Cloud Run 的說明文件。

涵蓋內容

  • 如何針對從 Cloud Storage 值區擷取的非結構化資料 (以 PDF 格式擷取) 建立 Vertex AI Search 應用程式
  • 如何在 Cloud Run 中使用以來源為基礎的部署建立 HTTP 端點
  • 如何按照最低權限原則建立服務帳戶，讓 Cloud Run 服務查詢 Vertex AI Search 應用程式。
  • 如何叫用 Cloud Run 服務來查詢 Vertex AI Search 應用程式

8. 清除所用資源

為避免產生意外費用 (舉例來說，如果不小心叫用這個 Cloud 函式的次數超出免費方案的每月 Cloud 函式叫用分配數量)，您可以刪除 Cloud 函式或刪除步驟 2 中建立的專案。

如要刪除 Cloud 函式，請前往 Cloud 函式 (https://console.cloud.google.com/functions/)，然後刪除 imagen_vqa 函式 (若使用不同的名稱，則為 $FUNCTION_NAME)。

如果選擇刪除整個專案，您可以前往 https://console.cloud.google.com/cloud-resource-manager，選取您在步驟 2 建立的專案，然後選擇「刪除」。如果刪除專案，您必須變更 Cloud SDK 中的專案。您可以執行 gcloud projects list 來查看可用專案的清單。