Method: projects.locations.collections.engines.servingConfigs.search

검색을 수행합니다.

HTTP 요청

POST https://discoveryengine.googleapis.com/v1/{servingConfig=projects/*/locations/*/collections/*/engines/*/servingConfigs/*}:search

URL은 gRPC 트랜스코딩 문법을 사용합니다.

경로 매개변수

매개변수
servingConfig

string

필수 항목입니다. 서빙Configs.search 서빙 구성의 리소스 이름입니다(예: projects/*/locations/global/collections/default_collection/engines/*/servingConfigs/default_serving_config 또는 projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config). 이 필드는 검색하는 데 사용되는 모델 집합인 서빙 구성 이름을 식별하는 데 사용됩니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "branch": string,
  "query": string,
  "imageQuery": {
    object (ImageQuery)
  },
  "pageSize": integer,
  "pageToken": string,
  "offset": integer,
  "oneBoxPageSize": integer,
  "dataStoreSpecs": [
    {
      object (DataStoreSpec)
    }
  ],
  "filter": string,
  "canonicalFilter": string,
  "orderBy": string,
  "userInfo": {
    object (UserInfo)
  },
  "languageCode": string,
  "facetSpecs": [
    {
      object (FacetSpec)
    }
  ],
  "boostSpec": {
    object (BoostSpec)
  },
  "params": {
    string: value,
    ...
  },
  "queryExpansionSpec": {
    object (QueryExpansionSpec)
  },
  "spellCorrectionSpec": {
    object (SpellCorrectionSpec)
  },
  "userPseudoId": string,
  "contentSearchSpec": {
    object (ContentSearchSpec)
  },
  "rankingExpression": string,
  "rankingExpressionBackend": enum (RankingExpressionBackend),
  "safeSearch": boolean,
  "userLabels": {
    string: string,
    ...
  },
  "naturalLanguageQueryUnderstandingSpec": {
    object (NaturalLanguageQueryUnderstandingSpec)
  },
  "searchAsYouTypeSpec": {
    object (SearchAsYouTypeSpec)
  },
  "displaySpec": {
    object (DisplaySpec)
  },
  "session": string,
  "sessionSpec": {
    object (SessionSpec)
  },
  "relevanceThreshold": enum (RelevanceThreshold),
  "relevanceScoreSpec": {
    object (RelevanceScoreSpec)
  }
}
필드
branch

string

브랜치 리소스 이름입니다(예: projects/*/locations/global/collections/default_collection/dataStores/default_data_store/branches/0).

default_branch를 브랜치 ID로 사용하거나 이 필드를 비워 기본 브랜치에서 문서를 검색합니다.
query

string

원시 검색어입니다.
imageQuery

object (ImageQuery)

원시 이미지 쿼리입니다.
pageSize

integer

반환할 최대 Document 수입니다. 허용되는 최대값은 데이터 유형에 따라 다릅니다. 최댓값을 초과하는 값은 최댓값으로 변환됩니다.

  • 기본 색인 생성이 있는 웹사이트: 기본값 10, 최댓값 25
  • 고급 색인 생성이 있는 웹사이트: 기본값 25, 최댓값 50
  • 기타: 기본값 50, 최댓값 100

이 필드가 음수이면 INVALID_ARGUMENT이 반환됩니다.
pageToken

string

이전 SearchService.Search 호출에서 수신한 페이지 토큰입니다. 후속 페이지를 검색하려면 이를 입력합니다.

페이지를 매길 때 SearchService.Search에 제공된 다른 모든 매개변수는 페이지 토큰을 제공한 호출과 일치해야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.
offset

integer

검색 결과에서 현재 오프셋 (API에서 관련 있는 것으로 간주되는 Document 중 시작 결과 위치)을 지정하는 0부터 시작하는 정수입니다. 이 필드는 pageToken이 설정되지 않은 경우에만 고려됩니다.

이 필드가 음수이면 INVALID_ARGUMENT이 반환됩니다.

큰 오프셋은 적절한 기준점으로 제한될 수 있습니다.
oneBoxPageSize

integer

OneBox에 반환할 최대 결과 수입니다. 이는 각 OneBox 유형에 개별적으로 적용됩니다. 기본값은 10입니다.
dataStoreSpecs[]

object (DataStoreSpec)

검색할 특정 DataStore와 해당 데이터 스토어의 구성을 정의하는 사양입니다. 데이터 스토어가 여러 개인 Engine에만 적용됩니다. 단일 데이터 스토어가 있는 엔진의 경우 SearchRequest 바로 아래의 사양을 사용해야 합니다.
filter

string

필터 구문은 필터링되는 문서의 하나 이상의 필드에서 조건자를 구성하기 위한 표현식 언어로 구성됩니다. 필터 표현식은 대소문자를 구분합니다.

이 필드를 인식할 수 없으면 INVALID_ARGUMENT가 반환됩니다.

Vertex AI servingConfigs.search의 필터링은 LHS 필터 키를 Vertex AI servingConfigs.search 백엔드에 정의된 키 속성에 매핑하여 실행됩니다. 이 매핑은 고객이 스키마에 정의합니다. 예를 들어 미디어 고객의 스키마에 'name' 필드가 있을 수 있습니다. 이 경우 필터는 다음과 같습니다. filter --> name:'ANY("king kong")'

구문 및 필터 연산자를 비롯한 필터링에 대한 자세한 내용은 필터를 참고하세요.
canonicalFilter

string

사용자가 검색 페이지에서 필터를 선택하지 않고 검색을 실행할 때 적용되는 기본 필터입니다.

질문 확장과 같은 품질 개선이 필요한 경우 모든 검색 요청에 적용되는 필터입니다. 쿼리에 결과가 충분하지 않은 경우 이 필터를 사용하여 쿼리 확장 흐름을 사용 설정할지 여부를 결정합니다. 확장된 검색어 검색에는 원래 필터가 계속 사용됩니다. 높은 검색 품질을 달성하려면 이 필드를 사용하는 것이 좋습니다.

필터 구문에 대한 자세한 내용은 SearchRequest.filter를 참고하세요.
orderBy

string

문서가 반환되는 순서입니다. 문서는 Document 객체의 필드별로 정렬할 수 있습니다. 관련성별로 정렬하는 경우 설정하지 않은 상태로 둡니다. orderBy 표현식은 대소문자를 구분합니다.

웹사이트 검색 결과 정렬에 대한 자세한 내용은 웹 검색 결과 정렬을 참고하세요. 의료 검색 결과 정렬에 대한 자세한 내용은 의료 검색 결과 정렬을 참고하세요. 이 필드를 인식할 수 없으면 INVALID_ARGUMENT가 반환됩니다.
userInfo

object (UserInfo)

최종 사용자에 관한 정보입니다. 분석 및 맞춤설정에 적극 권장됩니다. UserInfo.user_agent은 분석을 위해 deviceType을 추론하는 데 사용됩니다.
languageCode

string

BCP-47 언어 코드(예: 'en-US' 또는 'sr-Latn') 자세한 내용은 표준 필드를 참고하세요. 이 필드는 쿼리를 더 잘 해석하는 데 도움이 됩니다. 값을 지정하지 않으면 쿼리 언어 코드가 자동으로 감지되지만 정확하지 않을 수 있습니다.
facetSpecs[]

object (FacetSpec)

패싯 검색을 위한 패싯 사양입니다. 비어 있으면 패싯이 반환되지 않습니다.

최대 100개의 값이 허용됩니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.
boostSpec

object (BoostSpec)

특정 문서를 상단으로 올리는 부스트 사양입니다. 부스팅에 대한 자세한 내용은 부스팅을 참고하세요.
params

map (key: string, value: value (Value format))

추가 검색 매개변수입니다.

공개 웹사이트 검색의 경우 지원되는 값은 다음과 같습니다.

  • user_country_code: 문자열입니다. 기본값은 비어 있습니다. 비어 있지 않은 값으로 설정하면 제공된 위치에 따라 결과가 제한되거나 부스팅됩니다. 예를 들면 user_country_code: "au"입니다.

사용 가능한 코드는 국가 코드를 참고하세요.

  • searchType: double 기본값은 비어 있습니다. 값에 따라 웹페이지가 아닌 검색을 사용 설정합니다. 유일하게 유효한 비기본값은 1이며, 이 값은 이미지 검색을 사용 설정합니다. 예를 들면 searchType: 1입니다.
queryExpansionSpec

object (QueryExpansionSpec)

검색어 확장이 발생하는 조건을 지정하는 검색어 확장 사양입니다.
spellCorrectionSpec

object (SpellCorrectionSpec)

맞춤법 수정이 적용되는 모드를 지정하는 맞춤법 수정 사양입니다.
userPseudoId

string

방문자 추적을 위한 고유 식별자입니다. 예를 들어 단일 기기에서 방문자를 고유하게 식별할 수 있는 HTTP 쿠키를 사용하여 이를 구현할 수 있습니다. 이 고유 식별자는 방문자가 웹사이트에 로그인 또는 로그아웃해도 변경되지 않아야 합니다.

이 필드에는 unknown_visitor과 같은 고정 값이 있어서는 안 됩니다(NOT).

UserEvent.user_pseudo_id 및 CompleteQueryRequest.user_pseudo_id과 동일한 식별자여야 합니다.

필드는 길이 제한이 128자(영문 기준)인 UTF-8로 인코딩된 문자열이어야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.
contentSearchSpec

object (ContentSearchSpec)

콘텐츠 검색의 동작을 구성하기 위한 사양입니다.
rankingExpression

string

(선택사항) 순위 표현식은 검색 문서의 맞춤 순위를 제어합니다. 이렇게 하면 ServingConfig.ranking_expression이 재정의됩니다. 구문과 지원되는 기능은 rankingExpressionBackend 값에 따라 달라집니다. rankingExpressionBackend이 제공되지 않으면 기본값은 RANK_BY_EMBEDDING입니다.

rankingExpressionBackend가 제공되지 않거나 RANK_BY_EMBEDDING로 설정된 경우 '+'로 조인된 단일 함수 또는 여러 함수여야 합니다.

  • rankingExpression = function, { " + ", function };

지원되는 함수:

  • double * relevanceScore
  • double * dotProduct(embedding_field_path)

함수 변수:

  • relevanceScore: 쿼리와 문서 간의 관련성을 측정하는 데 사용되는 사전 정의된 키워드입니다.
  • embedding_field_path: 쿼리 임베딩 벡터와 함께 사용되는 문서 임베딩 필드입니다.
  • dotProduct: embedding_field_path과 질문 임베딩 벡터 간의 임베딩 함수입니다.

순위 표현식의 예:

문서에 doc_embedding이라는 삽입 필드가 있는 경우 순위 표현식은 0.5 * relevanceScore + 0.3 * dotProduct(doc_embedding)일 수 있습니다.

rankingExpressionBackend이 RANK_BY_FORMULA로 설정된 경우 다음 표현식 유형 (및 + 또는 * 연산자를 사용하여 연결된 조합)이 지원됩니다.

  • double
  • signal
  • log(signal)
  • exp(signal)
  • rr(signal, double > 0) -- 두 번째 인수가 분모 상수인 역수 순위 변환입니다.
  • isNan(signal) - 신호가 NaN이면 0을 반환하고, 그렇지 않으면 1을 반환합니다.
  • fillNan(signal1, signal2 | double) -- signal1이 NaN이면 signal2 | double을 반환하고, 그렇지 않으면 signal1을 반환합니다.

다음은 지원되는 순위 표현식 유형을 사용하는 순위 공식의 몇 가지 예입니다.

  • 0.2 * semanticSimilarityScore + 0.8 * log(keywordSimilarityScore) -- 주로 keywordSimilarityScore의 로그로 순위를 지정하며 semantic_smilarity_score 조정이 약간 있습니다.
  • 0.2 * exp(fillNan(semanticSimilarityScore, 0)) + 0.3 * isNan(keywordSimilarityScore): semanticSimilarityScore의 지수로 순위를 지정합니다. 값이 NaN인 경우 0으로 채우고 semanticSimilarityScore이 NaN인 경우 최종 점수에 상수 0.3 조정을 추가합니다.
  • 0.2 * rr(semanticSimilarityScore, 16) + 0.8 * rr(keywordSimilarityScore, 16) - semantic_smilarity_score의 역수 순위를 약간 조정한 keywordSimilarityScore의 역수 순위로 대부분 순위를 지정합니다.

다음 신호가 지원됩니다.

  • semanticSimilarityScore: Google 소유 모델에서 생성된 임베딩을 사용하여 계산된 의미 유사성 조정입니다. 이 점수는 검색 쿼리가 문서와 얼마나 의미상 유사한지를 나타냅니다.
  • keywordSimilarityScore: 키워드 일치 조정은 Best Match 25 (BM25) 순위 지정 함수를 사용합니다. 이 점수는 확률 모델을 사용하여 문서가 특정 질문과 관련이 있을 확률을 추정하여 계산됩니다.
  • relevanceScore: 독점적인 Google 모델을 사용하여 문서의 콘텐츠와 관련된 맥락에서 사용자 쿼리의 의미와 의도를 파악하는 의미론적 관련성 조정입니다.
  • pctrRank: 순위로 사용되는 예상 전환율 조정은 예상 클릭률 (pCTR)을 사용하여 사용자 관점에서 검색 결과의 관련성과 매력을 측정합니다. pCTR이 높을수록 결과가 사용자의 쿼리 및 의도를 충족할 가능성이 높으므로 순위 지정에 유용한 신호가 됩니다.
  • freshnessRank: 순위로 표시된 최신성 조정
  • documentAge: 문서가 마지막으로 업데이트된 후 경과된 시간(단위: 시간)입니다. 부동 소수점 숫자입니다(예: 0.25는 15분을 의미합니다.
  • topicalityRank: 순위로 표시되는 주제 조정입니다. 독점 Google 모델을 사용하여 질문과 문서 간의 키워드 기반 중복을 확인합니다.
  • baseRank: 결과의 기본 순위
rankingExpressionBackend

enum (RankingExpressionBackend)

(선택사항) 순위 표현식 평가에 사용할 백엔드입니다.
userLabels

map (key: string, value: string)

리소스에 적용된 사용자 라벨은 다음 요구사항을 충족해야 합니다.

  • 각 리소스는 여러 개의 라벨(최대 64개)을 가질 수 있습니다.
  • 각 라벨은 키-값 쌍이어야 합니다.
  • 키는 비워 둘 수 없으며 최소 길이는 1자이고 최대 길이는 63자입니다. 값은 비워 둘 수 있으며 최대 길이는 63자(영문 기준)입니다.
  • 키와 값에는 소문자, 숫자, 밑줄, 대시만 사용할 수 있습니다. 모든 문자는 UTF-8 인코딩을 사용해야 하며 국제 문자가 허용됩니다.
  • 라벨의 키 부분은 고유해야 합니다. 그러나 여러 리소스에 동일한 키를 사용할 수 있습니다.
  • 키는 소문자나 국제 문자로 시작해야 합니다.

자세한 내용은 Google Cloud 문서를 참고하세요.
naturalLanguageQueryUnderstandingSpec

object (NaturalLanguageQueryUnderstandingSpec)

(선택사항) 쿼리에서 구조화된 필드 필터를 추출하는 등 자연어 쿼리 이해 기능의 구성입니다. 자세한 내용은 이 문서를 참고하세요. naturalLanguageQueryUnderstandingSpec가 지정되지 않으면 추가 자연어 쿼리 이해가 실행되지 않습니다.
searchAsYouTypeSpec

object (SearchAsYouTypeSpec)

입력 시 검색 구성입니다. IndustryVertical.MEDIA 카테고리에서만 지원됩니다.
displaySpec

object (DisplaySpec)

(선택사항) 검색 결과의 일치 항목 강조 표시와 같은 디스플레이 기능 구성입니다.
session

string

세션 리소스 이름입니다. (선택사항)

세션을 사용하면 사용자가 다중 턴 /검색 API 호출을 수행하거나 /검색 API 호출과 /답변 API 호출 간에 조정을 할 수 있습니다.

예 1 (다중 턴 /search API 호출): 첫 번째 호출에서 생성된 세션 ID로 /search API를 호출합니다. 여기서는 이전 검색어가 쿼리 순위에 고려됩니다. 즉, 첫 번째 질문이 '2022년 Alphabet의 실적은 어땠어?'인 경우 현재 질문이 '2023년은 어때?'인 경우 현재 질문은 '2023년 Alphabet의 실적은 어때?'로 해석됩니다.

예 2(/search API 호출과 /answer API 호출 간의 조정): 첫 번째 호출에서 생성된 세션 ID로 /answer API를 호출합니다. 여기서는 첫 번째 검색 호출의 검색 결과 컨텍스트에서 답변이 생성됩니다.

Multi-turn servingConfigs.search 기능은 현재 비공개 GA 단계에 있습니다. 이 기능이 공개 GA로 출시되기 전에 v1alpha 또는 v1beta 버전을 사용하거나 Google 지원팀을 통해 허용 목록에 추가해 달라고 요청하세요.
sessionSpec

object (SessionSpec)

세션 사양입니다.

session가 설정된 경우에만 사용할 수 있습니다.
relevanceThreshold

enum (RelevanceThreshold)

검색 결과의 관련성 기준점입니다.

정확도와 재현율의 균형을 활용하여 매우 정확한 결과와 관련 정보의 포괄적인 범위를 제공하는 Google 정의 기준을 기본값으로 설정합니다.

의료 검색에는 이 기능이 지원되지 않습니다.
relevanceScoreSpec

object (RelevanceScoreSpec)

(선택사항) 관련성 점수를 반환하기 위한 사양입니다.

응답 본문

성공한 경우 응답 본문에 SearchResponse의 인스턴스가 포함됩니다.

승인 범위

다음 OAuth 범위 중 하나가 필요합니다.

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.assist.readwrite

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

IAM 권한

servingConfig 리소스에 대해서는 다음 IAM 권한이 필요합니다.

  • discoveryengine.servingConfigs.search

자세한 내용은 IAM 문서를 참조하세요.