知识库管理（创建、更新、查询、删除） - 表格存储

通过以下接口管理知识库的生命周期：创建、更新配置、查询详情、列出和删除知识库。

创建知识库

调用 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 字符，不能包含 `.`。如需提升请提交工单或加入表格存储技术交流群36165029092后联系技术支持
字段数量	最多 200 个。如需提升请提交工单或加入表格存储技术交流群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` 模式需要，需提前联系表格存储注册

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