取得搜尋結果 (舊版)

這個頁面說明如何使用 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 編碼的字串，可做為追蹤使用者的專屬匿名 ID。長度上限為 128 個半形字元。 Google 強烈建議使用這個欄位，因為這有助於提升模型效能和個人化品質。您可以使用 HTTP Cookie 做為這個欄位的值，明確識別單一裝置上的訪客。以下是幾個重要考量：

      • 訪客登入或登出網站時，這個 ID 不會變更。
      • 這個欄位不得為多位使用者設定相同的 ID。 否則，如果多位使用者使用相同的 User-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：選用。執行多面向搜尋的 Facet 規格。

    • 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. 在「應用程式」頁面中找出應用程式名稱，然後從「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 模型，請參閱「指定摘要模型」和「指定答案模型」。