Node.js SDK を使用したメモリストアの利用 - Tablestore - Alibaba Cloud ドキュメントセンター

メモリストアサービスインターフェイスは Table Store Node.js SDK に統合されており、TableStore.Client から呼び出すことができます。メソッド名は、createMemoryStore や addMemories のようなキャメルケースです。

インストール

npm を使用して Node.js SDK をインストールします。バージョンは 5.6.5 以降である必要があります。

npm install tablestore@^5.6.5

クライアントの初期化

インスタンスエンドポイント、AccessKey、およびインスタンス名で TableStore.Client を初期化します。

const TableStore = require("tablestore");

const client = new TableStore.Client({
  accessKeyId: "<AccessKey ID>",
  secretAccessKey: "<AccessKey Secret>",
  endpoint: "https://<instance>.cn-beijing.ots.aliyuncs.com",
  instancename: "<instance-name>",
});

パラメーター：

endpoint: インスタンスのアクセスアドレス。形式は https://<instance>.<region>.ots.aliyuncs.com です。
accessKeyId: Alibaba Cloud アカウントまたは RAM ユーザーの AccessKey ID。
secretAccessKey: Alibaba Cloud アカウントまたは RAM ユーザーの AccessKey シークレットです。
instancename: Tablestore インスタンスの名前。

メモリストアの作成

createMemoryStore を呼び出して、Agent の長期記憶用のメモリストアを作成します。

await client.createMemoryStore({
  memoryStoreName: "agent_memory",
  description: "Agent long-term memory store",
});

メモリストアを作成すると、Table Store は非同期でセカンダリインデックスを初期化します。インデックスが利用可能になるまで 約 1 分 待ってから、データを書き込んだり、検索を実行したりできます。

メモリの追加

メモリへの書き込みは、会話メッセージのリスト (messages) または前処理済みのテキスト (text) の 2 つの入力形式をサポートしています。どちらの形式でも、appId、tenantId、agentId、および runId を含む完全な Scope が必要です。

会話メッセージから

ユーザーとエージェント間の複数ターンの会話を messages フィールドに渡すと、サーバーがバックグラウンドで長期記憶を抽出します。

await client.addMemories({
  memoryStoreName: "agent_memory",
  scope: {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "assistant",
    runId: "session-001",
  },
  messages: [
    { role: "user", content: "I like coffee" },
    { role: "assistant", content: "OK, I'll remember that" },
  ],
  metadata: {
    source: "chat",
  },
  sync: true,
});

パラメーター：

memoryStoreName：対象のメモリストアの名前。
scope: メモリのスコープを指定します。4 つのセグメントはすべて必須です。
messages: 各メッセージに role と content を含む対話メッセージのリスト。
metadata: ビジネスタギングに使用されるカスタムメタデータです。
sync: 長期記憶を同期的に抽出するかどうかを指定します。デフォルト値は false です。値が false の場合、API は元のメッセージを保存してすぐに応答を返します。長期記憶の抽出はバックグラウンドで完了します。

テキストから

会話の抽出プロセスをスキップし、テキストを直接、長期記憶として書き込みます。

await client.addMemories({
  memoryStoreName: "agent_memory",
  scope: {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "assistant",
    runId: "session-001",
  },
  text: "The user likes coffee and prefers concise answers.",
});

メモリの検索

searchMemories を使用して、指定されたスコープ内でベクトル検索を実行します。agentId および runId フィールドでワイルドカード文字 * を使用すると、複数のエージェントやセッションにわたる関連メモリを取得できます。

const result = await client.searchMemories({
  memoryStoreName: "agent_memory",
  scope: {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "*",
    runId: "*",
  },
  query: "What drinks does the user like?",
  topK: 5,
  enableRerank: true,
});

for (const item of result.results || []) {
  console.log(item.unit.id, item.unit.text, item.score);
}

パラメーター：

query：検索テキスト。
topK: 返される結果の最大数です。デフォルト値は 10 で、値の範囲は 1 ～ 50 です。
enableRerank: リランキングを有効にするかどうかを指定します。デフォルト値は true です。

レスポンスの results リストの各要素には、ヒットしたメモリユニット unit とスコア score が含まれています。unit 内のフィールドはスネークケースで命名されます。詳細については、「API リファレンス」をご参照ください。

メモリの管理

長期記憶を一覧表示、取得、更新、および削除できます。単一の記憶を取得、更新、または削除する場合、scope パラメーターの 4 つのセグメントすべてが必須であり、ワイルドカード文字 * は使用できません。

メモリのリスト表示

Scope に基づいて、一致する長期記憶を一覧表示します。agentId と runId では、ワイルドカード文字 * を使用できます。

const result = await client.listMemories({
  memoryStoreName: "agent_memory",
  scope: {
    appId: "app-001",
    tenantId: "*",
    agentId: "*",
    runId: "*",
  },
  limit: 20,
});

メモリの取得

memoryId を指定して単一の長期記憶を取得するには、完全な Scope (4 つすべてのセグメントが必要です) を渡す必要があります。

const memory = await client.getMemory({
  memoryStoreName: "agent_memory",
  memoryId: "mem-001",
  scope: {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "assistant",
    runId: "session-001",
  },
});

メモリの更新

単一の長期記憶のテキストまたはメタデータを更新します。 4 つのフィールドすべてを指定した、完全なスコープを指定する必要があります。

await client.updateMemory({
  memoryStoreName: "agent_memory",
  memoryId: "mem-001",
  scope: {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "assistant",
    runId: "session-001",
  },
  text: "The user prefers coffee and likes concise answers.",
  metadata: {
    source: "manual",
  },
});

メモリの削除

単一の長期記憶を削除します。 4 つのフィールドすべてを指定した、完全なスコープを指定する必要があります。

await client.deleteMemory({
  memoryStoreName: "agent_memory",
  memoryId: "mem-001",
  scope: {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "assistant",
    runId: "session-001",
  },
});

短期記憶のクエリ

短期記憶は元のセッションメッセージです。短期記憶をクエリするには、4 つのパラメーター appId、tenantId、agentId、および runId を渡す必要があります。すべてのパラメーターが必須で、ワイルドカードは使用できません *。

const messages = await client.listMemoryStoreMessages({
  memoryStoreName: "agent_memory",
  scope: {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "assistant",
    runId: "session-001",
  },
  limit: 100,
});

リクエスト監査のクエリ

listMemoryStoreRequests API を使用して、メモリストアの API 呼び出し監査ログをクエリし、Scope や操作タイプ (operation) などのディメンションでフィルターすることで、問題のトラブルシューティングや呼び出し量のモニタリングができます。

const requests = await client.listMemoryStoreRequests({
  memoryStoreName: "agent_memory",
  scope: {
    appId: "app-001",
    tenantId: "*",
    agentId: "*",
    runId: "*",
  },
  operation: "AddMemories",
  limit: 50,
});

パラメーター：

operation：AddMemories や SearchMemories などの操作の種類。
limit: 返す最大件数。