1. 總覽
在本實驗室中,您將建立 GenAI 代理程式、將其連線至 Cloud Run 應用程式,並將代理程式整合至 Slack 工作區。

學習目標
本實驗室主要分為幾個部分:
- 部署 Cloud Run 應用程式,與 Gemini API 整合
- 在 AI 應用程式中建立及部署對話式代理
- 將 Agent 整合至 Slack
- 設定資料儲存庫,以便對 PDF 文件進行問答
必要條件
- 本實驗室假設您已熟悉 Cloud 控制台和 Cloud Shell 環境。
2. 設定和需求
設定 Cloud 專案
- 登入 Google Cloud 控制台,然後建立新專案或重複使用現有專案。如果沒有 Gmail 或 Google Workspace 帳戶,請先建立帳戶。



- 專案名稱是這個專案參與者的顯示名稱。這是 Google API 未使用的字元字串。你隨時可以更新。
- 專案 ID 在所有 Google Cloud 專案中都是不重複的,而且設定後即無法變更。Cloud 控制台會自動產生專屬字串,通常您不需要在意該字串為何。在大多數程式碼研究室中,您需要參照專案 ID (通常標示為
PROJECT_ID)。如果您不喜歡產生的 ID,可以產生另一個隨機 ID。你也可以嘗試使用自己的名稱,看看是否可用。完成這個步驟後就無法變更,且專案期間會維持不變。 - 請注意,有些 API 會使用第三個值,也就是「專案編號」。如要進一步瞭解這三種值,請參閱說明文件。
- 接著,您需要在 Cloud 控制台中啟用帳單,才能使用 Cloud 資源/API。完成這個程式碼研究室的費用不高,甚至可能完全免費。如要關閉資源,避免在本教學課程結束後繼續產生費用,請刪除您建立的資源或專案。Google Cloud 新使用者可參加價值$300 美元的免費試用計畫。
環境設定
開啟 Gemini 對話。

啟用 Gemini for Google Cloud API:


按一下「Start chatting」,然後按照其中一個範例問題操作,或自行輸入提示詞來試用。

建議提示詞:
- 請用 5 個重點說明 Cloud Run。
- 您是 Google Cloud Run 產品經理,請用 5 個簡短重點向學生說明 Cloud Run。
- 您是 Google Cloud Run 產品經理,請用 5 個簡短重點向認證 Kubernetes 開發人員說明 Cloud Run。
- 您是 Google Cloud Run 產品經理,請以 5 個簡短重點,向資深開發人員說明何時該使用 Cloud Run,何時該使用 GKE。
如要進一步瞭解如何撰寫更優質的提示,請參閱提示指南。
瞭解 Gemini for Google Cloud 如何使用您的資料
Google 對隱私權的承諾
Google 是業界首批發布 AI/機器學習隱私權承諾的公司,該文提到我們的信念:除了極致的安全性之外,客戶也應該對儲存在雲端的自家資料保有最大的掌控權。
您提交及收到的資料
您向 Gemini 提出的問題 (包括提交給 Gemini 分析或完成的任何輸入資訊或程式碼),都稱為提示。您從 Gemini 取得的答案或程式碼完成建議稱為「回覆」。我們不會將您的提示詞或 Gemini 的回覆用做模型訓練資料。
提示加密
當您將提示提交給 Gemini 時,您的資料會在傳輸過程中加密,然後輸入 Gemini 的基礎模型。
Gemini 生成的節目資料
Gemini 是以 Google Cloud 第一方程式碼和精選第三方程式碼訓練而成。您必須對程式碼的安全性、測試和效用負責,包括 Gemini 提供的任何程式碼完成、生成或分析功能。
進一步瞭解 Google 如何處理提示。
3. 測試提示的選項
你可以透過多種方式測試提示。
Vertex AI Studio 是 Google Cloud Vertex AI 平台的一部分,專門用於簡化及加速生成式 AI 模型的開發和使用。
Google AI Studio 是網頁工具,可讓您設計提示工程原型,並透過 Gemini API 進行實驗。
- Gemini 網頁應用程式 (gemini.google.com)
Google Gemini 網頁應用程式 (gemini.google.com) 是一款網頁工具,可協助您探索及運用 Google Gemini AI 模型強大的功能。
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'
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"
啟用必要服務,即可使用 Vertex AI API 和 Gemini 對話。
gcloud services enable \
generativelanguage.googleapis.com \
aiplatform.googleapis.com \
cloudaicompanion.googleapis.com \
dialogflow.googleapis.com \
run.googleapis.com \
cloudresourcemanager.googleapis.com \
discoveryengine.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 解釋程式碼
開啟「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"
在 Secret Manager 中建立及儲存多個密鑰。
echo -n $JIRA_API_TOKEN | \
gcloud secrets create JIRA_API_TOKEN \
--data-file=-
echo -n $GITLAB_PERSONAL_ACCESS_TOKEN | \
gcloud secrets create GITLAB_PERSONAL_ACCESS_TOKEN \
--data-file=-
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 說明指令:
What does this command do?
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

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

在幕後,這項指令會使用 Google Cloud 的 buildpacks 和 Cloud Build,從您的原始碼自動建構容器映像檔,而不必在機器上安裝 Docker,也不必設定 Buildpacks 或 Cloud Build。也就是說,上述單一指令會執行原本需要 gcloud builds submit 和 gcloud run deploy 指令才能執行的作業。
如果您已提供 Dockerfile(我們在這個存放區中就是這麼做),Cloud Build 就會使用該檔案建構容器映像檔,而不是依賴建構套件自動偵測及建構容器映像檔。如要進一步瞭解建構包,請參閱說明文件。
在 控制台中查看 Cloud Build 記錄。
在 Artifact Registry 中查看建立的 Docker 映像檔。
在 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
回覆內容會以 Markdown 格式呈現。以預覽模式顯示,方便閱讀。

7. AI 應用程式
在 Google Cloud 控制台搜尋列中輸入並開啟「AI Applications」。

建立 Conversational Agent 應用程式:

選取「Build your own」。

輸入顯示名稱的「Agent」,然後按一下「建立」。

設定應對手冊名稱:
Agent
設定目標:
Help users 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.
按一下「Save」:

使用右側的模擬工具對話方塊測試代理程式:

請參閱下方的類似對話:

代理程式工具設定
將滑鼠游標懸停在左側的扳手圖示上。開啟「工具」選單並建立新工具:

從「類型」下拉式選單中選取 OpenAPI。
設定工具名稱:
jira-project-status
設定說明:
Provides JIRA project status
切換分頁,檢查 Cloud Run 服務網址的控制台輸出內容。複製服務網址值。
設定結構定義 (YAML) - 取代 YOUR CLOUD RUN URL。
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:
/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:
$ref: '#/components/schemas/ProjectStatus'
components:
schemas:
Prompt:
type: object
required:
- prompt
properties:
prompt:
type: string
ProjectStatus:
type: object
required:
- message
properties:
message:
type: string
儲存工具設定:

選取左選單中的「Playbooks」,返回 Agent 設定並更新使用工具的指示:
新增使用新工具的操作說明,然後按一下「Save」:
- Use ${TOOL: jira-project-status} to help the user with JIRA project status.

切換至「Examples」分頁,然後新增範例:

設定顯示名稱:
jira-project-flow
使用底部的選單,模擬使用者和代理程式之間的對話:
範例流程:
Agent response: What's the project id?
使用者輸入內容:TEST-PROJECT-100
工具使用:jira-project-status
專員回覆:專案狀態詳細資料。

請參考下文建立範例。


按一下 Save,返回「代理程式模擬器」,然後重設所有現有對話。測試流程。


恭喜!整合連結至 Cloud Run 部署應用程式(API) 的工具後,您已成功授權 Agent 執行動作,並擴充 Agent 的功能。

查看 Conversational Agents 的最佳做法
查看可用的代理程式設定
- 記錄設定 - 啟用 Cloud Logging
- Git 整合 - 您可以透過 Git 整合,從 Git 存放區推送及提取代理程式。
- 選擇生成模型
- 詞元限制(輸入和輸出)

查看代理程式模擬工具控制項:

8. Slack 整合
開啟「整合」選單,然後按一下 Slack 圖塊上的「Connect」。



開啟連結並在 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
按一下「建立」:

安裝至 Workspace:

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

在「Basic Information / App Credentials」下方,複製「Signing Secret」,並在 Agent 的 Slack 整合中,將其設為「Signing Token」欄位的值。


開啟「OAuth & Permissions」,複製「Bot User OAuth Token」,並在 Agent 的 Slack 整合中,將其設為「存取權杖」欄位的值。

設定必填欄位,然後按一下「開始」。
代理程式的「Access Token」(存取權杖) 值是 Slack 的「Bot User OAUth Token」(機器人使用者 OAuth 權杖)。
代理程式的「簽署權杖」值是 Slack 的「簽署密鑰」。


複製「Webhook 網址」,然後返回 Slack 應用程式設定。
開啟「事件訂閱」部分,然後貼上網址。

儲存變更。

開啟「Slack」,然後輸入「@Agent」新增代理。
例如新增名為「@CX」的應用程式。



請專員提供 JIRA 專案摘要。

恭喜!代理程式已成功整合至 Slack 工作區。

9. PDF 文件問與答
本節說明如何使用 PDF 文件建立資料儲存庫,並將其連結至 Agent,根據文件內容啟用問與答功能。
建立 Cloud Storage bucket
開啟 Cloud Shell:https://shell.cloud.google.com/
使用 GCP 專案的最後 5 位數設定 bucket 名稱。範例:pdf-docs-3dw21
BUCKET_NAME=pdf-docs-LAST-5-DIGITS-OF-YOUR-PROJECT
建立 bucket 並上傳 PDF 文件。
gcloud storage buckets create gs://$BUCKET_NAME \
--location=us \
--default-storage-class=STANDARD \
--no-public-access-prevention \
--uniform-bucket-level-access
wget https://services.google.com/fh/files/misc/exec_guide_gen_ai.pdf
gsutil cp exec_guide_gen_ai.pdf gs://$BUCKET_NAME
資料儲存庫設定
返回代理控制台並開啟「Agent」,向下捲動並點選「+ Data store」。

請使用下列值:
工具名稱:pdf-docs
類型:Data store
說明:pdf-docs
按一下「Save」

按一下頁面底部的「Add data stores」,然後按一下「Create new data store」。

選取「Cloud Storage」做為資料來源。
選取:Unstructured documents
然後選取 GCS bucket/資料夾。

選取資料儲存庫位置的「us」。
資料儲存庫名稱請輸入「pdf-docs」
從下拉式選單中選取「Digital parser」。
啟用進階分塊。
在分塊中啟用祖系標題。
請按一下 [Create]。


點選資料儲存庫,然後查看「文件」、「活動」和「處理設定」。

匯入作業大約需要 5 到 10 分鐘。

剖析和分塊選項
您可以透過下列方式控制內容剖析:
- 數位剖析器。除非指定其他剖析器類型,否則所有檔案類型預設都會使用數位剖析器。如果資料儲存庫未指定其他預設剖析器,或指定的剖析器不支援擷取文件的檔案類型,數位剖析器就會處理擷取的文件。
- PDF 的 OCR 剖析。公開預先發布版。如果您打算上傳掃描的 PDF 或內含圖片文字的 PDF,可以開啟 OCR 剖析器,提升 PDF 索引品質。請參閱「關於 PDF 的 OCR 剖析功能」。
- 版面配置剖析器。如果您打算將 Vertex AI Search 用於 RAG,請為 HTML、PDF 或 DOCX 檔案啟用版面配置剖析器。如要瞭解這個剖析器和如何啟用,請參閱「為 RAG 分塊文件」。
工具設定
返回「代理程式工具」設定畫面,然後重新整理可用的資料儲存庫。
選取剛建立的資料儲存庫,然後按一下「Confirm」。

設定依據。
輸入「Google Cloud」做為公司名稱。
酬載設定 - 勾選「Include snippets in Conversational Messenger response payload"」。將值設為 5。
按一下「儲存」。

設定代理程式的指令
返回代理程式設定。
新增指令:
- Provide detailed answer to users questions about the exec guide to gen ai using information in the ${TOOL:pdf-docs}

儲存設定。
為 PDF 文件工具建立範例
切換至「範例」分頁。建立新範例:Guide to generative AI
使用「+」動作:

新增「使用者輸入內容」:
What are the main capabilities for generative AI?
新增「工具使用」功能。
- 工具和動作:「
pdf-docs」
輸入 (requestBody)
{
"query": "Main capabilities for generative AI",
"filter": "",
"userMetadata": {},
"fallback": ""
}
工具輸出內容:
{
"answer": "Detailed answer about main capabilities for generative AI",
"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"
}
]
}
新增「Agent response」
Detailed answer about main capabilities.
https://storage.cloud.google.com/pdf-docs-49ca4/exec_guide_gen_ai.pdf
設定範例:

工具叫用設定:

切換至模擬器,測試設定。
問題:
What are the 10 steps in the exec guide?

從「呼叫」下拉式選單中選取「Agent」,然後按一下「Save as example」。

提供名稱「user-question-flow」。
設定摘要:「Agent helped user answer question based on the pdf document」,然後按一下「儲存」。
設定服務專員回覆格式,並在工具輸出內容部分加入 PDF 文件連結。

儲存範例。
返回模擬工具並點按「Replay conversation」,查看更新後的回覆格式。如果在儲存範例後看到錯誤訊息,可能需要重新整理瀏覽器視窗,然後再次傳送提示來重新啟動對話:
What are the 10 steps in the exec guide?

提出其他問題:
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 文件。

恭喜!現在代理可以根據 PDF 文件提供有根據的答案。

10. 預先建構的代理程式
接著,您要從左側選單探索預先建構的代理程式。

選取其中一個代理程式並部署。瞭解代理程式的設定、指令和工具。

11. 恭喜!
恭喜,您已完成本實驗室!
涵蓋內容:
- 如何建立及部署 Conversational Agents
- 如何為以 Cloud Run 應用程式為基礎的代理程式新增工具
- 如何將代理程式整合至 Slack 工作區
- 如何設定資料儲存庫,以便對 PDF 文件進行問答
後續步驟:
- 查看 Conversational Agents 的最佳做法
清除所用資源
如要避免系統向您的 Google Cloud 帳戶收取本教學課程所用資源的費用,請刪除含有相關資源的專案,或者保留專案但刪除個別資源。
刪除專案
如要避免付費,最簡單的方法就是刪除您為了本教學課程所建立的專案。
©2024 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標,所有其他公司和產品名稱可能是其關聯公司的商標。