Tablestore:Search Memories

Prérequis

• Vous avez créé une instance AgentStorage dont le statut est normal, et vous avez obtenu le endpoint ainsi que le nom de l'instance.

• Vous avez créé une API Key.

• Règles de portée : le champ appId est obligatoire et ne peut pas être * ; les autres champs prennent par défaut la valeur __default__ s'ils sont omis, et ne correspondent à toutes les valeurs que si * est explicitement transmis. Les magasins de mémoire qui incluent une sortie file ne prennent pas encore en charge la recherche de portée avec des caractères génériques ; utilisez des portées exactes et, si nécessaire, combinez-les avec filter pour affiner davantage la plage.

Paramètres de la requête

Les champs scope et filter peuvent résoudre au maximum 1 000 portées de conversation uniques ; si cette limite est dépassée, l'erreur 400 INVALID_PARAMETER est renvoyée. Lorsque la requête de portée est temporairement indisponible, l'erreur 503 SERVICE_UNAVAILABLE est renvoyée. Les magasins de mémoire qui incluent une sortie file ne prennent pas encore en charge la recherche de portée avec des caractères génériques ; utilisez des portées exactes et, si nécessaire, combinez-les avec filter pour affiner davantage la plage.

Le champ metadata effectue une correspondance exacte sur la chaîne complète ; des caractères tels que *, ?, les virgules et les signes égal sont traités comme des caractères ordinaires, ce qui le rend adapté à la récupération de valeurs longues telles que les UUID et les ID de trace. Si le nombre de clés ou les limites de longueur clé-valeur sont dépassés, l'erreur 400 INVALID_PARAMETER est renvoyée. Pour la définition générale, consultez les Métadonnées.

Le paramètre topK s'applique séparément aux champs results et fileResults. En raison du filtrage par pertinence, de la déduplication ou d'un manque de données visibles, le nombre réel de résultats peut être inférieur à topK ; les applications ne doivent pas compter sur un nombre fixe d'éléments renvoyés.

Exemple de requête

Lors de l'utilisation de l'authentification par API Key, transmettez le nom de l'instance et la clé API via les en-têtes de requête x-ots-instancename et x-ots-apikey.

curl -X POST https://<endpoint>/SearchMemories \
  -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": "*",
    "runId": "*"
  },
  "filter": {"op": "eq", "field": "text", "value": "*sess*"},
  "contextScope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "query": "用户喜欢什么饮品",
  "topK": 5,
  "enableRerank": true,
  "includeEvidence": true,
  "thresholds": {
    "minSimilarity": 0.3,
    "minScore": 0.2
  },
  "metadata": {
    "source": "chat"
  }
}'

Réponse

Les champs results et fileResults sont renvoyés pour tous les magasins de mémoire, afin que les clients puissent utiliser la même structure de réponse. Les magasins de mémoire à double sortie renvoient au maximum topK résultats structurés et topK résultats de fichiers, respectivement.

Les éléments fileResults comportent les champs suivants.

Exemple de réponse pour un magasin de mémoire à double sortie :

Par défaut, les results sont triés par score dans l'ordre décroissant. Les résultats ne sont retriés par rankingScore dans l'ordre décroissant que si la réponse inclut rankingScore ; le classement souple de session n'écrase pas le score.

Le champ results[].unit contient les champs internes suivants. Les champs d'unité de mémoire renvoyés par ListMemories et GetMemory sont cohérents avec ceux-ci. Les vecteurs d'embedding ne sont pas renvoyés dans la réponse.

Lorsque contextScope est fourni, le service peut prioriser les mémoires de la conversation actuelle parmi les candidats ayant une pertinence sémantique similaire. Ce champ affecte uniquement le classement et n'étend pas la plage de données spécifiée par scope et filter, ni ne permet de contourner les thresholds ou les seuils de compatibilité.

{
    "memoryStoreName": "agent_memory",
    "results": [
        {
            "unit": {
                "id": "1b88d0d65a5b6c0d9142e9b7c7347048",
                "conversation_key": "app-001/user-001/assistant/session-001",
                "scope": {
                    "appId": "app-001",
                    "tenantId": "user-001",
                    "agentId": "assistant",
                    "runId": "session-001"
                },
                "memcell_id": "87e8805d6df9866dce823d135cfd6dff",
                "unit_type": "entity_fact",
                "text": "[2026-08-25T05:52:19Z] 我写脚本只用 Python。",
                "search_text": "用户编程语言偏好\n我写脚本只用 Python。\nkeywords: Python, 脚本, 编程语言, 偏好\nPython 脚本语言 技术偏好\nuser\n记住：我的内部工号是 FALCON-9931，常驻杭州，写脚本只用 Python。\ntime: 2026-08-25T05:52:19Z",
                "keywords": [
                    "Python",
                    "脚本",
                    "编程语言",
                    "偏好"
                ],
                "source_turn_ids": [
                    "aa5f2e1d34b8ced5b044239f0fc75bee"
                ],
                "source_turn_refs": [
                    {
                        "messageId": "aa5f2e1d34b8ced5b044239f0fc75bee",
                        "timestampMs": 1787637139185
                    }
                ],
                "type_label": "profile_fact",
                "date_bucket": "2026-08",
                "metadata": {
                    "content_hash": "4ec0592b5550159a3f77b9dc62bca64e",
                    "session_date": "5:52 AM on 25 August, 2026",
                    "source_quote": "写脚本只用 Python"
                },
                "metadata_json": "{\"content_hash\":\"4ec0592b5550159a3f77b9dc62bca64e\",\"session_date\":\"5:52 AM on 25 August, 2026\",\"source_quote\":\"写脚本只用 Python\"}",
                "metadata_flat": "content_hash=4ec0592b5550159a3f77b9dc62bca64e,session_date=5:52 AM on 25 August, 2026,source_quote=写脚本只用 Python",
                "deleted": false,
                "created_at": "2026-08-25T05:52:19.185Z",
                "salience": 0.8,
                "version": 1,
                "title": "用户编程语言偏好",
                "effective_at": "2026-08-25T05:52:19Z",
                "updated_at": "2026-08-25T05:52:30.509Z",
                "time_source": "source_message",
                "time_precision": "second"
            },
            "score": 0.3358759430317645,
            "similarity": 0.2652787210590392,
            "source": "vector"
        },
        {
            "unit": {
                "id": "546b00a31ddd5e76e309e2da5cb0030e",
                "conversation_key": "app-001/user-001/assistant/session-001",
                "scope": {
                    "appId": "app-001",
                    "tenantId": "user-001",
                    "agentId": "assistant",
                    "runId": "session-001"
                },
                "memcell_id": "87e8805d6df9866dce823d135cfd6dff",
                "unit_type": "entity_fact",
                "text": "[2026-08-25T05:52:19Z] 我常驻杭州。",
                "search_text": "用户常驻地\n我常驻杭州。\nkeywords: 杭州, 常驻, 地理位置\n杭州 常驻地 地理位置\nuser\n记住：我的内部工号是 FALCON-9931，常驻杭州，写脚本只用 Python。\ntime: 2026-08-25T05:52:19Z",
                "keywords": [
                    "杭州",
                    "常驻",
                    "地理位置"
                ],
                "source_turn_ids": [
                    "aa5f2e1d34b8ced5b044239f0fc75bee"
                ],
                "source_turn_refs": [
                    {
                        "messageId": "aa5f2e1d34b8ced5b044239f0fc75bee",
                        "timestampMs": 1787637139185
                    }
                ],
                "type_label": "profile_fact",
                "date_bucket": "2026-08",
                "metadata": {
                    "content_hash": "9f9821b441975f392313a2d7aec6ed6e",
                    "session_date": "5:52 AM on 25 August, 2026",
                    "source_quote": "常驻杭州"
                },
                "metadata_json": "{\"content_hash\":\"9f9821b441975f392313a2d7aec6ed6e\",\"session_date\":\"5:52 AM on 25 August, 2026\",\"source_quote\":\"常驻杭州\"}",
                "metadata_flat": "content_hash=9f9821b441975f392313a2d7aec6ed6e,session_date=5:52 AM on 25 August, 2026,source_quote=常驻杭州",
                "deleted": false,
                "created_at": "2026-08-25T05:52:19.185Z",
                "salience": 0.8,
                "version": 1,
                "title": "用户常驻地",
                "effective_at": "2026-08-25T05:52:19Z",
                "updated_at": "2026-08-25T05:52:30.509Z",
                "time_source": "source_message",
                "time_precision": "second"
            },
            "score": 0.32277120656532554,
            "similarity": 0.25208147048454044,
            "source": "vector"
        },
        {
            "unit": {
                "id": "4f6ddad33fad6f52d475c69708b44dd1",
                "conversation_key": "app-001/user-001/assistant/session-001",
                "scope": {
                    "appId": "app-001",
                    "tenantId": "user-001",
                    "agentId": "assistant",
                    "runId": "session-001"
                },
                "memcell_id": "87e8805d6df9866dce823d135cfd6dff",
                "unit_type": "entity_fact",
                "text": "[2026-08-25T05:52:19Z] 我的内部工号是 FALCON-9931。",
                "search_text": "用户内部工号\n我的内部工号是 FALCON-9931。\nkeywords: 工号, FALCON-9931, 内部标识\nFALCON-9931 工号 身份标识\nuser\n记住：我的内部工号是 FALCON-9931，常驻杭州，写脚本只用 Python。\ntime: 2026-08-25T05:52:19Z",
                "keywords": [
                    "工号",
                    "FALCON-9931",
                    "内部标识"
                ],
                "source_turn_ids": [
                    "aa5f2e1d34b8ced5b044239f0fc75bee"
                ],
                "source_turn_refs": [
                    {
                        "messageId": "aa5f2e1d34b8ced5b044239f0fc75bee",
                        "timestampMs": 1787637139185
                    }
                ],
                "type_label": "profile_fact",
                "date_bucket": "2026-08",
                "metadata": {
                    "content_hash": "d0b62aedd9294009f14ed6ab951ebfed",
                    "session_date": "5:52 AM on 25 August, 2026",
                    "source_quote": "我的内部工号是 FALCON-9931"
                },
                "metadata_json": "{\"content_hash\":\"d0b62aedd9294009f14ed6ab951ebfed\",\"session_date\":\"5:52 AM on 25 August, 2026\",\"source_quote\":\"我的内部工号是 FALCON-9931\"}",
                "metadata_flat": "content_hash=d0b62aedd9294009f14ed6ab951ebfed,session_date=5:52 AM on 25 August, 2026,source_quote=我的内部工号是 FALCON-9931",
                "deleted": false,
                "created_at": "2026-08-25T05:52:19.185Z",
                "salience": 0.8,
                "version": 1,
                "title": "用户内部工号",
                "effective_at": "2026-08-25T05:52:19Z",
                "updated_at": "2026-08-25T05:52:30.509Z",
                "time_source": "source_message",
                "time_precision": "second"
            },
            "score": 0.2805238412257555,
            "similarity": 0.23675615504707195,
            "source": "vector"
        }
    ],
    "scope": {
        "appId": "app-001",
        "tenantId": "user-001",
        "agentId": "*",
        "runId": "*"
    }
}