이 페이지는 Cloud Translation API를 통해 번역되었습니다.

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

HTTP 요청
경로 매개변수
요청 본문
- JSON 표현
응답 본문
승인 범위
IAM 권한

검색을 수행합니다.

HTTP 요청

POST https://discoveryengine.googleapis.com/v1beta/{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`). 이 필드는 검색하는 데 사용되는 모델 집합인 서빙 구성 이름을 식별하는 데 사용됩니다.

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 표현

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, "regionCode": string, "facetSpecs": [ { object (`FacetSpec`) } ], "boostSpec": { object (`BoostSpec`) }, "params": { string: value, ... }, "queryExpansionSpec": { object (`QueryExpansionSpec`) }, "spellCorrectionSpec": { object (`SpellCorrectionSpec`) }, "userPseudoId": string, "contentSearchSpec": { object (`ContentSearchSpec`) }, "embeddingSpec": { object (`EmbeddingSpec`) }, "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`), "personalizationSpec": { object (`PersonalizationSpec`) }, "relevanceScoreSpec": { object (`RelevanceScoreSpec`) }, "searchAddonSpec": { object (`SearchAddonSpec`) } }

{
  "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,
  "regionCode": string,
  "facetSpecs": [
    {
      object (FacetSpec)
    }
  ],
  "boostSpec": {
    object (BoostSpec)
  },
  "params": {
    string: value,
    ...
  },
  "queryExpansionSpec": {
    object (QueryExpansionSpec)
  },
  "spellCorrectionSpec": {
    object (SpellCorrectionSpec)
  },
  "userPseudoId": string,
  "contentSearchSpec": {
    object (ContentSearchSpec)
  },
  "embeddingSpec": {
    object (EmbeddingSpec)
  },
  "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),
  "personalizationSpec": {
    object (PersonalizationSpec)
  },
  "relevanceScoreSpec": {
    object (RelevanceScoreSpec)
  },
  "searchAddonSpec": {
    object (SearchAddonSpec)
  }
}

필드
`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') 자세한 내용은 표준 필드를 참고하세요. 이 필드는 쿼리를 더 잘 해석하는 데 도움이 됩니다. 값을 지정하지 않으면 쿼리 언어 코드가 자동으로 감지되지만 정확하지 않을 수 있습니다.
`regionCode`	`string` 위치를 나타내는 Unicode 국가/지역 코드(CLDR)입니다(예: 'US', '419'). 자세한 내용은 표준 필드를 참고하세요. 설정된 경우 제공된 regionCode를 기반으로 결과가 부스팅됩니다.
`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)` 콘텐츠 검색의 동작을 구성하기 위한 사양입니다.
`embeddingSpec`	`object (EmbeddingSpec)` 제공된 임베딩을 사용하여 추가 시맨틱 문서 검색을 실행합니다. 검색은 `SearchRequest.EmbeddingSpec.EmbeddingVector.vector`와 `SearchRequest.EmbeddingSpec.EmbeddingVector.field_path`에 제공된 문서 임베딩의 내적을 기반으로 합니다. `SearchRequest.EmbeddingSpec.EmbeddingVector.field_path`가 제공되지 않으면 `ServingConfig.EmbeddingConfig.field_path`가 사용됩니다.
`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)` (선택사항) 순위 표현식 평가에 사용할 백엔드입니다.
`safeSearch`	`boolean` 세이프 서치를 사용 설정할지 여부입니다. 웹사이트 검색에만 지원됩니다.
`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 정의 기준을 기본값으로 설정합니다. 의료 검색에는 이 기능이 지원되지 않습니다.
`personalizationSpec`	`object (PersonalizationSpec)` 맞춤설정 사양입니다. `ServingConfig.personalization_spec`와 `SearchRequest.personalization_spec`가 모두 설정된 경우 `SearchRequest.personalization_spec`가 `ServingConfig.personalization_spec`보다 우선 적용됩니다.
`relevanceScoreSpec`	`object (RelevanceScoreSpec)` (선택사항) 관련성 점수를 반환하기 위한 사양입니다.
`searchAddonSpec`	`object (SearchAddonSpec)` (선택사항) SearchAddonSpec은 새로운 가격 재산정 모델에 따라 검색의 부가기능을 사용 중지하는 데 사용됩니다. 이 필드는 검색 요청에만 지원됩니다.

응답 본문

성공한 경우 응답 본문에 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 문서를 참조하세요.