Memory Store Python SDK - Tablestore - Alibaba Cloud Documentation Center

SDK Python Tablestore terintegrasi dengan API layanan Memory Store, memungkinkan Anda memanggil API sinkron melalui OTSClient dan API asinkron melalui AsyncOTSClient.

Instalasi

Instal SDK Python menggunakan pip versi 6.4.5 atau yang lebih baru.

pip install "tablestore>=6.4.5"

Inisialisasi klien

Inisialisasi klien sinkron OTSClient dengan titik akhir instans, AccessKey, dan nama instans.

from tablestore import OTSClient

client = OTSClient(
    "https://<instance>.cn-beijing.ots.aliyuncs.com",
    "<AccessKey ID>",
    "<AccessKey Secret>",
    "<instance-name>",
)

Deskripsi parameter:

Endpoint: Alamat akses instans. Formatnya adalah https://<instance>.<region>.ots.aliyuncs.com.
AccessKey ID: ID AccessKey dari Akun Alibaba Cloud atau Pengguna RAM Anda.
AccessKey Secret: Secret AccessKey dari Akun Alibaba Cloud atau Pengguna RAM Anda.
Nama instans: Nama instans Tablestore Anda.

Buat penyimpanan memori

Panggil create_memory_store untuk membuat memory store guna menyimpan memori jangka panjang Agen.

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

Setelah memory store dibuat, indeks sekunder diinisialisasi secara asinkron. Tunggu sekitar 1 menit hingga indeks siap digunakan sebelum melakukan operasi tulis dan pencarian.

Tambahkan memori

Penulisan ke memori mendukung dua format input: daftar pesan dialog (messages) atau teks yang telah diproses sebelumnya (text). Untuk kedua format tersebut, Anda harus menentukan Scope lengkap yang mencakup appId, tenantId, agentId, dan runId.

Tambahkan pesan dialog

Anda meneruskan percakapan multi-putaran antara pengguna dan Agen dalam bidang messages, dan server mengekstraksi memori jangka panjang di latar belakang.

client.add_memories({
    "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": "Okay, I've remembered that"},
    ],
    "metadata": {
        "source": "chat"
    },
    "sync": True,
})

Deskripsi parameter:

memoryStoreName: Nama memory store tujuan.
scope: Cakupan memori. Keempat segmen wajib disertakan.
messages: Daftar pesan dialog. Setiap pesan berisi role dan content.
metadata: Metadata kustom untuk penandaan bisnis.
sync: Menentukan apakah ekstraksi memori jangka panjang dilakukan secara sinkron. Nilai default-nya adalah False. Jika parameter ini diatur ke False, API akan menyimpan pesan asli dan langsung mengembalikan respons, sementara ekstraksi memori jangka panjang dilakukan di latar belakang.

Tambahkan teks

Anda juga dapat menambahkan potongan teks secara langsung sebagai memori.

client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "app-001",
        "tenantId": "user-001",
        "agentId": "assistant",
        "runId": "session-001",
    },
    "text": "The user likes coffee and prefers a concise response style",
})

Cari memori jangka panjang

Gunakan search_memories untuk melakukan pencarian vektor dalam Scope tertentu. Anda dapat menggunakan wildcard * pada bidang agentId dan runId untuk mengambil memori relevan lintas Agen dan sesi.

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

for item in result.get("results", []):
    unit = item["unit"]
    print(unit["id"], unit["text"], item["score"])

Deskripsi parameter:

query: Teks kueri pencarian.
topK: Jumlah maksimum hasil yang dikembalikan. Nilai default-nya adalah 10, dan rentang validnya adalah 1 hingga 50.
enableRerank: Menentukan apakah penyusunan ulang diaktifkan. Nilai default-nya adalah True.

Dalam respons, setiap elemen dalam daftar results berisi unit memori yang cocok unit dan skor score. Bidang dalam unit menggunakan penamaan snake_case. Untuk informasi selengkapnya, lihat Referensi API.

Kelola memori jangka panjang

Mendukung operasi daftar, ambil, perbarui, dan hapus memori jangka panjang. Saat Anda mengambil, memperbarui, atau menghapus satu memori, keempat segmen parameter scope wajib disertakan, dan wildcard * tidak diperbolehkan.

Daftar memori

Menampilkan daftar memori jangka panjang yang sesuai berdasarkan Scope. agentId dan runId mendukung wildcard *.

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

Ambil memori

Untuk mengambil satu memori jangka panjang berdasarkan memoryId, Anda harus memberikan Scope lengkap (keempat segmen wajib disertakan).

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

Perbarui memori

Memperbarui teks atau metadata dari satu memori jangka panjang. Anda harus memberikan scope lengkap (keempat segmen wajib disertakan).

client.update_memory({
    "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"
    },
})

Hapus memori

Menghapus satu memori jangka panjang. Anda harus memberikan scope lengkap (keempat segmen wajib disertakan).

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

Kueri memori jangka pendek

Memori jangka pendek merujuk pada pesan sesi asli. Untuk mengkueri memori jangka pendek, Anda harus memberikan keempat parameter appId, tenantId, agentId, dan runId. Semua parameter wajib disertakan, dan wildcard tidak diperbolehkan *.

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

Audit Permintaan Kueri

Anda dapat menggunakan list_memory_store_requests untuk mengkueri log audit pemanggilan API untuk suatu memory store, serta memfilternya berdasarkan dimensi seperti Scope dan jenis operasi (operation) guna memecahkan masalah dan memantau volume pemanggilan.

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

Deskripsi parameter:

operation: Jenis operasi, seperti AddMemories atau SearchMemories.
limit: Jumlah maksimum entri yang dikembalikan.

Klien asinkron

AsyncOTSClient menyediakan antarmuka asinkron. Tanda tangan metode dan parameter inputnya sama dengan OTSClient, dan semua pemanggilan dieksekusi menggunakan await. Klien ini direkomendasikan untuk digunakan dalam skenario konkurensi tinggi seperti layanan web dan aplikasi agen.

import asyncio
from tablestore import AsyncOTSClient

async def main():
    async with AsyncOTSClient(
        "https://<instance>.cn-beijing.ots.aliyuncs.com",
        "<AccessKey ID>",
        "<AccessKey Secret>",
        "<instance-name>",
    ) as client:
        await client.add_memories({
            "memoryStoreName": "agent_memory",
            "scope": {
                "appId": "app-001",
                "tenantId": "user-001",
                "agentId": "assistant",
                "runId": "session-001",
            },
            "text": "The user prefers a concise response style",
        })

        result = await client.search_memories({
            "memoryStoreName": "agent_memory",
            "scope": {
                "appId": "app-001",
                "tenantId": "user-001",
                "agentId": "*",
                "runId": "*",
            },
            "query": "What response style does the user prefer?",
            "topK": 5,
        })
        print(result)

asyncio.run(main())