Recuperare i ricordi

Questa pagina descrive come recuperare i ricordi generati e caricati da Memory Bank. Per l'intero flusso di lavoro di configurazione, generazione e utilizzo di Memory Bank, consulta la guida rapida con l'API REST.

Prima di iniziare

Per completare i passaggi descritti in questa pagina, devi prima completare i passaggi descritti in Configurazione di Memory Bank.

Recupera operazioni

Per recuperare i ricordi generati, hai a disposizione le seguenti opzioni:

Ottieni memoria: ottieni l'intero contenuto di una singola memoria utilizzando l'SDK Vertex AI.
Elenca ricordi: elenca i ricordi utilizzando l'SDK Vertex AI o la console Google Cloud .
Recupera ricordi: utilizzando l'SDK Vertex AI, recupera i ricordi utilizzando il recupero dei ricordi basato sull'ambito. Recupera i ricordi utilizzando la ricerca per somiglianza o tutti i ricordi nell'ambito.

Recuperare un ricordo

Utilizza GetMemories per ottenere l'intero contenuto di un singolo ricordo:

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

Sostituisci quanto segue:

MEMORY_NAME: un nome di memoria completo nel formato "projects/.../locations/.../reasoningEngines/.../memories...".

Elenco dei ricordi

Console

Per gli agenti di cui è stato eseguito il deployment, puoi utilizzare la console Google Cloud per elencare tutte le memorie associate alla tua istanza di Agent Engine:

Nella console Google Cloud , vai alla pagina Vertex AI Agent Engine.

Vai ad Agent Engine

Nell'elenco vengono visualizzate le istanze di Agent Engine che fanno parte del progetto selezionato. Puoi utilizzare il campo Filtra per filtrare l'elenco in base alla colonna specificata.
Fai clic sul nome dell'istanza di Agent Engine.
Fai clic sulla scheda Ricordi. Viene visualizzato un elenco di ricordi per ID.

SDK Vertex AI

Utilizza ListMemories per recuperare tutti i ricordi nel tuo Memory Bank.

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

Recuperare i ricordi utilizzando il recupero basato sull'ambito

Puoi utilizzare RetrieveMemories per recuperare i ricordi per un ambito specifico. Vengono restituite solo le memorie che hanno esattamente lo stesso ambito (indipendentemente dall'ordine) della richiesta di recupero. Ad esempio, puoi recuperare tutti i ricordi associati a un determinato utente utilizzando {"user_id": "123"}. Se non vengono restituiti ricordi, la banca dati dei ricordi non ne ha per l'ambito fornito.

L'ambito di un ricordo viene definito quando il ricordo viene generato o creato ed è immutabile.

Puoi utilizzare RetrieveMemories per eseguire le seguenti operazioni per un ambito specifico:

Recuperare i ricordi utilizzando la ricerca di similarità
Recuperare tutti i ricordi

Recuperare i ricordi utilizzando la ricerca di similarità

Nei casi in cui hai molti ricordi per un ambito specifico, puoi utilizzare la ricerca di similarità per recuperare solo i ricordi più simili fornendo i parametri di ricerca di similarità. Memory Bank prende in considerazione solo i ricordi che hanno esattamente lo stesso ambito della richiesta quando esegue la ricerca di similarità. La ricerca di somiglianze confronta i vettori di embedding tra i fatti dei ricordi e la query di ricerca della richiesta.

I ricordi restituiti sono ordinati dal più simile (distanza euclidea più breve) al meno simile (distanza euclidea più lunga):

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

Sostituisci quanto segue:

QUERY: La query per cui eseguire la ricerca di similarità. Ad esempio, puoi utilizzare l'ultimo turno della conversazione come query.
SCOPE: un dizionario che rappresenta l'ambito della ricerca di similarità. Ad esempio, {"user_id": "123"}. Vengono prese in considerazione solo le memorie con lo stesso ambito della richiesta.

Recuperare tutti i ricordi

Se non vengono forniti parametri di ricerca per similarità, RetrieveMemories restituisce tutti i ricordi che hanno l'ambito fornito, indipendentemente dalla loro somiglianza con la conversazione attuale.

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

Sostituisci quanto segue:

SCOPE: un dizionario che rappresenta l'ambito del recupero. Ad esempio, {"user_id": "123"}. Vengono restituiti solo i ricordi con lo stesso ambito della richiesta.

Filtrare i ricordi

Questa sezione descrive come utilizzare i filtri per limitare il recupero dei ricordi. Puoi filtrare in base a:

Metadati che utilizzano l'attributo filter_groups per il recupero basato sull'ambito.
Campi di sistema che utilizzano filter. I campi di sistema includono topics, create_time, update_time e fact dei ricordi.

Il filtro dei metadati e dei campi di sistema può essere utilizzato nella stessa richiesta.

Filtrare per metadati

Quando crei, aggiorni o generi ricordi, puoi applicare metadati strutturati ai ricordi archiviati:

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

Puoi filtrare in base a questi metadati quando recuperi i ricordi utilizzando l'attributo filter_groups. I filtri dei metadati sono definiti in forma normale disgiuntiva (DNF), che è un'espressione logica di OR di AND.

Ad esempio, la seguente richiesta recupererà i ricordi che includono i metadati ({"my_string_key": {"string_value": "my_value"}} AND {"my_double_key": {"double": 1.23}}) OR {"my_string_key": {"string_value": "other"}}.

Dizionario

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

Basato sulla classe

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

Filtrare in base ai campi di sistema

Puoi filtrare in base ai campi di sistema utilizzando l'attributo filter, che prevede un valore stringa che utilizza la sintassi EBNF. I campi di sistema includono create_time, update_time, fact e topics.

La sintassi EBNF presenta i seguenti requisiti per la creazione di una stringa di filtro:

Per combinare i filtri, utilizza AND e OR.
La stringa deve utilizzare virgolette doppie ".
I campi di data e ora (come create_time) devono utilizzare una stringa tra virgolette doppie che rappresenta la data e l'ora ISO 8601 o un campo numerico che rappresenta i microsecondi dall'epoca Unix.

Ad esempio, il seguente filtro può essere utilizzato per recuperare i ricordi in cui fact include la sottostringa "allergie" e update_time è successivo al 1° gennaio 2026.

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

Filtrare per argomenti

I ricordi generati vengono etichettati automaticamente con l'argomento del ricordo pertinente.

Per filtrare in base agli argomenti gestiti, utilizza topics.managed_memory_topic come nome del campo e il valore ManagedTopicEnum previsto, ad esempio topics.managed_memory_topic: USER_PREFERENCES.

Per filtrare in base agli argomenti personalizzati, utilizza topics.custom_memory_topic_label come nome del campo e l'etichetta dell'argomento previsto come valore, ad esempio 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}
)

Recuperare i ricordi Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Recupera operazioni

Recuperare un ricordo

Elenco dei ricordi

Console

SDK Vertex AI

Recuperare i ricordi utilizzando il recupero basato sull'ambito

Recuperare i ricordi utilizzando la ricerca di similarità

Recuperare tutti i ricordi

Filtrare i ricordi

Filtrare per metadati

Dizionario

Basato sulla classe

Filtrare in base ai campi di sistema

Filtrare per argomenti

Recuperare i ricordi