Tablestore:クイックスタート

前提条件

開始する前に、次の要件を満たしていることを確認してください。

• サポート対象リージョンで有効化済みの Tablestore インスタンス

  説明

  Knowledge Storage は現在、中国 (北京)、中国 (上海)、中国 (杭州)、中国 (深圳)、香港 (中国)、およびシンガポールでご利用いただけます。

• ソースドキュメント用の OSS バケット

  説明

  OSS バケットは、Tablestore インスタンスと同じリージョンにある必要があります。

• Knowledge Storage サービスへの OSS アクセス権限。まだ付与していない場合は、ワンクリック権限付与リンクから権限を付与してください。

• Tablestore と OSS にアクセスするための AccessKey 認証情報 (AccessKey ID および AccessKey Secret)

組み込みダッシュボードの使用

tablestore-agent-cli の組み込みダッシュボードを使用すると、認証情報の設定、ナレッジベースの管理、ドキュメントのアップロード、取得の実行をコーディングなしで行うことができます。

1. CLI をインストールします。Node.js 18 以降が必要です。

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

2. ダッシュボードを起動します。

   tablestore-agent-cli dashboard start

3. ブラウザで http://127.0.0.1:3000 を開き、ダッシュボードで次の操作を実行します。

   • Tablestore および OSS のアクセス認証情報を設定します。

   • ナレッジベースを作成し、ローカルドキュメントをアップロードして、取得を実行します。

CLI ベースのワークフローや高度な機能 (インスタンス管理、バッチ操作、カスタム埋め込みモデルなど) については、「Agent Storage CLI」および「ナレッジベースの操作」をご参照ください。

エージェントストレージ SDK の使用

エージェントストレージ 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. ナレッジベースを作成します (デフォルトは、ベクトル検索と全文検索を組み合わせたハイブリッド取得を行う Bailian 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": "What are the installation steps for the product"},
})
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: 'What are the installation steps for the product' },
});
for (const r of results.data.retrievalResults) {
  console.log(`[${r.score.toFixed(4)}] ${r.content.slice(0, 80)}`);
}

メタデータフィルタリング、再ランキング、チャンクレベルの管理、カスタム埋め込みモデルなどの高度な機能を含む詳細については、「エージェントストレージ SDK」をご参照ください。

AI エージェントフレームワークとの統合

Knowledge Storage を Hermes、OpenClaw、Claude Code などの AI エージェントフレームワークと統合するには、tablestore-agent-cli が提供するスキル統合をインストールします。エージェントは、SDK コードを必要とせずに、ナレッジベースを直接呼び出して取得、書き込み、管理操作を実行できます。

統合手順の詳細については、「AI エージェントとの統合」をご参照ください。