快速开始

前提条件

• 已开通 Tablestore 服务并创建实例。

  说明

  当前知识存储服务支持的地域：华北2（北京）、华东2（上海）、华东1（杭州）、华南1（深圳）、中国香港、新加坡。

• 已开通 OSS 服务并创建 Bucket，用于存储原始文档。OSS Bucket 与 Tablestore 实例必须在同一地域。

• 已完成 OSS 授权。知识库读写 OSS Bucket 需要授权，通过授权表格存储读写 OSS一键授权。

• 已获取 Tablestore 与 OSS 实例的 AccessKey ID 和 AccessKey Secret。

• 如需使用 RAM 子账号访问知识存储服务，请参见配置访问权限。

通过命令行工具 Dashboard

命令行工具 tablestore-agent-cli 内置基于 Next.js 的 Web Dashboard，提供凭证配置、知识库管理、文档上传与检索调试的可视化界面，无需编码即可完成端到端的知识库操作。

1. 安装命令行工具。要求 Node.js 18 及以上版本。

   npm install -g @tablestore/tablestore-agent-cli --registry=https://registry.npmjs.org/

2. 启动 Dashboard。默认监听 127.0.0.1:3000。

   tablestore-agent-cli dashboard start

3. 在浏览器打开 http://127.0.0.1:3000，在 Dashboard 界面中完成以下操作：

   • 配置 Tablestore 与 OSS 的访问凭证。

   • 创建知识库、上传本地文档、执行检索。

如需通过命令行完成上述操作或使用更多高级功能（例如实例管理、批量操作、自定义 Embedding 模型等），参见命令行工具和知识库操作。

通过 Agent Storage SDK

Agent Storage SDK 提供 Python 与 TypeScript 两种语言。以下最简示例展示如何完成创建知识库、上传文档、等待索引完成、执行检索这 4 个步骤。

pip install tablestore-agent-storage

from tablestore_agent_storage import AgentStorageClient
import time

client = AgentStorageClient(
    access_key_id="<AccessKey ID>",
    access_key_secret="<AccessKey Secret>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
    oss_endpoint="https://oss-<region>.aliyuncs.com",
    oss_bucket_name="<bucket-name>",
)

# 1. 创建知识库（默认使用百炼 text-embedding-v4 向量模型 + 向量检索与全文检索的混合检索）
client.create_knowledge_base({"knowledgeBaseName": "product_docs_kb"})

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

# 3. 轮询等待索引完成
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": "产品的安装步骤是什么"},
})
for r in results["data"]["retrievalResults"]:
    print(f"[{r['score']:.4f}] {r['content'][:80]}")

npm install @tablestore/agent-storage

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

const client = new NodeAgentStorageClient({
  accessKeyId: '<AccessKey ID>',
  accessKeySecret: '<AccessKey Secret>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
  ossEndpoint: 'https://oss-<region>.aliyuncs.com',
  ossBucketName: '<bucket-name>',
  ossAccessKeyId: '<AccessKey ID>',
  ossAccessKeySecret: '<AccessKey Secret>',
});

// 1. 创建知识库
await client.createKnowledgeBase({ knowledgeBaseName: 'product_docs_kb' });

// 2. 上传本地文档
const resp = await client.uploadDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [{ filePath: '/path/to/file.pdf' }],
});
const docId = resp.data.documentDetails[0].docId;

// 3. 轮询等待索引完成
while (true) {
  const { data } = await client.getDocument({ knowledgeBaseName: 'product_docs_kb', docId });
  if (data && data[0].status === 'completed') break;
  await new Promise((r) => setTimeout(r, 5000));
}

// 4. 执行检索
const results = await client.retrieve({
  knowledgeBaseName: 'product_docs_kb',
  retrievalQuery: { type: 'TEXT', text: '产品的安装步骤是什么' },
});
for (const r of results.data.retrievalResults) {
  console.log(`[${r.score.toFixed(4)}] ${r.content.slice(0, 80)}`);
}

完整 SDK 用法（元数据过滤、Rerank 重排、Chunk 级管理、自定义 Embedding 模型等），参见Agent Storage SDK。

接入 AI Agent 框架

如果在 Hermes、OpenClaw、Claude Code 等 AI Agent 框架中使用知识存储，可通过命令行工具的 Skill 集成，让 Agent 直接调用知识库完成检索、写入与管理操作，无需手动编写 SDK 调用代码。

详细集成步骤参见Agent 生态集成。