知識庫混合檢索與Rerank排序策略配置（向量、全文、中繼資料過濾） - Tablestore

通過 Retrieve 介面在知識庫中執行語義檢索，返回與查詢文本最相關的切片列表。支援向量檢索、全文檢索索引及混合檢索，支援中繼資料過濾和多種排序（Rerank）策略。

檢索配置優先順序

Retrieve 介面的檢索配置（retrievalConfiguration）按以下優先順序確定最終生效的參數：

優先順序	來源	說明
1（最高）	Retrieve 介面參數	本次請求中傳入的 `retrievalConfiguration`，僅對當次生效
2	知識庫層級配置	建立知識庫時設定，可通過 UpdateKnowledgeBase 隨時修改
3（最低）	系統預設值	向量 + 全文混合檢索，WEIGHT 加權融合（向量 0.7 : 全文 0.3），返回 20 條結果

最簡單的檢索請求只需傳 knowledgeBaseName 和 retrievalQuery，系統自動使用知識庫配置或預設值。

檢索類型

類型	說明	適用情境
`DENSE_VECTOR`	向量檢索，基於語義相似性	用自然語言描述需求，需要理解語義。如"怎麼安裝"能匹配到"部署步驟"
`FULL_TEXT`	全文檢索索引，基於關鍵詞匹配	輸入精確關鍵詞、專有名詞或編號

向量檢索和全文檢索索引在召回上具有互補能力：向量檢索擅長語義理解，全文檢索索引擅長精確匹配。建議同時開啟兩種檢索類型，通過 Rerank 融合結果。

Rerank 排序策略

Rerank 將向量檢索和全文檢索索引的結果融合排序，返回最終結果。

WEIGHT（加權融合）

按比例加權向量與全文檢索索引得分。適合需要精細控制兩路檢索貢獻比例的情境。推薦作為預設選擇。

配置參數：

參數	類型	預設值	說明
`denseVectorSearchWeight`	double	0.7	向量檢索加權比例
`fullTextSearchWeight`	double	0.3	全文檢索索引加權比例

RRF（Reciprocal Rank Fusion）

按排名倒數加權融合多路檢索結果。無需額外模型調用，延遲低，效果穩定。

配置參數：

參數	類型	預設值	說明
`denseVectorSearchWeight`	double	1.0	向量檢索權重
`fullTextSearchWeight`	double	1.0	全文檢索索引權重
`k`	int	60	RRF 演算法參數，必須大於 0

配置樣本：

{
  "rerankingConfiguration": {
    "type": "RRF",
    "numberOfResults": 5,
    "rrfConfiguration": {
      "denseVectorSearchWeight": 0.6,
      "fullTextSearchWeight": 0.4,
      "k": 20
    }
  }
}

MODEL（模型 Rerank）

調用 Rerank 模型（如 gte-rerank-v2）對候選結果重排序。排序品質最高，但會引入額外延遲和計算成本。

配置參數：

參數	類型	預設值	說明
`provider`	string	`bailian`	Rerank 模型提供方，當前僅支援百鍊
`model`	string	`gte-rerank-v2`	Rerank 模型名稱

策略選擇建議

情境	推薦策略
通用情境，對延遲敏感	RRF
需要精細控制向量與全文檢索索引的比例	WEIGHT
對排序品質要求極高，可接受額外延遲	MODEL

中繼資料過濾

在檢索時通過 filter 參數按中繼資料條件過濾結果，縮小候選範圍。過濾欄位必須在建立知識庫時通過 metadata 定義。

比較運算元

運算元	符號	說明	適用類型
`equals`	=	等於	所有類型
`notEquals`	≠	不等於	所有類型
`greaterThan`	>	大於	long, double, date
`greaterThanOrEquals`	≥	大於等於	long, double, date
`lessThan`	<	小於	long, double, date
`lessThanOrEquals`	≤	小於等於	long, double, date

集合與匹配運算元

運算元	說明	適用類型
`in`	值在給定集合中	所有類型
`notIn`	值不在給定集合中	所有類型
`startsWith`	字串首碼匹配	string
`stringContains`	字串包含匹配	string
`listContains`	列表欄位包含指定元素	list 類型

邏輯組合運算元

運算元	說明
`andAll`	所有條件同時滿足
`orAll`	任一條件滿足
`notAll`	所有條件都不滿足

andAll、orAll和notAll支援嵌套，可構建複雜的組合過濾邏輯。

過濾樣本

查詢 category 為 “technology” 或 “science”，且 score ≥ 60，且 title 以“產品”開頭的文檔：

{
  "filter": {
    "andAll": [
      {"in": {"key": "category", "value": ["technology", "science"]}},
      {"greaterThanOrEquals": {"key": "score", "value": 60}},
      {"startsWith": {"key": "title", "value": "產品"}}
    ]
  }
}

使用 orAll 實現“或”邏輯：查詢 status 為 “active” 或 score > 90 的文檔：

{
  "filter": {
    "orAll": [
      {"equals": {"key": "status", "value": "active"}},
      {"greaterThan": {"key": "score", "value": 90}}
    ]
  }
}

Retrieve 介面

請求參數

參數	類型	說明
`knowledgeBaseName`	string	知識庫名稱（必填）
`subspace`	list<string>	子空間列表，最多 32 個。開啟 subspace 時必填
`retrievalQuery`	object	檢索查詢（必填）
`retrievalQuery.type`	string	查詢類型（必填）。當前僅支援 `TEXT`
`retrievalQuery.text`	string	檢索文本（必填）。最長 128 字元
`retrievalConfiguration`	object	檢索配置，不傳時使用知識庫層級配置或系統預設值
`retrievalConfiguration.searchType`	list<string>	檢索類型
`retrievalConfiguration.denseVectorSearchConfiguration.numberOfResults`	int	向量檢索返回數量，最大 100
`retrievalConfiguration.fullTextSearchConfiguration.numberOfResults`	int	全文檢索索引返回數量，最大 100
`retrievalConfiguration.rerankingConfiguration`	object	Rerank 配置
`retrievalConfiguration.filter`	object	中繼資料過濾條件

響應說明

響應欄位

欄位	類型	說明
`retrievalResults`	list<object>	檢索結果清單，按相關性得分降序排列
`retrievalResults[].docId`	string	所屬文檔 ID
`retrievalResults[].chunkId`	int	切片 ID
`retrievalResults[].ossKey`	string	所屬文檔 OSS 路徑
`retrievalResults[].score`	float	相關性得分，越高越相關
`retrievalResults[].content`	string	切片原文內容
`retrievalResults[].subspace`	string	所屬子空間
`retrievalResults[].metadata`	object	文檔中繼資料

程式碼範例

最簡樣本

請求裡面不設定檢索參數，使用知識庫層級配置或系統預設值：

resp = client.retrieve({
    "knowledgeBaseName": "product_docs_kb",
    "retrievalQuery": {"type": "TEXT", "text": "產品的安裝步驟是什麼"}
})

for r in resp["data"]["retrievalResults"]:
    print(f"[{r['score']:.4f}] {r['content'][:80]}...")

完整樣本

檢索請求裡面設定全部或部分檢索參數，覆蓋知識庫層級配置：

resp = client.retrieve({
    "knowledgeBaseName": "product_docs_kb",
    "subspace": ["default"],
    "retrievalQuery": {"type": "TEXT", "text": "產品的安裝步驟是什麼"},
    "retrievalConfiguration": {
        "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
        "denseVectorSearchConfiguration": {"numberOfResults": 10},
        "fullTextSearchConfiguration": {"numberOfResults": 10},
        "rerankingConfiguration": {
            "type": "RRF",
            "numberOfResults": 5,
            "rrfConfiguration": {
                "denseVectorSearchWeight": 0.6,
                "fullTextSearchWeight": 0.4,
                "k": 60
            }
        },
        "filter": {
            "andAll": [
                {"in": {"key": "category", "value": ["產品文檔"]}}
            ]
        }
    }
})

for result in resp["data"]["retrievalResults"]:
    print(f"[score={result['score']:.4f}] {result['content'][:100]}...")
    print(f"  來源: {result['ossKey']}, chunkId: {result['chunkId']}")

Model 類方式

使用 Model 類構建請求，獲得更好的 IDE 代碼補全和類型檢查：

from tablestore_agent_storage.models import (
    RetrieveRequest, RetrievalQuery, RetrievalQueryType
)

resp = client.retrieve(RetrieveRequest(
    knowledge_base_name="product_docs_kb",
    retrieval_query=RetrievalQuery(
        text="產品的安裝步驟是什麼",
        type=RetrievalQueryType.TEXT
    )
))

響應樣本

{
  "code": "SUCCESS",
  "data": {
    "retrievalResults": [
      {
        "ossKey": "oss://example-bucket/docs/product_manual.pdf",
        "docId": "96fb386e-...",
        "chunkId": 3,
        "subspace": "default",
        "score": 0.85,
        "content": "第一步：下載安裝包...",
        "metadata": {"author": "張三", "category": "產品文檔"}
      }
    ]
  },
  "message": "succeed"
}

注意事項

問題	說明
檢索文本過長	`text` 最長 128 字元或漢字，超過會報錯說明如有業務需求請提交工單或加入Table Store技術交流群36165029092後聯絡支援人員。
Filter 欄位未定義	過濾欄位必須在建立知識庫時已定義為 metadata
RRF 的 k 值為 0	`k` 必須大於 0，否則報 `VALIDATION_ERROR`
文檔未索引完成	`Pending` 或 `Indexing` 狀態的文檔無法被檢索
未傳 subspace	知識庫開啟 subspace 後必須傳此參數

檢索調優

numberOfResults 參數關係

檢索流程中有三層 numberOfResults，理解它們的關係是調優的關鍵：

denseVectorSearchConfiguration.numberOfResults = N1  ← 向量檢索召回數
fullTextSearchConfiguration.numberOfResults         = N2  ← 全文檢索索引召回數
rerankingConfiguration.numberOfResults           = N3  ← Rerank 後最終返回數

N1 和 N2 決定候選池大小，越大召回率越高，但計算成本也越高。
N3 決定最終返回的結果數，通常 N3 < N1 且 N3 < N2。
推薦起始配置：N1 = N2 = 20，N3 = 5–10。根據實際效果逐步調整。

檢索類型選擇

情境	推薦檢索類型	說明
用自然語言提問	`DENSE_VECTOR` + `FULL_TEXT`	向量捕捉語義，全文保障關鍵詞命中
輸入精確關鍵詞或編號	優先 `FULL_TEXT`	向量檢索對精確匹配不敏感
純語義理解情境	優先 `DENSE_VECTOR`	如"怎麼安裝"匹配"部署步驟"

Metadata Filter 使用建議

Filter 在檢索前縮小候選範圍，同時提升檢索精度和效能。
過濾欄位必須在建立知識庫時定義為 metadata，運行時無法新增。
對於日期範圍過濾，使用 date 類型而非 string 類型，以支援範圍比較運算元。