검색결과 가져오기

이 페이지에서는 Google Cloud 콘솔을 사용하여 검색 결과를 미리보고 API를 사용하여 검색 결과를 가져오는 방법을 보여줍니다.

또한 웹 페이지에 추가할 검색 위젯을 만드는 대신 API 호출을 수행하고 이러한 호출을 서버 또는 애플리케이션에 통합할 수 있습니다. 이 페이지에는 서비스 계정과 함께 gRPC 클라이언트 라이브러리를 사용하여 검색 쿼리를 수행하는 방법에 대한 코드 샘플이 포함되어 있습니다.

웹사이트 데이터가 있는 앱의 검색 결과 가져오기

콘솔

Google Cloud 콘솔을 사용하여 웹사이트 데이터가 있는 앱의 검색 결과를 미리보려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.

    AI Applications

  2. 수정하려는 앱의 이름을 클릭합니다.

  3. 미리보기를 클릭합니다.

  4. 콘솔에서 미리보기 페이지를 엽니다.

  5. 선택사항: 여러 데이터 스토어를 앱에 연결했지만 특정 데이터 스토어에서만 결과를 표시하려면 결과를 가져오려는 해당 데이터 스토어를 선택합니다.

  6. 검색 쿼리를 입력합니다.

    자동 완성을 사용 설정한 경우 입력할 때 검색창 아래에 자동 완성 추천 목록이 표시됩니다.

  7. Enter 키를 눌러 검색어를 제출합니다.

    • 검색창 아래에 검색 결과 목록이 표시됩니다.
    • 각 결과에는 제목, 스니펫, URL이 포함됩니다.
    • 결과를 클릭하면 URL이 열립니다.
    • 앱에 고급 LLM 기능이 사용 설정되어 있으면 생성된 답변도 표시될 수 있습니다.

REST

API를 사용해서 웹사이트 데이터가 있는 앱의 검색 결과를 가져오려면 engines.servingConfigs.search 메서드를 사용합니다.

  1. 앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.

    1. Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.

      앱으로 이동

    2. 앱 페이지에서 앱 이름을 찾고 ID 열에서 앱 ID를 가져옵니다.

  2. 검색 결과를 가져옵니다.

    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 맵 필드에 지원되는 유일한 항목입니다. 기본값은 비어 있습니다. 허용되는 값은 프로그래밍 검색 엔진 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 인코딩 문자열입니다. 최대 길이는 128자(영문 기준)입니다. 모델 성능 및 맞춤설정 품질이 향상되므로 이 필드를 사용하는 것이 좋습니다. 이 필드에는 단일 기기의 방문자를 고유하게 식별하는 HTTP 쿠키를 사용할 수 있습니다. 몇 가지 중요한 고려사항은 다음과 같습니다.

      • 이 식별자는 방문자가 웹사이트에 로그인 또는 로그아웃할 때 변경되지 않습니다.
      • 여러 사용자에 대해 이 필드를 동일한 식별자로 설정하면 안 됩니다. 그렇지 않으면 여러 사용자에 대해 동일한 사용자 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/&#42;/locations/global/collections/default_collection/engines/&#42;/servingConfigs/default_serving_config`,
 *                                       or
 *                                       `projects/&#42;/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 키)

서비스 계정 또는 사용자 계정을 통해 OAuth 2.0을 사용하는 대신 API 키로 검색 메서드 호출을 인증하려면 searchLite 메서드를 사용하는 다음 절차를 따르세요. searchLite 메서드는 공개 웹사이트를 검색하는 데만 사용할 수 있다는 점을 제외하고 search 메서드와 동일한 기능을 제공합니다.

searchLite 메서드는 다음 조건에서 특히 적합합니다.

  • 서비스 계정 또는 사용자 계정을 통해 OAuth 2.0을 설정하는 것이 실용적이지 않은 정적 웹사이트가 있습니다.

  • 프로그래밍 검색 엔진의 Custom Search Site Restricted JSON API에서 Vertex AI Search로 이전했습니다.

  • 검색 위젯을 사용하지 않으려는 경우

시작하기 전에

servingConfigs.searchLite 메서드를 호출하려면 API 키가 필요합니다. API 키가 없는 경우 검색 앱 배포 (API 키)의 1단계를 완료하세요.

절차

REST

API를 사용하여 API 키로 인증된 공개 웹사이트 데이터가 있는 앱의 검색 결과를 가져오려면 engines.servingConfigs.searchLite 메서드를 사용합니다.

  1. 앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.

    1. Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.

      앱으로 이동

    2. 앱 페이지에서 앱 이름을 찾고 ID 열에서 앱 ID를 가져옵니다.

  2. 다음 curl 명령어를 실행하여 검색 결과를 가져옵니다.

    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 인코딩 문자열입니다. 최대 길이는 128자(영문 기준)입니다. 모델 성능 및 맞춤설정 품질이 향상되므로 이 필드를 사용하는 것이 좋습니다. 이 필드에는 단일 기기의 방문자를 고유하게 식별하는 HTTP 쿠키를 사용할 수 있습니다. 몇 가지 중요한 고려사항은 다음과 같습니다.

      • 이 식별자는 방문자가 웹사이트에 로그인 또는 로그아웃할 때 변경되지 않습니다.
      • 여러 사용자에 대해 이 필드를 동일한 식별자로 설정하면 안 됩니다. 그렇지 않으면 여러 사용자에 대해 동일한 사용자 ID를 사용하면 서로 다른 사용자의 이벤트 기록이 결합되고 모델 품질이 저하될 수 있습니다.
      • 이 필드에는 개인 식별 정보 (PII)를 포함해서는 안 됩니다.
      • 특정 검색 또는 탐색 요청의 경우 이 필드는 사용자 이벤트의 해당 userPseudoId 필드에 매핑되어야 합니다.

      자세한 내용은 userPseudoId를 참조하세요.

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 메서드를 사용합니다.

  1. 앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.

    1. Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.

      앱으로 이동

    2. 앱 페이지에서 앱 이름을 찾고 ID 열에서 앱 ID를 가져옵니다.

  2. 검색 결과를 가져옵니다.

    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 인코딩 문자열입니다. 최대 길이는 128자(영문 기준)입니다. 모델 성능 및 맞춤설정 품질이 향상되므로 이 필드를 사용하는 것이 좋습니다. 이 필드에는 단일 기기의 방문자를 고유하게 식별하는 HTTP 쿠키를 사용할 수 있습니다. 몇 가지 중요한 고려사항은 다음과 같습니다.

      • 이 식별자는 방문자가 웹사이트에 로그인 또는 로그아웃할 때 변경되지 않습니다.
      • 여러 사용자에 대해 이 필드를 동일한 식별자로 설정하면 안 됩니다. 그렇지 않으면 여러 사용자에 대해 동일한 사용자 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: 선택사항입니다. 패싯 검색을 수행할 패싯 사양입니다.

    • 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/&#42;/locations/global/collections/default_collection/engines/&#42;/servingConfigs/default_serving_config`,
 *                                       or
 *                                       `projects/&#42;/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

검색 결과와 함께 문서 관련성 점수 가져오기

문서 관련성 점수는 문서에 대한 쿼리의 유사성을 기반으로 합니다. 점수는 0, 0.1, 0.2, ..., 1.0 범위의 11개 버킷에 배치됩니다. 점수가 높을수록 문서의 관련성이 높습니다.

다음 사용 사례의 문서 관련성 점수를 고려하세요.

  • 관련성 점수를 기반으로 검색 후 필터링하여 관련 없는 결과 삭제

  • 검색 후 순위 지정 또는 다른 애플리케이션의 입력

  • 디버깅: 관련성 점수를 통해 일부 검색 결과가 반환되는 이유를 파악할 수 있습니다.

각 검색 결과에 대해 관련성 점수가 반환될 수 있습니다.

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

아래 절차의 명령어 예시도 참고하세요.

시작하기 전에: 검색 앱이 정형 또는 비정형 데이터 스토어와 연결되어 있는지 확인합니다. 즉, 웹사이트 검색 앱의 경우 문서 관련성 점수를 반환할 수 없습니다.

REST

검색 결과와 함께 문서 관련성 점수를 반환하도록 요청하려면 다음과 같이 engines.servingConfigs.search 메서드를 사용하세요.

  1. 앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.

    1. Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.

      앱으로 이동

    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: 검색할 쿼리 텍스트입니다.

모델별 검색 요약 차이

쿼리에 대해 검색 요약을 생성할 때는 콘솔 결과와 API 결과 간에 요약이 다른 것을 확인할 수 있습니다. 이러한 차이가 발견되는 이유는 콘솔에 사용되는 LLM 모델이 API와 다르기 때문일 수 있습니다. 이 페이지의 curl 및 코드 예시에는 안정적인 LLM 모델이 사용됩니다.

  • UI의 미리보기 페이지에 사용되는 LLM 모델을 변경하거나 보려면(고급 검색 애플리케이션 및 의료 애플리케이션에서만 지원됨)

    1. 앱의 구성 페이지 > UI 탭으로 이동합니다.

    2. 검색 유형을 선택합니다.

      • 답변으로 검색을 선택하여 검색 결과 위에 생성형 요약을 표시합니다.
      • 후속 질문이 포함된 검색을 선택하여 생성형 요약과 후속 질문이 포함된 대화형 검색을 사용 설정합니다.

    3. 요약용 대규모 언어 모델 섹션에서 모델을 선택합니다.

  • 메서드 호출의 경우 안정적인 모델이 기본 모델입니다. 안정적인 모델이 아닌 LLM 모델을 사용하려면 요약 모델 지정 및 답변 모델 지정을 참고하세요.

    다음 단계

  • 웹페이지에 검색 위젯 추가

  • 검색 API를 사용하여 일반 검색 앱에서 데이터를 탐색합니다.