Method: projects.locations.dataStores.documents.search

단일 DataStore의 문서를 검색합니다.

순위가 매겨진 하위 문서 세그먼트를 반환하며, 각 세그먼트는 원래 문서로 다시 참조되고 인용에 필요한 출처를 포함합니다.

HTTP 요청

POST https://vectorsearch.googleapis.com/v1beta/{parent}/documents:search

경로 매개변수

매개변수
parent

string

필수 항목입니다. 검색할 DataStore입니다. 형식: projects/{project}/locations/{location}/dataStores/{dataStore}

요청 본문

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

JSON 표현 
{
  "topK": integer,
  "documentIds": [
    string
  ],
  "rankingSpec": {
    object (RankingSpec)
  },
  "filter": {
    object
  },
  "outputFields": {
    object (OutputFields)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "textQuery": {
    object (TextQuery)
  }
  // End of mutually exclusive fields.
}
필드
topK

integer

(선택사항) 반환할 결과 수입니다. 기본값은 10입니다. 100을 초과하는 값은 100으로 변환됩니다.
documentIds[]

string

(선택사항) 검색을 이 문서 ID로 제한합니다. 최대 100개입니다. 비어 있으면 전체 DataStore가 검색됩니다.
rankingSpec

object (RankingSpec)

(선택사항) 결과의 순위가 지정되는 방식을 제어합니다.
filter

object (Struct format)

(선택사항) 검색을 이 필터와 일치하는 세그먼트로 제한합니다. DocumentSearchResult의 필드 경로에 대한 JSON 객체입니다.

  • metadata.<property>: DataStore의 documentMetadataSchema에 선언된 속성(예: metadata.category)
  • unstructured_details.page_range.start_page 및 .end_page: UNSTRUCTURED DataStore의 경우 모든 세그먼트에 페이지 범위가 있는 것은 아닙니다. UnstructuredSegmentDetails.page_range를 참고하세요.
  • video_details.start_offset 및 .end_offset: VIDEO DataStore의 경우 초 단위입니다.

비교: $eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $all, $exists $and, $or, $not와 결합하여 최대 2단계 깊이로 중첩합니다. 예를 들면 다음과 같습니다.

{"$and": [{"metadata.year": {"$gte": 2025}}, {"unstructured_details.page_range.start_page": {"$lte": 20}}]}
outputFields

object (OutputFields)

(선택사항) 각 결과에 반환할 필드입니다.
필수 항목입니다. 검색할 쿼리입니다. 쿼리 유형을 정확히 하나만 설정해야 합니다. 다음은 상호 배타적인 필드 목록입니다. 응답에서 최대 하나의 필드가 설정됩니다.
textQuery

object (TextQuery)

텍스트 쿼리입니다.
상호 배타적인 필드의 끝입니다.

응답 본문

DocumentSearchService.SearchDocuments의 응답 메시지입니다.

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

JSON 표현 
{
  "results": [
    {
      object (DocumentSearchResult)
    }
  ],
  "warnings": [
    {
      object (Status)
    }
  ]
}
필드
results[]

object (DocumentSearchResult)

출력 전용입니다. 검색 기준과 일치하는 문서 세그먼트이며 관련성 순으로 정렬됩니다.
warnings[]

object (Status)

출력 전용입니다. 실행 중에 발생한 경고 또는 심각하지 않은 오류입니다.

승인 범위

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

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/vectorsearch
  • https://www.googleapis.com/auth/vectorsearch.readonly

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

TextQuery

텍스트 쿼리입니다.

JSON 표현 
{
  "text": string
}
필드
text

string

필수 항목입니다. 검색할 텍스트입니다.

RankingSpec

결과의 순위가 지정되는 방식을 제어합니다.

JSON 표현 
{
  "rerankingSpec": {
    object (RerankingSpec)
  }
}
필드
rerankingSpec

object (RerankingSpec)

(선택사항) 순위 재지정 단계를 제어합니다.

RerankingSpec

하이브리드 검색 및 Reciprocal Rank Fusion (RRF) 후 후보 결과에 적용되는 시맨틱 재정렬 구성입니다.

JSON 표현 
{
  "enabled": boolean,
  "rankOversamplingFactor": integer
}
필드
enabled

boolean

(선택사항) 융합된 결과의 순위를 다시 매길지 여부입니다. 기본값은 false입니다. 호출자가 선택하지 않는 한 결과는 RRF 융합 순서로 반환됩니다.

사용 설정하면 재정렬은 Vertex 순위 서비스에서 semantic-ranker-fast@latest를 사용하며 호출자의 프로젝트에서 Discovery Engine API를 사용 설정해야 합니다.

VIDEO DataStore에는 지원되지 않습니다. 이를 사용 설정하는 요청은 INVALID_ARGUMENT으로 인해 실패합니다.
rankOversamplingFactor

integer

(선택사항) 순위를 다시 매기기 전에 후보를 오버샘플링하는 데 사용할 계수입니다. 재정렬을 위해 검색된 총 후보 수는 min(rankOversamplingFactor * topK, 200)개입니다. 순위 재지정 후 결과가 SearchDocumentsRequest.top_k개로 잘립니다.

enabled가 true가 아니면 무시됩니다. 사용 설정하면 기본값은 5입니다(min(5 * topK, 200) 후보 검색, 최대 200개).

오버샘플링 없이 순위를 다시 매기려면 이 필드를 1로 설정합니다.

OutputFields

모든 결과에 포함되는 필드 외에 각 DocumentSearchResult에 반환할 필드입니다.

JSON 표현 
{
  "metadata": [
    string
  ]
}
필드
metadata[]

string

(선택사항) DocumentSearchResult.document.metadata에서 반환할 메타데이터 속성으로, DataStore의 documentMetadataSchema에 선언된 대로 이름이 지정됩니다. 중첩된 속성은 filter에서 사용하는 metadata. 프리픽스 없이 점으로 구분된 경로(예: address.city)로 이름이 지정됩니다. "*"는 선언된 모든 속성을 반환합니다. 설정 해제하면 아무것도 반환되지 않습니다. 문서에 값이 없는 속성은 생략됩니다.

DocumentSearchResult

문서의 일치하는 단일 세그먼트입니다.

JSON 표현 
{
  "document": {
    object (Document)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "videoDetails": {
    object (VideoSegmentDetails)
  },
  "unstructuredDetails": {
    object (UnstructuredSegmentDetails)
  }
  // End of mutually exclusive fields.
}
필드
document

object (Document)

출력 전용입니다. 리소스 이름과 이 세그먼트가 수집된 Cloud Storage 위치를 포함하여 이 세그먼트가 속한 문서입니다.

모든 문서 필드가 채워지는 것은 아닙니다. 전체 문서를 가져오려면 반환된 문서 이름에서 documents.get을 호출합니다.
문서 내에서 세그먼트가 위치하는 위치에 대한 세부정보입니다. 설정되는 필드는 상위 DataStore의 document_type를 따릅니다. 다음은 상호 배타적인 필드 목록입니다. 응답에서 최대 하나의 필드가 설정됩니다.
videoDetails

object (VideoSegmentDetails)

상위 Datastore의 documentType가 VIDEO인 경우에 설정됩니다.
unstructuredDetails

object (UnstructuredSegmentDetails)

상위 Datastore의 documentType가 UNSTRUCTURED인 경우에 설정됩니다.
상호 배타적인 필드의 끝입니다.

VideoSegmentDetails

동영상 문서 내에서 세그먼트를 찾습니다.

JSON 표현 
{
  "startOffset": string,
  "endOffset": string
}
필드
startOffset

string (Duration format)

출력 전용입니다. 원본 동영상의 시작을 기준으로 이 세그먼트가 시작되는 위치입니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.
endOffset

string (Duration format)

출력 전용입니다. 원본 동영상의 시작을 기준으로 이 세그먼트가 끝나는 위치입니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.

UnstructuredSegmentDetails

비정형 문서 내에서 세그먼트를 찾아 텍스트를 전달합니다.

JSON 표현 
{
  "contentSnippet": string,
  "pageRange": {
    object (PageRange)
  }
}
필드
contentSnippet

string

출력 전용입니다. 세그먼트의 텍스트 콘텐츠입니다.
pageRange

object (PageRange)

출력 전용입니다. 소스 문서에서 세그먼트가 위치하는 곳입니다. PDF, PowerPoint, Excel 파일에 설정합니다. 여기서 페이지는 PDF 페이지, 슬라이드 또는 시트입니다. 일반 텍스트 및 Word 파일의 경우 파일이 페이지로 분할된 경우에만 설정합니다(디지털 파싱이 포함된 pageSegmentationConfig). 페이지는 순서대로 번호가 매겨진 연속된 텍스트 섹션입니다.

PageRange

소스 문서 내의 페이지 범위입니다. 페이지는 1부터 시작하며 범위는 포함됩니다. 단일 페이지는 startPage == endPage로 표시됩니다.

JSON 표현 
{
  "startPage": string,
  "endPage": string
}
필드
startPage

string (int64 format)

출력 전용입니다. 범위의 첫 번째 페이지입니다.
endPage

string (int64 format)

출력 전용입니다. 범위의 마지막 페이지입니다.