針對文件和 API 呼叫進行 QA 的 GenAI Agent

1. 總覽

在本研究室中，您將建立 GenAI 代理程式，將其連結至 Cloud Run 應用程式，並將代理程式整合至 Slack 工作區。

學習目標

本實驗室分為幾個主要部分：

• 部署 Cloud Run 應用程式，以便整合 Gemini API
• 建立及部署 Vertex AI Agent
• 將 Agent 整合至 Slack
• 設定 PDF 文件問答資料儲存庫

必要條件

• 本實驗室假設您已熟悉 Cloud 控制台和 Cloud Shell 環境。

2. 設定和需求

Cloud 專案設定

1. 登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果您還沒有 Gmail 或 Google Workspace 帳戶，請務必建立帳戶。

• 「Project name」是這個專案參與者的顯示名稱。這是 Google API 不會使用的字元字串。您隨時可以更新。
• 專案 ID 在所有 Google Cloud 專案中都是不重複的值，且無法變更 (設定後即無法變更)。Cloud 控制台會自動產生專屬字串，您通常不需要特別留意。在大多數程式碼研究室中，您都需要參照專案 ID (通常會以 PROJECT_ID 表示)。如果您不喜歡系統產生的 ID，可以隨機產生另一個 ID。或者，您也可以自行嘗試，看看是否可用。在這個步驟完成後就無法變更，且會在整個專案期間維持不變。
• 提醒您，有些 API 會使用第三個值「專案編號」。如要進一步瞭解這三個值，請參閱說明文件。

注意：專案 ID 在全球範圍內是唯一的，選取後就無法由其他人使用。你是該 ID 的唯一使用者。即使刪除專案，也無法再次使用該 ID

注意：如果你使用 Gmail 帳戶，可以將預設位置設為「無機構」。如果你使用 Google Workspace 帳戶，請選擇貴機構適用的位置。

2. 接下來，您需要在 Cloud 控制台中啟用帳單功能，才能使用 Cloud 資源/API。執行這個程式碼研究室不會產生太多費用，甚至可能完全不會產生費用。如要關閉資源，避免在本教學課程結束後繼續產生費用，您可以刪除建立的資源或專案。Google Cloud 新使用者可享有價值 $300 美元的免費試用期。

環境設定

開啟 Gemini 對話。

啟用 Cloud AI Companion API：

按一下「Start chatting」，然後按照其中一個範例問題操作，或自行輸入提示，即可試用這項功能。

建議提示：

• 以 5 個重點說明 Cloud Run。
• 您是 Google Cloud Run 產品經理，請向學生解釋 Cloud Run 的 5 個重點。
• 您是 Google Cloud Run 產品經理，向 Kubernetes 認證開發人員解釋 Cloud Run 的 5 大重點。
• 您是 Google Cloud Run 產品經理，請向資深開發人員說明在哪些情況下應使用 Cloud Run 而非 GKE，並以 5 個重點說明。

詳情請參閱提示指南，進一步瞭解如何撰寫更優質的提示。

Gemini for Google Cloud 如何使用您的資料

Google 的隱私權承諾

Google 是第一間發表 AI/機器學習隱私權承諾的公司，該文提到我們的信念：除了極致的安全性之外，客戶也應該對儲存在雲端的自家資料保有最大的掌控權。

您提交及收到的資料

您向 Gemini 提出的問題，包括您提交給 Gemini 以便分析或完成的任何輸入資訊或程式碼，都稱為提示。您從 Gemini 收到的答案或程式碼完成作業稱為回覆。Gemini 不會將您的提示或回覆內容做為模型訓練資料。

提示訊息加密

向 Gemini 提交提示時，您的資料會在傳輸過程中經過加密，並做為輸入內容傳送至 Gemini 中的基礎模型。

由 Gemini 產生的節目資料

Gemini 是根據第一方 Google Cloud 程式碼和精選第三方程式碼進行訓練。您必須負責程式碼的安全性、測試和效能，包括 Gemini 提供的任何程式碼完成、產生或分析功能。

進一步瞭解 Google 如何處理提示。

3. 測試提示的選項

您可以透過多種方式測試提示。

• Vertex AI Studio

Vertex AI Studio 是 Google Cloud Vertex AI 平台的一部分，專門用於簡化及加速生成式 AI 模型的開發與使用。

• Google AI Studio

Google AI Studio 是網頁式工具，可用於設計原型，並透過提示設計和 Gemini API 進行實驗。

• Gemini 網頁應用程式 (gemini.google.com)

Google Gemini 網頁應用程式 (gemini.google.com) 是一項網頁式工具，可協助您探索並運用 Google Gemini AI 模型的強大功能。

• Android 版和 iOS 版的 Google Gemini 行動應用程式

4. 複製存放區

返回 Google Cloud 控制台，然後按一下搜尋列右側的圖示，啟用 Cloud Shell。

在已開啟的終端機中執行下列指令

git clone https://github.com/GoogleCloudPlatform/genai-for-developers.git

cd genai-for-developers

git checkout slack-agent-jira-lab

按一下「開啟編輯器」

使用「File / Open Folder」選單項目開啟「genai-for-developers」。

開啟新的終端機

5. 建立服務帳戶

建立新的服務帳戶和金鑰。

您將使用這個服務帳戶，從 Cloud Run 應用程式向 Vertex AI Gemini API 發出 API 呼叫。

使用 Qwiklabs 專案詳細資料設定專案詳細資料。

範例：qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR_QWIKLABS_PROJECT_ID

建立服務帳戶並授予角色。

export LOCATION=us-central1
export PROJECT_ID=$(gcloud config get-value project)
export SERVICE_ACCOUNT_NAME='vertex-client'
export DISPLAY_NAME='Vertex Client'
export KEY_FILE_NAME='vertex-client-key'

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME --project $PROJECT_ID --display-name "$DISPLAY_NAME"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudbuild.builds.editor"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/artifactregistry.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/secretmanager.secretAccessor"


gcloud iam service-accounts keys create $KEY_FILE_NAME.json --iam-account=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

如果系統提示您授權，請按一下「授權」繼續操作。

啟用必要服務，以便使用 Vertex AI API 和 Gemini 聊天功能。

gcloud services enable \
    generativelanguage.googleapis.com \
    aiplatform.googleapis.com \
    cloudaicompanion.googleapis.com \
    run.googleapis.com \
    cloudresourcemanager.googleapis.com

啟用必要服務，以便使用 Vertex AI API 和 Gemini 聊天功能。

gcloud services enable \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    runapps.googleapis.com \
    workstations.googleapis.com \
    servicemanagement.googleapis.com \
    secretmanager.googleapis.com \
    containerscanning.googleapis.com

啟用 Gemini Code Assist

按一下右下角的「Gemini」圖示，然後依序按一下「Sign-in」和「Select Google Cloud project」。

在彈出式視窗中，選取 qwiklabs 專案。

範例：

開啟檔案「devai-api/app/routes.py」，然後在檔案中任一處按一下滑鼠右鍵，並在內容選單中選取「Gemini Code Assist > Explain this"」。

查看 Gemini 針對所選檔案提供的說明。

6. 將 Devai-API 部署至 Cloud Run

確認你位於正確的資料夾。

cd ~/genai-for-developers/devai-api

在本實驗室中，我們會遵循最佳做法，並使用 Secret Manager 在 Cloud Run 中儲存及參照存取權杖和 LangChain API 金鑰值。

設定環境變數。

export JIRA_API_TOKEN=your-jira-token
export JIRA_USERNAME="YOUR-EMAIL"
export JIRA_INSTANCE_URL="https://YOUR-JIRA-PROJECT.atlassian.net"
export JIRA_PROJECT_KEY="YOUR-JIRA-PROJECT-KEY"
export JIRA_CLOUD=true

export GITLAB_PERSONAL_ACCESS_TOKEN=your-gitlab-token
export GITLAB_URL="https://gitlab.com"
export GITLAB_BRANCH="devai"
export GITLAB_BASE_BRANCH="main"
export GITLAB_REPOSITORY="GITLAB-USERID/GITLAB-REPO"

export LANGCHAIN_API_KEY=your-langchain-key
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"

將 JIRA 存取權杖儲存在 Secret Manager 中。

echo -n $JIRA_API_TOKEN | \
 gcloud secrets create JIRA_API_TOKEN \
 --data-file=-

將 GitLab 存取權杖儲存在 Secret Manager 中。

echo -n $GITLAB_PERSONAL_ACCESS_TOKEN | \
 gcloud secrets create GITLAB_PERSONAL_ACCESS_TOKEN \
 --data-file=-

將 LangChain API 金鑰儲存在 Secret Manager 中。

echo -n $LANGCHAIN_API_KEY | \
 gcloud secrets create LANGCHAIN_API_KEY \
 --data-file=-

將應用程式部署至 Cloud Run。

gcloud run deploy devai-api \
  --source=. \
  --region="$LOCATION" \
  --allow-unauthenticated \
  --service-account vertex-client \
  --set-env-vars PROJECT_ID="$PROJECT_ID" \
  --set-env-vars LOCATION="$LOCATION" \
  --set-env-vars GITLAB_URL="$GITLAB_URL" \
  --set-env-vars GITLAB_REPOSITORY="$GITLAB_REPOSITORY" \
  --set-env-vars GITLAB_BRANCH="$GITLAB_BRANCH" \
  --set-env-vars GITLAB_BASE_BRANCH="$GITLAB_BASE_BRANCH" \
  --set-env-vars JIRA_USERNAME="$JIRA_USERNAME" \
  --set-env-vars JIRA_INSTANCE_URL="$JIRA_INSTANCE_URL" \
  --set-env-vars JIRA_PROJECT_KEY="$JIRA_PROJECT_KEY" \
  --set-env-vars JIRA_CLOUD="$JIRA_CLOUD" \
  --set-env-vars LANGCHAIN_TRACING_V2="$LANGCHAIN_TRACING_V2" \
  --update-secrets="LANGCHAIN_API_KEY=LANGCHAIN_API_KEY:latest" \
  --update-secrets="GITLAB_PERSONAL_ACCESS_TOKEN=GITLAB_PERSONAL_ACCESS_TOKEN:latest" \
  --update-secrets="JIRA_API_TOKEN=JIRA_API_TOKEN:latest" \
  --min-instances=1 \
  --max-instances=3

回答 Y 以建立 Artifact Registry Docker 存放區。

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in 
region [us-central1] will be created.

Do you want to continue (Y/n)?  y

請 Gemini 說明指令：

請查看下方的 gcloud run deploy SERVICE_NAME --source=. 流程。瞭解詳情。

在幕後，這個指令會使用 Google Cloud 的 buildpacks 和 Cloud Build，自動從原始碼建構容器映像檔，不必在電腦上安裝 Docker 或設定 Buildpacks 或 Cloud Build。也就是說，上述單一指令可執行原本需要 gcloud builds submit 和 gcloud run deploy 指令才能執行的動作。

如果您已提供 Dockerfile(我們在這個存放區中已提供)，Cloud Build 就會使用該檔案建構容器映像檔，而不會依賴 Buildpack 自動偵測及建構容器映像檔。如要進一步瞭解 Buildpack，請參閱說明文件。

在 控制台中查看 Cloud Build 記錄。

在 Artifact Registry 中查看已建立的 Docker 映像檔。

開啟 cloud-run-source-deploy/devai-api，查看系統自動偵測到的安全漏洞。檢查是否有修正程式可用，並根據說明瞭解如何修正。

在 Cloud Console 中查看 Cloud Run 執行個體詳細資料。

執行 curl 指令測試端點。

curl -X POST \
   -H "Content-Type: application/json" \
   -d '{"prompt": "PROJECT-100"}' \
   $(gcloud  run services list --filter="(devai-api)" --format="value(URL)")/generate

查看輸出內容：

7. Vertex AI Agent Builder

搜尋並開啟「Agent Builder」。

啟動 API

建立虛擬服務專員應用程式：

輸入「代理人」做為顯示名稱，然後按一下「同意並建立」。

設定虛擬服務專員名稱：

Agent

設定目標：

Help user with questions about JIRA project

設定操作說明：

- Greet the users, then ask how you can help them today.
- Summarize the user's request and ask them to confirm that you understood correctly.
  - If necessary, seek clarifying details.
- Thank the user for their business and say goodbye.

按一下「儲存」：

使用模擬器聊天功能測試服務專員：

開啟「工具」選單並建立新的工具：

從「類型」下拉式選單中選取 OpenAPI。

設定工具名稱：

jira-project-status

設定說明：

Returns JIRA project status

設定結構定義 (YAML) - 請將「YOUR CLOUD RUN URL」替換為您的 Cloud Run 網址。

openapi: 3.0.0
info:
 title: CR API
 version: 1.0.0
 description: >-
   This is the OpenAPI specification of a service.
servers:
 - url: 'https://YOUR CLOUD RUN URL'
paths:
 /create-jira-issue:
   post:
     summary: Request impl
     operationId: create-jira-issue
     requestBody:
       description: Request impl
       required: true
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Prompt'
     responses:
       '200':
         description: Generated
         content:
           application/json:
             schema:
               type: string
 /generate:
   post:
     summary: Request impl
     operationId: generate
     requestBody:
       description: Request impl
       required: true
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Prompt'
     responses:
       '200':
         description: Generated
         content:
           application/json:
             schema:
               type: string

 /test:
   get:
     summary: Request impl
     operationId: test
     responses:
       '200':
         description: Generated
         content:
           application/json:
             schema:
               type: string                    
components:
 schemas:
   Prompt:
     type: object
     required:
       - prompt
     properties:
       prompt:
         type: string

儲存工具設定：

返回代理程式設定，並更新使用工具的操作說明：

新增操作說明，說明如何使用新工具：

- Use ${TOOL: jira-project-status} to help the user with JIRA project status.

切換至「示例」分頁並新增示例：

設定顯示名稱：

jira-project-flow

使用底部的選單，模擬使用者和服務專員之間的對話：

工具叫用設定：

按一下「儲存」和「取消」。返回 Agent 模擬器並測試流程。

查看 Vertex AI Agents 的最佳做法

代理程式設定

記錄設定

模型設定。

GitGub 整合功能，用於推送及還原代理程式設定。

代理程式模擬器控制項：

8. Slack 整合

開啟「整合」選單，然後按一下 Slack 資訊方塊上的「連結」。

開啟連結，並在 https://api.slack.com/apps 建立新的 Slack 應用程式

選取「資訊清單」：

選擇用於開發應用程式的工作區

切換至 YAML 並貼上此資訊清單：

display_information:
  name: Agent
  description: Agent
  background_color: "#1148b8"
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: Agent
    always_online: true
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - chat:write
      - im:history
      - im:read
      - im:write
      - incoming-webhook
settings:
  event_subscriptions:
    request_url: https://dialogflow-slack-4vnhuutqka-uc.a.run.app
    bot_events:
      - app_mention
      - message.im
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

按一下「建立」：

安裝至工作區：

選取「#general」頻道，然後按一下「允許」

在「基本資訊 / 應用程式憑證」下方，複製「簽署密鑰」，並在 Slack 整合中設定。

開啟「OAuth 和權限」，複製「機器人使用者 OAuth 權杖」，然後在 Slack 整合中設定。

設定必要欄位，然後按一下「開始」。

代理人的「存取權杖」值為 Slack 的「機器人使用者 OAuth 權杖」。

代理人的「Signing Token」值為 Slack 的「Signing Secret」。

複製「Webhook 網址」並返回 Slack 應用程式設定。

開啟「事件訂閱」部分，然後貼上網址。

儲存變更。

開啟「Slack」，然後輸入「@Agent」新增服務專員。

例如新增名稱為「@CX」的應用程式。

請服務專員提供 JIRA 專案摘要。

9. 針對 PDF 文件進行問答

建立 Cloud Storage 值區

在 Cloud 控制台中開啟 GCS：https://console.cloud.google.com/storage/browser

建立新的值區。

值區名稱：輸入「pdf-docs」+ GCP 專案的最後 5 個數字。

位置類型：multi-region, us。

儲存空間級別：Standard

存取控管：Uniform

資料保護：uncheck soft delete policy

請按一下 [Create]。

確認「系統會禁止公開存取」。

下載 PDF 報表並上傳至值區。https://services.google.com/fh/files/misc/exec_guide_gen_ai.pdf

上傳檔案檢視畫面中的值區：

資料儲存庫設定

返回「Agent 控制台」，開啟「Agent」，然後向下捲動並點選「+ Data store」。

請使用下列值：

工具名稱：pdf-docs

類型：Data store

說明：pdf-docs

按一下「Save」

按一下頁面底部的「Create a data store」。

當系統詢問「是否同意在美國區域中建立搜尋與對話資料儲存庫？」時，請按一下「AGREE」。

在「提供公司」欄位中輸入「Google」。

在下一個畫面中，按一下「CREATE DATA STORE」。

選取「Cloud Storage」做為資料來源。

準備要擷取的資料

https://cloud.google.com/generative-ai-app-builder/docs/prepare-data

HTML 和 TXT 檔案的大小不得超過 2.5 MB。

PDF、PPTX 和 DOCX 檔案的大小不得超過 100 MB。

一次最多可匯入 100,000 個檔案。

選取：unstructured documents

並選取 GCS 值區/資料夾。

按一下「繼續」：

資料儲存庫名稱類型：pdf-docs

在下拉式選單中選取「Digital parser」。

啟用進階分塊功能。

在分塊中啟用祖系標題。

請按一下 [Create]。

選取資料儲存庫，然後按一下「Create」

按一下資料儲存庫，並查看「文件」、「活動」和「處理設定」。

匯入作業大約需要 5 到 10 分鐘才能完成。

剖析和分割選項

您可以透過下列方式控制內容剖析：

• 數位剖析器。除非指定其他剖析器類型，否則系統會預設為為所有檔案類型啟用數位剖析器。如果資料儲存庫未指定其他預設剖析器，或是指定的剖析器不支援攝入文件的檔案類型，數位剖析器就會處理攝入的文件。
• PDF OCR 剖析。公開測試版。如果您打算上傳掃描的 PDF 檔案，或圖片內含文字的 PDF 檔案，可以開啟 OCR 剖析器，改善 PDF 索引。請參閱「關於 PDF 光學字元辨識剖析」。
• 版面配置剖析器。公開測試版。如果您打算將 Vertex AI Search 用於 RAG，請為 HTML、PDF 或 DOCX 檔案啟用版面配置剖析器。如要瞭解這個剖析器的相關資訊，以及如何啟用剖析器，請參閱「RAG 的區塊文件」。

進一步瞭解如何剖析文件及進行分塊。

工具設定

返回設定工具的分頁。

重新整理瀏覽器，然後從「Unstructured」下拉式選單中選取「pdf-docs」。

設定接地。

輸入「Google」做為公司名稱。

酬載設定 - 勾選「Include snippets in the response payload」

請按一下 [Save]。

代理程式的操作說明設定

返回代理程式設定。

新增操作說明：

- Provide detailed answer to users questions about the exec guide to gen ai using information in the ${TOOL:pdf-docs}

儲存設定。

建立 PDF 文件工具範例

切換至「範例」分頁。建立新範例。

使用「+」動作：

新增「使用者輸入」：

What are the main capabilities?

新增「工具使用情形」。

• 工具和動作："pdf-docs"

輸入內容 (requestBody)

{
  "query": "Main capabilities",
  "filter": "",
  "userMetadata": {},
  "fallback": ""
}

工具輸出內容：

{
  "answer": "Detailed answer about main capabilities",
  "snippets": [
    {
      "uri": "https://storage.cloud.google.com/pdf-docs-49ca4/exec_guide_gen_ai.pdf",
      "text": "Detailed answer about main capabilities",
      "title": "exec_guide_gen_ai"
    }
  ]
}

新增「服務專員回覆」

Detailed answer about main capabilities. 

https://storage.cloud.google.com/pdf-docs-49ca4/exec_guide_gen_ai.pdf

設定範例：

工具叫用設定：

在模擬器中向 Google 助理發送問題，測試設定。

問題：

What are the 10 steps in the exec guide?

選取「Agent」，然後按一下「Save example」。

提供名稱「user-question-flow」，然後儲存。

請設定服務專員回應的格式，並在工具輸出區段中附上 PDF 文件的連結。

儲存範例。

返回模擬器，然後按一下「Replay conversation」。檢查更新後的回應格式。

提出其他問題：

What are the main capabilities in the exec guide?

來源 PDF 文件。

問題：

What should I consider when evaluating projects?

來源 PDF 文件。

問題：

What are the priority use cases in Retail and CPG in the exec guide?

來源 PDF 文件。

10. 預先建構的代理程式

透過左側選單探索預先建構的代理程式。

選取其中一個代理程式並部署。探索 Google 服務中心的設定、操作說明和工具。

11. 恭喜！

恭喜，您已完成實驗室！

涵蓋內容：

• 如何部署 Cloud Run 應用程式，以便與 Gemini API 整合
• 如何建立及部署 Vertex AI Agent
• 如何為代理程式新增 Slack 整合
• 如何設定 PDF 文件問答資料儲存庫

下一步：

• 查看 Vertex AI Agents 的最佳做法

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本教學課程所用資源的費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

刪除專案

如要避免付費，最簡單的方法就是刪除您為了本教學課程所建立的專案。

© 2024 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標，其他公司和產品名稱則有可能是其關聯公司的商標。