AddMemories Write memories - Tablestore - Centre de documentation Alibaba Cloud

Utilisez l'opération AddMemories pour écrire des messages de conversation ou du texte dans un magasin de mémoires configuré avec inputType=messages. Le service stocke les messages d'origine sous forme de mémoire à court terme et génère de manière asynchrone une mémoire structurée, des fichiers de mémoire en lecture seule, ou les deux, selon les paramètres outputTypes du magasin.

Prérequis

Vous avez créé une instance AgentStorage dont l'état est normal, et vous avez obtenu le point de terminaison ainsi que le nom de l'instance.
Vous avez généré une clé API.
Le paramètre inputType du magasin de mémoires cible doit être défini sur messages.
Règles de portée : lors de l'écriture des données, le champ appId est obligatoire et les caractères génériques (*) ne sont pas autorisés. Si d'autres champs sont omis, ils prennent la valeur par défaut __default__.

Paramètres de requête

Champ

Type

Obligatoire

Description

memoryStoreName

string

Oui

Nom du magasin de mémoires cible.

scope

object

Oui

Portée. Lors de l'écriture des données, le champ appId est obligatoire et les caractères génériques (*) ne sont pas autorisés.

messages

array

text ou messages

Tableau de messages de conversation. Ce tableau peut contenir jusqu'à 20 messages, et la longueur totale du contenu ne doit pas dépasser 32 000 octets (UTF-8).

text

string

messages ou texte

Contenu textuel. La longueur maximale est de 32 000 octets (UTF-8).

metadata

object

Non

Paires clé-valeur de type chaîne au niveau de l'écriture. Jusqu'à 16 clés sont autorisées. Chaque clé peut comporter jusqu'à 64 caractères Unicode. La taille totale après encodage JSON ne doit pas dépasser 65 536 octets (UTF-8, 64 KiB).

sync

boolean

Non

Indique s'il faut attendre de manière synchrone la fin de la génération de la mémoire structurée. Valeur par défaut : false. Si le magasin de mémoires utilise la sortie file, ce paramètre doit être défini sur false. Dans le cas contraire, l'erreur 400 INVALID_PARAMETER est renvoyée.

referenceTime

string

Non

Heure de référence de la session au format RFC3339 (point d'ancrage « as-of »). Une fois ce paramètre défini, les messages qui ne contiennent pas de champ timestamp utilisent cette heure comme heure de l'événement au lieu de l'heure du serveur. Ce paramètre s'applique aux scénarios d'importation historique ou par lots.

Les limites de l'opération AddMemories sont soumises aux restrictions décrites dans la section Limitations et remarques.

Une écriture réussie indique que le service a reçu les messages. La génération de toutes les sorties dépend de l'état de la tâche. Pour les appels asynchrones, enregistrez l'identifiant requestId présent dans la réponse. Ne générez pas ce champ dans le corps de la requête. Une fois les fichiers générés, appelez l'opération ListItems avec la portée exacte, puis lisez le contenu en appelant GetItem(view=full).

Exemples de requêtes

Lorsque vous utilisez l'authentification par clé API, transmettez le nom de l'instance et la clé API dans les en-têtes de requête x-ots-instancename et x-ots-apikey.

curl -X POST https://<endpoint>/AddMemories \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "messages": [
    {
      "role": "user",
      "content": "I like drinking coffee."
    },
    {
      "role": "assistant",
      "content": "OK, I noted that."
    }
  ],
  "metadata": {
    "source": "chat"
  },
  "sync": false
}'

Écriture de texte :

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001"
  },
  "text": "The user likes coffee and prefers concise responses."
}

Réponse

Champ

Description

requestId

Identifiant de la requête.

status

État de la requête. Les écritures asynchrones renvoient généralement running.

acceptedMessages

Nombre de messages reçus.

scope

Portée utilisée pour l'écriture effective.

memoryStoreName

Nom du magasin de mémoires.

memcellsCreated

Renvoyé pour les écritures synchrones. Indique le nombre de segments de mémoire créés.

unitsCreated

Renvoyé pour les écritures synchrones. Indique le nombre d'unités de mémoire à long terme créées.

memoryIds

Renvoyé uniquement lorsque sync=true. Tableau contenant les identifiants de la mémoire à long terme générée avec succès. L'ordre correspond au résultat final du traitement et la longueur est égale à unitsCreated. Si aucune mémoire à long terme n'est générée, un tableau vide est renvoyé.

Lorsque la requête spécifie sync=true, vous pouvez obtenir directement les identifiants de la mémoire à long terme générée à partir du tableau memoryIds dans la réponse.

{
  "requestId": "req-001",
  "status": "completed",
  "acceptedMessages": 2,
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "memoryStoreName": "agent_memory",
  "memcellsCreated": 1,
  "unitsCreated": 1,
  "memoryIds": [
    "memory-001"
  ]
}