本文档介绍了如何使用 Agent Platform SDK 执行这些提取操作。
如果您使用智能体开发套件 (ADK)，智能体可以自动为您编排这些调用。请参阅 ADK 快速入门。
准备工作
如需完成本页面中的步骤，您必须先完成设置记忆库中的步骤。
提取操作
您可以通过以下方式获取生成的记忆：
获取记忆：使用 Agent Platform SDK 获取单个记忆的完整内容。
检索记忆：使用 Agent Platform SDK，通过基于范围的记忆检索功能检索记忆。使用相似度搜索功能检索记忆，或检索范围内的所有记忆。
列出记忆：使用 Agent Platform SDK 列出记忆。
获取记忆内容
使用 GetMemories 获取单个记忆的完整内容：
memory = client.agent_engines.memories.get(
name="MEMORY_NAME")
替换以下内容：
MEMORY_NAME：完全限定的记忆名称，格式为“projects/…/locations/…/reasoningEngines/…/memories…”。
使用基于范围的检索功能提取记忆
您可以使用 RetrieveMemories 检索特定范围内的记忆。系统只会返回与检索请求具有完全相同范围（不考虑顺序）的记忆。例如，您可以使用 {"user_id": "123"} 检索范围限定为特定用户的所有记忆。如果未返回任何记忆，则表示记忆库中没有适用于所提供范围的任何记忆。
记忆的范围是在生成或创建记忆时定义的，并且不可变。
您可以使用 RetrieveMemories 针对特定范围执行以下操作：
使用相似度搜索功能检索记忆
如果您在特定范围内有许多记忆，则可以通过提供相似性搜索参数，使用相似性搜索仅检索最相似的记忆。记忆库在执行相似性搜索时，只会考虑与请求具有完全相同范围的记忆。相似度搜索会比较记忆的事实与请求的搜索查询之间的嵌入向量。
返回的记忆会按相似度从高（欧几里得距离最短）到低（欧几里得距离最长）排序：
results = client.agent_engines.memories.retrieve(
name=memory_bank.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 `page` to retrieve memories.
results.page
"""
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
),
]
"""
替换以下内容：
QUERY：要执行相似度搜索的查询。例如，您可以使用对话的最后一轮用户对话作为查询。SCOPE：一个字典，用于表示相似度搜索的范围。例如{"user_id": "123"}。系统只会考虑与请求具有相同范围的记忆。
检索所有记忆
如果未提供任何相似性搜索参数，RetrieveMemories 会返回具有所提供范围的所有记忆，无论这些记忆与当前对话的相似性如何。
results = client.agent_engines.memories.retrieve(
name=memory_bank.api_resource.name,
scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `page` to retrieve up to 100 memories per page.
results.page
"""
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."
}
),
]
"""
替换以下内容：
SCOPE：表示检索范围的字典。例如{"user_id": "123"}。系统只会返回与请求具有相同范围的记忆。
列出记忆
使用 ListMemories 从记忆库中检索记忆，而无需进行基于范围的过滤。对于基于范围的检索，请改用 RetrieveMemories。不建议将 ListMemories 用于低延迟检索。
pager = client.agent_engines.memories.list(name=memory_bank.api_resource.name)
for page in pager:
print(page)
过滤回忆
本部分介绍了如何使用过滤条件来限制要提取的回忆。您可以按以下条件进行过滤：
使用
filter_groups属性进行基于范围的检索的元数据。使用
filter的系统字段。系统字段包括记忆的topics、create_time、update_time和fact。
您可以在同一请求中同时使用元数据过滤和系统字段过滤。
按元数据过滤
在创建、更新或生成回忆时，您可以将结构化元数据应用于存储的回忆：
import datetime
from vertexai import types
metadata = {
"my_string_key": types.MemoryMetadataValue(string_value="my_string_value"),
"my_double_key": types.MemoryMetadataValue(double_value=123.456),
"my_boolean_key": types.MemoryMetadataValue(bool_value=True),
"my_timestamp_key": types.MemoryMetadataValue(
timestamp_value=datetime.datetime(
2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
)
),
}
client.agent_engines.memories.create(
...,
config={"metadata": metadata}
)
client.agent_engines.memories.update(
...,
config={"metadata": metadata}
)
client.agent_engines.memories.generate(
...,
config={"metadata": metadata}
)
使用 filter_groups 属性检索回忆时，您可以按此元数据进行过滤。元数据过滤器以析取范式 (DNF) 定义，即以 AND 连接的子句的 OR 逻辑表达式。
例如，以下请求将检索包含元数据 ({"my_string_key": {"string_value": "my_value"}} AND {"my_double_key": {"double": 1.23}}) OR {"my_string_key": {"string_value":
"other"}} 的回忆。
字典
results = client.agent_engines.memories.retrieve(
...,
config={
# Each element of `filter_groups` is combined using OR logic.
"filter_groups": [
{
# Each element of `filters` is combined using AND logic.
"filters": [
{
"key": "my_string_key",
"value": {"string_value": "my_value"}
},
{
"key": "my_double_key",
"value": {"double_value": 1.23}
}
]
},
{
"filters": [
{
"key": "my_string_key",
"value": {"string_value": "other"}
}
]
}
]
}
)
基于类
from vertexai import types
results = client.agent_engines.memories.retrieve(
...,
config=types.RetrieveAgentEngineMemoriesConfig(
# Each element of `filter_groups` is combined using OR logic.
filter_groups=[
types.MemoryConjunctionFilter(
# Each element of `filters` is combined using AND logic.
filters=[
types.MemoryFilter(
key="my_string_key",
value=types.MemoryMetadataValue(string_value="my_value")
),
types.MemoryFilter(
key="my_double_key",
value=types.MemoryMetadataValue(double_value=1.23)
)
]
),
types.MemoryConjunctionFilter(
filters=[
types.MemoryFilter(
key="my_string_key",
value=types.MemoryMetadataValue(string_value="other")
)
]
)
]
)
)
按系统字段过滤
您可以使用 filter 属性按系统字段进行过滤，该属性需要使用 EBNF 语法提供字符串值。系统字段包括 create_time、update_time、fact 和 topics。
在构建过滤字符串时，EBNF 语法有以下要求：
- 如需组合过滤条件，请使用
AND和OR。 - 字符串应使用双引号
"。 - 日期时间字段（例如
create_time）可以使用表示 ISO 8601 日期时间的双引号字符串，也可以使用表示自 Unix 纪元以来的微秒数的数字字段。
例如，以下过滤条件可用于提取 fact 包含子字符串“allergies”且 update_time 在 2026 年 1 月 1 日之后的记忆。
filter_string = 'fact=~".*allergies.*" AND update_time>="2026-01-01T00:00:00Z"'
client.agent_engines.memories.retrieve(
...,
config={"filter": filter_string}
)
client.agent_engines.memories.list(
...,
config={"filter": filter_string}
)
按主题过滤
生成的记忆会自动添加相关记忆主题标签。
如需按受管理的广告主题过滤，请使用 topics.managed_memory_topic 作为字段名称，并使用预期值 ManagedTopicEnum 作为值，例如 topics.managed_memory_topic: USER_PREFERENCES。
如需按自定义主题过滤，请使用 topics.custom_memory_topic_label 作为字段名称，并使用预期主题的标签作为值，例如 topics.custom_memory_topic_label: custom-label。
filter_string = "topics.managed_memory_topic: USER_PREFERENCES " + \
"OR topics.custom_memory_topic_label: custom-label"
client.agent_engines.memories.retrieve(
...,
config={"filter": filter_string}
)
client.agent_engines.memories.list(
...,
config={"filter": filter_string}
)