Erinnerungen abrufen

Auf dieser Seite wird beschrieben, wie Sie generierte und hochgeladene Erinnerungen aus der Memory Bank abrufen. Den gesamten Workflow zum Konfigurieren, Generieren und Verwenden von Memory Bank finden Sie in der Kurzanleitung zur REST API.

Hinweise

Bevor Sie die Schritte auf dieser Seite ausführen können, müssen Sie die Schritte unter Memory Bank einrichten ausführen.

Abrufvorgänge

Sie haben folgende Möglichkeiten, generierte Erinnerungen abzurufen:

Speicher abrufen: Mit dem Vertex AI SDK können Sie den vollständigen Inhalt eines einzelnen Speichers abrufen.
Erinnerungen auflisten: Erinnerungen mit dem Vertex AI SDK oder der Google Cloud Console auflisten.
Erinnerungen abrufen: Mit dem Vertex AI SDK können Sie Erinnerungen mithilfe des bereichsbasierten Abrufs von Erinnerungen abrufen. Sie können Erinnerungen über die Ähnlichkeitssuche oder alle Erinnerungen im Bereich abrufen.

Gemerkte Informationen abrufen

Verwenden Sie GetMemories, um den vollständigen Inhalt einer einzelnen Erinnerung abzurufen:

memory = client.agent_engines.memories.get(
    name="MEMORY_NAME")

Ersetzen Sie Folgendes:

MEMORY_NAME: Ein vollständig qualifizierter Name des Speichers im Format „projects/.../locations/.../reasoningEngines/.../memories...“.

Erinnerungen auflisten

Console

Bei bereitgestellten Agenten können Sie in der Google Cloud Console alle Erinnerungen auflisten, die mit Ihrer Agent Engine-Instanz verknüpft sind:

Rufen Sie in der Google Cloud Console die Seite Vertex AI Agent Engine auf.

Zu Agent Engine

Agent Engine-Instanzen, die Teil des ausgewählten Projekts sind, werden in der Liste angezeigt. Mit dem Feld Filtern können Sie die Liste nach der von Ihnen angegebenen Spalte filtern.
Klicken Sie auf den Namen Ihrer Agent Engine-Instanz.
Klicken Sie auf den Tab Erinnerungen. Eine Liste der Erinnerungen wird nach ID angezeigt.

Vertex AI SDK

Mit ListMemories können Sie alle Erinnerungen in Ihrem Erinnerungsspeicher abrufen.

pager = client.agent_engines.memories.list(name=agent_engine.api_resource.name)
for page in pager:
  print(page)

Erinnerungen mithilfe des bereichsbasierten Abrufs abrufen

Mit RetrieveMemories können Sie Erinnerungen für einen bestimmten Bereich abrufen. Es werden nur Erinnerungen zurückgegeben, die genau denselben Umfang (unabhängig von der Reihenfolge) wie die Abrufanfrage haben. So können Sie beispielsweise mit {"user_id": "123"} alle Erinnerungen abrufen, die auf einen bestimmten Nutzer beschränkt sind. Wenn keine Erinnerungen zurückgegeben werden, sind für den angegebenen Bereich keine Erinnerungen im Memory Bank vorhanden.

Der Umfang einer Erinnerung wird beim Generieren oder Erstellen der Erinnerung definiert und kann nicht geändert werden.

Mit RetrieveMemories können Sie die folgenden Vorgänge für einen bestimmten Bereich ausführen:

Erinnerungen mit der Ähnlichkeitssuche abrufen
Alle Erinnerungen abrufen

Erinnerungen mit der Ähnlichkeitssuche abrufen

Wenn Sie viele Erinnerungen für einen bestimmten Bereich haben, können Sie die Ähnlichkeitssuche verwenden, um nur die ähnlichsten Erinnerungen abzurufen. Dazu müssen Sie Parameter für die Ähnlichkeitssuche angeben. Memory Bank berücksichtigt bei der Ähnlichkeitssuche nur Erinnerungen, die genau denselben Umfang wie die Anfrage haben. Bei der Ähnlichkeitssuche werden die Einbettungsvektoren zwischen den Fakten der Erinnerungen und der Suchanfrage verglichen.

Die zurückgegebenen Erinnerungen werden von der ähnlichsten (kürzester euklidischer Abstand) zur am wenigsten ähnlichen (größter euklidischer Abstand) sortiert:

results = client.agent_engines.memories.retrieve(
    name=agent_engine.api_resource.name,
    scope=SCOPE,
    similarity_search_params={
        "search_query": "QUERY",
        # Optional. Defaults to 3.
        "top_k": 3
    }
)
# RetrieveMemories returns a pager. You can use `list` to retrieve all memories.
list(results)

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      },
      distance=0.5
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      },
      distance=0.7
    ),
]
"""

Ersetzen Sie Folgendes:

QUERY: Die Abfrage, für die die Ähnlichkeitssuche durchgeführt werden soll. Sie können beispielsweise den letzten Nutzerbeitrag der Unterhaltung als Anfrage verwenden.
SCOPE: Ein Dictionary, das den Umfang der Ähnlichkeitssuche darstellt. Beispiel: {"user_id": "123"}. Es werden nur Erinnerungen mit demselben Umfang wie die Anfrage berücksichtigt.

Alle gemerkten Informationen abrufen

Wenn keine Parameter für die Ähnlichkeitssuche angegeben werden, gibt RetrieveMemories alle Erinnerungen mit dem angegebenen Bereich zurück, unabhängig von ihrer Ähnlichkeit mit der aktuellen Unterhaltung.

results = client.agent_engines.memories.retrieve(
    name=agent_engine.api_resource.name,
    scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `list` to retrieve all pages' memories.
list(results)

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      }
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      }
    ),
]
"""

Ersetzen Sie Folgendes:

SCOPE: Ein Dictionary, das den Bereich für den Abruf darstellt. Beispiel: {"user_id": "123"}. Es werden nur Erinnerungen mit demselben Umfang wie die Anfrage zurückgegeben.

Erinnerungen filtern

In diesem Abschnitt wird beschrieben, wie Sie mit Filtern einschränken, welche Erinnerungen abgerufen werden. Sie können nach folgenden Kriterien filtern:

Metadaten mit dem Attribut filter_groups für den bereichsbasierten Abruf.
Systemfelder mit filter. Systemfelder umfassen die Erinnerungsfelder topics, create_time, update_time und fact.

Sowohl Metadaten- als auch Systemfeldfilter können in derselben Anfrage verwendet werden.

Nach Metadaten filtern

Beim Erstellen, Aktualisieren oder Generieren von Erinnerungen können Sie strukturierte Metadaten auf die gespeicherten Erinnerungen anwenden:

import datetime

from vertexai import types

metadata = {
    "my_string_key": types.MemoryMetadataValue(string_value="my_string_value"),
    "my_double_key": types.MemoryMetadataValue(double_value=123.456),
    "my_boolean_key": types.MemoryMetadataValue(bool_value=True),
    "my_timestamp_key": types.MemoryMetadataValue(
        timestamp_value=datetime.datetime(
            2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
        )
    ),
}

client.agent_engines.memories.create(
  ...,
  config={"metadata": metadata}
)

client.agent_engines.memories.update(
  ...,
  config={"metadata": metadata}
)

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

Sie können nach diesen Metadaten filtern, wenn Sie Erinnerungen mit dem Attribut filter_groups abrufen. Metadatenfilter werden in disjunktiver Normalform (DNF) definiert, einem logischen Ausdruck aus ODER- und UND-Verknüpfungen.

Mit der folgenden Anfrage werden beispielsweise Erinnerungen abgerufen, die die Metadaten ({"my_string_key": {"string_value": "my_value"}} UND {"my_double_key": {"double": 1.23}}) ODER {"my_string_key": {"string_value": "other"}} enthalten.

Wörterbuch

results = client.agent_engines.memories.retrieve(
  ...,
  config={
    # Each element of `filter_groups` is combined using OR logic.
    "filter_groups": [
      {
        # Each element of `filters` is combined using AND logic.
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "my_value"}
          },
          {
            "key": "my_double_key",
            "value": {"double_value": 1.23}
          }
        ]
      },
      {
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "other"}
          }
        ]
      }
    ]
  }
)

Klassenbasiert

from vertexai import types

results = client.agent_engines.memories.retrieve(
  ...,
  config=types.RetrieveAgentEngineMemoriesConfig(
    # Each element of `filter_groups` is combined using OR logic.
    filter_groups=[
      types.MemoryConjunctionFilter(
        # Each element of `filters` is combined using AND logic.
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="my_value")
          ),
          types.MemoryFilter(
            key="my_double_key",
            value=types.MemoryMetadataValue(double_value=1.23)
          )
        ]
      ),
      types.MemoryConjunctionFilter(
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="other")
          )
        ]
      )
    ]
  )
)

Nach Systemfeldern filtern

Sie können Systemfelder mit dem Attribut filter filtern. Es wird ein Stringwert in EBNF-Syntax erwartet. Systemfelder umfassen create_time, update_time, fact und topics.

Für die EBNF-Syntax gelten beim Erstellen eines Filterstrings die folgenden Anforderungen:

Wenn Sie Filter kombinieren möchten, verwenden Sie AND und OR.
Für Strings sollten doppelte Anführungszeichen " verwendet werden.
Für Datums-/Uhrzeitfelder (z. B. create_time) sollte entweder ein in doppelte Anführungszeichen gesetzter String verwendet werden, der das ISO 8601-Datums-/Uhrzeitformat darstellt, oder ein numerisches Feld, das Mikrosekunden seit der Unix-Epoche darstellt.

Mit dem folgenden Filter können Sie beispielsweise Erinnerungen abrufen, bei denen fact den Teilstring „allergies“ enthält und update_time nach dem 1. Januar 2026 liegt.

filter_string = 'fact=~".*allergies.*" AND update_time>="2026-01-01T00:00:00Z"''

client.agent_engines.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.agent_engines.memories.list(
  ...,
  config={"filter": filter_string}
)

Nach Themen filtern

Generierte Erinnerungen werden automatisch mit dem entsprechenden Erinnerungsthema gekennzeichnet.

Wenn Sie nach verwalteten Themen filtern möchten, verwenden Sie topics.managed_memory_topic als Feldname und den erwarteten ManagedTopicEnum als Wert, z. B. topics.managed_memory_topic: USER_PREFERENCES.

Wenn Sie nach benutzerdefinierten Themen filtern möchten, verwenden Sie topics.custom_memory_topic_label als Feldname und das Label des erwarteten Themas als Wert, z. B. topics.custom_memory_topic_label: custom-label.

filter_string = "topics.managed_memory_topic: USER_PREFERENCES " + \
"OR topics.custom_memory_topic_label: custom-label"

client.agent_engines.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.agent_engines.memories.list(
  ...,
  config={"filter": filter_string}
)

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

Hinweise

Abrufvorgänge

Gemerkte Informationen abrufen

Erinnerungen auflisten

Console

Vertex AI SDK

Erinnerungen mithilfe des bereichsbasierten Abrufs abrufen

Erinnerungen mit der Ähnlichkeitssuche abrufen

Alle gemerkten Informationen abrufen

Erinnerungen filtern

Nach Metadaten filtern

Wörterbuch

Klassenbasiert

Nach Systemfeldern filtern

Nach Themen filtern

Erinnerungen abrufen