使用排名 API 提升搜尋和 RAG 品質

在 Agent Search 中使用檢索增強生成 (RAG) 時，您可以根據查詢為一組文件排序。

Ranking API 會根據文件與查詢的關聯程度，重新排列文件清單。嵌入只會考量文件和查詢的語意相似度，而 Ranking API 則能精確評估文件回答特定查詢的成效。擷取初始候選文件後，您可以使用排名 API 提升搜尋結果品質。

排名 API 為無狀態，因此呼叫 API 前不需為文件建立索引。只要傳入查詢和文件即可。因此，這項 API 非常適合用於重新排序向量搜尋和其他搜尋解決方案的文件。

本頁面說明如何使用 Ranking API，根據查詢為一組文件排名。

用途

Ranking API 的主要用途是提升搜尋結果品質。

不過，只要需要找出與使用者查詢最相關的內容，Ranking API 都能派上用場。舉例來說，Ranking API 可協助您執行下列操作：

• 找出合適的內容，提供給 LLM 做為基準

• 提升現有搜尋體驗的關聯性

• 找出文件的相關部分

下列流程概述如何使用 Ranking API，提升分塊文件的結果品質：

1. 使用 Document AI Layout Parser API，將一組文件分割為幾個分塊。

2. 使用嵌入 API 為每個區塊建立嵌入。

3. 將嵌入載入向量搜尋或其他搜尋解決方案。

4. 查詢搜尋索引，並擷取最相關的區塊。

5. 使用 Ranking API 重新排序相關區塊。

輸入資料

Ranking API 需要下列輸入內容：

• 要用來為記錄排名的查詢。

  例如：

  "query": "Why is the sky blue?"
  

• 與查詢相關的一組記錄。記錄會以物件陣列的形式提供。每筆記錄都可以包含專屬 ID、標題和文件內容。每筆記錄都必須包含標題和/或內容。每筆記錄支援的權杖數量上限，取決於使用的模型版本。舉例來說，003 以下版本支援 512 個詞元，004 版則支援 1024 個詞元。如果標題和內容的總長度超過模型的詞元限制，系統會將多餘的內容分塊並分段處理。如果記錄過長，系統會截斷並忽略部分內容。

  每項要求最多可包含 1,000 筆記錄。

  舉例來說，記錄陣列看起來像這樣。實際上，陣列中會包含更多記錄，內容也會更長：

  "records": [
     {
         "id": "1",
         "title": "The Color of the Sky: A Poem",
         "content": "A canvas stretched across the day,\nWhere sunlight learns to dance and play.\nBlue, a hue of scattered light,\nA gentle whisper, soft and bright."
     },
     {
         "id": "2",
         "title": "The Science of a Blue Sky",
         "content": "The sky appears blue due to a phenomenon called Rayleigh scattering. Sunlight is comprised of all the colors of the rainbow. Blue light has shorter wavelengths than other colors, and is thus scattered more easily."
     }
  ]
  

• 選用：Ranking API 傳回的記錄數量上限。根據預設，系統會傳回所有記錄，但您可以使用 topN 欄位減少傳回的記錄數量。無論設定的值為何，所有記錄都會進行排名。

  舉例來說，下列查詢會傳回排名前 10 的記錄：

  "topN": 10,
  

• 選用：這項設定可指定是否只要 API 傳回記錄 ID，還是要一併傳回記錄標題和內容。根據預設，系統會傳回完整記錄。設定這項屬性的主要原因，是為了縮減回應酬載的大小。

  舉例來說，如果設為 true，系統只會傳回記錄 ID，不會傳回標題或內容：

  "ignoreRecordDetailsInResponse": true,
  

• 選用：模型名稱。這會指定用於文件排名的模型。如未指定模型，則會使用 semantic-ranker-default@latest，自動指向最新可用模型。如要指向特定模型，請指定「支援的模型」中列出的其中一個模型名稱，例如 semantic-ranker-512-003。

  在以下範例中，model 設為 semantic-ranker-default@latest。也就是說，Ranking API 一律會使用最新的可用模型。

  "model": "semantic-ranker-default@latest"
  

輸出資料

Ranking API 會傳回排名記錄清單，並提供下列輸出內容：

• 分數：介於 0 和 1 之間的浮點值，表示記錄的關聯性。

• ID：記錄的專屬 ID。

• 如果要求，則為完整物件：ID、標題和內容。

  例如：

{
    "records": [
        {
            "id": "2",
            "score": 0.98,
            "title": "The Science of a Blue Sky",
            "content": "The sky appears blue due to a phenomenon called Rayleigh scattering. Sunlight is comprised of all the colors of the rainbow. Blue light has shorter wavelengths than other colors, and is thus scattered more easily."
        },
        {
            "id": "1",
            "score": 0.64,
            "title": "The Color of the Sky: A Poem",
            "content": "A canvas stretched across the day,\nWhere sunlight learns to dance and play.\nBlue, a hue of scattered light,\nA gentle whisper, soft and bright."
        }
    ]
}

根據查詢對一組記錄進行排名 (或重新排名)

一般來說，您會向排名 API 提供查詢和一組與該查詢相關的記錄，這些記錄已透過其他方法 (例如關鍵字搜尋或向量搜尋) 排序。接著，您可以使用 Ranking API 提高排名品質，並判斷分數，指出每筆記錄與查詢的關聯性。

1. 取得查詢和結果記錄。請確認每筆記錄都有 ID，以及標題和/或內容。

   每筆記錄支援的權杖數量上限取決於模型版本。003 以下版本 (例如 semantic-ranker-512-003) 的模型，每筆記錄支援 512 個詞元。從 004 版本開始，這項限制會提高至 1024 個詞元。如果標題和內容的總長度超過模型的詞元限制，系統會將多餘的內容分塊並分段處理。在極端情況下，如果記錄過長，系統會截斷並忽略部分內容。

2. 使用下列程式碼呼叫 rankingConfigs.rank 方法：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/rankingConfigs/default_ranking_config:rank" \
-d '{
"model": "semantic-ranker-default@latest",
"query": "QUERY",
"records": [
    {
        "id": "RECORD_ID_1",
        "title": "TITLE_1",
        "content": "CONTENT_1"
    },
    {
        "id": "RECORD_ID_2",
        "title": "TITLE_2",
        "content": "CONTENT_2"
    },
    {
        "id": "RECORD_ID_3",
        "title": "TITLE_3",
        "content": "CONTENT_3"
    }
]
}'

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: my-project-123" \
    "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/rankingConfigs/default_ranking_config:rank" \
    -d '{
        "model": "semantic-ranker-default@latest",
        "query": "what is Google gemini?",
        "records": [
            {
                "id": "1",
                "title": "Gemini",
                "content": "The Gemini zodiac symbol often depicts two figures standing side-by-side."
            },
            {
                "id": "2",
                "title": "Gemini",
                "content": "Gemini is a cutting edge large language model created by Google."
            },
            {
                "id": "3",
                "title": "Gemini Constellation",
                "content": "Gemini is a constellation that can be seen in the night sky."
            }
        ]
    }'
    

{
    "records": [
        {
            "id": "2",
            "title": "Gemini",
            "content": "Gemini is a cutting edge large language model created by Google.",
            "score": 0.97
        },
        {
            "id": "3",
            "title": "Gemini Constellation",
            "content": "Gemini is a constellation that can be seen in the night sky.",
            "score": 0.18
        },
        {
            "id": "1",
            "title": "Gemini",
            "content": "The Gemini zodiac symbol often depicts two figures standing side-by-side.",
            "score": 0.05
        }
    ]
}

from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"

client = discoveryengine.RankServiceClient()

# The full resource name of the ranking config.
# Format: projects/{project_id}/locations/{location}/rankingConfigs/default_ranking_config
ranking_config = client.ranking_config_path(
    project=project_id,
    location="global",
    ranking_config="default_ranking_config",
)
request = discoveryengine.RankRequest(
    ranking_config=ranking_config,
    model="semantic-ranker-default@latest",
    top_n=10,
    query="What is Google Gemini?",
    records=[
        discoveryengine.RankingRecord(
            id="1",
            title="Gemini",
            content="The Gemini zodiac symbol often depicts two figures standing side-by-side.",
        ),
        discoveryengine.RankingRecord(
            id="2",
            title="Gemini",
            content="Gemini is a cutting edge large language model created by Google.",
        ),
        discoveryengine.RankingRecord(
            id="3",
            title="Gemini Constellation",
            content="Gemini is a constellation that can be seen in the night sky.",
        ),
    ],
)

response = client.rank(request=request)

# Handle the response
print(response)

支援的模型

可用的模型如下。

後續步驟

瞭解如何搭配使用排名方法與其他 RAG API，根據非結構化資料生成有依據的答案。