知識庫管理員（建立、更新、查詢、刪除） - Tablestore

通過以下介面管理知識庫的生命週期：建立、更新配置、查詢詳情、列出和刪除知識庫。

建立知識庫

調用 create_knowledge_base 建立一個新的知識庫。系統自動在 Tablestore 中建立對應的 Document 表和 Chunk 表。

請求參數

參數	類型	說明
`knowledgeBaseName`	string	知識庫名稱（必填）。字母開頭，僅允許字母、數字和底線，長度 1–64 字元，不可重複。
`description`	string	知識庫描述，最大 4KB
`subspace`	boolean	是否開啟子空間，詳見Subspace 多租戶。預設為 false，開啟後所有文檔操作和檢索必須指定 subspace 欄位。建立後不可修改
`tags`	list<string>	標籤列表，總長度不超過 4KB
`metadata`	list<object>	中繼資料欄位定義，詳見下方說明
`embeddingConfiguration`	object	Embedding 配置，建立後不可修改。不傳時預設使用百鍊 `text-embedding-v4`（1024 維）
`retrievalConfiguration`	object	預設檢索配置。Retrieve 介面不傳配置時使用此處的設定。建立後可通過 UpdateKnowledgeBase 修改

metadata 欄位定義

每個元素包含 name（欄位名）和 type（欄位類型）。

定義項	說明
支援的類型	`string`、`long`、`double`、`boolean`、`date`、`string_list`、`long_list`、`double_list`、`boolean_list`、`date_list` 說明 `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`
欄位名	最大 128 字元，不能包含 `.`。如需提升請提交工單或加入Table Store技術交流群36165029092後聯絡支援人員
欄位數量	最多 200 個。如需提升請提交工單或加入Table Store技術交流群36165029092後聯絡支援人員
保留欄位	`_uid`、`_id`、`_type`、`_all`、`_parent`、`_routing`、`_index`、`_size`、`_timestamp`、`_ttl`、`_score`

重要

metadata 欄位定義建立後不可增刪。建立前應梳理所有可能用於過濾檢索結果的維度，一次性定義完整。

embeddingConfiguration

參數	類型	說明
`provider`	string	模型提供方。預設為 `bailian`（百鍊內建），也支援 `custom`（自訂）
`model`	string	模型名稱。預設為 `text-embedding-v4`，百鍊還支援 `text-embedding-v3`
`dimension`	int	向量維度。預設為 1024
`apiKey`	string	僅 `custom` 模式需要
`url`	string	僅 `custom` 模式需要，需提前聯絡Table Store註冊

retrievalConfiguration

參數	類型	說明
`searchType`	list<string>	檢索類型。預設為 `["DENSE_VECTOR", "FULL_TEXT"]`
`denseVectorSearchConfiguration.numberOfResults`	int	向量檢索返回數量。預設為 20
`fullTextSearchConfiguration.numberOfResults`	int	全文檢索索引返回數量。預設為 20
`rerankingConfiguration.type`	string	Rerank 類型：`RRF`、`WEIGHT` 或 `MODEL`。預設為 `WEIGHT`
`rerankingConfiguration.numberOfResults`	int	Rerank 後返回的結果數。預設為 20
`weightConfiguration.denseVectorSearchWeight`	double	向量檢索加權比例。預設為 0.7
`weightConfiguration.fullTextSearchWeight`	double	全文檢索索引加權比例。預設為 0.3
`rrfConfiguration.denseVectorSearchWeight`	double	RRF 模式下的向量檢索權重。預設為 1.0
`rrfConfiguration.fullTextSearchWeight`	double	RRF 模式下的全文檢索索引權重。預設為 1.0
`rrfConfiguration.k`	int	RRF 演算法參數。預設為 60，必須大於 0
`modelConfiguration.provider`	string	Rerank 模型提供方。預設 `bailian`，當前僅支援百鍊
`modelConfiguration.model`	string	Rerank 模型名稱。預設 `gte-rerank-v2`（新加坡地區預設`qwen3-rerank`）

完整的檢索配置說明參見檢索和排序。

程式碼範例

以下為建立知識庫的程式碼範例。

最簡樣本

使用預設配置建立知識庫。Embedding 預設使用百鍊 text-embedding-v4（1024 維），檢索預設使用向量 + 全文混合檢索，Rerank 預設使用 WEIGHT 加權融合（向量 0.7 : 全文 0.3）。

client.create_knowledge_base({
    "knowledgeBaseName": "product_docs_kb"
})

完整樣本

自訂 Embedding 模型、檢索策略和中繼資料欄位：

client.create_knowledge_base({
    "knowledgeBaseName": "product_docs_kb",
    "description": "產品文檔知識庫",
    "subspace": True,
    "tags": ["產品", "文檔"],
    "metadata": [
        {"name": "author", "type": "string"},
        {"name": "category", "type": "string"},
        {"name": "publish_date", "type": "date"}
    ],
    "embeddingConfiguration": {
        "provider": "bailian",
        "model": "text-embedding-v4",
        "dimension": 1024
    },
    "retrievalConfiguration": {
        "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
        "denseVectorSearchConfiguration": {"numberOfResults": 10},
        "fullTextSearchConfiguration": {"numberOfResults": 10},
        "rerankingConfiguration": {
            "type": "WEIGHT",
            "numberOfResults": 5,
            "weightConfiguration": {
                "denseVectorSearchWeight": 0.7,
                "fullTextSearchWeight": 0.3
            }
        }
    }
})

響應說明

正常響應：

{"code": "SUCCESS", "data": {}, "message": "succeed"}

異常響應樣本：

{
  "code": "INVALID_PARAMETER",
  "message": "Unknown field type: strings, supported types: string, long, double, boolean, date, string_list, long_list, double_list, boolean_list, date_list"
}

注意事項

embeddingConfiguration 建立後不可修改。如需更換 Embedding 模型，必須刪除並重建知識庫。
metadata 欄位定義建立後不可增刪。
subspace 開關建立後不可修改。
metadata 欄位名不能使用 .，不能使用保留欄位。欄位類型拼字錯誤會直接報錯。

更新知識庫

調用 update_knowledge_base 更新知識庫的描述、標籤或檢索配置。

請求參數

參數	類型	說明
`knowledgeBaseName`	string	知識庫名稱（必填）
`description`	string	更新描述資訊，最大 4KB
`tags`	list<string>	更新標籤
`retrievalConfiguration`	object	更新預設檢索配置

說明

description、tags、retrievalConfiguration 至少填一個，否則報錯。

程式碼範例

client.update_knowledge_base({
    "knowledgeBaseName": "product_docs_kb",
    "description": "更新後的描述",
    "tags": ["上線"],
    "retrievalConfiguration": {
        "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
        "rerankingConfiguration": {
            "type": "RRF",
            "numberOfResults": 10,
            "rrfConfiguration": {
                "denseVectorSearchWeight": 0.7,
                "fullTextSearchWeight": 0.3,
                "k": 60
            }
        }
    }
})

注意事項

修改 retrievalConfiguration 後，後續所有未傳入檢索配置的 Retrieve 請求會使用新配置。已顯式傳入配置的 Retrieve 請求不受影響。
embeddingConfiguration 和 metadata 不可通過此介面修改。

查詢知識庫詳情

調用 describe_knowledge_base 查詢指定知識庫的完整配置。

請求參數

參數	類型	說明
`knowledgeBaseName`	string	知識庫名稱（必填）

程式碼範例

resp = client.describe_knowledge_base({
    "knowledgeBaseName": "product_docs_kb"
})

data = resp["data"]
print(f"名稱: {data['knowledgeBaseName']}")
print(f"Embedding: {data['embeddingConfiguration']}")
print(f"檢索配置: {data['retrievalConfiguration']}")

響應說明

響應欄位

欄位	類型	說明
`knowledgeBaseName`	string	知識庫名稱
`description`	string	知識庫描述
`tags`	list<string>	標籤列表
`subspace`	boolean	是否開啟子空間
`createdAt`	int	建立時間戳記（毫秒）
`updatedAt`	int	更新時間戳記（毫秒）
`metadata`	list<object>	中繼資料欄位定義
`embeddingConfiguration`	object	Embedding 配置
`retrievalConfiguration`	object	檢索配置

響應樣本

{
  "code": "SUCCESS",
  "data": {
    "knowledgeBaseName": "product_docs_kb",
    "description": "產品文檔知識庫",
    "tags": ["產品", "文檔"],
    "subspace": true,
    "metadata": [{"name": "author", "type": "string"}],
    "createdAt": 1774494642525,
    "updatedAt": 1774494642525,
    "embeddingConfiguration": {
      "provider": "bailian",
      "model": "text-embedding-v4",
      "dimension": 1024
    },
    "retrievalConfiguration": {
      "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
      "denseVectorSearchConfiguration": {"numberOfResults": 20},
      "fullTextSearchConfiguration": {"numberOfResults": 20},
      "rerankingConfiguration": {
        "type": "WEIGHT",
        "numberOfResults": 20,
        "weightConfiguration": {
          "denseVectorSearchWeight": 0.7,
          "fullTextSearchWeight": 0.3
        }
      }
    }
  },
  "message": "succeed"
}

列出知識庫

調用 list_knowledge_base 分頁查詢當前 Project 下的所有知識庫。

請求參數

參數	類型	說明
`maxResults`	int	返回數量。預設為 10，最大 100
`nextToken`	string	翻頁 token，首次請求不傳

程式碼範例

# 擷取第一頁
resp = client.list_knowledge_base({"maxResults": 10})

for kb in resp["data"]["knowledgeBases"]:
    print(f"{kb['knowledgeBaseName']} - {kb.get('description', '')}")

# 翻頁
next_token = resp["data"].get("nextToken")
if next_token:
    resp = client.list_knowledge_base({
        "maxResults": 10,
        "nextToken": next_token
    })

響應說明

欄位	類型	說明
`knowledgeBases`	list<object>	知識庫列表，每項含 `knowledgeBaseName`、`description`、`subspace`、`tags`、`createdAt`、`updatedAt`
`nextToken`	string	翻頁 token，為空白表示已到最後一頁

注意事項

maxResults 最大值為 100，傳入超過 100 的值會報 INVALID_PARAMETER。

刪除知識庫

調用 delete_knowledge_base 刪除指定的知識庫。

重要

此操作無法復原。刪除知識庫會同時刪除其下所有 Document 和 Chunk 資料。

請求參數

參數	類型	說明
`knowledgeBaseName`	string	知識庫名稱（必填）

程式碼範例

client.delete_knowledge_base({
    "knowledgeBaseName": "product_docs_kb"
})

響應說明

正常響應：

{"code": "SUCCESS", "data": {}, "message": "succeed"}

異常響應：

{"code": "NOT_FOUND", "message": "KnowledgeBaseName:[product_docs_kb] not found"}