程式碼研究室簡介
1. 總覽
在本研究室中，您將建立 GenAI Agent、將其連結至 Cloud Run 應用程式，並將這個服務整合至 Slack 工作區。
學習目標
本研究室包含幾個主要部分：
- 部署 Cloud Run 應用程式，以便整合 Gemini API
- 建立及部署對話式代理程式
- 將 Agent 整合至 Slack
- 設定 PDF 文件問答資料儲存庫
必要條件
- 本實驗室假設您已熟悉 Cloud 控制台和 Cloud Shell 環境。
2. 設定和需求
Cloud 專案設定
- 登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果您還沒有 Gmail 或 Google Workspace 帳戶，請務必建立帳戶。
- 「Project name」是這個專案參與者的顯示名稱。這是 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 產品經理，向學生解釋 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 是 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'
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"
如果系統要求您授權，請點選「授權」繼續操作。
啟用必要服務，以便使用 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 解釋程式碼
開啟檔案「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 就會使用該檔案建構容器映像檔，而不會依賴 Buildpack 自動偵測及建構容器映像檔。如要進一步瞭解 Buildpack，請參閱說明文件。
在 控制台中查看 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. Vertex AI Agent Builder
搜尋並開啟「Agent Builder」。
啟用 API：
建立對話型代理應用程式：
啟用 Dialogflow API：
選取專案：
按一下「建立虛擬服務專員」：
選取「自行建構」。
在「顯示名稱」欄位輸入「Agent」，然後按一下「建立」。
設定應對手冊名稱：
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
設定說明：
Provides JIRA project status
設定結構定義 (YAML) - 請將「YOUR CLOUD RUN URL」替換為您的 Cloud Run 網址。切換分頁，並檢查控制台輸出的 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:
/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
儲存工具設定：
選取左選單中的「Playbook」，即可返回 Agent 設定，並更新使用這項工具的操作說明：
新增操作說明，然後按一下「儲存」：
- Use ${TOOL: jira-project-status} to help the user with JIRA project status.
切換至「示例」分頁並新增示例：
設定顯示名稱：
jira-project-flow
使用底部的選單，模擬使用者和服務專員之間的對話：
範例流程：
服務專員回覆：專案 ID 是什麼？
使用者輸入內容：TEST-PROJECT-100
工具用途：jira-project-status
服務專員回應：專案狀態詳細資料。
請參考下方資源建立範例。
按一下「儲存」，返回 Agent 模擬器並測試流程。重設所有現有對話。
恭喜！您已成功整合與在 Cloud Run 上部署的 API 相關聯的工具，讓服務機器人執行動作。
查看 Vertex AI Agents 的最佳做法
查看可用的服務專員設定
- 記錄設定 - 啟用 Cloud Logging
- Git 整合：Git 整合可讓您從 Git 存放區推送及提取代理程式。
- 生成式模型選取
- 符號限制(輸入和輸出)
查看 Agent 模擬器控制項：
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」頻道，然後按一下「允許」
在「基本資訊 / 應用程式憑證」下方，複製「簽署密鑰」，並在 Agent 的 Slack 整合中將其設為「簽署權杖」欄位的值。
開啟「OAuth 和權限」，複製「Bot User OAuth 權杖」，然後在 Agent 的 Slack 整合中將其設為「存取權杖」欄位的值。
設定必要欄位，然後按一下「開始」。
代理人的「存取權杖」值為 Slack 的「機器人使用者 OAuth 權杖」。
代理人的「Signing Token」值為 Slack 的「Signing Secret」。
複製「Webhook 網址」並返回 Slack 應用程式設定。
開啟「事件訂閱」部分，然後貼上網址。
儲存變更。
開啟「Slack」，然後輸入「@Agent」新增服務專員。
例如新增名稱為「@CX」的應用程式。
請服務專員提供 JIRA 專案摘要。
恭喜！服務機器人已成功整合至 Slack 工作區。
9. 針對 PDF 文件進行問答
本節將概略說明如何使用 PDF 文件建立資料儲存庫，並將其連結至服務專員，以便根據文件內容啟用問答功能。
建立 Cloud Storage 值區
開啟 Cloud Shell：https://shell.cloud.google.com/
請使用 GCP 專案的最後 5 碼設定值區名稱。範例：pdf-docs-3dw21
BUCKET_NAME=pdf-docs-LAST-5-DIGITS-OF-YOUR-PROJECT
建立值區並上傳 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 值區/資料夾。
選取資料儲存庫位置的「us」。
資料儲存庫名稱請輸入：「pdf-docs」
在下拉式選單中選取「Digital parser」。
啟用進階分塊功能。
在分塊中啟用祖系標題。
請按一下 [Create]。
按一下資料儲存庫，並查看「文件」、「活動」和「處理設定」。
匯入作業大約需要 5 到 10 分鐘才能完成。
剖析和分割選項
您可以透過下列方式控制內容剖析：
- 數位剖析器。除非指定其他剖析器類型，否則系統會預設為為所有檔案類型啟用數位剖析器。如果資料儲存庫未指定其他預設剖析器，或是指定的剖析器不支援攝入文件的檔案類型，數位剖析器就會處理攝入的文件。
- PDF OCR 剖析。公開測試版。如果您打算上傳掃描的 PDF 檔案，或圖片內含文字的 PDF 檔案，可以開啟 OCR 剖析器，改善 PDF 索引。請參閱「關於 PDF 光學字元辨識剖析」。
- 版面配置剖析器。如果您打算將 Vertex AI Search 用於 RAG，請為 HTML、PDF 或 DOCX 檔案啟用版面配置剖析器。如要瞭解這個剖析器的相關資訊，以及如何啟用剖析器，請參閱「RAG 的區塊文件」。
工具設定
返回「Agent's Tool」設定畫面，並重新整理可用的資料儲存庫。
選取剛建立的資料儲存庫，然後按一下「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-Docs 工具範例
切換至「範例」分頁。建立新範例：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"
}
]
}
新增「服務專員回覆」
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 文件。
恭喜！Agent 現可根據 PDF 文件提供有依據的答案。
11. 恭喜！
恭喜，您已完成實驗室！
涵蓋的內容：
- 如何建立及部署對話式代理
- 如何為 Cloud Run 應用程式所支援的代理人新增工具
- 如何將 Bot 整合至 Slack 工作區
- 如何設定 PDF 文件問答資料儲存庫
下一步：
- 查看 Vertex AI Agents 的最佳做法
清除所用資源
如要避免系統向您的 Google Cloud 帳戶收取本教學課程所用資源的費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。
刪除專案
如要避免付費，最簡單的方法就是刪除您為了本教學課程所建立的專案。
© 2024 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標，其他公司和產品名稱則有可能是其關聯公司的商標。