1. 總覽
在本研究室中,您將建立 GenAI 代理程式,將其連結至 Cloud Run 應用程式,並將代理程式整合至 Slack 工作區。
學習目標
本實驗室分為幾個主要部分:
- 部署 Cloud Run 應用程式,以便整合 Gemini API
- 建立及部署 Vertex AI Agent
- 將 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 對話。
啟用 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 是 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"
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 的商標,其他公司和產品名稱則有可能是其關聯公司的商標。