Générer des souvenirs

Preview

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

La banque de mémoire vous permet de construire des souvenirs à long terme à partir des conversations entre l'utilisateur et votre agent. Cette page explique comment fonctionne la génération de souvenirs, comment personnaliser l'extraction des souvenirs et comment déclencher la génération de souvenirs.

Comprendre la génération de mémoire

Memory Bank extrait des souvenirs à partir de données sources et les organise automatiquement pour une collection spécifique (définie par un scope) en ajoutant, en modifiant et en supprimant des souvenirs au fil du temps.

Lorsque vous déclenchez la génération de souvenirs, la Banque de souvenirs effectue les opérations suivantes :

• Extraction : extrait des informations sur l'utilisateur à partir de ses conversations avec l'agent. Seules les informations correspondant à au moins l'un des thèmes de mémoire de votre instance seront conservées.

• Consolidation : identifie si les souvenirs existants de même portée doivent être supprimés ou mis à jour en fonction des informations extraites. La banque de souvenirs vérifie que les nouveaux souvenirs ne sont pas des doublons ni des contradictions avant de les fusionner avec les souvenirs existants. Si les infos mémorisées existantes ne chevauchent pas les nouvelles informations, une nouvelle info mémorisée est créée.

Important : Toutes les interactions avec l'agent utilisateur n'entraînent pas la création ni la mise à jour de souvenirs. La mémoire ne conserve que les informations jugées utiles pour les interactions futures.

Les souvenirs ne peuvent être extraits que du texte, des fichiers intégrés et des données de fichier du contenu source. Tous les autres contenus, y compris les appels et les réponses de fonctions, sont ignorés lors de la génération de souvenirs.

Les souvenirs peuvent être extraits des images, des vidéos et des contenus audio fournis par l'utilisateur. Si la banque de mémoire juge que le contexte fourni par l'entrée multimodale est pertinent pour les interactions futures, une mémoire textuelle peut être créée, incluant les informations extraites de l'entrée. Par exemple, si l'utilisateur fournit une image d'un golden retriever avec le texte "C'est mon chien", la Banque de souvenirs génère un souvenir tel que "Mon chien est un golden retriever".

Attention : Bien que la Banque de mémoire ait été conçue pour exclure les données sensibles ou personnelles, le système n'est pas infaillible. Par conséquent, vous devez supposer que certaines informations sensibles ou personnelles peuvent toujours être stockées et ne pas vous fier uniquement à cette fonctionnalité pour filtrer ces données.

Thèmes de souvenirs

Les "thèmes de mémoire" identifient les informations que la mémoire considère comme importantes et qui doivent donc être conservées en tant que souvenirs générés. La banque de mémoire accepte deux types de thèmes de mémoire :

• Sujets gérés : le libellé et les instructions sont définis par la banque de souvenirs. Il vous suffit d'indiquer le nom du thème géré. Exemple :

  Dictionnaire

  memory_topic = {
      "managed_memory_topic": {
          "managed_topic_enum": "USER_PERSONAL_INFO"
      }
  }
  

  Basé sur les classes

  from vertexai.types import ManagedTopicEnum
  from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
  from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
  
  memory_topic = MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
      )
  )
  

• Thèmes personnalisés : le libellé et les instructions sont définis par vous lorsque vous configurez votre instance Memory Bank. Elles seront utilisées dans la requête pour l'étape d'extraction de la mémoire. Exemple :

  Dictionnaire

  memory_topic = {
      "custom_memory_topic": {
          "label": "business_feedback",
          "description": """Specific user feedback about their experience at
  the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
  staff friendliness, service speed, cleanliness, and any suggestions for
  improvement."""
      }
  }
  

  Basé sur les classes

  from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
  from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
  
  memory_topic = MemoryTopic(
      custom_memory_topic=CustomMemoryTopic(
          label="business_feedback",
          description="""Specific user feedback about their experience at
  the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
  staff friendliness, service speed, cleanliness, and any suggestions for
  improvement."""
      )
  )
  

  Lorsque vous utilisez des thèmes personnalisés, nous vous recommandons également de fournir des exemples few-shot pour montrer comment les souvenirs doivent être extraits de votre conversation.

Par défaut, la banque de mémoire conserve tous les sujets gérés suivants :

• Informations personnelles (USER_PERSONAL_INFO) : informations personnelles importantes sur l'utilisateur, comme son nom, ses relations, ses loisirs et les dates importantes. Par exemple, "Je travaille chez Google" ou "Mon anniversaire de mariage est le 31 décembre".
• Préférences utilisateur (USER_PREFERENCES) : préférences, styles ou motifs exprimés ou implicites. Par exemple, "Je préfère le siège du milieu".
• Événements clés et résultats des tâches dans la conversation (KEY_CONVERSATION_DETAILS) : étapes importantes ou conclusions dans le dialogue. Par exemple, "J'ai réservé des billets d'avion aller-retour entre JFK et SFO. Je pars le 1er juin 2025 et reviens le 7 juin 2025."
• Instructions explicites pour se souvenir d'une information ou l'oublier (EXPLICIT_INSTRUCTIONS) : informations que l'utilisateur demande explicitement à l'agent de mémoriser ou d'oublier. Par exemple, si l'utilisateur dit "Souviens-toi que j'utilise principalement Python", la Banque de mémoire génère un souvenir tel que "J'utilise principalement Python".

Cela équivaut à utiliser l'ensemble de rubriques sur la mémoire gérée suivant :

Dictionnaire

  memory_topics = [
      {"managed_memory_topic": {"managed_topic_enum": "USER_PERSONAL_INFO"}},
      {"managed_memory_topic": {"managed_topic_enum": "USER_PREFERENCES"}},
      {"managed_memory_topic": {"managed_topic_enum": "KEY_CONVERSATION_DETAILS"}},
      {"managed_memory_topic": {"managed_topic_enum": "EXPLICIT_INSTRUCTIONS"}},
  ]

Basé sur les classes

from vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

memory_topics = [
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.KEY_CONVERSATION_DETAILS)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.EXPLICIT_INSTRUCTIONS)),
]

Si vous souhaitez personnaliser les thèmes que la banque de mémoire conserve, définissez les thèmes de mémoire dans votre configuration de personnalisation lorsque vous configurez la banque de mémoire.

Générer des souvenirs

Pour suivre les étapes décrites dans ce guide, vous devez d'abord suivre celles de la section Configurer Memory Bank.

Vous pouvez déclencher la génération de souvenirs à l'aide de GenerateMemories à la fin d'une session ou à intervalles réguliers au cours d'une session. La génération de mémoire extrait le contexte clé des conversations sources et le combine aux souvenirs existants pour la même portée. Par exemple, vous pouvez créer des souvenirs au niveau de la session à l'aide d'un champ d'application tel que {"user_id": "123", "session_id": "456"}. Les souvenirs ayant la même portée peuvent être regroupés et récupérés ensemble.

Lorsque vous appelez GenerateMemories, vous devez fournir la conversation source via les sessions Agent Engine ou directement au format JSON :

Format JSON

Si vous utilisez un stockage de session différent de celui des sessions Agent Engine, fournissez la conversation source directement au format JSON :

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": EVENTS
    },
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

Remplacez les éléments suivants :

• EVENTS : liste des dictionnaires de contenu. Exemple :

[
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I'm work with LLM agents!"}
      ]
    }
  }
]

• SCOPE : dictionnaire représentant le champ d'application des souvenirs générés. Exemple :{"session_id": "MY_SESSION"} Seuls les souvenirs ayant la même portée sont pris en compte pour la consolidation.

Sessions Agent Engine

Avec les sessions Agent Engine, la banque de mémoire utilise les événements de session comme source de conversation pour générer la mémoire.

Pour définir le champ d'application des souvenirs générés, la banque de souvenirs extrait et utilise l'ID utilisateur de la session par défaut. Par exemple, la portée des souvenirs est stockée sous la forme {"user_id": "123"} si le user_id de la session est "123". Vous pouvez également fournir un scope directement, ce qui remplace l'utilisation du user_id de la session comme portée.

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    "session": "SESSION_NAME"
  },
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

Remplacez les éléments suivants :

• SESSION_NAME : nom de la session.

• (Facultatif) SCOPE : dictionnaire représentant le champ d'application des souvenirs générés. Exemple :{"session_id": "MY_SESSION"} Seuls les souvenirs ayant la même portée sont pris en compte pour la consolidation. Si aucune valeur n'est spécifiée, {"user_id": session.user_id} est utilisé.

GenerateMemories est une opération de longue durée. Une fois l'opération terminée, AgentEngineGenerateMemoriesOperation contient la liste des souvenirs générés, le cas échéant :

AgentEngineGenerateMemoriesOperation(
  name="projects/.../locations/.../reasoningEngines/.../operations/...",
  done=True,
  response=GenerateMemoriesResponse(
    generatedMemories=[
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="CREATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="UPDATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="DELETED",
      ),
    ]
  )
)

Chaque souvenir généré inclut l'action qui a été effectué sur ce souvenir :

• CREATED : indique qu'un nouveau souvenir a été ajouté, représentant un nouveau concept qui n'a pas été capturé par les souvenirs existants.
• UPDATED : indique qu'une mémoire existante a été mise à jour, ce qui se produit si la mémoire couvrait des concepts similaires à ceux des nouvelles informations extraites. Les faits mémorisés peuvent être mis à jour avec de nouvelles informations ou rester les mêmes.
• DELETED : indique que la mémoire existante a été supprimée, car ses informations étaient en contradiction avec les nouvelles informations extraites de la conversation.

Remarque : Si la Banque de souvenirs ne trouve pas d'informations pertinentes dans la conversation de l'agent utilisateur, aucun souvenir n'est généré.

Pour les souvenirs CREATED ou UPDATED, vous pouvez utiliser GetMemories pour récupérer l'intégralité du contenu du souvenir. La récupération des souvenirs DELETED génère une erreur 404.

Génération de souvenirs en arrière-plan

GenerateMemories est une opération de longue durée. Par défaut, client.agent_engines.generate_memories est une fonction bloquante qui continue d'interroger l'opération jusqu'à ce qu'elle soit terminée. L'exécution de la génération de souvenirs en tant qu'opération de blocage est utile lorsque vous souhaitez inspecter manuellement les souvenirs générés ou lorsque vous souhaitez informer les utilisateurs finaux des souvenirs qui ont été générés.

Toutefois, pour les agents de production, vous souhaitez généralement exécuter la génération de mémoire en arrière-plan en tant que processus asynchrone. Dans la plupart des cas, le client n'a pas besoin d'utiliser le résultat de l'exécution en cours. Il est donc inutile d'entraîner une latence supplémentaire en attendant une réponse. Si vous souhaitez que la génération de mémoire s'exécute en arrière-plan, définissez wait_for_completion sur False :

client.agent_engines.memories.generate(
    ...,
    config={
        "wait_for_completion": False
    }
)

Consolidation des souvenirs pré-extraits

Au lieu d'utiliser le processus d'extraction automatique de la banque de souvenirs, vous pouvez fournir directement des souvenirs pré-extraits. Les souvenirs de source directe seront regroupés avec les souvenirs existants pour la même portée. Cela peut être utile lorsque vous souhaitez que votre agent ou un humain dans la boucle soit responsable de l'extraction des souvenirs, mais que vous souhaitez toujours profiter de la consolidation de la banque de mémoire pour vous assurer qu'il n'y a pas de souvenirs en double ou contradictoires.

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Remplacez les éléments suivants :

• FACT : fait préextrait à consolider avec les souvenirs existants. Vous pouvez fournir jusqu'à cinq faits pré-extraits dans une liste comme celle-ci :

  {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
  

• SCOPE : dictionnaire représentant le champ d'application des souvenirs générés. Exemple :{"session_id": "MY_SESSION"} Seuls les souvenirs ayant la même portée sont pris en compte pour la consolidation.

Étapes suivantes

• Récupérer les souvenirs générés
• Personnaliser le comportement d'extraction de la mémoire