검색 결과 가져오기 (기존)

이 페이지에서는 API를 사용하여 검색 결과를 가져오는 방법을 보여줍니다.

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

검색결과 가져오기

API를 사용하여 검색 결과를 가져올 수 있습니다.

REST

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

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

    1. Google Cloud 콘솔에서 Gemini Enterprise 페이지로 이동합니다.

      앱으로 이동

    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: 프로젝트의 ID입니다.
    • APP_ID: 쿼리할 앱의 ID입니다.
    • QUERY: 검색할 쿼리 텍스트입니다.
    • USER_PSEUDO_ID: 사용자를 추적하는 고유한 가명 식별자 역할을 하는 UTF-8로 인코딩된 문자열입니다. 최대 길이는 128자(영문 기준)입니다. 모델 성능 및 맞춤설정 품질이 향상되므로 이 필드를 사용하는 것이 좋습니다. 이 필드에는 단일 기기의 방문자를 고유하게 식별하는 HTTP 쿠키를 사용할 수 있습니다. 몇 가지 중요한 고려사항은 다음과 같습니다.

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

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

    • PAGE_SIZE: 검색으로 반환된 결과 수입니다. 허용되는 최대 페이지 크기는 데이터 유형에 따라 다릅니다. 최댓값을 초과하는 페이지 크기는 최댓값으로 변환됩니다.

    • 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: 검색할 특정 데이터 스토어의 필터입니다. 검색 앱이 여러 데이터 스토어에 연결된 경우에 사용할 수 있습니다. 자세한 내용은 DataStoreSpec을 참조하세요.

    • 검색 응답에서 안내식 검색 결과 보기:

      안내식 검색 결과는 정형 및 비정형 검색의 검색 응답으로 반환됩니다. 안내식 검색 결과에는 검색 결과 문서를 기반으로 추출된 속성 키-값 쌍의 목록이 포함됩니다. 그러면 사용자가 일부 속성 키와 값을 필터로 사용해서 검색 결과를 미세 조정할 수 있습니다.

      이 응답 예시에서 녹색 색상은 _gs.color: ANY("green")으로 지정된 필터 필드로 새로운 검색 요청을 수행하여 검색 결과를 미세 조정하기 위해 사용되었습니다.

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

검색 결과로 문서 관련성 점수 가져오기

문서 관련성 점수는 문서에 대한 쿼리의 유사성을 기반으로 합니다. 점수는 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 콘솔에서 Gemini Enterprise 페이지로 이동합니다.

      앱으로 이동

    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: 프로젝트의 ID입니다.
    • APP_ID: 쿼리할 앱의 ID입니다.
    • QUERY: 검색할 쿼리 텍스트입니다.

모델별 검색 요약 차이

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

  • UI의 미리보기 페이지에 사용되는 LLM 모델을 변경하거나 보려면 해당 앱에서 구성 페이지 > UI 탭으로 이동합니다.

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