Erinnerungen erstellen

Mit Memory Bank können Sie langfristig gemerkte Informationen aus Unterhaltungen zwischen dem Nutzer und Ihrem Agent erstellen. Auf dieser Seite wird beschrieben, wie die Erinnerungsgenerierung funktioniert, wie Sie die Extraktion von Erinnerungen anpassen und wie Sie die Erinnerungsgenerierung auslösen können.

Erstellen von Erinnerungen

Memory Bank extrahiert Erinnerungen aus Quelldaten und stellt Erinnerungen für eine bestimmte Sammlung von Erinnerungen (definiert durch ein scope) selbst zusammen, indem im Laufe der Zeit Erinnerungen hinzugefügt, aktualisiert und entfernt werden.

Wenn Sie die Generierung von Erinnerungen auslösen, führt Memory Bank die folgenden Vorgänge aus:

  • Extraktion: Extrahiert Informationen über den Nutzer aus seinen Unterhaltungen mit dem Agent. Es werden nur Informationen gespeichert, die mindestens einem der Gedächtnisthemen Ihrer Instanz entsprechen.

  • Konsolidierung: Gibt an, ob vorhandene Erinnerungen mit demselben Umfang basierend auf den extrahierten Informationen gelöscht oder aktualisiert werden sollen. Memory Bank prüft, ob neue Erinnerungen doppelt oder widersprüchlich sind, bevor sie mit bestehenden Erinnerungen zusammengeführt werden. Wenn sich vorhandene Erinnerungen nicht mit den neuen Informationen überschneiden, wird eine neue Erinnerung erstellt.

Erinnerungen können nur aus Text, Inline-Dateien und Dateidaten im Quellinhalt extrahiert werden. Alle anderen Inhalte, einschließlich Funktionsaufrufen und Antworten, werden bei der Erstellung von Erinnerungen ignoriert.

Erinnerungen können aus Bildern, Videos und Audio extrahiert werden, die vom Nutzer bereitgestellt werden. Wenn der durch die multimodale Eingabe bereitgestellte Kontext von Memory Bank als sinnvoll für zukünftige Interaktionen eingestuft wird, kann ein textuelles Gedächtnis erstellt werden, das Informationen aus der Eingabe enthält. Wenn der Nutzer beispielsweise ein Bild eines Golden Retrievers mit dem Text „Das ist mein Hund“ bereitstellt, generiert Memory Bank eine Erinnerung wie „Mein Hund ist ein Golden Retriever“.

Erinnerungsthemen

„Memory-Themen“ geben an, welche Informationen Memory Bank als wichtig erachtet und daher als generierte Erinnerungen gespeichert werden sollten. Memory Bank unterstützt zwei Arten von Memory-Themen:

  • Verwaltete Themen: Label und Anleitung werden von Memory Bank definiert. Sie müssen nur den Namen des verwalteten Themas angeben. Beispiel:

    Wörterbuch

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

    Klassenbasiert

    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
    )
)

  • Benutzerdefinierte Themen: Label und Anleitung werden von Ihnen bei der Einrichtung Ihrer Memory Bank-Instanz definiert. Sie werden im Prompt für den Extraktionsschritt der Memory Bank verwendet. Beispiel:

    Wörterbuch

    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."""
    }
}

    Klassenbasiert

    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."""
    )
)

    Wenn Sie benutzerdefinierte Themen verwenden, sollten Sie auch Few-Shot-Beispiele angeben, um zu zeigen, wie Erinnerungen aus Ihrem Gespräch extrahiert werden sollen.

Standardmäßig werden in Memory Bank alle folgenden verwalteten Themen gespeichert:

  • Personenbezogene Daten (USER_PERSONAL_INFO): Wichtige personenbezogene Daten des Nutzers, z. B. Namen, Beziehungen, Hobbys und wichtige Termine. Beispiele: „Ich arbeite bei Google“ oder „Mein Hochzeitstag ist am 31. Dezember“.
  • Nutzereinstellungen (USER_PREFERENCES): Angegebene oder implizierte Vorlieben, Abneigungen, bevorzugte Stile oder Muster. Beispiel: „Ich bevorzuge den mittleren Sitzplatz.“
  • Wichtige Unterhaltungsereignisse und Aufgabenergebnisse (KEY_CONVERSATION_DETAILS): Wichtige Meilensteine oder Schlussfolgerungen im Dialog. Beispiel: „Ich habe Flugtickets für einen Hin- und Rückflug zwischen JFK und SFO gebucht. Ich reise am 1. Juni 2025 ab und kehre am 7. Juni 2025 zurück.“
  • Explizite Anweisungen zum Merken / Vergessen (EXPLICIT_INSTRUCTIONS): Informationen, die der Nutzer explizit vom Agenten verlangt, dass er sie sich merkt oder vergisst. Wenn der Nutzer beispielsweise sagt: „Denk daran, dass ich hauptsächlich Python verwende“, generiert Memory Bank einen Eintrag wie „Ich verwende hauptsächlich Python“.

Dies entspricht der Verwendung der folgenden Themen zur Verwaltung des Arbeitsspeichers:

Wörterbuch

  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"}},
  ]

Klassenbasiert

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)),
]

Wenn Sie anpassen möchten, welche Themen in der Wissensdatenbank gespeichert werden, legen Sie die Themen für die Wissensdatenbank bei der Einrichtung der Wissensdatenbank in Ihrer Konfiguration zur Anpassung fest.

Erinnerungen erstellen

Um die in diesem Leitfaden beschriebenen Schritte auszuführen, müssen Sie zuerst die Schritte unter Für Memory Bank einrichten ausführen.

Sie können die Generierung von Erinnerungen mit GenerateMemories am Ende einer Sitzung oder in regelmäßigen Abständen innerhalb einer Sitzung auslösen. Beim Generieren von Erinnerungen wird der wichtigste Kontext aus Quellunterhaltungen extrahiert und mit vorhandenen Erinnerungen für denselben Bereich kombiniert. Sie können beispielsweise Erinnerungen auf Sitzungsebene erstellen, indem Sie einen Bereich wie {"user_id": "123", "session_id": "456"} verwenden. Erinnerungen mit demselben Umfang können zusammengefasst und gemeinsam abgerufen werden.

Wenn Sie GenerateMemories aufrufen, müssen Sie die Quellunterhaltung über Agent Engine-Sitzungen oder direkt im JSON-Format angeben:

JSON-Format

Geben Sie die Quellunterhaltung direkt im JSON-Format an, wenn Sie einen anderen Sitzungsspeicher als Agent Engine Sessions verwenden:

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

Ersetzen Sie Folgendes:

  • EVENTS: Liste der Inhaltswörterbücher. Beispiel:
[
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I'm work with LLM agents!"}
      ]
    }
  }
]
  • SCOPE: Ein Dictionary, das den Umfang der generierten Erinnerungen darstellt. Beispiel: {"session_id": "MY_SESSION"}. Für die Konsolidierung werden nur Erinnerungen mit demselben Umfang berücksichtigt.

Agent Engine-Sitzungen

Bei Agent Engine-Sitzungen verwendet Memory Bank Sitzungsereignisse als Quellunterhaltung für die Speichergenerierung.

Um die generierten Erinnerungen einzugrenzen, wird standardmäßig die Nutzer-ID aus der Sitzung extrahiert und verwendet. Der Bereich der Erinnerungen wird beispielsweise als {"user_id": "123"} gespeichert, wenn die user_id der Sitzung „123“ ist. Sie können auch direkt ein scope angeben. In diesem Fall wird nicht der user_id der Sitzung als Bereich verwendet.

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
  }
)

Ersetzen Sie Folgendes:

  • SESSION_NAME: Der Sitzungsname.

  • (Optional) SCOPE: Ein Dictionary, das den Umfang der generierten Erinnerungen darstellt. Beispiel: {"session_id": "MY_SESSION"}. Für die Konsolidierung werden nur Erinnerungen mit demselben Umfang berücksichtigt. Wenn nicht angegeben, wird {"user_id": session.user_id} verwendet.

GenerateMemories ist ein Vorgang mit langer Ausführungszeit. Wenn der Vorgang abgeschlossen ist, enthält AgentEngineGenerateMemoriesOperation eine Liste der generierten Erinnerungen, sofern welche generiert wurden:

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",
      ),
    ]
  )
)

Jede generierte Erinnerung enthält die action, die für diese Erinnerung ausgeführt wurde:

  • CREATED: Gibt an, dass eine neue Erinnerung hinzugefügt wurde, die ein neues Konzept darstellt, das nicht von vorhandenen Erinnerungen erfasst wurde.
  • UPDATED: Gibt an, dass ein vorhandener Speicher aktualisiert wurde. Dies geschieht, wenn der Speicher ähnliche Konzepte wie die neu extrahierten Informationen abdeckt. Die Fakten im Gedächtnis können mit neuen Informationen aktualisiert werden oder gleich bleiben.
  • DELETED: Gibt an, dass der vorhandene Speicher gelöscht wurde, weil seine Informationen im Widerspruch zu neuen Informationen standen, die aus dem Gespräch extrahiert wurden.

Für CREATED- oder UPDATED-Gedächtnisse können Sie GetMemories verwenden, um den vollständigen Inhalt des Gedächtnisses abzurufen. Beim Abrufen von DELETED-Erinnerungen wird ein 404-Fehler ausgegeben.

Erinnerungen im Hintergrund generieren

GenerateMemories ist ein Vorgang mit langer Ausführungszeit. Standardmäßig ist client.agent_engines.generate_memories eine blockierende Funktion, die den Vorgang so lange abfragt, bis er abgeschlossen ist. Die Ausführung der Speichergenerierung als blockierender Vorgang ist hilfreich, wenn Sie die generierten Erinnerungen manuell prüfen oder Endnutzer darüber informieren möchten, welche Erinnerungen generiert wurden.

Bei Produktions-Agents sollten Sie die Speichergenerierung jedoch in der Regel im Hintergrund als asynchronen Prozess ausführen. In den meisten Fällen muss der Client die Ausgabe für den aktuellen Lauf nicht verwenden. Es ist daher nicht erforderlich, zusätzliche Latenzzeiten durch Warten auf eine Antwort in Kauf zu nehmen. Wenn die Speichergenerierung im Hintergrund ausgeführt werden soll, setzen Sie wait_for_completion auf False:

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

Zusammenführen von vorab extrahierten Erinnerungen

Alternativ zum automatischen Extraktionsprozess von Memory Bank können Sie auch direkt vorab extrahierte Erinnerungen bereitstellen. Erinnerungen aus direkten Quellen werden mit vorhandenen Erinnerungen für denselben Bereich zusammengeführt. Das kann nützlich sein, wenn Sie möchten, dass Ihr Agent oder ein Mensch für das Extrahieren von Erinnerungen verantwortlich ist, Sie aber trotzdem die Konsolidierung der Memory Bank nutzen möchten, um sicherzustellen, dass es keine doppelten oder widersprüchlichen Erinnerungen gibt.

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

Ersetzen Sie Folgendes:

  • FACT: Die vorab extrahierte Information, die mit vorhandenen Erinnerungen zusammengeführt werden soll. Sie können bis zu fünf vorab extrahierte Fakten in einer Liste wie der folgenden angeben:

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

  • SCOPE: Ein Dictionary, das den Umfang der generierten Erinnerungen darstellt. Beispiel: {"session_id": "MY_SESSION"}. Für die Konsolidierung werden nur Erinnerungen mit demselben Umfang berücksichtigt.

Nächste Schritte