Tablestore:praktik terbaik

Desain cakupan yang stabil

Cakupan menyediakan isolasi memori dan mengontrol rentang pengambilan. Sebelum integrasi, definisikan makna bisnis dari keempat bidang tingkat tersebut untuk mencegah ketidakkonsistenan antara kriteria penulisan dan pengambilan.

Pemetaan yang direkomendasikan untuk bidang empat tingkat:

Gunakan cakupan lengkap saat menulis data:

{
  "appId": "customer_service",
  "tenantId": "user_001",
  "agentId": "assistant",
  "runId": "session_20260513"
}

Menulis data dengan cakupan lengkap memastikan atribusi data yang jelas dan memungkinkan Anda melakukan kueri memori jangka pendek pada tingkat sesi.

Pilih cakupan pengambilan berdasarkan tujuan bisnis

Saat mengambil memori jangka panjang dengan SearchMemories, parameter appId dan tenantId wajib diisi. Anda dapat menggunakan karakter wildcard (*) untuk parameter agentId dan runId. Pilih kombinasi cakupan yang sesuai dengan tujuan bisnis Anda.

{
  "appId": "customer_service",
  "tenantId": "user_001",
  "agentId": "assistant",
  "runId": "session_20260513"
}

{
  "appId": "customer_service",
  "tenantId": "user_001",
  "agentId": "assistant",
  "runId": "*"
}

{
  "appId": "customer_service",
  "tenantId": "user_001",
  "agentId": "*",
  "runId": "*"
}

Utamakan pesan percakapan

AddMemories mendukung dua jenis input: messages dan text. Agen percakapan mengutamakan messages dan mempertahankan role, timestamp, serta metadata tingkat pesan.

{
  "messages": [
    {
      "role": "user",
      "content": "Untuk perjalanan bisnis mendatang, harap prioritaskan pemesanan kursi dekat jendela untuk saya.",
      "timestamp": "2026-05-13T10:00:00Z",
      "metadata": {
        "channel": "chat"
      }
    },
    {
      "role": "assistant",
      "content": "Mengerti. Saya akan mengingat preferensi ini."
    }
  ]
}

Menulis pesan percakapan memberikan dua manfaat:

• Anda dapat melakukan kueri pesan asli sebagai memori jangka pendek, memungkinkan pemutaran ulang percakapan dan troubleshooting.

• Sisi server dapat mengekstraksi memori jangka panjang dari konteks percakapan, menyederhanakan identifikasi jenis unit seperti atomic_fact, temporal_anchor, dan preference.

Gunakan penulisan sinkron secara tepat

Nilai default parameter AddMemories.sync adalah false, yang menentukan penulisan asinkron. Dalam mode ini, layanan pertama-tama menyimpan pesan asli, lalu mengekstraksi memori jangka panjang sebagai tugas latar belakang. Memori tersebut biasanya dapat diambil dengan SearchMemories dalam waktu 15 detik setelah operasi penulisan selesai.

Tabel berikut memberikan rekomendasi untuk berbagai skenario:

Kontrol topK pengambilan

Nilai default parameter SearchMemories.topK adalah 10, dengan rentang 1 hingga 50. Untuk sebagian besar skenario agen, nilai antara 5 dan 10 sudah cukup.

Ikuti prinsip-prinsip berikut saat menyesuaikan nilainya:

• Menambah nilai topK dapat meningkatkan recall, tetapi juga menambah panjang konteks dan biaya pemrosesan untuk tugas downstream.

• Masukkan hanya memori yang benar-benar dibutuhkan agen. Hal ini mencegah memori yang tidak relevan mengurangi bobot prompt.

Biarkan Rerank aktif

Parameter SearchMemories.enableRerank diatur ke true secara default. Untuk skenario percakapan yang memerlukan relevansi tinggi, kami merekomendasikan mempertahankan pengaturan default ini.

Nonaktifkan Rerank hanya dalam skenario berikut:

• Anda secara eksplisit perlu mengurangi latensi pengambilan per permintaan.

• Anda sedang melakukan pengujian kinerja pengambilan dan perlu menonaktifkan reranking untuk menetapkan garis dasar.

Gunakan metadata untuk memberi tag sumber data

Gunakan bidang metadata untuk menyimpan tag ringan, contohnya:

{
  "source": "chat",
  "channel": "web",
  "topic": "preference"
}

Ikuti rekomendasi berikut:

• Pertahankan konsistensi nama kunci. Gunakan satu bidang untuk makna yang sama agar tidak mencampur kunci seperti src, source, dan from.

• Gunakan nilai string, bukan objek bersarang.

• Jangan menyimpan blok teks besar. Sebagai gantinya, tulis konten berbentuk panjang ke bidang text atau messages.content.

• Simpan semua bidang yang diperlukan untuk pemfilteran pengambilan di metadata guna menyederhanakan auditing dan pemfilteran.

Lakukan kueri memori jangka pendek untuk pemutaran ulang dan troubleshooting

Memori jangka pendek terdiri dari pesan percakapan asli. Panggil operasi ListMemoryStoreMessages untuk memutar ulang percakapan, memverifikasi pernyataan asli pengguna, atau melakukan troubleshooting terhadap hasil ekstraksi memori jangka panjang.

Operasi ini mengharuskan Anda menentukan nilai untuk keempat bidang cakupan: appId, tenantId, agentId, dan runId. Karakter wildcard tidak didukung.

{
  "appId": "customer_service",
  "tenantId": "user_001",
  "agentId": "assistant",
  "runId": "session_20260513"
}

Gunakan audit permintaan untuk troubleshooting

Jika hasil penulisan atau pengambilan tidak sesuai harapan, pertama-tama ambil audit permintaan menggunakan operasi ListMemoryStoreRequests:

• Periksa apakah permintaan AddMemories berhasil.

• Periksa apakah tugas ekstraksi untuk penulisan asinkron gagal.

• Periksa cakupan dalam permintaan SearchMemories dan status pengembaliannya.

• Gunakan requestId untuk mengorelasikan log sisi aplikasi dan mengidentifikasi panggilan spesifik yang menyebabkan masalah.

Untuk deskripsi bidang yang dikembalikan oleh audit permintaan, lihat Referensi API.

Integrasi plugin agen

Saat menggunakan plugin Hermes atau OpenClaw, kami merekomendasikan mempertahankan strategi plugin default:

• Gunakan cakupan yang tepat untuk operasi penulisan.

• Gunakan cakupan lintas-agen dan lintas-sesi dalam penyewa yang sama untuk operasi pengambilan.

• Izinkan plugin membuat memory store secara otomatis jika belum ada.

Jika bisnis Anda memerlukan isolasi yang lebih ketat (misalnya, agen berbeda tidak boleh berbagi memori), gunakan SDK untuk melakukan panggilan langsung dan tentukan cakupan lengkap selama pengambilan. Untuk langkah dan parameter integrasi plugin, lihat integrasi ekosistem agen.