取得搜尋結果 (舊版)

本頁說明如何使用 API 取得搜尋結果。

您可以傳送 API 呼叫，並整合到伺服器或應用程式。本頁面提供程式碼範例，說明如何使用 gRPC 用戶端程式庫和服務帳戶執行搜尋查詢。

取得搜尋結果

您可以使用 API 取得搜尋結果。

REST

如要透過 API 取得含有結構化或非結構化資料的應用程式搜尋結果，請使用 engines.servingConfigs.search 方法：

  1. 找出應用程式 ID。如果您已有應用程式 ID，請跳到下一個步驟。

    1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

      前往「應用程式」

    2. 在「Apps」(應用程式) 頁面中，找出應用程式名稱，然後從「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 編碼字串，做為追蹤使用者的不重複匿名 ID。長度上限為 128 個半形字元。Google 強烈建議使用這個欄位，因為這能提升模型效能和個人化品質。您可以使用 HTTP Cookie 填寫這個欄位，在單一裝置上明確識別訪客。以下是幾項重要考量：

      • 即使訪客登入或登出網站，這個 ID 也不會改變。
      • 請勿將這個欄位設為多位使用者共用的 ID。 否則，如果多位使用者共用同一個使用者 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"
    }
  ]
}
}

取得搜尋結果的文件關聯性分數

文件關聯性分數是根據查詢與文件的相似度計算。分數會分成 11 個區間：0、0.1、0.2、… 到 1.0。 分數越高，代表文件關聯性越高。

請考量下列用途的文件關聯性分數：

  • 根據關聯性分數篩選搜尋結果，移除不相關的結果

  • 搜尋後排名或做為其他應用程式的輸入內容

  • 偵錯：關聯性分數可協助您深入分析系統傳回某些搜尋結果的原因

每筆搜尋結果都會傳回關聯性分數：

  "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. 在「Apps」(應用程式) 頁面中，找出應用程式名稱，然後從「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 模型。

  • 如要變更或查看使用者介面「預覽」頁面中使用的 LLM 模型，請前往應用程式的「設定」頁面 >「UI」分頁。

  • 如果是方法呼叫，穩定版模型是預設模型。如要使用穩定版以外的 LLM 模型，請參閱「指定摘要模型」和「指定答案模型」。