取得搜尋結果

本頁說明如何使用 Google Cloud 控制台預覽搜尋結果，以及如何使用 API 取得搜尋結果。

注意： 如要瞭解如何取得媒體應用程式的搜尋結果，請參閱「取得媒體搜尋結果」一文。

此外，除了建立搜尋小工具並新增到網頁，您還能傳送 API 呼叫，並整合到伺服器或應用程式。本頁面提供程式碼範例，說明如何使用 gRPC 用戶端程式庫和服務帳戶發出搜尋查詢。

注意： 視資料量而定，資料擷取作業完成後，可能需要數小時才能產生預覽畫面。

加上雙引號的完全比對

如要完全相符的搜尋結果，請在搜尋查詢前後加上雙引號 ("")。這類搜尋通常稱為「加引號」搜尋。

如果沒有用雙引號括住搜尋查詢，則搜尋會部分相符。這類搜尋也稱為「未加引號」搜尋。

舉例來說，如果搜尋查詢是 "query": "\"Mary had a little lamb\""， Vertex AI Search 會完全比對這個詞組，不會傳回含有 Mary had lamb (缺少字詞) 或 a little lamb had Mary (字詞順序不同) 的搜尋結果。

您可以透過不同方式，將完全比對搜尋與邏輯運算子結合，縮小搜尋結果範圍。詳情請參閱「搜尋查詢情境」。

邏輯運算子

搜尋結構化資料和含有中繼資料的非結構化資料時，您可以在搜尋中加入邏輯運算子。在多個字詞或詞組之間，您可以在搜尋查詢中加入 OR 和 AND。不支援 NOT 邏輯運算子

搜尋字詞的連結方式會決定結果的精確度：

且

查詢中的每個字詞都必須出現在結果中。舉例來說，搜尋 jazz AND piano 會顯示同時包含 jazz 和 piano 的結果。

或

結果中必須至少包含一個查詢字詞。舉例來說，搜尋「rock OR pop」會傳回包含「rock」、「pop」或兩者的結果。

您可以將不同的邏輯運算子彼此組合，或與完全比對搜尋搭配使用，藉此縮小搜尋結果範圍。

搜尋查詢情境

下表列出使用完全比對或部分比對搜尋時，可能會遇到的幾種情況。

情境	說明	範例
不含任何邏輯運算子的部分比對搜尋	如果搜尋字詞沒有加上雙引號，且字詞之間沒有邏輯運算子，搜尋時系統會假設字詞之間有 AND 運算子。此外，由於 Vertex AI Search 會進行語意搜尋，因此搜尋結果也可能包含系統認為與查詢相關的其他文件。	"query": "Mary little lamb" 對於這項查詢，回覆中最相關的文件包含所有字詞 Mary、little 和 lamb。回覆中也可能包含其他含有語意相關字詞的文件。
完全比對搜尋，不含任何邏輯運算子	如果多個個別搜尋字詞或詞組以半形雙引號括住，且之間沒有邏輯運算子，搜尋時會視為詞組之間有 AND 運算子。在查詢中至少一個搜尋字詞加上雙引號，系統就會停用整個查詢的語意搜尋功能。	"query": "\"Mary\" \"little lamb\"" 這項查詢的搜尋結果會同時包含「Mary」和「little lamb」這兩個詞組。
完全比對和部分比對搜尋	在查詢中為至少一個搜尋字詞加上雙引號，系統就會停用整個查詢的語意搜尋功能。 如果指定邏輯運算子，系統會按照指定方式處理。如果查詢中未指定任何邏輯運算子，搜尋作業會假設各個片語之間均有 AND 運算子。	"query": "Mary \"little lamb\"" 對於這項查詢，搜尋功能會將詞組之間的運算子視為 AND。由於「Mary」這個字詞未加上引號，因此不會完全相符。

使用網站資料取得應用程式的搜尋結果

控制台

如要透過 Google Cloud 控制台預覽含有網站資料的應用程式搜尋結果，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「AI Applications」頁面。

   AI 應用程式

2. 按一下要編輯的應用程式名稱。

3. 按一下「預覽」。

4. 在控制台中開啟「預覽」頁面。

5. 選用：如果應用程式連結多個資料儲存庫，但您只想要特定資料儲存庫的結果，請選取該資料儲存庫。

6. 輸入搜尋查詢。

   如果已啟用自動完成功能，搜尋列下方會在您輸入內容時顯示自動完成建議清單。

7. 按下 Enter 鍵提交查詢。

   • 搜尋列下方會顯示搜尋結果清單。
   • 每個結果都包含標題、摘要和網址。
   • 點選搜尋結果即可開啟該網址。
   • 如果應用程式已啟用進階 LLM 功能，系統也可能會顯示生成式回答。

REST

如要使用 API 取得含有網站資料的應用程式搜尋結果，請使用 engines.servingConfigs.search 方法：

注意：您可以使用 engines.servingConfigs.search 方法搜尋應用程式，並使用 dataStores.servingConfigs.search 方法搜尋資料儲存庫。Google 建議使用 engines.servingConfigs.search 方法進行搜尋，以執行下列程序。

1. 找出應用程式 ID。如果已有應用程式 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面。

      前往「應用程式」

   2. 在「應用程式」頁面中找出應用程式名稱，然後從「ID」欄取得應用程式的 ID。

2. 取得搜尋結果。

   重要詞彙：在 Vertex AI Search 中，API 脈絡下的「應用程式」一詞可與「引擎」互換使用。

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \
   -d '{
   "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search",
   "query": "QUERY",
   "pageSize": "PAGE_SIZE",
   "offset": "OFFSET",
   "orderBy": "ORDER_BY",
   "params": {"user_country_code": "USER_COUNTRY_CODE",
   "searchType": "SEARCH_TYPE"},
   "filter": "FILTER",
   "boostSpec": "BOOST_SPEC",
   "contentSearchSpec": {
      "searchResultMode": "RESULT_MODE"
    },
    "userPseudoId": "USER_PSEUDO_ID",
    "dataStoreSpecs": [{"DATA_STORE_SPEC"}]
   }'
   

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的 ID。
   • APP_ID：要查詢的 Vertex AI Search 應用程式 ID。
   • QUERY：要搜尋的查詢文字。

   • PAGE_SIZE：搜尋傳回的結果數量。 允許的頁面大小上限取決於資料類型。如果網頁大小超出上限，系統會強制設為上限值。

     • 基本索引網站：預設 10，最多 25
     • 進階索引建立功能：預設 25、最多 50
     • 其他：預設 50、最大 100

   • OFFSET：結果的起始索引。預設值為 0。

     舉例來說，如果偏移值為 2，頁面大小為 10，且有 15 個結果要傳回，則第一頁會傳回結果 2 到 12。

   • ORDER_BY：結果的排列順序。要排序的屬性必須有數值解讀，例如 date。詳情請參閱「排序網頁搜尋結果」。

   • USER_COUNTRY_CODE：使用者的位置。這個鍵/值組合是 params 對應欄位唯一支援的項目。預設值為空白。如需可接受的值，請參閱 Programmable Search Engine JSON API 參考說明文件中的「國家/地區代碼」。

   • SEARCH_TYPE：要執行的搜尋類型。文件搜尋的預設值為 0。圖片搜尋支援的另一個值為 1。

   • FILTER：文字欄位，可使用篩選器運算式篩選搜尋結果。預設值為空字串。如要進一步瞭解如何使用 filter 欄位，請參閱「篩選網站搜尋結果」。

   • BOOST_SPEC：選用。用來提高或隱藏文件優先順序的規格。值：

     • BOOST： 範圍 [-1,1] 中的浮點數。如果值為負數，結果會遭到降級 (顯示在結果的較下方)。如果值為正數，結果就會獲得升級 (在結果中排名較高)。
     • CONDITION： 用來選取要套用加成效果的文件的文字篩選運算式。篩選器必須評估布林值。 如要瞭解如何提升結構化搜尋的搜尋結果，請參閱「提升搜尋結果」。

   • RESULT_MODE：決定搜尋結果是以完整文件還是以區塊形式傳回。如要取得區塊，資料儲存庫必須開啟文件區塊功能。可接受的值為 documents 和 chunks。如果資料儲存區已啟用分塊功能，預設值為 chunks。否則預設值為 documents。如要瞭解文件分塊，請參閱「剖析文件及進行分塊」。這個欄位目前為公開預先發布版，如要使用，請在 curl 指令中將 v1 變更為 v1alpha。

   • USER_PSEUDO_ID：以 UTF-8 編碼的字串，可做為追蹤使用者的專屬匿名 ID。長度上限為 128 個半形字元。 Google 強烈建議使用這個欄位，因為這有助於提升模型效能和個人化品質。您可以使用 HTTP Cookie 做為這個欄位的值，明確識別單一裝置上的訪客。以下是幾個重要考量：

     • 訪客登入或登出網站時，這個 ID 不會變更。
     • 這個欄位不得為多位使用者設定相同的 ID。 否則，如果多位使用者使用相同的 User-ID，系統可能會合併不同使用者的事件記錄，導致模型品質下降。
     • 這個欄位不得包含個人識別資訊 (PII)。
     • 針對特定搜尋或瀏覽要求，這個欄位必須對應至使用者事件中的相應 userPseudoId 欄位。

     詳情請參閱「userPseudoId」。

   • DATA_STORE_SPEC：特定資料存放區的篩選條件，用於搜尋。如果搜尋應用程式已連結至多個資料儲存庫，但您只想要特定資料儲存庫的結果，請使用 dataStoreSpecs。詳情請參閱「DataStoreSpec」。

C#

詳情請參閱 Vertex AI Search C# API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

using Google.Api.Gax;
using Google.Cloud.DiscoveryEngine.V1Beta;
using Google.Protobuf.WellKnownTypes;
using System;

public sealed partial class GeneratedSearchServiceClientSnippets
{
    /// <summary>Snippet for Search</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void SearchRequestObject()
    {
        // Create client
        SearchServiceClient searchServiceClient = SearchServiceClient.Create();
        // Initialize request argument(s)
        SearchRequest request = new SearchRequest
        {
            ServingConfigAsServingConfigName = ServingConfigName.FromProjectLocationDataStoreServingConfig("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]"),
            BranchAsBranchName = BranchName.FromProjectLocationDataStoreBranch("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[BRANCH]"),
            Query = "",
            Offset = 0,
            Filter = "",
            OrderBy = "",
            FacetSpecs =
            {
                new SearchRequest.Types.FacetSpec(),
            },
            BoostSpec = new SearchRequest.Types.BoostSpec(),
            Params = { { "", new Value() }, },
            QueryExpansionSpec = new SearchRequest.Types.QueryExpansionSpec(),
            SpellCorrectionSpec = new SearchRequest.Types.SpellCorrectionSpec(),
            UserPseudoId = "",
            ImageQuery = new SearchRequest.Types.ImageQuery(),
            SafeSearch = false,
            UserInfo = new UserInfo(),
            UserLabels = { { "", "" }, },
            EmbeddingSpec = new SearchRequest.Types.EmbeddingSpec(),
            ContentSearchSpec = new SearchRequest.Types.ContentSearchSpec(),
            RankingExpression = "",
            NaturalLanguageQueryUnderstandingSpec = new SearchRequest.Types.NaturalLanguageQueryUnderstandingSpec(),
            CanonicalFilter = "",
            SearchAsYouTypeSpec = new SearchRequest.Types.SearchAsYouTypeSpec(),
            DataStoreSpecs =
            {
                new SearchRequest.Types.DataStoreSpec(),
            },
            LanguageCode = "",
            RegionCode = "",
            SessionAsSessionName = SessionName.FromProjectLocationDataStoreSession("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SESSION]"),
            SessionSpec = new SearchRequest.Types.SessionSpec(),
            RelevanceThreshold = SearchRequest.Types.RelevanceThreshold.Unspecified,
            PersonalizationSpec = new SearchRequest.Types.PersonalizationSpec(),
            OneBoxPageSize = 0,
            RankingExpressionBackend = SearchRequest.Types.RankingExpressionBackend.Unspecified,
        };
        // Make the request
        PagedEnumerable<SearchResponse, SearchResponse.Types.SearchResult> response = searchServiceClient.Search(request);

        // Iterate over all response items, lazily performing RPCs as required
        foreach (SearchResponse.Types.SearchResult item in response)
        {
            // Do something with each item
            Console.WriteLine(item);
        }

        // Or iterate over pages (of server-defined size), performing one RPC per page
        foreach (SearchResponse page in response.AsRawResponses())
        {
            // Do something with each page of items
            Console.WriteLine("A page of results:");
            foreach (SearchResponse.Types.SearchResult item in page)
            {
                // Do something with each item
                Console.WriteLine(item);
            }
        }

        // Or retrieve a single page of known size (unless it's the final page), performing as many RPCs as required
        int pageSize = 10;
        Page<SearchResponse.Types.SearchResult> singlePage = response.ReadPage(pageSize);
        // Do something with the page of items
        Console.WriteLine($"A page of {pageSize} results (unless it's the final page):");
        foreach (SearchResponse.Types.SearchResult item in singlePage)
        {
            // Do something with each item
            Console.WriteLine(item);
        }
        // Store the pageToken, for when the next page is required.
        string nextPageToken = singlePage.NextPageToken;
    }
}

Java

詳情請參閱 Vertex AI Search Java API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

import com.google.cloud.discoveryengine.v1.SearchRequest;
import com.google.cloud.discoveryengine.v1.SearchResponse;
import com.google.cloud.discoveryengine.v1.SearchServiceClient;
import com.google.cloud.discoveryengine.v1.SearchServiceSettings;
import com.google.cloud.discoveryengine.v1.ServingConfigName;
import java.io.IOException;
import java.util.concurrent.ExecutionException;

public class Search {
  public static void main() throws IOException, ExecutionException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String projectId = "PROJECT_ID";
    // Location of the data store. Options: "global", "us", "eu"
    String location = "global";
    // Collection containing the data store.
    String collectionId = "default_collection";
    // Data store ID.
    String dataStoreId = "DATA_STORE_ID";
    // Serving configuration. Options: "default_search"
    String servingConfigId = "default_search";
    // Search Query for the data store.
    String searchQuery = "Google";
    search(projectId, location, collectionId, dataStoreId, servingConfigId, searchQuery);
  }

  /** Performs a search on a given datastore. */
  public static void search(
      String projectId,
      String location,
      String collectionId,
      String dataStoreId,
      String servingConfigId,
      String searchQuery)
      throws IOException, ExecutionException {
    // For more information, refer to:
    // https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    String endpoint = (location.equals("global")) 
        ? String.format("discoveryengine.googleapis.com:443", location) 
        : String.format("%s-discoveryengine.googleapis.com:443", location);
    SearchServiceSettings settings =
        SearchServiceSettings.newBuilder().setEndpoint(endpoint).build();
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `searchServiceClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (SearchServiceClient searchServiceClient = SearchServiceClient.create(settings)) {
      SearchRequest request =
          SearchRequest.newBuilder()
              .setServingConfig(
                  ServingConfigName.formatProjectLocationCollectionDataStoreServingConfigName(
                      projectId, location, collectionId, dataStoreId, servingConfigId))
              .setQuery(searchQuery)
              .setPageSize(10)
              .build();
      SearchResponse response = searchServiceClient.search(request).getPage().getResponse();
      for (SearchResponse.SearchResult element : response.getResultsList()) {
        System.out.println("Response content: " + element);
      }
    }
  }
}

Node.js

詳情請參閱 Vertex AI Search Node.js API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const location = 'YOUR_LOCATION';              // Options: 'global', 'us', 'eu'
// const collectionId = 'default_collection';     // Options: 'default_collection'
// const dataStoreId = 'YOUR_DATA_STORE_ID'       // Create in Cloud Console
// const servingConfigId = 'default_config';      // Options: 'default_config'
// const searchQuery = 'Google';

const {SearchServiceClient} = require('@google-cloud/discoveryengine').v1beta;

// For more information, refer to:
// https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
const apiEndpoint =
  location === 'global'
    ? 'discoveryengine.googleapis.com'
    : `${location}-discoveryengine.googleapis.com`;

// Instantiates a client
const client = new SearchServiceClient({apiEndpoint: apiEndpoint});

async function search() {
  // The full resource name of the search engine serving configuration.
  // Example: projects/{projectId}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}/servingConfigs/{servingConfigId}
  // You must create a search engine in the Cloud Console first.
  const name = client.projectLocationCollectionDataStoreServingConfigPath(
    projectId,
    location,
    collectionId,
    dataStoreId,
    servingConfigId
  );

  const request = {
    pageSize: 10,
    query: searchQuery,
    servingConfig: name,
  };

  const IResponseParams = {
    ISearchResult: 0,
    ISearchRequest: 1,
    ISearchResponse: 2,
  };

  // Perform search request
  const response = await client.search(request, {
    // Warning: Should always disable autoPaginate to avoid iterate through all pages.
    //
    // By default NodeJS SDK returns an iterable where you can iterate through all
    // search results instead of only the limited number of results requested on
    // pageSize, by sending multiple sequential search requests page-by-page while
    // iterating, until it exhausts all the search results. This will be unexpected and
    // may cause high Search API usage and long wait time, especially when the matched
    // document numbers are huge.
    autoPaginate: false,
  });
  const results = response[IResponseParams.ISearchResponse].results;

  for (const result of results) {
    console.log(result);
  }
}

PHP

詳情請參閱 Vertex AI Search PHP API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

use Google\ApiCore\ApiException;
use Google\ApiCore\PagedListResponse;
use Google\Cloud\DiscoveryEngine\V1beta\Client\SearchServiceClient;
use Google\Cloud\DiscoveryEngine\V1beta\SearchRequest;
use Google\Cloud\DiscoveryEngine\V1beta\SearchResponse\SearchResult;

/**
 * Performs a search.
 *
 * @param string $formattedServingConfig The resource name of the Search serving config, such as
 *                                       `projects/*/locations/global/collections/default_collection/engines/*/servingConfigs/default_serving_config`,
 *                                       or
 *                                       `projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config`.
 *                                       This field is used to identify the serving configuration name, set
 *                                       of models used to make the search. Please see
 *                                       {@see SearchServiceClient::servingConfigName()} for help formatting this field.
 */
function search_sample(string $formattedServingConfig): void
{
    // Create a client.
    $searchServiceClient = new SearchServiceClient();

    // Prepare the request message.
    $request = (new SearchRequest())
        ->setServingConfig($formattedServingConfig);

    // Call the API and handle any network failures.
    try {
        /** @var PagedListResponse $response */
        $response = $searchServiceClient->search($request);

        /** @var SearchResult $element */
        foreach ($response as $element) {
            printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $formattedServingConfig = SearchServiceClient::servingConfigName(
        '[PROJECT]',
        '[LOCATION]',
        '[DATA_STORE]',
        '[SERVING_CONFIG]'
    );

    search_sample($formattedServingConfig);
}

Python

詳情請參閱 Vertex AI Search Python API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"          # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"
# search_query = "YOUR_SEARCH_QUERY"


def search_sample(
    project_id: str,
    location: str,
    engine_id: str,
    search_query: str,
) -> discoveryengine.services.search_service.pagers.SearchPager:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.SearchServiceClient(client_options=client_options)

    # The full resource name of the search app serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_config"

    # Optional - only supported for unstructured data: Configuration options for search.
    # Refer to the `ContentSearchSpec` reference for all supported fields:
    # https://cloud.google.com/python/docs/reference/discoveryengine/latest/google.cloud.discoveryengine_v1.types.SearchRequest.ContentSearchSpec
    content_search_spec = discoveryengine.SearchRequest.ContentSearchSpec(
        # For information about snippets, refer to:
        # https://cloud.google.com/generative-ai-app-builder/docs/snippets
        snippet_spec=discoveryengine.SearchRequest.ContentSearchSpec.SnippetSpec(
            return_snippet=True
        ),
        # For information about search summaries, refer to:
        # https://cloud.google.com/generative-ai-app-builder/docs/get-search-summaries
        summary_spec=discoveryengine.SearchRequest.ContentSearchSpec.SummarySpec(
            summary_result_count=5,
            include_citations=True,
            ignore_adversarial_query=True,
            ignore_non_summary_seeking_query=True,
            model_prompt_spec=discoveryengine.SearchRequest.ContentSearchSpec.SummarySpec.ModelPromptSpec(
                preamble="YOUR_CUSTOM_PROMPT"
            ),
            model_spec=discoveryengine.SearchRequest.ContentSearchSpec.SummarySpec.ModelSpec(
                version="stable",
            ),
        ),
    )

    # Refer to the `SearchRequest` reference for all supported fields:
    # https://cloud.google.com/python/docs/reference/discoveryengine/latest/google.cloud.discoveryengine_v1.types.SearchRequest
    request = discoveryengine.SearchRequest(
        serving_config=serving_config,
        query=search_query,
        page_size=10,
        content_search_spec=content_search_spec,
        query_expansion_spec=discoveryengine.SearchRequest.QueryExpansionSpec(
            condition=discoveryengine.SearchRequest.QueryExpansionSpec.Condition.AUTO,
        ),
        spell_correction_spec=discoveryengine.SearchRequest.SpellCorrectionSpec(
            mode=discoveryengine.SearchRequest.SpellCorrectionSpec.Mode.AUTO
        ),
        # Optional: Use fine-tuned model for this request
        # custom_fine_tuning_spec=discoveryengine.CustomFineTuningSpec(
        #     enable_search_adaptor=True
        # ),
    )

    page_result = client.search(request)

    # Handle the response
    for response in page_result:
        print(response)

    return page_result

Ruby

詳情請參閱 Vertex AI Search Ruby API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

require "google/cloud/discovery_engine/v1beta"

##
# Snippet for the search call in the SearchService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1beta::SearchService::Client#search.
#
def search
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1beta::SearchService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1beta::SearchRequest.new

  # Call the search method.
  result = client.search request

  # The returned object is of type Gapic::PagedEnumerable. You can iterate
  # over elements, and API calls will be issued to fetch pages as needed.
  result.each do |item|
    # Each element is of type ::Google::Cloud::DiscoveryEngine::V1beta::SearchResponse::SearchResult.
    p item
  end
end

使用網站資料取得應用程式的搜尋結果 (API 金鑰)

如要使用 API 金鑰驗證搜尋方法呼叫，而非透過服務帳戶或使用者帳戶使用 OAuth 2.0，請按照下列程序操作，其中會使用 searchLite 方法。searchLite 方法與 search 方法的功能相同，但只能用於搜尋公開網站。

在下列情況中，searchLite 方法特別適用：

• 您有靜態網站，透過服務帳戶或使用者帳戶設定 OAuth 2.0 並不實際。

• 您已從程式化搜尋引擎的 Custom Search Site Restricted JSON API 遷移至 Vertex AI Search。

• 不想使用搜尋小工具。

事前準備

您必須先取得 API 金鑰，才能呼叫 servingConfigs.searchLite 方法。如果您沒有 API 金鑰，請完成「部署搜尋應用程式 (API 金鑰)」的步驟 1。

程序

REST

如要使用 API 取得應用程式的搜尋結果，並透過 API 金鑰驗證公開網站資料，請使用 engines.servingConfigs.searchLite 方法：

注意：您可以使用 engines.servingConfigs.searchLite 方法搜尋應用程式，並使用 dataStores.servingConfigs.searchLite 方法搜尋資料儲存庫。Google 建議使用 engines.servingConfigs.search 方法進行搜尋，以執行下列程序。

1. 找出應用程式 ID。如果已有應用程式 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面。

      前往「應用程式」

   2. 在「應用程式」頁面中找出應用程式名稱，然後從「ID」欄取得應用程式的 ID。

2. 執行下列 curl 指令，取得搜尋結果：

   重要詞彙：在 Vertex AI Search 中，API 脈絡下的「應用程式」一詞可與「引擎」互換使用。

   curl -X POST -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:searchLite?key=API_KEY" \
   -d '{
   "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search",
   "query": "QUERY",
   "userPseudoId": "USER_PSEUDO_ID"
   }'
   

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的 ID。

   • API_KEY：您的 API 金鑰字串。

   • PROJECT_ID： Google Cloud 專案的 ID。

   • APP_ID：要查詢的 Vertex AI Search 應用程式 ID。

   • QUERY：要搜尋的查詢文字。

   • USER_PSEUDO_ID：以 UTF-8 編碼的字串，可做為追蹤使用者的專屬匿名 ID。長度上限為 128 個半形字元。 Google 強烈建議使用這個欄位，因為這有助於提升模型效能和個人化品質。您可以使用 HTTP Cookie 做為這個欄位的值，明確識別單一裝置上的訪客。以下是幾個重要考量：

     • 訪客登入或登出網站時，這個 ID 不會變更。
     • 這個欄位不得為多位使用者設定相同的 ID。 否則，如果多位使用者使用相同的 User-ID，系統可能會合併不同使用者的事件記錄，導致模型品質下降。
     • 這個欄位不得包含個人識別資訊 (PII)。
     • 針對特定搜尋或瀏覽要求，這個欄位必須對應至使用者事件中的相應 userPseudoId 欄位。

     詳情請參閱「userPseudoId」。

     注意： 這個指令只會使用必要輸入內容，並假設選填欄位採用預設值。如需可嘗試的其他欄位清單，請參閱 engines.servingConfigs.searchLite。

Python

詳情請參閱 Vertex AI Search Python API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"          # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"
# api_key = "YOUR_API_KEY"
# search_query = "YOUR_SEARCH_QUERY"


def search_lite_sample(
    project_id: str,
    location: str,
    engine_id: str,
    api_key: str,
    search_query: str,
) -> discoveryengine.services.search_service.pagers.SearchLitePager:

    client_options = ClientOptions(
        # For information on API Keys, refer to:
        # https://cloud.google.com/generative-ai-app-builder/docs/migrate-from-cse#api-key-deploy
        api_key=api_key,
        #  For more information, refer to:
        # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
        api_endpoint=(
            f"{location}-discoveryengine.googleapis.com"
            if location != "global"
            else None
        ),
    )

    # Create a client
    client = discoveryengine.SearchServiceClient(client_options=client_options)

    # The full resource name of the search app serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_config"

    # Refer to the `SearchRequest` reference for all supported fields:
    # https://cloud.google.com/python/docs/reference/discoveryengine/latest/google.cloud.discoveryengine_v1.types.SearchRequest
    request = discoveryengine.SearchRequest(
        serving_config=serving_config,
        query=search_query,
    )

    page_result = client.search_lite(request)

    # Handle the response
    for response in page_result:
        print(response)

    return page_result

取得以結構化或非結構化資料為基礎的應用程式搜尋結果

您可以從 Google Cloud 控制台預覽搜尋結果，也可以使用 API 取得搜尋結果。

控制台

注意： 如果您已為資料來源設定第三方存取控管，則必須完成額外步驟，才能在控制台中預覽結果。請參閱「預覽使用第三方存取控管設定的應用程式結果」。

如要透過 Google Cloud 控制台預覽以結構化或非結構化資料為基礎的應用程式搜尋結果，請按照下列步驟操作：

1. 在控制台中開啟「預覽」頁面。

2. 輸入搜尋查詢。

   如果已啟用自動完成功能，搜尋列下方會在您輸入內容時顯示自動完成建議清單。

3. (選用) 如果您已將多個資料儲存庫連結至應用程式，但只想取得特定資料儲存庫的結果，請選取該資料儲存庫。

4. 按下 Enter 鍵提交查詢。

   搜尋列下方會顯示搜尋結果清單。

   結構化資料適用下列規定：

   • 如果未在「設定」 >「設定結果中的欄位」中定義屬性對應，搜尋結果就會顯示為原始屬性名稱和值的清單。

   • 如果已在「設定」>「設定結果中的欄位」中儲存任何屬性對應，搜尋結果的顯示方式就會與「設定」頁面預覽畫面相同。

   • 如果「設定」>「構面設定」中指定了任何構面，系統會以相同方式顯示。

REST

如要使用 API 從含有結構化/非結構化資料的應用程式取得搜尋結果，請使用 engines.servingConfigs.search 方法：

注意：您可以使用 engines.servingConfigs.search 方法搜尋應用程式，並使用 dataStores.servingConfigs.search 方法搜尋資料儲存庫。Google 建議使用 engines.servingConfigs.search 方法進行搜尋，以執行下列程序。

1. 找出應用程式 ID。如果已有應用程式 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面。

      前往「應用程式」

   2. 在「應用程式」頁面中找出應用程式名稱，然後從「ID」欄取得應用程式的 ID。

2. 取得搜尋結果。

   重要詞彙：在 Vertex AI Search 中，API 脈絡下的「應用程式」一詞可與「引擎」互換使用。

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \
   -d '{
   "query": "QUERY",
   "userPseudoId": "USER_PSEUDO_ID",
   "pageSize": "PAGE_SIZE",
   "offset": "OFFSET",
   "orderBy": "ORDER_BY",
   "filter": "FILTER",
   "boostSpec": "BOOST_SPEC",
   "facetSpec": "FACET_SPEC",
   "queryExpansionSpec": "QUERY_EXPANSION_SPEC",
   "spellCorrectionSpec": "SPELL_CORRECTION_SPEC",
   "contentSearchSpec": "CONTENT_SEARCH_SPEC",
   "dataStoreSpecs": [{"DATA_STORE_SPEC"}],
   }'
   

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的 ID。
   • APP_ID：要查詢的 Vertex AI Search 應用程式 ID。
   • QUERY：要搜尋的查詢文字。

   • USER_PSEUDO_ID：以 UTF-8 編碼的字串，可做為追蹤使用者的專屬匿名 ID。長度上限為 128 個半形字元。 Google 強烈建議使用這個欄位，因為這有助於提升模型效能和個人化品質。您可以使用 HTTP Cookie 做為這個欄位的值，明確識別單一裝置上的訪客。以下是幾個重要考量：

     • 訪客登入或登出網站時，這個 ID 不會變更。
     • 這個欄位不得為多位使用者設定相同的 ID。 否則，如果多位使用者使用相同的 User-ID，系統可能會合併不同使用者的事件記錄，導致模型品質下降。
     • 這個欄位不得包含個人識別資訊 (PII)。
     • 針對特定搜尋或瀏覽要求，這個欄位必須對應至使用者事件中的相應 userPseudoId 欄位。

     詳情請參閱「userPseudoId」。

   • PAGE_SIZE：搜尋傳回的結果數量。允許的頁面大小上限取決於資料類型。如果頁面大小超過上限，系統會強制設為上限值。

     • 基本索引網站：預設 10，最多 25
     • 進階索引建立功能：預設 25、最多 50
     • 其他：預設 50、最大 100

   • OFFSET：選用。結果的起始索引。 預設值為 0。

     舉例來說，如果偏移值為 2，頁面大小為 10，且有 15 個結果要傳回，則第一頁會傳回結果 2 到 11。

   • ORDER_BY：選用。結果的排列順序。

   • FILTER：選用。文字欄位，可使用篩選器運算式篩選搜尋結果。預設值為空字串，表示未套用任何篩選器。

     範例：color: ANY("red", "blue") AND score: IN(*, 100.0e)

     詳情請參閱「篩選結構化或非結構化資料的搜尋結果」。

   • BOOST_SPEC：選用。可提升或隱藏文件的規格。值：

     • BOOST： 範圍 [-1,1] 中的浮點數。如果值為負數，結果會遭到降級 (顯示在結果的較下方)。如果值為正數，結果就會獲得升級 (在結果中排名較高)。
     • CONDITION： 用來選取要套用加成效果的文件的文字篩選運算式。篩選器必須評估布林值。

     如要瞭解如何提升結構化搜尋的搜尋結果，請參閱「提升搜尋結果」。

   • FACET_SPEC：選用。執行多面向搜尋的 Facet 規格。

   • QUERY_EXPANSION_SPEC：選用。這項規格可決定查詢擴展的條件。預設值為 DISABLED。

   • SPELL_CORRECTION_SPEC：選用。這項規格可決定在哪些條件下進行拼字修正。預設值為 AUTO。

   • CONTENT_SEARCH_SPEC：選用。取得程式碼片段、擷取式答案、擷取式片段和搜尋摘要。僅適用於非結構化資料。如需詳細資訊，請參閱：

     • 使用文字片段和內容擷取功能
     • 取得搜尋摘要

   • DATA_STORE_SPEC：特定資料儲存空間的篩選條件，可供搜尋。如果搜尋應用程式連結至多個資料儲存庫，即可使用這項功能。

   • 在搜尋回應中查看導覽搜尋結果：

     系統會傳回引導式搜尋結果，以及結構化和非結構化搜尋的搜尋回覆。導覽式搜尋結果會根據搜尋結果文件，列出擷取的屬性鍵/值組合。使用者可以將部分屬性鍵和值做為篩選條件，縮小搜尋結果範圍。

     在本例中，我們使用綠色來縮小搜尋結果範圍，方法是發出新的搜尋要求，並將篩選欄位指定為 _gs.color: ANY("green")：

     {
     "guidedSearchResult": {
       "refinementAttributes": [
         {
           "attributeKey": "_gs.color",
           "attributeValue": "green"
         },
         {
           "attributeKey": "_gs.category",
           "attributeValue": "shoe"
         }
       ]
     }
     }
     

C#

詳情請參閱 Vertex AI Search C# API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

using Google.Api.Gax;
using Google.Cloud.DiscoveryEngine.V1Beta;
using Google.Protobuf.WellKnownTypes;
using System;

public sealed partial class GeneratedSearchServiceClientSnippets
{
    /// <summary>Snippet for Search</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void SearchRequestObject()
    {
        // Create client
        SearchServiceClient searchServiceClient = SearchServiceClient.Create();
        // Initialize request argument(s)
        SearchRequest request = new SearchRequest
        {
            ServingConfigAsServingConfigName = ServingConfigName.FromProjectLocationDataStoreServingConfig("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SERVING_CONFIG]"),
            BranchAsBranchName = BranchName.FromProjectLocationDataStoreBranch("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[BRANCH]"),
            Query = "",
            Offset = 0,
            Filter = "",
            OrderBy = "",
            FacetSpecs =
            {
                new SearchRequest.Types.FacetSpec(),
            },
            BoostSpec = new SearchRequest.Types.BoostSpec(),
            Params = { { "", new Value() }, },
            QueryExpansionSpec = new SearchRequest.Types.QueryExpansionSpec(),
            SpellCorrectionSpec = new SearchRequest.Types.SpellCorrectionSpec(),
            UserPseudoId = "",
            ImageQuery = new SearchRequest.Types.ImageQuery(),
            SafeSearch = false,
            UserInfo = new UserInfo(),
            UserLabels = { { "", "" }, },
            EmbeddingSpec = new SearchRequest.Types.EmbeddingSpec(),
            ContentSearchSpec = new SearchRequest.Types.ContentSearchSpec(),
            RankingExpression = "",
            NaturalLanguageQueryUnderstandingSpec = new SearchRequest.Types.NaturalLanguageQueryUnderstandingSpec(),
            CanonicalFilter = "",
            SearchAsYouTypeSpec = new SearchRequest.Types.SearchAsYouTypeSpec(),
            DataStoreSpecs =
            {
                new SearchRequest.Types.DataStoreSpec(),
            },
            LanguageCode = "",
            RegionCode = "",
            SessionAsSessionName = SessionName.FromProjectLocationDataStoreSession("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[SESSION]"),
            SessionSpec = new SearchRequest.Types.SessionSpec(),
            RelevanceThreshold = SearchRequest.Types.RelevanceThreshold.Unspecified,
            PersonalizationSpec = new SearchRequest.Types.PersonalizationSpec(),
            OneBoxPageSize = 0,
            RankingExpressionBackend = SearchRequest.Types.RankingExpressionBackend.Unspecified,
        };
        // Make the request
        PagedEnumerable<SearchResponse, SearchResponse.Types.SearchResult> response = searchServiceClient.Search(request);

        // Iterate over all response items, lazily performing RPCs as required
        foreach (SearchResponse.Types.SearchResult item in response)
        {
            // Do something with each item
            Console.WriteLine(item);
        }

        // Or iterate over pages (of server-defined size), performing one RPC per page
        foreach (SearchResponse page in response.AsRawResponses())
        {
            // Do something with each page of items
            Console.WriteLine("A page of results:");
            foreach (SearchResponse.Types.SearchResult item in page)
            {
                // Do something with each item
                Console.WriteLine(item);
            }
        }

        // Or retrieve a single page of known size (unless it's the final page), performing as many RPCs as required
        int pageSize = 10;
        Page<SearchResponse.Types.SearchResult> singlePage = response.ReadPage(pageSize);
        // Do something with the page of items
        Console.WriteLine($"A page of {pageSize} results (unless it's the final page):");
        foreach (SearchResponse.Types.SearchResult item in singlePage)
        {
            // Do something with each item
            Console.WriteLine(item);
        }
        // Store the pageToken, for when the next page is required.
        string nextPageToken = singlePage.NextPageToken;
    }
}

Java

詳情請參閱 Vertex AI Search Java API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

import com.google.cloud.discoveryengine.v1.SearchRequest;
import com.google.cloud.discoveryengine.v1.SearchResponse;
import com.google.cloud.discoveryengine.v1.SearchServiceClient;
import com.google.cloud.discoveryengine.v1.SearchServiceSettings;
import com.google.cloud.discoveryengine.v1.ServingConfigName;
import java.io.IOException;
import java.util.concurrent.ExecutionException;

public class Search {
  public static void main() throws IOException, ExecutionException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String projectId = "PROJECT_ID";
    // Location of the data store. Options: "global", "us", "eu"
    String location = "global";
    // Collection containing the data store.
    String collectionId = "default_collection";
    // Data store ID.
    String dataStoreId = "DATA_STORE_ID";
    // Serving configuration. Options: "default_search"
    String servingConfigId = "default_search";
    // Search Query for the data store.
    String searchQuery = "Google";
    search(projectId, location, collectionId, dataStoreId, servingConfigId, searchQuery);
  }

  /** Performs a search on a given datastore. */
  public static void search(
      String projectId,
      String location,
      String collectionId,
      String dataStoreId,
      String servingConfigId,
      String searchQuery)
      throws IOException, ExecutionException {
    // For more information, refer to:
    // https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    String endpoint = (location.equals("global")) 
        ? String.format("discoveryengine.googleapis.com:443", location) 
        : String.format("%s-discoveryengine.googleapis.com:443", location);
    SearchServiceSettings settings =
        SearchServiceSettings.newBuilder().setEndpoint(endpoint).build();
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `searchServiceClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (SearchServiceClient searchServiceClient = SearchServiceClient.create(settings)) {
      SearchRequest request =
          SearchRequest.newBuilder()
              .setServingConfig(
                  ServingConfigName.formatProjectLocationCollectionDataStoreServingConfigName(
                      projectId, location, collectionId, dataStoreId, servingConfigId))
              .setQuery(searchQuery)
              .setPageSize(10)
              .build();
      SearchResponse response = searchServiceClient.search(request).getPage().getResponse();
      for (SearchResponse.SearchResult element : response.getResultsList()) {
        System.out.println("Response content: " + element);
      }
    }
  }
}

Node.js

詳情請參閱 Vertex AI Search Node.js API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const location = 'YOUR_LOCATION';              // Options: 'global', 'us', 'eu'
// const collectionId = 'default_collection';     // Options: 'default_collection'
// const dataStoreId = 'YOUR_DATA_STORE_ID'       // Create in Cloud Console
// const servingConfigId = 'default_config';      // Options: 'default_config'
// const searchQuery = 'Google';

const {SearchServiceClient} = require('@google-cloud/discoveryengine').v1beta;

// For more information, refer to:
// https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
const apiEndpoint =
  location === 'global'
    ? 'discoveryengine.googleapis.com'
    : `${location}-discoveryengine.googleapis.com`;

// Instantiates a client
const client = new SearchServiceClient({apiEndpoint: apiEndpoint});

async function search() {
  // The full resource name of the search engine serving configuration.
  // Example: projects/{projectId}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}/servingConfigs/{servingConfigId}
  // You must create a search engine in the Cloud Console first.
  const name = client.projectLocationCollectionDataStoreServingConfigPath(
    projectId,
    location,
    collectionId,
    dataStoreId,
    servingConfigId
  );

  const request = {
    pageSize: 10,
    query: searchQuery,
    servingConfig: name,
  };

  const IResponseParams = {
    ISearchResult: 0,
    ISearchRequest: 1,
    ISearchResponse: 2,
  };

  // Perform search request
  const response = await client.search(request, {
    // Warning: Should always disable autoPaginate to avoid iterate through all pages.
    //
    // By default NodeJS SDK returns an iterable where you can iterate through all
    // search results instead of only the limited number of results requested on
    // pageSize, by sending multiple sequential search requests page-by-page while
    // iterating, until it exhausts all the search results. This will be unexpected and
    // may cause high Search API usage and long wait time, especially when the matched
    // document numbers are huge.
    autoPaginate: false,
  });
  const results = response[IResponseParams.ISearchResponse].results;

  for (const result of results) {
    console.log(result);
  }
}

PHP

詳情請參閱 Vertex AI Search PHP API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

use Google\ApiCore\ApiException;
use Google\ApiCore\PagedListResponse;
use Google\Cloud\DiscoveryEngine\V1beta\Client\SearchServiceClient;
use Google\Cloud\DiscoveryEngine\V1beta\SearchRequest;
use Google\Cloud\DiscoveryEngine\V1beta\SearchResponse\SearchResult;

/**
 * Performs a search.
 *
 * @param string $formattedServingConfig The resource name of the Search serving config, such as
 *                                       `projects/*/locations/global/collections/default_collection/engines/*/servingConfigs/default_serving_config`,
 *                                       or
 *                                       `projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config`.
 *                                       This field is used to identify the serving configuration name, set
 *                                       of models used to make the search. Please see
 *                                       {@see SearchServiceClient::servingConfigName()} for help formatting this field.
 */
function search_sample(string $formattedServingConfig): void
{
    // Create a client.
    $searchServiceClient = new SearchServiceClient();

    // Prepare the request message.
    $request = (new SearchRequest())
        ->setServingConfig($formattedServingConfig);

    // Call the API and handle any network failures.
    try {
        /** @var PagedListResponse $response */
        $response = $searchServiceClient->search($request);

        /** @var SearchResult $element */
        foreach ($response as $element) {
            printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $formattedServingConfig = SearchServiceClient::servingConfigName(
        '[PROJECT]',
        '[LOCATION]',
        '[DATA_STORE]',
        '[SERVING_CONFIG]'
    );

    search_sample($formattedServingConfig);
}

Python

詳情請參閱 Vertex AI Search Python API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"          # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"
# search_query = "YOUR_SEARCH_QUERY"


def search_sample(
    project_id: str,
    location: str,
    engine_id: str,
    search_query: str,
) -> discoveryengine.services.search_service.pagers.SearchPager:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.SearchServiceClient(client_options=client_options)

    # The full resource name of the search app serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_config"

    # Optional - only supported for unstructured data: Configuration options for search.
    # Refer to the `ContentSearchSpec` reference for all supported fields:
    # https://cloud.google.com/python/docs/reference/discoveryengine/latest/google.cloud.discoveryengine_v1.types.SearchRequest.ContentSearchSpec
    content_search_spec = discoveryengine.SearchRequest.ContentSearchSpec(
        # For information about snippets, refer to:
        # https://cloud.google.com/generative-ai-app-builder/docs/snippets
        snippet_spec=discoveryengine.SearchRequest.ContentSearchSpec.SnippetSpec(
            return_snippet=True
        ),
        # For information about search summaries, refer to:
        # https://cloud.google.com/generative-ai-app-builder/docs/get-search-summaries
        summary_spec=discoveryengine.SearchRequest.ContentSearchSpec.SummarySpec(
            summary_result_count=5,
            include_citations=True,
            ignore_adversarial_query=True,
            ignore_non_summary_seeking_query=True,
            model_prompt_spec=discoveryengine.SearchRequest.ContentSearchSpec.SummarySpec.ModelPromptSpec(
                preamble="YOUR_CUSTOM_PROMPT"
            ),
            model_spec=discoveryengine.SearchRequest.ContentSearchSpec.SummarySpec.ModelSpec(
                version="stable",
            ),
        ),
    )

    # Refer to the `SearchRequest` reference for all supported fields:
    # https://cloud.google.com/python/docs/reference/discoveryengine/latest/google.cloud.discoveryengine_v1.types.SearchRequest
    request = discoveryengine.SearchRequest(
        serving_config=serving_config,
        query=search_query,
        page_size=10,
        content_search_spec=content_search_spec,
        query_expansion_spec=discoveryengine.SearchRequest.QueryExpansionSpec(
            condition=discoveryengine.SearchRequest.QueryExpansionSpec.Condition.AUTO,
        ),
        spell_correction_spec=discoveryengine.SearchRequest.SpellCorrectionSpec(
            mode=discoveryengine.SearchRequest.SpellCorrectionSpec.Mode.AUTO
        ),
        # Optional: Use fine-tuned model for this request
        # custom_fine_tuning_spec=discoveryengine.CustomFineTuningSpec(
        #     enable_search_adaptor=True
        # ),
    )

    page_result = client.search(request)

    # Handle the response
    for response in page_result:
        print(response)

    return page_result

Ruby

詳情請參閱 Vertex AI Search Ruby API 參考文件。

如要向 Vertex AI Search 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

require "google/cloud/discovery_engine/v1beta"

##
# Snippet for the search call in the SearchService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1beta::SearchService::Client#search.
#
def search
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1beta::SearchService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1beta::SearchRequest.new

  # Call the search method.
  result = client.search request

  # The returned object is of type Gapic::PagedEnumerable. You can iterate
  # over elements, and API calls will be issued to fetch pages as needed.
  result.each do |item|
    # Each element is of type ::Google::Cloud::DiscoveryEngine::V1beta::SearchResponse::SearchResult.
    p item
  end
end

取得搜尋結果的文件關聯性分數

文件關聯性分數是根據查詢與文件的相似程度計算，分數會歸入 11 個值區，範圍為 0、0.1、0.2... 到 1.0。 分數越高，代表文件越符合需求。

請考慮下列用途的文件關聯分數：

• 根據關聯性分數篩選搜尋結果，移除不相關的結果

• 搜尋後排名或做為其他應用程式的輸入內容

• 偵錯：關聯性分數可深入瞭解系統傳回某些搜尋結果的原因

系統會為每項搜尋結果傳回關聯性分數：

  "results": [
    {
      "id": "DOCUMENT_ID",
      "document": {
      ...
      },
      "modelScores": {
        "relevance_score": {
          "values": [
            DOCUMENT-RELEVANCE-SCORE
          ]
        }
      }
    },
  ...
  ]

另請參閱下方程序中的指令範例。

事前準備：請確認搜尋應用程式已與結構化或非結構化資料儲存庫建立關聯。也就是說，網站搜尋應用程式無法傳回文件相關性分數。

REST

如要要求系統在搜尋結果中傳回文件相關性分數，請使用 engines.servingConfigs.search 方法，如下所示：

注意： 系統不一定會傳回分數。請確保搜尋結果的後續處理作業不會依賴分數。

1. 找出應用程式 ID。如果已有應用程式 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「AI Applications」頁面。

      前往「應用程式」

   2. 在「應用程式」頁面中找出應用程式名稱，然後從「ID」欄取得應用程式的 ID。

2. 執行下列 curl 指令，取得搜尋結果傳回的分數。

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \
   -d '{
        "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search",
        "query": "QUERY",
        "relevanceScoreSpec": {
          "returnRelevanceScore": true
        }
   }'
   

   • PROJECT_ID： Google Cloud 專案的 ID。
   • APP_ID：要查詢的 Vertex AI Search 應用程式 ID。
   • QUERY：要搜尋的查詢文字。

   指令和部分結果範例

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/default_search:search" \
   -d '{
         "servingConfig": "projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/default_search",
         "query": "When was Verily founded and what is its mission?",
         "relevanceScoreSpec": {
           "returnRelevanceScore": true
         }
   }'
   
   {
     "results": [
       {
         "id": "f1b0d98bd2a078a6dfb4f809c3028565",
         "document": {
           "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/f1b0d98bd2a078a6dfb4f809c3028565",
           "id": "f1b0d98bd2a078a6dfb4f809c3028565",
           "derivedStructData": {
             "link": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2019_alphabet_annual_report.pdf",
             "extractive_answers": [
               {
                 "pageNumber": "70",
                 "content": "VERILY Verily is a life science and healthcare company with a mission to make the world's health data useful so that people enjoy healthier lives. In December 2018, Verily received $900 million in cash from a $1.0 billion investment round. The remaining $100 million was received in the first quarter of 2019."
               }
             ],
             "title": "2019_alphabet_annual_report"
           }
         },
         "modelScores": {
           "relevance_score": {
             "values": [
               0.7
             ]
           }
         }
       },
       {
         "id": "0371b29bfa18ac43896b86a7b63d00b0",
         "document": {
           "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/0371b29bfa18ac43896b86a7b63d00b0",
           "id": "0371b29bfa18ac43896b86a7b63d00b0",
           "derivedStructData": {
             "link": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/20190429_alphabet_10Q.pdf",
             "title": "GOOG 10-Q Q1 2019",
             "extractive_answers": [
               {
                 "content": "Verily Verily is a life science company with a mission to make the world's health data useful so that people enjoy healthier lives. In December 2018, Verily received $900 million in cash from a $1.0 billion investment round. The remaining $100 million was received in the first quarter of 2019.",
                 "pageNumber": "21"
               }
             ]
           }
         },
        "modelScores": {
           "relevance_score": {
             "values": [
               0.5
             ]
           }
         }
       },
       ...
       {
         "id": "e6bbd0d82dc2a2fc7ccf1bd82ac6334f",
         "document": {
           "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/e6bbd0d82dc2a2fc7ccf1bd82ac6334f",
           "id": "e6bbd0d82dc2a2fc7ccf1bd82ac6334f",
           "derivedStructData": {
             "title": "2021_Q1_Earnings_Transcript",
             "link": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2021_Q1_Earnings_Transcript.pdf",
             "extractive_answers": [
               {
                 "pageNumber": "2",
                 "content": "Our strength in AI and ML is also helping Financial Services customers improve efficiency of payments, reduce fraud and risk, and deliver faster payment solutions."
               }
             ]
           }
         },
         "modelScores": {
           "relevance_score": {
             "values": [
               0
             ]
           }
         }
       }
     ],
     "totalSize": 76,
     "attributionToken": "8QHw8AoLCIW4_b0GELHd3lgSJDY3YmU1ZGMwLTAwMDAtMmM1OC04NzcyLTc0NzQ0NjNiOGMyNSIHR0VORVJJQyqcAcb77TDHy_MX8tntMI6-nRWK4uQwwvCeFYX77TDvifIwq8SKLauR3zCq-LMt0IrIMNSynRWc1rctv_7kML7l3zDZveQwkPeyMMP77TD12e0wpd_hMIfi5DCRv9owgvvtMJWSxTCOkckwu-XfMK7Eii3sifIwqJHfMKjf4TCt-LMtlL_aMJ_Wty23t4wto4CXIs2KyDDcveQwwv7kMDABShIweDU3MGFkYWI4MzQ4NmY0MGE",
     "nextPageToken": "UjMjhjYzYDN0cDN30iM3cDOtgTNjJTLwADMw0iZiRWNlJ2N2QiGBUd0gWLEG4bjhWICMIBM1IgC",
     "summary": {},
     "queryExpansionInfo": {}
   }
   

注意： 這份文件相關性分數與用於篩選搜尋結果的相關程度不同，且更精確。

搜尋摘要功能因模型而異

如果您為查詢產生搜尋摘要，可能會發現主控台結果和 API 結果的摘要有所不同。如果看到這則訊息，可能是因為控制台使用的 LLM 模型與 API 不同。本頁的 curl 和程式碼範例使用穩定版 LLM 模型。

• 如要變更或查看 UI「預覽」頁面中使用的 LLM 模型 (僅支援進階搜尋應用程式和醫療保健應用程式)。

  1. 前往應用程式的「Configurations」頁面 >「UI」分頁。

  2. 選取「搜尋類型」：

     • 選取「搜尋並取得答案」，即可在搜尋結果上方顯示生成摘要。
     • 選取「含後續查詢的搜尋」，啟用對話式搜尋功能，系統會生成摘要並支援後續問題。

  3. 在「提供摘要的大型語言模型」部分，選取模型。

• 對於方法呼叫，穩定版模型是預設模型。如要使用穩定模型以外的 LLM 模型，請參閱「指定摘要模型」和「指定答案模型」。

  後續步驟

• 在網頁中新增搜尋小工具。

• 使用 Search API 瀏覽一般搜尋應用程式中的資料。