使用排名 API 改善搜尋和 RAG 品質

在 AI 應用程式中，您可以透過檢索增強生成 (RAG) 技術，根據查詢為一組文件進行排名。

排名 API 會取得文件清單，並根據文件與查詢的關聯性重新排序。與只會查看文件和查詢語意相似度的嵌入功能相比，排名 API 可提供精確的分數，指出文件回答特定查詢的程度。擷取初始候選文件集後，您可以使用排名 API 改善搜尋結果的品質。

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

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

用途

排名 API 的主要用途是改善搜尋結果的品質。

不過，如果您需要找出與使用者查詢最相關的內容，排名 API 就非常實用。舉例來說，排名 API 可協助您執行下列操作：

• 找出適合提供給 LLM 的內容，以便進行基礎訓練

• 改善現有搜尋體驗的關聯性

• 找出文件中的相關部分

以下流程概述如何使用排名 API 改善分割文件的結果品質：

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

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

3. 將嵌入內容載入 Vector Search 或其他搜尋解決方案。

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

5. 使用排名 API 重新為相關片段排序。

輸入資料

排名 API 需要下列輸入內容：

• 您要為其排名的查詢。

  例如：

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

• 與查詢相關的一組記錄。記錄會以物件陣列的形式提供。每筆記錄可包含專屬 ID、標題和文件內容。每個記錄都必須包含標題和/或內容。每筆記錄支援的權杖數量上限取決於所使用的模型版本。舉例來說，版本 003 以下的模型支援 512 個符記，而版本 004 則支援 1024 個符記。如果標題和內容的總長度超出模型的符記限制，系統會截斷多餘的內容。每項要求最多可包含 200 筆記錄。

  舉例來說，記錄陣列的格式如下：實際上，陣列會包含更多記錄，內容也會更長：

  "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."
     }
  ]
  

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

  例如，這會傳回排名前 10 位的記錄：

  "topN": 10,
  

• 選用：這個設定可指定您要 API 傳回的記錄 ID 為何，或是要傳回記錄標題和內容。根據預設，系統會傳回完整記錄。設定這個值的主要原因是，如果您想縮減回應酬載的大小。

  舉例來說，將值設為 true 只會傳回記錄 ID，而不會傳回標題或內容：

  "ignoreRecordDetailsInResponse": true,
  

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

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

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

輸出資料

排名 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 提供查詢，以及與該查詢相關的一組記錄，且這些記錄已透過其他方法 (例如關鍵字搜尋或向量搜尋) 進行排名。接著，您可以使用排名 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-512@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 使用排名方法，從非結構化資料產生根據基準生成的答案。