Tablestore：使用建議

Embedding 模型選型

Embedding 模型決定了向量檢索的語義理解能力，建立後不可修改，是建立知識庫前最重要的決策。

Metadata Schema 設計

metadata 欄位在建立知識庫時定義，建立後不可增刪。設計時遵循以下原則：

• 提前規劃：梳理所有可能用於過濾檢索結果的維度（分類、時間、作者、版本、部門等），建立時一次性定義。

• 選擇正確的類型：日期用 date 類型（而非 string），數值用 long 或 double，以支援範圍過濾（greaterThanOrEquals 等）。

  說明

  date支援的格式：yyyy-MM-dd、yyyy-MM-dd HH:mm:ss、yyyy-MM-dd HH:mm:ss.SSS、yyyyMMdd HHmmss、yyyy-MM-dd'T'HH:mm:ss

• 控制欄位數量：最多支援 200 個欄位，但建議只定義實際需要的欄位。

• 注意總大小限制：所有 metadata 的 key + value 合計不超過 4KB。避免在 metadata 中儲存大段文本。

Subspace 規劃

大批量文檔匯入

單次 AddDocuments 最多 10 個文檔。大大量匯入時建議：

• 分批上傳：每批 10 個文檔，按批次串列調用 AddDocuments。

• 控制並發：注意 QPS 限制，避免觸發限流。

• 非同步等待：所有批次上傳完成後，統一輪詢文檔狀態，而非每上傳一批就等待完成。

• 錯誤處理：逐個檢查每個文檔的 status，對 failed 的文檔記錄失敗原因，修正後重試。

OSS 檔案準備

• 確保 OSS Bucket 已授權給知識庫服務讀寫權限。授權方式參見快速開始中的前置準備。

• 單檔案不超過 50MB。

• 使用 inclusionFilters 和 exclusionFilters 在 OSS 目錄層級大量匯入，支援首尾 * 萬用字元（如 *.pdf、*report*）。

文檔狀態輪詢

正常情況下文檔上傳後無需主動輪詢，系統會自動完成索引。如需嚴格確認文檔是否已索引完成，建議採用指數退避策略。

文檔處理時間受檔案大小、類型和數量影響，小檔案通常幾秒完成，大檔案或大量匯入可能需要數分鐘。退避策略在等待時間不確定時比固定間隔更合理：短檔案快速返回，長檔案不會頻繁輪詢浪費資源。

檢索類型選擇

Rerank 策略選擇

numberOfResults 調優

檢索流程中有三層 numberOfResults：

• N1（denseVectorSearchConfiguration.numberOfResults）：向量檢索召回數

• N2（fullTextSearchConfiguration.numberOfResults）：全文檢索索引召回數

• N3（rerankingConfiguration.numberOfResults）：Rerank 後最終返回數

N1 和 N2 決定候選池大小，N3 決定最終返回的結果數。推薦起始配置：N1 = N2 = 20，N3 = 5–10。

Metadata Filter 使用建議

• Filter 在檢索前縮小候選範圍，同時提升精度和效能。

• 過濾欄位必須在建立知識庫時定義為 metadata。

• 對日期範圍過濾，使用 date 類型以支援範圍比較。

日期格式

metadata 中 date 類型支援以下格式：

使用不支援的日期格式會導致 AddDocuments 時文檔狀態為 failed。