借助记忆库,您可以根据用户与智能体之间的对话构建长期记忆。本页介绍了记忆生成功能的运作方式、如何自定义记忆提取方式,以及如何触发记忆生成。
了解记忆生成功能
记忆库从源数据中提取记忆,并通过随时间推移添加、更新和移除记忆,为特定记忆集合(由 scope
定义)自行整理记忆。
当您触发记忆生成时,记忆库会执行以下操作:
提取:从用户与代理的对话中提取有关用户的信息。系统只会保留与实例的至少一个内存主题匹配的信息。
整合:根据提取的信息,确定是否应删除或更新具有相同范围的现有记忆。记忆库会在将新记忆与现有记忆合并之前,检查新记忆是否重复或矛盾。如果现有记忆与新信息不重叠,系统会创建新的记忆。
记忆只能从源内容中的文本、内嵌文件和文件数据中提取。生成记忆时,系统会忽略所有其他内容,包括函数调用和响应。
记忆可以从用户提供的图片、视频和音频中提取。如果记忆库认为多模态输入提供的情境对未来的互动有意义,则可能会创建文本记忆,其中包含从输入中提取的信息。例如,如果用户提供了一张金毛寻回犬的图片,并附上“这是我的狗”的文字,记忆库就会生成“我的狗是金毛寻回犬”之类的记忆。
回忆主题
“记忆主题”用于标识记忆库认为有意义的信息,因此应将其作为生成的记忆进行保留。记忆库支持两种类型的记忆主题:
受管理的知识主题:标签和说明由记忆库定义。您只需提供受管理的广告主题的名称。例如:
字典
memory_topic = { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } }
基于类的
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 ) )
自定义主题:在设置记忆库实例时,您可以自行定义标签和说明。它们将用于记忆库提取步骤的提示中。例如:
字典
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.""" } }
基于类的
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.""" ) )
使用自定义主题时,建议同时提供少样本示例,以演示如何从对话中提取记忆。
默认情况下,记忆库会保留以下所有受管理的 topic:
- 个人信息 (
USER_PERSONAL_INFO
):与用户相关的重要个人信息,例如姓名、关系、爱好和重要日期。例如,“我在 Google 工作”或“我的结婚纪念日是 12 月 31 日”。 - 用户偏好 (
USER_PREFERENCES
):明确或隐含的喜好、厌恶、偏好的风格或图案。例如,“我喜欢中间的座位。” - 关键对话事件和任务结果 (
KEY_CONVERSATION_DETAILS
):对话中的重要里程碑或结论。例如,“我预订了从 JFK 机场往返 SFO 机场的机票。我将于 2025 年 6 月 1 日出发,并于 2025 年 6 月 7 日返回。” - 明确的记忆 / 忘记指令 (
EXPLICIT_INSTRUCTIONS
):用户明确要求智能体记住或忘记的信息。例如,如果用户说“记住,我主要使用 Python”,记忆库会生成一条记忆,例如“我主要使用 Python”。
这相当于使用以下一组受管理的内存主题:
字典
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"}},
]
基于类的
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)),
]
如果您想自定义记忆库持久保留哪些主题,请在设置记忆库时,在自定义配置中设置记忆主题。
生成回忆
如需完成本指南中演示的步骤,您必须先按照设置 Memory Bank 中的步骤操作。
您可以在会话结束时或在会话期间定期使用 GenerateMemories
触发记忆生成。记忆生成功能会从源对话中提取关键上下文,并将其与同一范围内的现有记忆相结合。例如,您可以使用 {"user_id": "123", "session_id": "456"}
等范围创建会话级记忆。具有相同范围的记忆可以合并并一起检索。
调用 GenerateMemories
时,您必须通过 Agent Engine 会话或直接通过 JSON 格式提供源对话:
JSON 格式
如果您使用的会话存储方式与 Agent Engine 会话不同,请直接以 JSON 格式提供源对话:
client.agent_engines.generate_memories(
name=agent_engine.api_resource.name,
direct_contents_source={
"events": EVENTS
},
scope=SCOPE,
config={
"wait_for_completion": True
}
)
替换以下内容:
- EVENTS:内容字典列表。例如:
[
{
"content": {
"role": "user",
"parts": [
{"text": "I'm work with LLM agents!"}
]
}
}
]
- SCOPE:一个字典,用于表示生成的记忆的范围。例如
{"session_id": "MY_SESSION"}
。只有范围相同的记忆才会被考虑用于整合。
Agent Engine 会话
借助 Agent Engine 会话,记忆库可使用会话事件作为记忆生成的源对话。
为了确定生成的记忆的范围,记忆库默认会从会话中提取并使用用户 ID。例如,如果会话的 user_id
为“123”,则将记忆的范围存储为 {"user_id": "123"}
。您还可以直接提供 scope
,这会替换使用会话的 user_id
作为范围。
client.agent_engines.generate_memories(
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
}
)
替换以下内容:
SESSION_NAME:会话名称。
(可选)SCOPE:一个字典,用于表示生成的记忆的范围。例如
{"session_id": "MY_SESSION"}
。只有范围相同的记忆才会被考虑用于整合。如果未提供,则系统会使用{"user_id": session.user_id}
。
GenerateMemories
是一项长时间运行的操作。操作完成后,AgentEngineGenerateMemoriesOperation
将包含生成的记忆列表(如果有):
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",
),
]
)
)
每个生成的记忆都包含对该记忆执行的 action
:
CREATED
:表示添加了新的记忆,代表现有记忆未捕获的新概念。UPDATED
:表示现有记忆已更新,如果记忆涵盖的概念与新提取的信息类似,就会发生这种情况。记忆中的事实可能会根据新信息进行更新,也可能保持不变。DELETED
:表示系统已删除现有记忆,因为其信息与从对话中提取的新信息相矛盾。
对于 CREATED
或 UPDATED
记忆,您可以使用 GetMemories
检索记忆的完整内容。检索 DELETED
记忆会导致 404 错误。
正在后台生成回忆
GenerateMemories
是一项长时间运行的操作。默认情况下,client.agent_engines.generate_memories
是一个阻塞函数,会继续轮询操作,直到操作完成。如果您想手动检查生成的记忆,或者想通知最终用户生成了哪些记忆,那么将记忆生成作为阻塞操作执行会很有帮助。
不过,对于生产代理,您通常希望在后台以异步进程运行记忆生成。在大多数情况下,客户端不需要使用当前运行的输出,因此无需等待响应而产生额外的延迟。如果您希望内存生成在后台执行,请将 wait_for_completion
设置为 False
:
client.agent_engines.generate_memories(
...,
config={
"wait_for_completion": False
}
)
整合预提取的回忆
除了使用记忆库的自动提取流程之外,您还可以直接提供预提取的记忆。直接来源回忆将与同一范围内的现有回忆合并。如果您希望代理或人工在环负责提取记忆,但仍想利用记忆库的整合功能来确保没有重复或矛盾的记忆,那么此功能会非常有用。
client.agent_engines.generate_memories(
name=agent_engine.api_resource.name,
direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
scope=SCOPE
)
替换以下内容:
FACT:应与现有记忆整合的预提取事实。您可以在列表中提供最多 5 个预提取的事实,如下所示:
{"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
SCOPE:一个字典,用于表示生成的记忆的范围。例如
{"session_id": "MY_SESSION"}
。只有范围相同的记忆才会被考虑用于整合。