Esta página foi traduzida pela API Cloud Translation.

Revisões de memórias

Esta página descreve como os recursos de revisão de memória são criados e geridos para o banco de memória do Vertex AI Agent Engine.

Ciclo de vida de uma memória e das respetivas revisões

Origens de dados e revisões da memória

As memórias podem ser criadas, atualizadas ou eliminadas diretamente (através de CreateMemory, UpdateMemory ou DeleteMemory, respetivamente) ou dinamicamente (através de GenerateMemories). Os recursos de revisão de memórias fornecem um histórico de versões completo de um recurso de memória em todas as operações de mutação. É guardada automaticamente uma nova revisão imutável sempre que a memória é criada ou modificada. Isto dá-lhe transparência sobre a forma como uma memória evoluiu e (para a geração de memórias) que informações específicas foram extraídas e consolidadas em cada passo.

Cada recurso de memória tem um ou mais recursos de revisão de memória filho associados:

Os recursos Memory refletem sempre o estado atual e consolidado das informações. Uma única memória pode refletir dados derivados de vários pedidos e origens de dados.

Memory(
    create_time=datetime.datetime(...),
    fact='This is my current memory content after consolidation',
    name='projects/.../locations/.../reasoningEngines/../memories/...',
    scope={
      'my_scope_key': 'my_scope_value'
    },
    topics=[
      MemoryTopicId(
        managed_memory_topic=<ManagedTopicEnum.USER_PERSONAL_INFO: 'USER_PERSONAL_INFO'>
      ),
    ],
    update_time=datetime.datetime(...)
)

Os recursos MemoryRevisions representam os estados históricos da memória principal. Cada revisão é uma imagem da memória num evento de mutação. Se uma memória foi alterada através de GenerateMemories, a revisão também inclui as informações que foram extraídas da origem de dados (extracted_memories) antes de serem consolidadas com o conteúdo existente da memória.

MemoryRevision(
    create_time=datetime.datetime(...),
    expire_time=datetime.datetime(...),
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This information was extracted from my data source'
      ),
    ],
    fact='This is my current memory content after consolidation',
    name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...'
)

As revisões de memórias estão ativadas por predefinição. Para desativar as revisões de memórias, consulte o artigo Desativar revisões de memórias.

Criação de memórias

As memórias podem ser criadas diretamente através de CreateMemory ou dinamicamente através de GenerateMemories. Com a geração de memórias, é criada uma memória se não existirem memórias que abranjam informações semelhantes para o mesmo âmbito:

# Direct creation using CreateMemory
client.agent_engines.memories.create(name=agent_engine_name, ...)

# Dynamic creation using GenerateMemory
client.agent_engines.memories.generate_memories(name=agent_engine_name, ...)

Quando é criada uma memória, são criados um recurso Memory único e um recurso MemoryRevision filho:

client.agent_engines.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my original fact.",
  ...
)
"""

list(client.agent_engines.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

Atualização da memória

As memórias podem ser atualizadas diretamente através de UpdateMemory ou dinamicamente através de GenerateMemories. Com a geração de memórias, as memórias são atualizadas dinamicamente quando o processo de consolidação decide que as novas informações são duplicadas, complementares ou contraditórias a todas as memórias existentes para o mesmo âmbito.

# Direct update using UpdateMemory
client.agent_engines.memories.update(name=memory_name, ...)

# Dynamic update using GenerateMemories
client.agent_engines.memories.generate_memories(name=agent_engine_name, ...)

Quando uma memória é atualizada, o recurso Memory existente é atualizado e é criado um novo recurso filho MemoryRevision.

client.agent_engines.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my updated fact.",
  ...
)
"""

list(client.agent_engines.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

Eliminação de memórias

As memórias podem ser criadas diretamente com DeleteMemory ou dinamicamente com GenerateMemories. Com a geração de memória, as memórias são eliminadas dinamicamente quando o processo de consolidação decide que as novas informações invalidam as informações existentes para o mesmo âmbito.

# Direct deletion using UpdateMemory
client.agent_engines.memories.delete(name=memory_name, ...)

# Dynamic delete using GenerateMemories
client.agent_engines.memories.generate_memories(name=agent_engine_name, ...)

Quando uma memória é eliminada, o recurso Memory existente é eliminado e é criado um novo recurso filho MemoryRevision. O fact na revisão de memória mais recente está vazio porque reflete uma mutação de eliminação.

client.agent_engines.memories.get(name=memory_name)
"""
404 Not Found.
"""

list(client.agent_engines.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/789",
    fact="",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

As revisões das memórias da criança só estão acessíveis até 48 horas após a eliminação da memória principal. Durante este período de recuperação, pode continuar a inspecionar as revisões da memória e recuperá-la revertendo-a para uma revisão anterior.

Operações de revisão da memória

Esta secção descreve como pode inspecionar revisões de memória e reverter uma memória para uma revisão anterior.

Liste as revisões

Use ListMemoryRevisions para devolver todas as revisões de memória pertencentes a uma memória.

list(client.agent_engines.memories.revisions.list(name=MEMORY_NAME))

Substitua o seguinte:

MEMORY_NAME: nome do recurso da memória no formato: projects/.../locations/.../reasoningEngines/.../memories/...

Ao gerar memórias, pode fornecer etiquetas de revisão que são aplicadas às revisões afiliadas. As etiquetas são pares de chave-valor arbitrários. Por exemplo, pode etiquetar revisões com um ID da origem de dados usada para gerar a memória e, em seguida, filtrar revisões por esta etiqueta:

response = client.agent_engines.memories.generate(
    ...,
    config={
        "revision_labels": {
            "data_source": "321"
        }
    }
)

list(client.agent_engines.memories.revisions.list(
    name=MEMORY_NAME,
    config={
      "filter": "labels.data_source=\"321\""
    }
))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    labels={
      "data_source": "123"
    }
    ...
  )
]
"""

Receba uma revisão

Use GetMemoryRevision para obter uma revisão de memória individual.

client.agent_engines.memories.revisions.get(name=MEMORY_REVISION_NAME)

Substitua o seguinte:

MEMORY_REVISION_NAME: nome do recurso da revisão de memória a obter no formato: projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...

Reverta uma memória

Use RollbackMemory para reverter uma memória para uma revisão anterior.

client.agent_engines.memories.rollback(
    name=name=MEMORY_NAME,
    target_revision_id=REVISION_ID
)

Substitua o seguinte:

MEMORY_NAME: nome do recurso da memória a atualizar no formato: projects/.../locations/.../reasoningEngines/.../memories/...
REVISION_ID: ID da revisão para a qual deve ser revertida. Este é o último segmento do nome do recurso de revisão de memória, como 789 em projects/MyProject/locations/us-central1/reasoningEngines/123/memories/456/revisions/789.

Se quiser anular uma alteração a uma memória feita pelo GenerateMemories, reverta a memória para a revisão anterior à alteração. A resposta de geração de memórias inclui uma referência à revisão anterior (previous_revision) para cada memória atualizada ou eliminada:

operation = client.agent_engines.memories.generate(
  ...
)

# Rollback the first generated memory to the previous revision.
client.agent_engines.memories.rollback(
    name=operation.response.generated_memories[0].memory.name,
    target_revision_id=operation.response.generated_memories[0].previous_revision
)

Desativar revisões de memória

As revisões de memórias estão ativadas por predefinição. Pode desativar as revisões de memória para todos os pedidos à sua instância do banco de memória ou para cada pedido individual. Se as revisões da memória estiverem desativadas, não é criada uma revisão da memória quando a memória é alterada.

Pode desativar as revisões de memória para todos os pedidos à sua instância do banco de memória quando configurar a instância:

client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": {
        "disable_memory_revisions": True
      }
    }
  }
)

Pode desativar as revisões de memória ao nível do pedido quando o envia:

Gere

client.agent_engines.memories.generate(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

Criar

client.agent_engines.memories.create(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

Atualizar

client.agent_engines.memories.update(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

Expiração da revisão

As revisões de memórias não são mantidas para sempre. Tem de definir a validade das revisões ou usar a validade predefinida. O tempo de vida (TTL) predefinido é de 365 dias. Pode configurar a expiração para todos os pedidos à sua instância do Memory Bank ou para cada pedido individual. Quando uma revisão de uma memória expira, não está disponível para inspeção nem reversões.

Pode configurar o TTL para todos os pedidos à sua instância do Memory Bank quando configurar a instância:

client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": {
        "ttl_config": {
          # Persist memory revisions for 30 days after they're created.
          "revision_ttl": f"{30 * 60 * 60 * 24}s"
        }
      }
    }
  }
)

Para configurar o TTL para cada revisão de memória ao nível do pedido, inclua revision_expire_time ou revision_ttl no seu pedido:

TTL

config = {
    # Persist memory revisions for 30 days after they're created.
    "revision_ttl": f"{30 * 60 * 60 * 24}s"
}

client.agent_engines.memories.create(
  ...,
  config=config
)

client.agent_engines.memories.update(
  ...,
  config=config
)

client.agent_engines.memories.generate(
  ...,
  config=config
)

Expiração

import datetime

config = {
    "revision_expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(weeks=3)
}

client.agent_engines.memories.create(
  ...,
  config=config
)

client.agent_engines.memories.update(
  ...,
  config=config
)

client.agent_engines.memories.generate(
  ...,
  config=config
)

Revisões de memórias Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Ciclo de vida de uma memória e das respetivas revisões

Criação de memórias

Atualização da memória

Eliminação de memórias

Operações de revisão da memória

Liste as revisões

Receba uma revisão

Reverta uma memória

Desativar revisões de memória

Gere

Criar

Atualizar

Expiração da revisão

TTL

Expiração

Revisões de memórias