Diese Seite wurde von der Cloud Translation API übersetzt.

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.

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

Arbeitsspeichergenerierung

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 vorhandenen Erinnerungen zusammengeführt werden. Wenn sich vorhandene Erinnerungen nicht mit den neuen Informationen überschneiden, wird eine neue Erinnerung erstellt.

Algorithmus zur Generierung von Erinnerungen

Mit Speicherüberarbeitungen können Sie die Zwischenschritte der Speichergenerierung untersuchen und sehen, wie sich ein Speicher über mehrere Anfragen hinweg ändert. Jede Überarbeitung enthält die Zwischenausgabe des Extraktionsschritts (extracted_memories) und des endgültigen Konsolidierungsschritts (fact) für jede Anfrage zur Generierung von Kontext.

list(client.agent_engines.memories.revisions.list(
  name="projects/.../locations/.../reasoningEngines/.../memories/.../revisions/..."))

"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This is the output of extraction for a single request.'
      ),
    ],
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This is my original fact.'
      ),
    ],
    ...
  )
]
"""

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 von 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 Speichern / Vergessen (EXPLICIT_INSTRUCTIONS): Informationen, die der Nutzer explizit vom Agenten speichern oder vergessen lassen möchte. 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 verwalteten Speichernutzung:

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.

Generierung von gemerkten Informationen auslösen

Sie können die Erinnerungserstellung 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.

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

Jeder generierte Kontext enthält die action, die für diesen Kontext ausgeführt wurde:

CREATED: Gibt an, dass eine neue Erinnerung hinzugefügt wurde, die ein neues Konzept darstellt, das nicht in vorhandenen Erinnerungen enthalten war.
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 Speicher können mit neuen Informationen aktualisiert werden oder gleich bleiben.
DELETED: Gibt an, dass das vorhandene Gedächtnis gelöscht wurde, weil seine Informationen im Widerspruch zu neuen Informationen standen, die aus dem Gespräch extrahiert wurden.

Bei CREATED- oder UPDATED-Gedächtnissen 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 abfragt, bis er abgeschlossen ist. Die Ausführung der Erinnerungserstellung 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
    }
)

Datenquellen

Es gibt mehrere Möglichkeiten, Quelldaten für die Speichergenerierung bereitzustellen:

Ereignisse direkt in der Nutzlast angeben:
Ereignisse mit Vertex AI Agent Engine-Sitzungen bereitstellen
Stellen Sie vorab extrahierte Fakten bereit, um sie mit vorhandenen Erinnerungen für denselben Bereich zusammenzuführen.

Wenn Sie Ereignisse direkt in der Nutzlast angeben oder Vertex AI Agent Engine-Sitzungen verwenden, werden Informationen aus der Unterhaltung extrahiert und mit vorhandenen Erinnerungen konsolidiert. Wenn Sie nur Informationen aus diesen Datenquellen extrahieren möchten, können Sie die Konsolidierung deaktivieren:

client.agent_engines.memories.generate(
    ...
    config={
        "disable_consolidation": True
    }
)

Ereignisse in der Nutzlast als Datenquelle verwenden

Verwenden Sie direct_contents_source, wenn Sie Erinnerungen anhand von Ereignissen erstellen möchten, die direkt in der Nutzlast enthalten sind. Aus diesen Ereignissen werden aussagekräftige Informationen extrahiert und mit vorhandenen Informationen für denselben Bereich zusammengeführt. Dieser Ansatz kann verwendet werden, wenn Sie einen anderen Sitzungsspeicher als Vertex AI Agent Engine Sessions verwenden.

Wörterbuch

Die Ereignisse sollten Content-Dictionaries enthalten.

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

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

Ersetzen Sie Folgendes:

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.

Klassenbasiert

Die Ereignisse sollten Content-Objekte enthalten.

from google import genai
import vertexai

events = [
  vertexai.types.GenerateMemoriesRequestDirectContentsSourceEvent(
    content=genai.types.Content(
      role="user",
      parts=[
        genai.types.Part.from_text(text="I work with LLM agents!")
      ]
    )
  )
]

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": events
    },
    # For example, `scope={"user_id": "123"}`.
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

Ersetzen Sie Folgendes:

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.

Vertex AI Agent Engine-Sitzungen als Datenquelle verwenden

Bei Agent Engine Sessions werden Sitzungsereignisse als Quellunterhaltung für die Speichergenerierung verwendet.

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. Dadurch wird die Verwendung von user_id der Sitzung als Bereich überschrieben.

Wörterbuch

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
      # For example, projects/.../locations/.../reasoningEngines/.../sessions/...
      "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 vollständig qualifizierte 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.

Klassenbasiert

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source=vertexai.types.GenerateMemoriesRequestVertexSessionSource(
      # For example, projects/.../locations/.../reasoningEngines/.../sessions/...
      session="SESSION_NAME"
  ),
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

Optional können Sie einen Zeitraum angeben, der festlegt, welche Ereignisse in der Sitzung berücksichtigt werden sollen. Wenn nichts angegeben ist, werden alle Ereignisse in der Sitzung berücksichtigt.

Wörterbuch

import datetime

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
      "session": "SESSION_NAME",
      # Extract memories from the last hour of events.
      "start_time": datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
      "end_time": datetime.datetime.now(tz=datetime.timezone.utc)
  },
  scope=SCOPE
)

Klassenbasiert

import datetime

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source=vertexai.types.GenerateMemoriesRequestVertexSessionSource(
      session="SESSION_NAME",
      # Extract memories from the last hour of events.
      start_time=datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
      end_time=datetime.datetime.now(tz=datetime.timezone.utc)
  ),
  scope=SCOPE
)

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, 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: Der vorab extrahierte Fakt, der 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.

Multimodale Eingabe verwenden

Sie können Erinnerungen aus multimodalen Eingaben extrahieren. Erinnerungen werden jedoch nur aus Text, Inline-Dateien und Dateidaten im Quellinhalt extrahiert. Alle anderen Inhalte, einschließlich Funktionsaufrufen und Antworten, werden beim Generieren 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 der Memory Bank als sinnvoll für zukünftige Interaktionen eingestuft wird, kann ein textueller Speicher erstellt werden, der aus der Eingabe extrahierte Informationen 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“.

Sie können beispielsweise ein Bild und Kontext für das Bild in der Nutzlast angeben:

Wörterbuch

with open(file_name, "rb") as f:
    inline_data = f.read()

events =  [
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "This is my dog"},
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": inline_data
          }
        },
        {
          "file_data": {
            "file_uri": "gs://cloud-samples-data/generative-ai/image/dog.jpg",
            "mime_type": "image/jpeg"
          }
        },
      ]
    }
  }
]

Klassenbasiert

from google import genai
import vertexai

with open(file_name, "rb") as f:
    inline_data = f.read()

events = [
  vertexai.types.GenerateMemoriesRequestDirectContentsSourceEvent(
    content=genai.types.Content(
      role="user",
      parts=[
        genai.types.Part.from_text(text="This is my dog"),
        genai.types.Part.from_bytes(
          data=inline_data,
          mime_type="image/jpeg",
        ),
        genai.types.Part.from_uri(
          file_uri="gs://cloud-samples-data/generative-ai/image/dog.jpg",
          mime_type="image/jpeg",
        )
      ]
    )
  )
]

Wenn Sie Vertex AI Agent Engine-Sitzungen als Datenquelle verwenden, werden die multimodalen Inhalte direkt in den Ereignissen der Sitzung bereitgestellt.

Erinnerungen erstellen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Arbeitsspeichergenerierung

Erinnerungsthemen

Wörterbuch

Klassenbasiert

Wörterbuch

Klassenbasiert

Wörterbuch

Klassenbasiert

Generierung von gemerkten Informationen auslösen

Erinnerungen im Hintergrund generieren

Datenquellen

Ereignisse in der Nutzlast als Datenquelle verwenden

Wörterbuch

Klassenbasiert

Vertex AI Agent Engine-Sitzungen als Datenquelle verwenden

Wörterbuch

Klassenbasiert

Wörterbuch

Klassenbasiert

Zusammenführen von vorab extrahierten Erinnerungen

Multimodale Eingabe verwenden

Wörterbuch

Klassenbasiert

Nächste Schritte

Erinnerungen erstellen