知识存储服务快速入门,4行代码跑通RAG检索 - 表格存储

得益于完善的默认策略设计，最简场景下只需4 行核心代码即可完成从创建知识库到语义检索的全过程，无需部署任何服务器。

前置准备

已开通表格存储服务。
说明
当前知识存储服务支持的地域：华北2（北京）、华东2（上海）、华东1（杭州）、华南1（深圳）、中国香港、新加坡。
已完成 OSS 授权。知识库需要读写 OSS Bucket 的权限，通过以下链接一键授权：授权表格存储读写 OSS。
已安装 Python SDK：
```
pip install tablestore-agent-storage
```

初始化客户端

将以下代码中的 AccessKey、Tablestore Endpoint、Tablestore 实例名称、OSS Endpoint 和 Bucket 名称替换为实际值。

说明

OSS Bucket和Tablestore实例必须在同一地域。

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-name>.<region-id>.ots.aliyuncs.com",
    ots_instance_name="<your-instance-name>",
    oss_endpoint="https://oss-<region-id>.aliyuncs.com",
    oss_bucket_name="<your-bucket-name>"
)

4 行代码跑通 RAG 检索

使用默认配置时，核心逻辑只需要少量代码即可完成。

# 1. 创建知识库
client.create_knowledge_base({"knowledgeBaseName": "product_docs_kb"})

# 2. 上传文档
resp = client.upload_documents({"knowledgeBaseName": "product_docs_kb", "documents": [{"filePath": "/path/to/file.pdf"}]})

# 3. 等待索引完成
import time
doc_id = resp["data"]["documentDetails"][0]["docId"]
while True:
    data = client.get_document({"knowledgeBaseName": "product_docs_kb", "docId": doc_id}).get("data") or []
    if data and data[0]["status"] == "completed":
        break
    time.sleep(5)

# 4. 检索
results = client.retrieve({"knowledgeBaseName": "product_docs_kb", "retrievalQuery": {"type": "TEXT", "text": "你的问题"}})

说明

上述代码仅展示核心逻辑。文档索引为异步过程，处理时间受文档大小、类型等因素影响，可能从数秒到分钟级别不等。实际业务中文档导入和检索通常是独立流程，无需等待索引完成。完整可运行示例请参考文档管理。

分步骤端到端示例

步骤一：创建知识库

不传配置时，Embedding 默认使用百炼 text-embedding-v4（1024 维），检索默认使用向量 + 全文混合检索。更多配置选项参见知识库管理。

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

步骤二：上传文档

SDK 自动将本地文件上传至 OSS 并添加到知识库。更多上传方式参见文档管理。

resp = client.upload_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [{"filePath": "/path/to/file.pdf"}]
})
doc_id = resp["data"]["documentDetails"][0]["docId"]

文档上传后，系统需要一定时间完成解析、切片和向量化。处理时间取决于文档大小和数量，通常在几秒到几分钟之间。文档状态变为 Completed 后才能被检索到，可通过 get_document 接口查询状态。详细的状态流转和轮询方法参见查询文档状态。

步骤三：检索

文档索引完成后，调用 Retrieve 接口执行语义检索。检索结果按相关性得分降序排列，每个结果包含切片原文和元数据，可直接作为 LLM 的上下文输入。检索策略配置参见检索和排序。

results = client.retrieve({
    "knowledgeBaseName": "product_docs_kb",
    "retrievalQuery": {"type": "TEXT", "text": "产品的安装步骤是什么"}
})
for r in results["data"]["retrievalResults"]:
    print(f"[{r['score']:.4f}] {r['content'][:80]}...")

步骤四：清理资源（可选）

重要

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

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