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.

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

• Ottieni ricordo: visualizza l'intero contenuto di un singolo ricordo.

• Elenca ricordi: elenca i ricordi

• Recupera ricordi: 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.

Configura l'ambiente

Prima di iniziare, devi configurare l'ambiente e l'istanza di Agent Engine. Questa sezione presuppone che tu abbia configurato un ambiente di sviluppo Python o che tu stia utilizzando un runtime con un ambiente di sviluppo Python (come Colab).

Importare librerie

Installa l'SDK Vertex AI:

  pip install google-cloud-aiplatform>=1.100.0

Configura un client SDK Vertex AI

  import vertexai

  client = vertexai.Client(
      project="PROJECT_ID",
      location="LOCATION",
  )

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: La tua regione. Per il Memory Bank di Vertex AI Agent Engine è supportato solo us-central1.

Configura l'istanza di Agent Engine

Per recuperare i ricordi da Memory Bank, devi prima disporre di un'istanza di Agent Engine. Puoi creare una nuova istanza o ottenerne una esistente. Le nuove istanze di Agent Engine sono vuote, a meno che tu non crei o generi ricordi.

agent_engine = client.agent_engines.create()

agent_engine = client.agent_engines.get(name="AGENT_ENGINE_NAME")

Recuperare un ricordo

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

memory = client.agent_engines.get_memory(name="MEMORY_NAME")

Sostituisci quanto segue:

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

Elenco dei ricordi

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

pager = client.agent_engines.list_memories(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 contiene 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 per similarità
• Recuperare tutti i ricordi

Recuperare i ricordi utilizzando la ricerca per similarità

Nei casi in cui hai molti ricordi per un ambito specifico, puoi utilizzare la ricerca per similarità per recuperare solo i ricordi più simili fornendo i parametri di ricerca per 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 per somiglianza 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.retrieve_memories(
    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 corrente.

results = client.agent_engines.retrieve_memories(
    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.