知识存储服务知识库创建与管理-表格存储 Tablestore(Tablestore)-阿里云帮助中心

管理知识存储服务中的知识库，包括创建、查询、列出、更新和删除操作。

创建知识库

知识库是文档、切片和检索配置的顶层容器。创建知识库前，需先创建 AgentStorage 实例，获取访问地址（endpoint）和实例名。如需从本地或 OSS 导入文档，账号下需有同地域的 OSS Bucket 并完成 OSS 授权。

基础设置

设置项	说明
名称	以字母开头，只能包含字母、数字和下划线，长度 1-64 字符，同一实例内不可重复
描述与标签	说明知识库用途，描述最大 4KB，标签总长度不超过 4KB
元数据模式	定义文档的附加属性（如来源、分类、版本号等自定义字段），用于检索时按字段过滤结果。支持 `string`/`long`/`double`/`boolean`/`date` 及对应 `_list` 类型，字段名最大 128 字节且不能含 `.`，最多 200 个字段
子空间	在同一知识库内按业务线、项目或租户隔离文档，开启后所有文档操作和检索必须指定 subspace
Embedding 模型	决定向量检索的语义理解能力。默认百炼 `text-embedding-v4`（1024 维），也支持自定义模型
检索配置	检索类型与 Rerank 策略。默认向量检索 + 全文检索的混合检索，Rerank 默认 WEIGHT 加权融合（向量 0.7 : 全文 0.3）

元数据字段定义和 Embedding 配置创建后不可修改，请在创建前规划完整。如需更换 Embedding 模型或增删元数据字段，必须删除并重建知识库。

控制台

登录Agent Storage控制台，点击知识库管理，点击新建知识库。
填写名称（以字母开头，只能包含字母、数字和下划线，最多 64 个字符），按需填写描述并选择资源组。
配置元数据模式：添加用于检索过滤的自定义字段（如作者、分类、版本号），选择字段类型。创建后不可增删。
按需开启子空间（多租户隔离）和多模态（图片入库与多模态检索）。
在高级设置中可自定义 Embedding 模型、召回数量、检索类型和重排序策略。没有明确调优需求时，建议先使用默认配置。
点击确定创建知识库。

多模态设置创建后不可修改，请在创建前确认。如出现 OSS 授权提示，请先完成授权再继续创建。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

# 初始化客户端（API Key 认证）
client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

# 创建知识库（默认使用百炼 text-embedding-v4，向量+全文混合检索）
client.create_knowledge_base({
    "knowledgeBaseName": "product_docs_kb",
    "description": "产品文档知识库",
    "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
            }
        }
    }
})

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

// 初始化客户端（API Key 认证）
const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

// 创建知识库
await client.createKnowledgeBase({
  knowledgeBaseName: 'product_docs_kb',
  description: '产品知识库',
  metadata: [
    { name: 'author', type: 'string' },
    { name: 'category', type: 'string' },
  ],
});

API

调用 CreateKnowledgeBase 创建知识库。完整请求字段与响应说明参见创建知识库。

查询知识库详情

查询指定知识库的完整配置，包括名称、描述、元数据定义、Embedding 配置和检索配置。

控制台

在知识库列表页，可点击目标卡片右上角的··· > 设置，查看知识库的完整配置。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

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']}")

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.describeKnowledgeBase({
  knowledgeBaseName: 'product_docs_kb',
});
console.log(resp.data);

API

调用 DescribeKnowledgeBase 查询知识库详情。完整字段参见查询知识库。

列出知识库

分页查询当前实例下的所有知识库。

控制台

在 知识库管理 页面可直接查看所有知识库列表，包含名称、描述和创建时间。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

# 获取第一页
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
    })

maxResults 最大 100，超过会报 INVALID_PARAMETER。

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.listKnowledgeBase({ maxResults: 10 });
for (const kb of resp.data.knowledgeBases) {
  console.log(kb.knowledgeBaseName, kb.description);
}

API

调用 ListKnowledgeBase 列出知识库。完整字段参见列出知识库。

更新知识库

更新知识库的描述、标签或检索配置。

控制台

在知识库列表页，点击目标知识库卡片右上角的··· > 设置，点击修改，更新描述、标签和检索配置。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

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

修改 retrievalConfiguration 后，后续未传入检索配置的 Retrieve 请求会使用新配置。已显式传入配置的请求不受影响。

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

await client.updateKnowledgeBase({
  knowledgeBaseName: 'product_docs_kb',
  description: '更新后的描述',
  tags: ['上线'],
});

API

调用 UpdateKnowledgeBase 更新知识库。完整字段参见更新知识库。

删除知识库

重要

此操作不可逆。删除知识库会同时删除其下所有文档和切片数据。

控制台

在知识库列表页，点击目标知识库卡片右上角的···，选择删除。需要输入知识库名称二次确认。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

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

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

await client.deleteKnowledgeBase({ knowledgeBaseName: 'product_docs_kb' });

API

调用 DeleteKnowledgeBase 删除知识库。完整字段参见删除知识库。