Tablestore 向け Agent Storage SDK - メモリストアとナレッジベース - Tablestore

Tablestore Agent Storage SDK を使用すると、Python と TypeScript で AI エージェントにメモリストアとナレッジベースの機能を追加できます。汎用の Tablestore SDK とは異なり、Agent Storage SDK は API キー認証をサポートしており、AccessKey 認証情報を管理する必要がありません。

Tablestore SDK との違い

Agent Storage SDK は Tablestore SDK から独立しており、エージェントストレージ操作のみを対象としています。次の表に主な違いを示します。

項目	Tablestore SDK	Agent Storage SDK
パッケージ	Python： `tablestore`、Node.js： `tablestore`	Python： `tablestore-agent-storage`、TypeScript： `@tablestore/agent-storage`
クライアントクラス	`OTSClient` / `AsyncOTSClient` / `TableStore.Client`	`AgentStorageClient`
スコープ	メモリストアを含むすべての Tablestore 操作	エージェントストレージ操作のみ (メモリストアとナレッジベース)
認証	AccessKey (AK/SK)	API キーまたは AccessKey (AK/SK)

インストールと設定

前提条件

HTTPS エンドポイントとインスタンス名を持つ Tablestore インスタンス。
API キー認証を使用する場合：対象のインスタンスで作成された API キー。API キーにバインドされた RAM ユーザーは ots:CallWithBearerToken 権限を持っている必要があり、API キーはそのユーザーのすべての RAM ポリシーを継承します。
ナレッジベース機能を使用する場合：ソースドキュメントを保存するための OSS バケット。SDK はドキュメントのアップロードに OSS アクセス認証情報 (AccessKey) を必要とします。クライアントの初期化時に oss_endpoint と oss_bucket_name を渡します。

インストール

使用する言語のパッケージをインストールします。

Python

pip install tablestore-agent-storage

TypeScript/Node.js

npm install @tablestore/agent-storage

認証

Agent Storage SDK は 2 つの認証方法をサポートしています。

方法	ユースケース	サポートされる操作	トランスポート
AccessKey (AK/SK)	テーブル管理やデータ操作を含むフルアクセス	すべての Tablestore 操作	HTTP または HTTPS
API キー	AccessKey 認証情報を管理しない AI シナリオ向けの軽量な統合	メモリストアとナレッジベース操作のみ	HTTPS のみ

API キーの作成と承認については、「API キー管理」をご参照ください。

クライアントの初期化

ほとんどのエージェントのユースケースでは、API キー認証を使用します。ナレッジベースのドキュメントをアップロードしたり、他の Tablestore 操作にアクセスしたりするには、AccessKey 認証情報と OSS 設定を提供してください。

API キーの使用 (推奨)

api_key パラメーターとインスタンス情報を使用してクライアントを初期化します。エンドポイントは HTTPS を使用する必要があります。

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_memory_stores({})
for store in resp["stores"]:
    print(store["memoryStoreName"])

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.listMemoryStores({});
for (const store of resp.stores) {
  console.log(store.memoryStoreName);
}

cURL

API キーを x-ots-apikey リクエストヘッダーで渡します。

curl -X POST 'https://<instance>.<region>.ots.aliyuncs.com/ListMemoryStores' \
  -H 'x-ots-instancename: <instance-name>' \
  -H 'x-ots-apikey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{}'

AccessKey の使用

すべての Tablestore 操作にアクセスしたり、OSS を介してナレッジベースのドキュメントをアップロードしたりするには、AccessKey 認証を使用します。

Python

from tablestore_agent_storage import AgentStorageClient

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 も設定します
    oss_endpoint="https://oss-<region>.aliyuncs.com",
    oss_bucket_name="<bucket-name>",
)

TypeScript

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

const client = new AgentStorageClient({
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
  accessKeyId: process.env.OTS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OTS_ACCESS_KEY_SECRET,
});

メモリストアの例

メモリストアは、AI エージェントの複数ターンにわたる会話の記憶を永続化し、ベクトルベースのセマンティック検索をサポートします。SDK のメソッドは REST API の操作に対応しています。Python のメソッドはスネークケース (snake_case) を、TypeScript のメソッドはキャメルケース (camelCase) を使用し、パラメーターは API 仕様と一致します。

Python

# 1. メモリ ストアの作成
client.create_memory_store({
    "memoryStoreName": "agent_memory",
    "description": "エージェント用の長期メモリ ストア",
    "extractInstructions": "ユーザーの食の好みと旅行の習慣に焦点を当てる",
})

# 2. 記憶の書き込み
client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "app-001",
        "tenantId": "user-001",
        "agentId": "assistant",
        "runId": "session-001",
    },
    "messages": [
        {"role": "user", "content": "私はアメリカーノコーヒーを飲むのが好きです"},
    ],
    "sync": True,
})

# 3. 記憶の検索
result = client.search_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "app-001",
        "tenantId": "user-001",
        "agentId": "*",
        "runId": "*",
    },
    "query": "ユーザーはどんな飲み物が好きですか",
    "topK": 5,
    "includeEvidence": True,
    "minSimilarity": 0.3,
})
for hit in result["data"]["memories"]:
    print(hit["content"], hit["similarity"])

# 4. メモリ ストアの一覧表示
resp = client.list_memory_stores({})
for store in resp["stores"]:
    print(store["memoryStoreName"])

TypeScript

// 1. メモリ ストアの作成
await client.createMemoryStore({
  memoryStoreName: 'agent_memory',
  description: 'エージェント用の長期メモリ ストア',
});

// 2. 記憶の書き込み
await client.addMemories({
  memoryStoreName: 'agent_memory',
  scope: {
    appId: 'app-001',
    tenantId: 'user-001',
    agentId: 'assistant',
    runId: 'session-001',
  },
  messages: [{ role: 'user', content: '私はアメリカーノコーヒーを飲むのが好きです' }],
  sync: true,
});

// 3. 記憶の検索
const result = await client.searchMemories({
  memoryStoreName: 'agent_memory',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: '*', runId: '*' },
  query: 'ユーザーはどんな飲み物が好きですか',
  topK: 5,
  includeEvidence: true,
});
for (const hit of result.data.memories) {
  console.log(hit.content, hit.similarity);
}

SDK は、メモリストアの更新、メモリストアの削除、スコープによる記憶の一覧表示、個々の記憶の取得、非同期タスクのクエリを行うためのメソッドも提供します。「メモリストア API リファレンス」には、利用可能なすべての操作とパラメーターが記載されています。

ナレッジベースの例

ナレッジベースは、企業の Q&A や RAG のために、自動的なドキュメントのチャンキング、ベクトル化、およびハイブリッド検索をサポートします。ソースドキュメントは OSS に保存され、Tablestore がチャンクのインデックス作成と取得を処理します。使用前に OSS と Tablestore の両方を設定してください。

埋め込みモデルを指定せずにナレッジベースを作成した場合、SDK は Alibaba Cloud の Model Studio text-embedding-v4 (1024 次元) を使用します。デフォルトでハイブリッド検索が有効になり、ベクトル検索と全文検索が組み合わされます。

Python

from tablestore_agent_storage import AgentStorageClient

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

# 1. ナレッジベースの作成 (デフォルトで Model Studio の text-embedding-v4 を使用します。
#    デフォルトの取得モードは、ベクトル検索と全文検索を組み合わせたハイブリッド検索です)
client.create_knowledge_base({
    "knowledgeBaseName": "product_kb",
    "description": "製品ナレッジベース",
})

# 2. ローカルドキュメントのアップロード (SDK は最初にファイルを OSS にアップロードし、その後チャンキングとベクトル化をトリガーします)
client.upload_documents({
    "knowledgeBaseName": "product_kb",
    "documents": [
        {
            "documentId": "doc-guide-001",
            "filePath": "./docs/product-overview.txt",
        },
        {
            "documentId": "doc-guide-002",
            "filePath": "./docs/sdk-intro.txt",
        },
    ],
})

# 3. ナレッジベース内のドキュメントの一覧表示
resp = client.list_documents({
    "knowledgeBaseName": "product_kb",
    "maxResults": 10,
})
for doc in resp["data"]["documentDetails"]:
    print(doc.get("documentId"), doc.get("ossKey"), doc.get("status"))

# 4. 取得
from tablestore_agent_storage.models import RetrieveRequest, RetrievalQuery

req = RetrieveRequest(
    knowledge_base_name="product_kb",
    retrieval_query=RetrievalQuery(text="Agent Storage SDK は何に使われますか"),
)
result = client.retrieve(req)
for hit in result["data"]["retrievalResults"]:
    print(hit)

# 5. ドキュメントの削除
client.delete_documents({
    "knowledgeBaseName": "product_kb",
    "documents": [{"documentId": "doc-guide-001"}],
})

# 6. ナレッジベースの削除
client.delete_knowledge_base({"knowledgeBaseName": "product_kb"})

TypeScript

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. ナレッジベースの作成 (デフォルトで Model Studio の text-embedding-v4 を使用します。
//    デフォルトの取得モードは、ベクトル検索と全文検索を組み合わせたハイブリッド検索です)
await client.createKnowledgeBase({
  knowledgeBaseName: 'product_kb',
  description: '製品ナレッジベース',
});

// 2. ローカルドキュメントのアップロード (SDK は最初にファイルを OSS にアップロードし、その後チャンキングとベクトル化をトリガーします)
//    TypeScript SDK はアップロード時にサーバー側で docId を生成し、カスタム documentId は受け付けません
await client.uploadDocuments({
  knowledgeBaseName: 'product_kb',
  documents: [
    { filePath: './docs/product-overview.txt' },
    { filePath: './docs/sdk-intro.txt' },
  ],
});

// 3. ナレッジベース内のドキュメントの一覧表示
const resp = await client.listDocuments({
  knowledgeBaseName: 'product_kb',
  maxResults: 10,
});
for (const doc of resp.data.documentDetails) {
  console.log(doc.docId, doc.ossKey, doc.status);
}

// 4. 取得
const result = await client.retrieve({
  knowledgeBaseName: 'product_kb',
  retrievalQuery: { text: 'Agent Storage SDK は何に使われますか' },
});
for (const hit of result.data.retrievalResults) {
  console.log(hit);
}

// 5. ドキュメントの削除 (TypeScript では、前のステップで返された ossKey を使用して削除するドキュメントを指定する必要があります)
await client.deleteDocuments({
  knowledgeBaseName: 'product_kb',
  documents: [{ ossKey: '<oss-key-from-list>' }],
});

// 6. ナレッジベースの削除
await client.deleteKnowledgeBase({ knowledgeBaseName: 'product_kb' });

ドキュメントのチャンキングとベクトル化は、アップロード後に非同期で実行されます。status フィールドを list_documents (TypeScript: listDocuments) でクエリして、インデックス作成の進捗状況を確認してください。

Tablestore SDK との違い

インストールと設定

前提条件

インストール

Python

TypeScript/Node.js

認証

クライアントの初期化

API キーの使用 (推奨)

Python

TypeScript

cURL

AccessKey の使用

Python

TypeScript

メモリ ストアの例

Python

TypeScript

ナレッジベースの例

Python

TypeScript

メモリストアの例