Vertex AI Search 扩展程序

预览

Vertex AI Extensions 是预览版产品，受 Google Cloud 服务专用条款的“正式发布前产品条款”约束。我们对正式发布前产品和功能的支持可能比较有限，并且对正式发布前产品和功能的更改可能与其他正式发布前版本不兼容。如需了解详情，请参阅发布阶段说明。此外，使用 Vertex AI Extensions，即表示您同意生成式 AI 预览版条款及条件（“预览版条款”）。

本文档介绍如何通过 Google Cloud 控制台和 Vertex AI API 注册和使用 Google 提供的 Vertex AI Search 扩展程序。借助此扩展程序，您可以访问和搜索网站语料库和非结构化数据，以提供对自然语言问题的相关回答，例如：

• “公司的竞争威胁从去年第 1 季度到今年第 1 季度有何变化？”
• “公司的哪些部门增长最快？有多快？”

Vertex AI Search 扩展程序使用 Vertex AI Search 从数据存储区中检索有意义的结果。Vertex AI Search 扩展程序在 OpenAPI 规范 vertex_ai_search.yaml 文件中定义。

如需使用 Vertex AI Search 扩展程序，您必须在具有指定搜索范围的全球区域中创建数据存储区。为获得最佳搜索结果，请为网站数据启用高级索引，并为非结构化数据启用企业版。如需了解详情，请参阅高级功能简介。

展开 收起

openapi: "3.0.0"
info:
  title: Vertex AI Search
  version: v1alpha
  description: >
    Performs search on user ingested data including website and unstructured data type.

    This extension is used when user wants to search or retrieve meaningful results from their ingested data in the Vertex AI Search service.

    Supported AuthTypes:
    - GOOGLE_SERVICE_ACCOUNT_AUTH: (only supports using Vertex AI Extension Service Agent).
paths:
  /search:
    get:
      operationId: search
      description: Retrieves the results from user's query by searching in the data store.
      parameters:
      - name: query
        in: query
        schema:
          type: string
        description: User natural language instructions for search.
        required: true
      responses:
        default:
          description: Search execution result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResult"

components:
  schemas:
    SearchResult:
      description: Top results from search response.
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
                description: Retrieved document title.
              display_link:
                type: string
                description: Retrieved document link to display.
              link:
                type: string
                description: Retrieved document link.
              extractive_segments:
                type: array
                description: Extractive segments from the retrieved file.
                items:
                  type: string
              extractive_answers:
                type: array
                description: Extractive answers from the retrieved file. These are generated from the extractive segments.
                items:
                  type: string

    

如需通过端到端教程了解 Google 扩展程序，请参阅以下 Jupyter 笔记本：

• 使用 Vertex AI Extensions 扩展程序实现业务分析师工作流：使用代码解释器扩展程序和 Vertex AI Search 扩展程序完成住房投资机会研究报告以提供给业务利益相关方参考。
  Colab | GitHub | Vertex AI Workbench
• 使用 Vertex AI Extensions 扩展程序实现游戏评价分析工作流：使用代码解释器扩展程序分析来自 Steam 的游戏评价。使用 Vertex AI Search 扩展程序汇总网站上的游戏评价。使用代码解释器扩展程序用生成的所有资源构建报告。
  Colab | GitHub | Vertex AI Workbench

准备工作

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Vertex AI API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Vertex AI API.

   Enable the API

注册并运行 Vertex AI Search 扩展程序

以下部分介绍如何使用 Google Cloud 控制台和 Vertex AI API 注册 Vertex AI Search 扩展程序。注册扩展程序后，您可以使用 Vertex AI API 运行该扩展程序。

控制台

注册扩展程序

执行以下步骤，使用 Google Cloud 控制台注册 Vertex AI Search 扩展程序。

1. 在 Google Cloud 控制台中，转到 Vertex AI Extensions页面。

   转到“Vertex AI Extensions”

2. 点击创建扩展程序。

3. 在创建新扩展程序对话框中，填写以下字段：

   • 扩展程序名称：输入扩展程序的名称，例如“vertex_search_extension”。
   • 说明：（可选）输入扩展程序说明，例如“Vertex AI 搜索扩展程序”。
   • 扩展程序类型：选择 Vertex AI search。

4. 在现在显示的 OpenAPI 规范文件部分中，确认已正确设置以下字段：

   • API 名称： vertex_ai_search。
   • API 说明： Performs search on user ingested data including website and unstructured data type...
   • 来源： Cloud Storage。
   • OpenAPI 规范 vertex-extension-public/vertex_ai_search.yaml。
   • 身份验证： Google service account。

5. 在运行时配置部分中，提供服务配置名称。服务配置名称在 vertexAiSearchRuntimeConfig 中指定。其完整格式如下所示：projects/PROJECT_ID/locations/global/collections/COLLECTION_NAME/engines/ENGINE/servingConfigs/SERVING_CONFIG

   • 将 COLLECTION_NAME 设置为 default_collection。
   • 将 ENGINE 设置为您在创建搜索应用时收到的应用 ID。如需了解详情，请参阅创建网站数据的搜索应用。
   • 将 SERVING_CONFIG 设置为 default_search。

6. 点击创建扩展程序。

REST

注册扩展程序

提交 Vertex AI API extensions.import 请求以注册 Vertex AI Search 扩展程序。

在使用任何请求数据之前，请先进行以下替换：

• PROJECT_ID：您的 Google Cloud 项目的 ID。
• REGION：Compute Engine 区域。
• DISPLAY_NAME：向用户显示的扩展程序名称，例如“my_search_extension”。
• DESCRIPTION：（可选）向用户显示的扩展程序说明，例如“搜索扩展程序”。
• SERVICE_ACCOUNT：（可选）Vertex AI Search 扩展程序使用 GOOGLE_SERVICE_ACCOUNT_AUTH，如示例请求正文中所示。如果您未指定服务账号，则扩展程序会使用默认的 Vertex AI Extension Service Agent 服务账号。如果您指定了其他服务账号，请在指定服务账号上授予对 Vertex AI Extension Service Agent 服务账号的 iam.serviceAccounts.getAccessToken 权限。
• SERVING_CONFIG_NAME：服务配置名称在 vertexAiSearchRuntimeConfig 中指定。其完整格式如下所示： projects/PROJECT_ID/locations/global/collections/COLLECTION_NAME/engines/ENGINE/servingConfigs/SERVING_CONFIG。
  • PROJECT_ID：您的 Google Cloud 项目的 ID。
  • 将 COLLECTION_NAME 设置为 default_collection。
  • ENGINE：您在创建搜索应用时收到的应用 ID。如需了解详情，请参阅创建网站数据的搜索应用。
  • 将 SERVING_CONFIG 设置为 default_search。
  扩展程序将用于读取输入文件的 Cloud Storage 存储桶，包括 gs:// 前缀，例如 gs://sample-bucket-name。如果指定，则必须将此存储桶的 roles/storage.objectViewer 角色分配给 Vertex Extension Custom Code Service Agent。

HTTP 方法和网址：

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import

请求 JSON 正文：

{
  "displayName":"DISPLAY_NAME",
  "description":"DESCRIPTION",
  "manifest":{
    "name":"code_interpreter_tool",
    "description":"A Google Code Interpreter tool",
    "apiSpec":{
      "openApiGcsUri":"gs://vertex-extension-public/code_interpreter.yaml"
    },
    "authConfig":{
      "authType":"GOOGLE_SERVICE_ACCOUNT_AUTH",
      "googleServiceAccountConfig":{
        "serviceAccount":"SERVICE_ACCOUNT"
      }
    }
  }
  "runtimeConfig": {
     "vertexAiSearchRuntimeConfig": {
        "servingConfigName": "SERVING_CONFIG_NAME",
     }
  }
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import" | Select-Object -Expand Content

运行扩展程序

您可以向 Vertex AI API 提交 execute 操作，以从数据存储区获取有意义的结果。

文档搜索

在使用任何请求数据之前，请先进行以下替换：

• PROJECT_ID：您的 Google Cloud 项目的 ID。
• REGION：Compute Engine 区域。
• EXTENSION_ID：Google Cloud 控制台的扩展程序详情中列出的 Vertex AI Search 扩展程序的 ID。

HTTP 方法和网址：

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute

请求 JSON 正文：

{
  "operation_id":"search",
  "operation_params":{
    "query":"Housing affordability since 2010",
  }
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute" | Select-Object -Expand Content