Console
    Contact Us Start free

    Vertex AI Search extension

    Preview

    Vertex AI Extensions is a Preview offering, subject to the "Pre-GA Offerings Terms" of the Google Cloud Service Specific Terms . Pre-GA products and features may have limited support, and changes to pre-GA products and features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions . Further, by using Vertex AI Extensions, you agree to the Generative AI Preview terms and conditions ("Preview Terms").

    This document shows you how to register and use the Google-provided Vertex AI Search extension from the Google Cloud console and the Vertex AI API. This extension lets you access and search website corpuses and unstructured data to provide relevant responses to natural language questions, such as:

    • "How did the competitive threats for the company change from Q1 of last year to Q1 of this year?"
    • "What parts of the company are growing the fastest? How fast?"

    The Vertex AI Search extension uses Vertex AI Search to retrieve meaningful results from your data store. The Vertex AI Search extension is defined in an OpenAPI Specification vertex_ai_search.yaml file.

    To use the Vertex AI Search extension, you must Create a data store in the global region with a specified search scope. For best search results, enable advanced indexing for website data and the Enterprise edition for unstructured data. See About advanced features for more information.

     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

    To learn about Google extensions with end-to-end tutorials, see the following Jupyter notebooks:

    Before you begin

    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.

      Go to project selector

    3. Verify 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.

      Go to project selector

    6. Verify that billing is enabled for your Google Cloud project .

    7. Enable the Vertex AI API.

      Enable the API

    Register and run the Vertex AI Search extension

    The following sections show you how to register the Vertex AI Search extension using the Google Cloud console and the Vertex AI API. After registering the extension, you can run it using the Vertex AI API.

    Console

    Register the extension

    Perform the following steps to register the Vertex AI Search extension using the Google Cloud console.

    1. In the Google Cloud console, go to the Vertex AI Extensionspage.

      Go to Vertex AI Extensions

    2. Click Create Extension.

    3. In the Create a new extensiondialog, fill in the following fields:

      • Extension name:Enter a name for your extension, such as "vertex_search_extension".
      • Description:(Optional) Enter an extension description, such as "A Vertex AI search extension".
      • Extension type:Select Vertex AI search .

    4. In the OpenAPI Spec filesection that now appears, confirm that the following fields are set correctly:

      • API name: vertex_ai_search .
      • API description: Performs search on user ingested data including website and unstructured data type...
      • Source: Cloud Storage .
      • OpenAPI Spec: vertex-extension-public/vertex_ai_search.yaml .
      • Authentication: Google service account .

    5. In the Runtime configurationssection, provide a serving configuration name. The serving configuration name is specified in the vertexAiSearchRuntimeConfig . It is formatted and completed as follows: projects/ PROJECT_ID /locations/global/collections/ COLLECTION_NAME /engines/ ENGINE /servingConfigs/ SERVING_CONFIG

      • Set COLLECTION_NAME to default_collection .
      • Set ENGINE to the application ID you received when you created your search application. To learn more, see Create a search app for website data .
      • Set SERVING_CONFIG to default_search .

    6. Click Create Extension.

    REST

    Register the extension

    Submit an Vertex AI API extensions.import request to register the Vertex AI Search extension.

    Before using any of the request data, make the following replacements:

    • PROJECT_ID : The ID of your Google Cloud project.
    • REGION : A Compute Engine region .
    • DISPLAY_NAME : The name extension that is displayed to users, such as "my_search_extension".
    • DESCRIPTION : (Optional) The extension description that is displayed to users, such as "A search extension".
    • SERVICE_ACCOUNT : (Optional) The Vertex AI Search extension uses GOOGLE_SERVICE_ACCOUNT_AUTH as shown in the sample request body. If you do not specify a service account, the extension uses the default Vertex AI Extension Service Agent service account. If you specify a different service account, grant the iam.serviceAccounts.getAccessToken permission to the Vertex AI Extension Service Agent service account on the specified service account.
    • SERVING_CONFIG_NAME : The serving configuration name is specified in the vertexAiSearchRuntimeConfig . It is formatted and completed as follows: projects/ PROJECT_ID /locations/global/collections/ COLLECTION_NAME /engines/ ENGINE /servingConfigs/ SERVING_CONFIG .
      • PROJECT_ID : The ID of your Google Cloud project.
      • Set COLLECTION_NAME to default_collection .
      • ENGINE : The application ID you received when you created your search application. To learn more, see Create a search app for website data .
      • Set SERVING_CONFIG to default_search .

    HTTP method and URL:

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

    Request JSON body:

    {
  "displayName":" DISPLAY_NAME 
",
  "description":" DESCRIPTION 
",
  "manifest":{
    "name":"vertex_ai_search_tool",
    "description":"A Vertex AI Search tool",
    "apiSpec":{
      "openApiGcsUri":"gs://vertex-extension-public/vertex_ai_search.yaml"
    },
    "authConfig":{
      "authType":"GOOGLE_SERVICE_ACCOUNT_AUTH",
      "googleServiceAccountConfig":{
        "serviceAccount":" SERVICE_ACCOUNT 
"
      }
    }
  }
  "runtimeConfig": {
     "vertexAiSearchRuntimeConfig": {
        "servingConfigName": " SERVING_CONFIG_NAME 
",
     }
  }
}

    To send your request, choose one of these options:

    curl

    Save the request body in a file named request.json , and execute the following command:

    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

    Save the request body in a file named request.json , and execute the following command:

    $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

    Run the extension

    You can submit an execute operation to the Vertex AI API to obtain meaningful results from your data store.

    Before using any of the request data, make the following replacements:

    • PROJECT_ID : The ID of your Google Cloud project.
    • REGION : A Compute Engine region .
    • EXTENSION_ID : The ID of your Vertex AI Search extension listed in the Extension detailsin the Google Cloud console.

    HTTP method and URL:

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

    Request JSON body:

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

    To send your request, choose one of these options:

    curl

    Save the request body in a file named request.json , and execute the following command:

    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

    Save the request body in a file named request.json , and execute the following command:

    $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
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: