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.

Informazioni sulla generazione di ricordi

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.

I ricordi possono essere 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 da Memory Bank significativo per le interazioni future, potrebbe essere creata una memoria 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".

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.

Generazione dei ricordi

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

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.

Quando chiami GenerateMemories, devi fornire la conversazione di origine tramite Agent Engine Sessions o direttamente tramite il formato JSON:

Formato JSON

Se utilizzi un archivio delle sessioni diverso da Agent Engine Sessions, fornisci la conversazione di origine direttamente in formato JSON:

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

Sostituisci quanto segue:

  • EVENTS: elenco dei dizionari dei contenuti. Ad esempio:
[
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I'm work with LLM agents!"}
      ]
    }
  }
]
  • 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.

Sessioni del motore agente

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.

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

Sostituisci quanto segue:

  • SESSION_NAME: Il nome della sessione.

  • (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}.

GenerateMemories è un'operazione a lunga esecuzione. Una volta completata l'operazione, AgentEngineGenerateMemoriesOperation conterrà 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 un ricordo esistente è stato aggiornato, il che si verifica se il ricordo 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 di DELETED ricordi 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 e continuerà a eseguire il polling dell'operazione finché non viene completata. L'esecuzione della generazione di ricordi come operazione di blocco è utile quando vuoi ispezionare manualmente i ricordi generati o quando vuoi comunicare agli utenti finali quali ricordi sono stati generati.

Tuttavia, per gli agenti di produzione, in genere vuoi 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
    }
)

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.

Passaggi successivi