使用 API 调用对文档和操作进行问答的 GenAI 代理

关于此 Codelab

上次更新时间：3月 18, 2025

Andrey Shakirov 编写

1. 概览

在本实验中，您将创建一个 GenAI 代理，将其连接到 Cloud Run 应用，并将该代理集成到 Slack 工作区。

学习内容

本实验包含几个主要部分：

部署 Cloud Run 应用以集成 Gemini API
创建和部署对话智能体
将聊天机器人集成到 Slack
为 PDF 文档问答功能配置数据存储区

前提条件

本实验假设您熟悉 Cloud 控制台和 Cloud Shell 环境。

2. 设置和要求

Cloud 项目设置

项目名称是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
项目 ID 在所有 Google Cloud 项目中是唯一的，并且是不可变的（一经设置便无法更改）。Cloud 控制台会自动生成一个唯一字符串；通常情况下，您无需关注该字符串。在大多数 Codelab 中，您都需要引用项目 ID（通常用 PROJECT_ID 标识）。如果您不喜欢生成的 ID，可以再随机生成一个 ID。或者，您也可以尝试自己的项目 ID，看看是否可用。完成此步骤后便无法更改该 ID，并且此 ID 在项目期间会一直保留。
此外，还有第三个值，即部分 API 使用的项目编号，供您参考。如需详细了解所有这三个值，请参阅文档。

接下来，您需要在 Cloud 控制台中启用结算功能，以便使用 Cloud 资源/API。运行此 Codelab 应该不会产生太多的费用（如果有的话）。若要关闭资源以避免产生超出本教程范围的结算费用，您可以删除自己创建的资源或删除项目。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。

环境设置

打开 Gemini 聊天。

为 Google Cloud API 启用 Gemini：

点击“Start chatting”，然后按照其中一个示例问题操作，或输入您自己的问题进行试用。

建议尝试的提示：

通过 5 个要点介绍 Cloud Run。
您是 Google Cloud Run 产品经理，需要用 5 个简短的要点向学生介绍 Cloud Run。
您是 Google Cloud Run 产品经理，需要向一名经过认证的 Kubernetes 开发者简要说明 5 个 Cloud Run 要点。
您是 Google Cloud Run 产品经理，请用 5 个关键要点向一名高级开发者说明何时使用 Cloud Run 而非 GKE。

如需详细了解如何撰写更优质的提示，请参阅提示指南。

Google Cloud 专用 Gemini 如何使用您的数据

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 Web 应用 (gemini.google.com)

Google Gemini Web 应用 (gemini.google.com) 是一款基于 Web 的工具，旨在帮助您探索和利用 Google 的 Gemini AI 模型的强大功能。

Android 版 Google Gemini 移动应用和 iOS 版 Google 应用

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 中创建并存储多个 Secret。

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 或者设置 Buildpack 或 Cloud Build。也就是说，上述单个命令完成了本来还需要执行 gcloud builds submit 和 gcloud run deploy 命令才能完成的任务。

如果您提供了 Dockerfile（我们在本代码库中就提供了），Cloud Build 将使用它来构建容器映像，而不是依赖于 Buildpack 自动检测和构建容器映像。如需详细了解 Buildpack，请参阅文档。

在 Cloud 控制台中查看 Cloud Build 日志。

在 Artifact Registry 中查看创建的 Docker 映像。

在 Cloud 控制台中查看 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：

选择您的项目：

点击“创建代理”：

选择“自行构建”。

在“显示名称”中输入“代理”，然后点击“创建”。

设置 Playbook 名称：

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) - 替换您的 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”，返回到代理配置，然后更新使用该工具的说明：

添加有关使用新工具的说明，然后点击“保存”：

- 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 关联的工具，您已成功授权 Agent 执行操作。

查看 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

点击“创建”：

安装到 Workspace：

选择“#general”渠道，然后点击“允许”

在“基本信息 / 应用凭据”下，复制“签名密钥”，并在客服人员的 Slack 集成中将其设置为“签名令牌”字段的值。

打开“OAuth 和权限”，复制“聊天机器人用户 OAuth 令牌”，然后在客服人员的 Slack 集成中将其设置为“访问令牌”字段的值。

设置必填字段，然后点击“开始”。

客服人员的“访问令牌”值为 Slack 中的“聊天机器人用户 OAUth 令牌”。

代理的“签名令牌”值为 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 的 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-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 文档。

恭喜！现在，客服人员可以根据 PDF 文档提供有依据的回答。

10. 预建代理

接下来，您将从左侧菜单中探索预构建的代理。

选择其中一个代理并进行部署。探索 Agent 的设置、说明和工具。

11. 恭喜！

恭喜，您已完成此实验！

所学内容：

如何创建和部署对话式智能体
如何为由 Cloud Run 应用支持的代理添加工具
如何将代理集成到 Slack 工作区
如何为 PDF 文档中的问答配置数据存储区

后续步骤：

查看 Vertex AI Agents 的最佳实践

清理

为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

删除项目

若要避免产生费用，最简单的方法是删除您为本教程创建的项目。

报告错误