知识库接入还能这么玩？Tablestore 四种方式实战揭秘-平芜编程栈

本文接《你的企业知识库，何必自己折腾？Tablestore 知识库服务帮你一站式搞定》。在了解知识库服务的背景、核心能力与典型应用场景的基础上，以下内容将详细介绍 API 接口设计、多种接入方式的操作步骤，以及基于真实数据集的评测结果与客户落地案例，帮助您快速将知识库服务集成到实际业务中。

一、API 接口概览

知识库提供三类 API：知识库管理、文档管理和 Chunk 管理，覆盖从创建知识库到精细化管理文档切片的完整生命周期。所有 API 均通过 SDK 调用，请求和响应均为 JSON 格式。

1.知识库管理接口

接口	功能说明	关键参数
CreateKnowledgeBase	创建知识库，配置 Embedding 模型和检索策略	knowledgeBaseName（必填）、metadata、embeddingConfiguration、retrievalConfiguration
UpdateKnowledgeBase	更新知识库描述、标签或检索配置	knowledgeBaseName（必填），description/tags/retrievalConfiguration 至少填一项
DescribeKnowledgeBase	查询知识库详情，返回完整配置信息	knowledgeBaseName
ListKnowledgeBase	分页列出当前实例下的所有知识库	maxResults（默认 10，最大 100）、nextToken
DeleteKnowledgeBase	删除指定知识库及其所有文档和切片	knowledgeBaseName

2.文档管理接口

接口	功能说明	关键参数
AddDocuments	上传文档到知识库，支持批量（单次最多 10 个）	knowledgeBaseName、documents（含 ossKey、metadata）、subspace（开启时必填）
GetDocument	查询文档详情，支持通过 docId 或 ossKey 定位	knowledgeBaseName、docId 或 ossKey
ListDocuments	分页列出知识库中的文档	knowledgeBaseName、maxResults（默认 10，最大 1000）、subspace（支持多值，最多 10 个）
DeleteDocuments	删除文档，支持通过 docId 或 ossKey 指定	knowledgeBaseName、documents
UpdateDocument	更新文档的 metadata（覆盖式更新）	knowledgeBaseName、docId 或 ossKey、metadata

3.检索接口（Retrieve）

Retrieve 是知识库最核心的接口，用于根据自然语言查询检索相关文档切片。

主要参数：

knowledgeBaseName：目标知识库
retrievalQuery：检索查询，type 为 TEXT，text 最长 128 字符
retrievalConfiguration：可选，覆盖知识库默认的检索配置（searchType、向量/全文检索数量、Rerank 策略）
subspace：支持多值联合检索（最多 32 个）
filter：Metadata 过滤条件

Metadata Filter 支持的算子：

算子	功能	支持类型
equals / notEquals	等于 / 不等于	string, number, boolean
greaterThan / greaterThanOrEquals	大于 / 大于等于	number
lessThan / lessThanOrEquals	小于 / 小于等于	number
in / notIn	在列表中 / 不在列表中	string list（1-10 项）
startsWith	前缀匹配	string
stringContains	包含子字符串	string
listContains	列表包含指定值	string_list
andAll / orAll / notAll	逻辑与 / 或 / 非	组合算子，支持嵌套

检索响应中每条结果包含：docId、chunkId、ossKey、score（相关性得分）、content（切片文本）、subspace 和 metadata。

4.Chunk 管理接口

接口	功能说明	关键参数
ListChunks	分页列出文档的所有切片	knowledgeBaseName、docId 或 ossKey、maxResults（默认 10，最大 1000）
UpdateChunks	批量更新切片内容、标题或状态（单次最多 10 个）	knowledgeBaseName、chunks（含 chunkId、title、content、status）

二、知识库接入方案

1.方式一：SDK 接入

适合有开发能力、希望将知识库集成到自有应用中的用户。

接入步骤

开通 Tablestore 服务：在阿里云控制台开通表格存储（Tablestore）服务，当前知识库服务支持北京、中国香港，其他 Region 陆续开服中。
一键授权 OSS：在控制台一键授权 Tablestore 知识库访问你的 OSS Bucket（用于读取原始文档和存储解析中间结果）。
获取访问凭证：准备好 AccessKey ID 和 AccessKey Secret。
安装 SDK：pip install tablestore-agent-storage
创建知识库 → 上传文档 → 检索：最少 4 行核心代码即可跑通。

代码示例

from tablestore_agent_storage import AgentStorageClient # 初始化客户端 client = AgentStorageClient( access_key_id="<your-access-key-id>", access_key_secret="<your-access-key-secret>", ots_endpoint="https://<instance>.cn-hangzhou.ots.aliyuncs.com", ots_instance_name="<your-instance-name>", oss_endpoint="https://oss-cn-hangzhou.aliyuncs.com", oss_bucket_name="<your-bucket-name>" ) # 1. 创建知识库（一行代码，所有配置使用默认值） client.create_knowledge_base({"knowledgeBaseName": "my_kb"}) # 2. 上传文档 resp = client.upload_documents({ "knowledgeBaseName": "my_kb", "documents": [{"filePath": "/path/to/file.pdf"}] }) # 3. 等待索引完成 import time doc_id = resp["data"]["documentDetails"][0]["docId"] while True: status = client.get_document({ "knowledgeBaseName": "my_kb", "docId": doc_id })["data"][0]["status"] if status == "completed": break time.sleep(5) # 4. 检索 results = client.retrieve({ "knowledgeBaseName": "my_kb", "retrievalQuery": {"type": "TEXT", "text": "你的问题"} }) for r in results["data"]["retrievalResults"]: print(f"[{r['score']:.4f}] {r['content'][:80]}...")

进阶配置

如果需要自定义 Embedding 模型、检索策略、元数据过滤等，可以在创建知识库时传入完整配置：

client.create_knowledge_base({ "knowledgeBaseName": "my_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": 20}, "fullTextSearchConfiguration": {"numberOfResults": 20}, "rerankingConfiguration": { "type": "WEIGHT", "numberOfResults": 10, "weightConfiguration": { "denseVectorSearchWeight": 0.7, "fullTextSearchWeight": 0.3 } } } })

2.方式二：AgentRun

适合希望通过可视化界面快速创建和管理知识库的用户。AgentRun 是以高代码为核心、开放生态、灵活组装的一站式 Agentic AI 基础设施平台，提供开发、部署与运维全生命周期管理。

第一步：登录 AgentRun 控制台

第二步：创建知识库

在自动配置下，仅需输入"知识库名称"即可完成知识库创建。如需进一步定制，可以配置以下参数：

描述：定义知识库用途等说明
标签：定义知识库标签内容
Embedding：选择 Embedding 模型，支持内置百炼模型
Metadata 配置：定义元数据字段，可用于检索过滤；元数据信息可在上传文档时写入
检索配置：设置检索类型、Rerank 配置

第三步：上传文档

文档上传后，后台服务会异步对文档进行解析、Embedding 等处理流程，等待文档状态从"索引中"变为"已完成"即可。

第四步：创建知识库助手

在 AgentRun 中创建一个知识库助手，将其关联到刚才创建的 Tablestore 知识库。

第五步：Agent 智能体集成

将知识库服务集成至 Agent 智能体中，完成后即可在 Agent 中基于知识库进行问答。

3.方式三：Dify 外接 Tablestore 知识库

适合已使用 Dify 构建 AI 应用、希望将 Tablestore 知识库作为外部知识源接入的用户。通过 Dify 的外部知识库插件机制，可以在不迁移数据的前提下，直接在 Dify 工作流中检索 Tablestore 知识库中的内容，实现 RAG 问答。

前置条件：
已完成 Tablestore 知识库的创建与文档上传（参考方式一或方式二）。
已部署 Dify 平台（支持 Docker 部署、阿里云计算巢部署等方式）。

第一步：安装 Tablestore 插件并配置 API 端点

在 Dify 插件市场搜索"Tablestore"，安装插件。安装完成后，点击 Dify 右上角的插件入口进入插件详情页，点击API 端点右侧的加号按钮新增端点配置。

在配置页面中填写 Tablestore 实例的相关信息（Endpoint、Instance Name、AccessKey 等）。

保存后，系统会生成一个 URL。将光标移至该 URL 上，点击复制按钮进行复制，并删除末尾的/retrieval后缀。根据部署环境不同，还需要替换 URL 中的localhost：

Docker 部署：替换为host.docker.internal
阿里云计算巢部署：替换为ack-dify-plugin-daemon
其他部署方式：替换为 dify-plugin 服务的实际 IP 或域名

第二步：注册外部知识库 API

进入 Dify 的知识库页面，点击外部知识库 API，将上一步获取的 API 端点 URL 和 API Key 填入对应字段，点击保存。

第三步：连接外部知识库

在知识库页面点击连接外部知识库，在弹出的配置面板中选择上一步注册的外部知识库 API，并填写外部知识库 ID——此处需填写 Tablestore 知识库服务中的知识库名称（即创建知识库时设定的knowledgeBaseName），完成后点击连接。

连接成功后，返回知识库主页面即可看到已连接的 Tablestore 外部知识库。

第四步：召回测试

点击进入已连接的知识库，执行召回测试，验证 Dify 是否能通过插件正确检索到 Tablestore 知识库中的相关内容。

第五步：在 Dify 工作流中使用

创建 Dify 工作流，添加知识检索节点，并在节点配置中关联已连接的 Tablestore 外部知识库。用户提问时，工作流会自动从 Tablestore 知识库中检索相关文档切片，作为上下文传递给 LLM 生成回答。

4.方式四：Tablestore Agent Skills & Dashboard 详情点击：让知识在 Agent 间流动 —— 表格存储知识库 Skills 实践指南

三、知识库评测

检索效果和性能是选择知识库方案最关键的两个指标。我们基于多个公开数据集和自定义数据集，使用开源评测框架 RAGAS，对 Tablestore 知识库服务与自建 RAGFlow 方案进行了系统评测。评测中 TopK、Rerank Mode、Embedding 模型等配置均保持一致。

1.效果评测 CMRC2018（中文阅读理解）

CMRC2018 是中文机器阅读理解的经典数据集，用于评测抽取式问答场景。以 TopK=5 为例：

指标	Tablestore	RAGFlow
答案准确率	80.5	77.3
答案完整率	56.5	48.5
幻觉率	3.6	5.5
上下文召回率	97.2	93.9
上下文精确率	93.0	92.0

SQuAD（英文阅读理解）

SQuAD 是最经典的英文阅读理解数据集。以 TopK=5 为例：

指标	Tablestore	RAGFlow
答案准确率	69.4	68.5
答案完整率	14.3	13.7
幻觉率	6.8	8.2
上下文召回率	93.6	90.7
上下文精确率	88.3	84.0

C-MTEB T2Retrieval（中文综合检索）

这是 C-MTEB 里的检索子任务，需要从大量语料中召回相关片段。以 TopK=10 为例：

指标	Tablestore	RAGFlow
答案准确率	59.6	56.5
答案完整率	38.6	35.7
幻觉率	17.5	22.9
上下文召回率	77.2	75.7
上下文精确率	51.9	53.4

自定义数据集（Tablestore 用户文档）

基于 Tablestore 用户文档构建的自定义数据集，涵盖了单切片、多切片、多跳问题、图表、QA 等维度。以 TopK=5 为例：

指标	Tablestore	RAGFlow
答案准确率	61.1	60.9
答案完整率	27.5	24.2
幻觉率	19.7	21.2
上下文召回率	77.1	72.5
上下文精确率	72.9	66.1

2.检索性能

基于 CMRC2018 数据集评测了单路查询延迟，评测中均使用 Weight 权重 Rerank，TopK=20

指标	Tablestore (ms)	RAGFlow (ms)
P50 延迟 (ms)	199	805
P95 延迟 (ms)	316	1049
平均延迟 (ms)	221	768

3.评测总结

Tablestore 知识库服务的检索延迟相比自建 RAGFlow 方案降低了约 70%
在四个数据集的评测中，检索质量各项指标均达到或优于自建 RagFlow 方案

四、客户案例

1.阿里云 PDS（网盘与相册服务）— AI 知识库助手

阿里云网盘与相册服务（PDS）是面向企业、团队与个人的数据管理开放平台，帮助客户快速构建支撑海量用户的网盘与相册服务。随着 AI 能力在文档场景的普及，PDS 为用户提供了"网盘即知识库"的体验——用户可以将网盘中的文档一键转化为个人知识库，通过 AI 助手进行智能问答和语义检索。

网盘中的文档类型多样（PDF、Word、PPT 等），需要统一的解析和向量化能力；同时作为多租户平台，每个用户的知识库数据必须严格隔离，不能出现跨用户的信息泄露。PDS 使用 Tablestore 存储网盘文件的元数据和 Embedding 语义数据，将网盘里的知识库文档进行预计分块，基于 AI 助手进行答疑和智能检索。

2.ECS 控制台 AI 助手

ECS AI 助手集成了智能问答、购买咨询、日常运维、资源管理、异常诊断、监控分析和远程命令等 8+ 核心场景，是阿里云控制台 AI 能力的标杆应用。除 ECS 外，OSS、ACK 等多条产品线的控制台助手也复用同一套知识库架构。

多产品线共用知识库带来了两个核心诉求——一是检索性能必须满足控制台场景的实时交互要求，用户提问后不能有明显等待；二是不同产品线的文档需要做多租户隔离，避免检索串扰。原有 RDS 方案在大规模知识库下存在慢查询问题，且中文分词索引的维护成本较高。迁移至 Tablestore 后，RAG 端到端平均时延降至1.24 秒，P99 时延优化40%。Tablestore 内置全文索引，无需额外维护中文分词组件，运维成本显著下降，慢查询问题彻底消除。通过多租隔离机制实现多产品线的数据隔离，统一架构支撑多个控制台助手的知识检索需求。

3.某个人网盘 APP

该产品是国内用户规模最大的个人网盘之一，存储了海量的图片、视频和文档等非结构化数据，数据规模达万亿级。产品希望基于用户已有的网盘数据，提供一键升级为个人知识库的能力，让用户可以对自己的文档进行语义检索和 AI 问答。

该场景下核心选型因素包括：

规模支撑能力，未来要持续提升规模上限；
多租户，不同租户间不能相互影响，包括数据和性能；
成本低，成本越低可以让越多的用户使用上新功能；

Tablestore 为该产品提供了大规模、低成本和多租户优化的存储与检索服务。借助 Tablestore 分布式架构的水平扩展能力应对万亿级数据规模，通过 Subspace 机制实现用户级的严格数据隔离和性能隔离，按量付费的 Serverless 模式将单用户边际成本控制在极低水平。业务团队得以将更多精力专注于产品体验的打磨，缩短研发周期，更快地将个人知识库能力交付给用户。