Cette page a été traduite par l'API Cloud Translation.

Révisions de la mémoire

Cette page explique comment les ressources de révision de la mémoire sont créées et gérées pour la banque de mémoire Vertex AI Agent Engine.

Cycle de vie d'un souvenir et de ses révisions

Sources de données et révisions de la mémoire

Les souvenirs peuvent être créés, mis à jour ou supprimés directement (à l'aide de CreateMemory, UpdateMemory ou DeleteMemory, respectivement) ou de manière dynamique (à l'aide de GenerateMemories). Les ressources de révision des souvenirs fournissent un historique complet des versions d'une ressource de souvenir pour toutes les opérations de mutation. Une nouvelle révision immuable est automatiquement enregistrée chaque fois que le souvenir est créé ou modifié. Vous pouvez ainsi voir comment un souvenir a évolué et (pour la génération de souvenirs) quelles informations spécifiques ont été extraites et consolidées à chaque étape.

Chaque ressource de mémoire est associée à une ou plusieurs ressources de révision de mémoire enfant :

Les ressources Memory reflètent toujours l'état actuel et consolidé des informations. Une même mémoire peut refléter des données dérivées provenant de plusieurs requêtes et sources de données.

Memory(
    create_time=datetime.datetime(...),
    fact='This is my current memory content after consolidation',
    name='projects/.../locations/.../reasoningEngines/../memories/...',
    scope={
      'my_scope_key': 'my_scope_value'
    },
    topics=[
      MemoryTopicId(
        managed_memory_topic=<ManagedTopicEnum.USER_PERSONAL_INFO: 'USER_PERSONAL_INFO'>
      ),
    ],
    update_time=datetime.datetime(...)
)

Les ressources MemoryRevisions représentent les états historiques de la mémoire parente. Chaque révision est un instantané de la mémoire lors d'un événement de mutation. Si un souvenir a été modifié à l'aide de GenerateMemories, la révision inclut également les informations extraites de la source de données (extracted_memories) avant qu'elles ne soient consolidées avec le contenu existant du souvenir.

MemoryRevision(
    create_time=datetime.datetime(...),
    expire_time=datetime.datetime(...),
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This information was extracted from my data source'
      ),
    ],
    fact='This is my current memory content after consolidation',
    name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...'
)

Les révisions de souvenirs sont activées par défaut. Pour désactiver les révisions de souvenirs, consultez Désactiver les révisions de souvenirs.

Création de souvenirs

Les souvenirs peuvent être créés directement à l'aide de CreateMemory ou de manière dynamique à l'aide de GenerateMemories. Avec la génération de souvenirs, un souvenir est créé s'il n'existe pas de souvenirs couvrant des informations similaires pour la même portée :

# Direct creation using CreateMemory
client.agent_engines.memories.create(name=agent_engine_name, ...)

# Dynamic creation using GenerateMemory
client.agent_engines.memories.generate_memories(name=agent_engine_name, ...)

Lorsqu'un souvenir est créé, une seule ressource Memory et une ressource enfant MemoryRevision sont créées :

client.agent_engines.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my original fact.",
  ...
)
"""

list(client.agent_engines.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

Info mémorisée modifiée

Les souvenirs peuvent être mis à jour directement à l'aide de UpdateMemory ou de manière dynamique à l'aide de GenerateMemories. Avec la génération de mémoire, les souvenirs sont mis à jour de manière dynamique lorsque le processus de consolidation décide que les nouvelles informations sont redondantes, complémentaires ou contradictoires par rapport à tous les souvenirs existants pour la même portée.

# Direct update using UpdateMemory
client.agent_engines.memories.update(name=memory_name, ...)

# Dynamic update using GenerateMemories
client.agent_engines.memories.generate_memories(name=agent_engine_name, ...)

Lorsqu'un souvenir est modifié, la ressource Memory existante est mise à jour et une ressource enfant MemoryRevision est créée.

client.agent_engines.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my updated fact.",
  ...
)
"""

list(client.agent_engines.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

Suppression des infos mémorisées

Les souvenirs peuvent être directement créés à l'aide de DeleteMemory ou de manière dynamique à l'aide de GenerateMemories. Avec la génération de mémoire, les souvenirs sont supprimés de manière dynamique lorsque le processus de consolidation décide que les nouvelles informations invalident les informations existantes pour la même portée.

# Direct deletion using UpdateMemory
client.agent_engines.memories.delete(name=memory_name, ...)

# Dynamic delete using GenerateMemories
client.agent_engines.memories.generate_memories(name=agent_engine_name, ...)

Lorsqu'un souvenir est supprimé, la ressource Memory existante est supprimée et une nouvelle ressource enfant MemoryRevision est créée. Le fact de la dernière révision de la mémoire est vide, car il reflète une mutation de suppression.

client.agent_engines.memories.get(name=memory_name)
"""
404 Not Found.
"""

list(client.agent_engines.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/789",
    fact="",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

Les révisions de la mémoire de l'enfant ne sont accessibles que pendant 48 heures maximum après la suppression de la mémoire du parent. Pendant cette période de récupération, vous pouvez continuer à inspecter vos révisions de souvenirs et récupérer votre souvenir en le rétablissant à une révision précédente.

Opérations de révision de la mémoire

Cette section explique comment inspecter les révisions de mémoire et effectuer un rollback d'une mémoire vers une révision précédente.

Lister les révisions

Utilisez ListMemoryRevisions pour renvoyer toutes les révisions de mémoire appartenant à une mémoire.

list(client.agent_engines.memories.revisions.list(name=MEMORY_NAME))

Remplacez les éléments suivants :

MEMORY_NAME : nom de ressource de la mémoire au format projects/.../locations/.../reasoningEngines/.../memories/....

Lorsque vous générez des souvenirs, vous pouvez fournir des libellés de révision qui sont appliqués aux révisions associées. Les libellés sont des paires clé/valeur arbitraires. Par exemple, vous pouvez libeller les révisions avec un ID de la source de données utilisée pour générer la mémoire, puis filtrer les révisions par ce libellé :

response = client.agent_engines.memories.generate(
    ...,
    config={
        "revision_labels": {
            "data_source": "321"
        }
    }
)

list(client.agent_engines.memories.revisions.list(
    name=MEMORY_NAME,
    config={
      "filter": "labels.data_source=\"321\""
    }
))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    labels={
      "data_source": "123"
    }
    ...
  )
]
"""

Obtenir une révision

Utilisez GetMemoryRevision pour récupérer une révision de mémoire individuelle.

client.agent_engines.memories.revisions.get(name=MEMORY_REVISION_NAME)

Remplacez les éléments suivants :

MEMORY_REVISION_NAME : nom de ressource de la révision de la mémoire à récupérer, au format projects/.../locations/.../reasoningEngines/.../memories/.../revisions/....

Rétablir un souvenir

Utilisez RollbackMemory pour rétablir une révision précédente d'un souvenir.

client.agent_engines.memories.rollback(
    name=name=MEMORY_NAME,
    target_revision_id=REVISION_ID
)

Remplacez les éléments suivants :

MEMORY_NAME : nom de ressource de la mémoire à mettre à jour au format projects/.../locations/.../reasoningEngines/.../memories/....
REVISION_ID : ID de la révision vers laquelle effectuer le rollback. Il s'agit du dernier segment du nom de ressource de la révision de la mémoire, comme 789 dans projects/MyProject/locations/us-central1/reasoningEngines/123/memories/456/revisions/789.

Si vous souhaitez annuler une modification apportée à un souvenir par GenerateMemories, rétablissez la version du souvenir antérieure à la modification. La réponse de génération de souvenirs inclut une référence à la révision précédente (previous_revision) pour chaque souvenir modifié ou supprimé :

operation = client.agent_engines.memories.generate(
  ...
)

# Rollback the first generated memory to the previous revision.
client.agent_engines.memories.rollback(
    name=operation.response.generated_memories[0].memory.name,
    target_revision_id=operation.response.generated_memories[0].previous_revision
)

Désactiver les révisions de souvenirs

Les révisions de la mémoire sont activées par défaut. Vous pouvez désactiver les révisions de mémoire pour toutes les requêtes adressées à votre instance de la Banque de données ou pour chaque requête individuelle. Si les révisions de mémoire sont désactivées, aucune révision de mémoire n'est créée lorsque la mémoire est modifiée.

Vous pouvez désactiver les révisions de souvenirs pour toutes les requêtes adressées à votre instance Memory Bank lorsque vous configurez l'instance :

client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": {
        "disable_memory_revisions": True
      }
    }
  }
)

Vous pouvez désactiver les révisions de mémoire au niveau d'une requête lorsque vous l'envoyez :

Générer

client.agent_engines.memories.generate(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

Créer

client.agent_engines.memories.create(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

Mettre à jour

client.agent_engines.memories.update(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

Expiration de la révision

Les révisions de souvenirs ne sont pas conservées indéfiniment. Vous devez définir l'expiration des révisions ou utiliser l'expiration par défaut. La valeur TTL (Time To Live) par défaut est de 365 jours. Vous pouvez configurer l'expiration pour toutes les requêtes adressées à votre instance Memory Bank ou pour chaque requête individuelle. Une fois qu'une révision de mémoire a expiré, elle n'est plus disponible pour l'inspection ou les rollbacks.

Vous pouvez configurer la valeur TTL pour toutes les requêtes adressées à votre instance Memory Bank lorsque vous la configurez :

client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": {
        "ttl_config": {
          # Persist memory revisions for 30 days after they're created.
          "revision_ttl": f"{30 * 60 * 60 * 24}s"
        }
      }
    }
  }
)

Pour configurer le TTL pour chaque révision de mémoire au niveau de la requête, incluez revision_expire_time ou revision_ttl dans votre requête :

Valeur TTL

config = {
    # Persist memory revisions for 30 days after they're created.
    "revision_ttl": f"{30 * 60 * 60 * 24}s"
}

client.agent_engines.memories.create(
  ...,
  config=config
)

client.agent_engines.memories.update(
  ...,
  config=config
)

client.agent_engines.memories.generate(
  ...,
  config=config
)

Expiration

import datetime

config = {
    "revision_expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(weeks=3)
}

client.agent_engines.memories.create(
  ...,
  config=config
)

client.agent_engines.memories.update(
  ...,
  config=config
)

client.agent_engines.memories.generate(
  ...,
  config=config
)

Révisions de la mémoire Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Cycle de vie d'un souvenir et de ses révisions

Création de souvenirs

Info mémorisée modifiée

Suppression des infos mémorisées

Opérations de révision de la mémoire

Lister les révisions

Obtenir une révision

Rétablir un souvenir

Désactiver les révisions de souvenirs

Générer

Créer

Mettre à jour

Expiration de la révision

Valeur TTL

Expiration

Révisions de la mémoire