Generare ricordi

Memory Bank ti consente di creare ricordi a lungo termine dalle conversazioni tra l'utente e il tuo agente. Questa pagina descrive il funzionamento della generazione dei ricordi, come puoi personalizzare la modalità di estrazione dei ricordi e come attivare la generazione dei ricordi.

Per completare i passaggi illustrati in questa guida, devi prima seguire i passaggi descritti in Configurazione di Memory Bank.

Informazioni sulla generazione di memoria

Memory Bank estrae i ricordi dai dati di origine e li seleziona automaticamente per una raccolta specifica (definita da un scope) aggiungendoli, aggiornandoli e rimuovendoli nel tempo.

Quando attivi la generazione di ricordi, Memory Bank esegue le seguenti operazioni:

  • Estrazione: estrae informazioni sull'utente dalle sue conversazioni con l'agente. Verranno conservate solo le informazioni che corrispondono ad almeno uno degli argomenti dei ricordi� della tua istanza.

  • Consolidamento: identifica se i ricordi esistenti con lo stesso ambito devono essere eliminati o aggiornati in base alle informazioni estratte. Memory Bank verifica che i nuovi ricordi non siano duplicati o contraddittori prima di unirli a quelli esistenti. Se i ricordi esistenti non si sovrappongono alle nuove informazioni, verrà creato un nuovo ricordo.

Argomenti dei ricordi

Gli "argomenti dei ricordi" identificano le informazioni che Memory Bank considera significative e che devono quindi essere mantenute come ricordi generati. Memory Bank supporta due tipi di argomenti di memoria:

  • Argomenti gestiti: l'etichetta e le istruzioni sono definite da Memory Bank. Devi solo fornire il nome dell'argomento gestito. Ad esempio:

    Dizionario

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

    Basato sulla classe

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

  • Argomenti personalizzati: l'etichetta e le istruzioni vengono definite da te durante la configurazione dell'istanza di Memory Bank. Verranno utilizzati nel prompt per il passaggio di estrazione di Memory Bank. Ad esempio:

    Dizionario

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

    Basato sulla classe

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

    Quando utilizzi argomenti personalizzati, ti consigliamo di fornire anche esempi few-shot per mostrare come estrarre i ricordi dalla conversazione.

Per impostazione predefinita, Memory Bank conserva tutti gli argomenti gestiti seguenti:

  • Informazioni personali (USER_PERSONAL_INFO): informazioni personali significative sull'utente, come nomi, relazioni, hobby e date importanti. Ad esempio, "Lavoro in Google" o "Il mio anniversario di matrimonio è il 31 dicembre".
  • Preferenze degli utenti (USER_PREFERENCES): Mi piace, Non mi piace, stili o motivi preferiti dichiarati o impliciti. Ad esempio, "Preferisco il posto centrale".
  • Eventi chiave della conversazione e risultati delle attività (KEY_CONVERSATION_DETAILS): traguardi o conclusioni importanti all'interno del dialogo. Ad esempio, "Ho prenotato biglietti aerei per un viaggio di andata e ritorno tra JFK e SFO. Parto il 1° giugno 2025 e torno il 7 giugno 2025."
  • Istruzioni esplicite per ricordare / dimenticare (EXPLICIT_INSTRUCTIONS): informazioni che l'utente chiede esplicitamente all'agente di ricordare o dimenticare. Ad esempio, se l'utente dice "Ricorda che uso principalmente Python", Memory Bank genera un ricordo come "Uso principalmente Python".

Ciò equivale a utilizzare il seguente insieme di argomenti di memoria gestita:

Dizionario

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

Basato sulla classe

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

Se vuoi personalizzare gli argomenti che Memory Bank conserva, imposta gli argomenti dei ricordi nella configurazione della personalizzazione durante la configurazione di Memory Bank.

Attivazione della generazione di memoria

Puoi attivare la generazione di ricordi utilizzando GenerateMemories alla fine di una sessione o a intervalli regolari all'interno di una sessione. La generazione di ricordi estrae il contesto chiave dalle conversazioni di origine e lo combina con i ricordi esistenti per lo stesso ambito. Ad esempio, puoi creare ricordi a livello di sessione utilizzando un ambito come {"user_id": "123", "session_id": "456"}. I ricordi con lo stesso ambito possono essere consolidati e recuperati insieme.

GenerateMemories è un'operazione a lunga esecuzione. Una volta completata l'operazione, AgentEngineGenerateMemoriesOperation contiene un elenco di ricordi generati, se presenti:

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

Ogni ricordo generato include l'action eseguita su quel ricordo:

  • CREATED: indica che è stato aggiunto un nuovo ricordo, che rappresenta un concetto nuovo non acquisito dai ricordi esistenti.
  • UPDATED: indica che una memoria esistente è stata aggiornata, il che si verifica se la memoria copriva concetti simili alle informazioni appena estratte. Il fatto della memoria potrebbe essere aggiornato con nuove informazioni o rimanere invariato.
  • DELETED: indica che la memoria esistente è stata eliminata perché le sue informazioni erano in contraddizione con le nuove informazioni estratte dalla conversazione.

Per i ricordi CREATED o UPDATED, puoi utilizzare GetMemories per recuperare l'intero contenuto del ricordo. Il recupero dei ricordi di DELETED genera un errore 404.

Generazione di ricordi in background

GenerateMemories è un'operazione a lunga esecuzione. Per impostazione predefinita, client.agent_engines.generate_memories è una funzione di blocco che esegue il polling dell'operazione fino al completamento. L'esecuzione della generazione di ricordi come operazione di blocco è utile quando vuoi ispezionare manualmente i ricordi generati o comunicare agli utenti finali quali ricordi sono stati generati.

Tuttavia, per gli agenti di produzione, in genere è preferibile eseguire la generazione di memoria in background come processo asincrono. Nella maggior parte dei casi, il client non ha bisogno di utilizzare l'output per l'esecuzione corrente, quindi non è necessario incorrere in un'ulteriore latenza in attesa di una risposta. Se vuoi che la generazione della memoria venga eseguita in background, imposta wait_for_completion su False:

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

Origini dati

Esistono diversi modi per fornire i dati di origine per la generazione di ricordi:

Quando fornisci eventi direttamente nel payload o utilizzi le sessioni di Vertex AI Agent Engine, le informazioni vengono estratte dalla conversazione e consolidate con le memorie esistenti. Se vuoi estrarre informazioni solo da queste origini dati, puoi disattivare il consolidamento:

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

Utilizzo degli eventi nel payload come origine dati

Utilizza direct_contents_source quando vuoi generare ricordi utilizzando gli eventi forniti direttamente nel payload. Da questi eventi vengono estratte informazioni significative, che vengono consolidate con quelle esistenti per lo stesso ambito. Questo approccio può essere utilizzato se utilizzi un archivio delle sessioni diverso da Vertex AI Agent Engine Sessions.

Dizionario

Gli eventi devono includere dizionari Content.

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

Sostituisci quanto segue:

  • SCOPE: Un dizionario che rappresenta l'ambito dei ricordi generati. Ad esempio, {"session_id": "MY_SESSION"}. Per il consolidamento vengono presi in considerazione solo i ricordi con lo stesso ambito.

Basato sulla classe

Gli eventi devono includere oggetti Content.

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

Sostituisci quanto segue:

  • SCOPE: Un dizionario che rappresenta l'ambito dei ricordi generati. Ad esempio, {"session_id": "MY_SESSION"}. Per il consolidamento vengono presi in considerazione solo i ricordi con lo stesso ambito.

Utilizzo delle sessioni di Vertex AI Agent Engine come origine dati

Con le sessioni di Agent Engine, Memory Bank utilizza gli eventi di sessione come conversazione di origine per la generazione della memoria.

Per definire l'ambito dei ricordi generati, Memory Bank estrae e utilizza per impostazione predefinita l'ID utente dalla sessione. Ad esempio, l'ambito dei ricordi viene memorizzato come {"user_id": "123"} se il user_id della sessione è "123". Puoi anche fornire un scope direttamente, che sostituisce l'utilizzo di user_id della sessione come ambito.

Dizionario

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

Sostituisci quanto segue:

  • SESSION_NAME: il nome della sessione completo.

  • (Facoltativo) SCOPE: un dizionario che rappresenta l'ambito dei ricordi generati. Ad esempio, {"session_id": "MY_SESSION"}. Per il consolidamento vengono presi in considerazione solo i ricordi con lo stesso ambito. Se non viene fornito, viene utilizzato {"user_id": session.user_id}.

Basato sulla classe

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

Se vuoi, puoi fornire un intervallo di tempo che indichi quali eventi della sessione devono essere inclusi. Se non viene fornito alcun valore, vengono inclusi tutti gli eventi nella sessione.

Dizionario

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
)

Basato sulla classe

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
)

Consolidamento dei ricordi preestratti

In alternativa all'utilizzo della procedura di estrazione automatica di Memory Bank, puoi fornire direttamente i ricordi preestratti. I ricordi di origine diretta verranno consolidati con i ricordi esistenti per lo stesso ambito. Può essere utile quando vuoi che il tuo agente o un operatore umano sia responsabile dell'estrazione dei ricordi, ma vuoi comunque sfruttare il consolidamento di Memory Bank per assicurarti che non ci siano ricordi duplicati o contraddittori.

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

Sostituisci quanto segue:

  • FACT: Il fatto pre-estratto che deve essere consolidato con i ricordi esistenti. Puoi fornire fino a 5 fatti preestratti in un elenco come il seguente:

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

  • SCOPE: Un dizionario che rappresenta l'ambito dei ricordi generati. Ad esempio, {"session_id": "MY_SESSION"}. Per il consolidamento vengono presi in considerazione solo i ricordi con lo stesso ambito.

Utilizzo dell'input multimodale

Puoi estrarre ricordi da input multimodali. Tuttavia, i ricordi vengono estratti solo da testo, file incorporati e dati dei file nei contenuti di origine. Tutti gli altri contenuti, incluse chiamate e risposte alle funzioni, vengono ignorati durante la generazione dei ricordi.

I ricordi possono essere estratti da immagini, video e audio forniti dall'utente. Se il contesto fornito dall'input multimodale viene giudicato significativo da Memory Bank per le interazioni future, potrebbe essere creato un ricordo testuale che includa le informazioni estratte dall'input. Ad esempio, se l'utente fornisce un'immagine di un golden retriever con il testo "Questo è il mio cane", Memory Bank genera un ricordo come "Il mio cane è un golden retriever".

Ad esempio, puoi fornire un'immagine e il contesto dell'immagine nel payload:

Dizionario

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

Basato sulla classe

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

Quando utilizzi le sessioni di Vertex AI Agent Engine come origine dati, i contenuti multimodali vengono forniti direttamente negli eventi della sessione.

Passaggi successivi