기억 가져오기

이 페이지에서는 생성되고 업로드된 기억을 메모리 뱅크에서 가져오는 방법을 설명합니다. 메모리 뱅크 구성, 생성, 사용에 관한 전체 워크플로는 REST API 사용하기 빠른 시작을 참고하세요.

참고: 메모리 뱅크를 사용하도록 Agent Development Kit 에이전트를 구성한 경우 에이전트가 RetrieveMemories 호출을 조정하므로 기억을 검색하기 위해 직접 호출할 필요가 없습니다.

시작하기 전에

이 페이지의 단계를 완료하려면 먼저 메모리 뱅크 설정의 단계를 완료해야 합니다.

가져오기 작업

생성된 기억을 가져오는 옵션은 다음과 같습니다.

• 기억 가져오기: Vertex AI SDK를 사용하여 단일 기억의 전체 콘텐츠를 가져옵니다.

• 메모리 나열: Vertex AI SDK 또는 Google Cloud 콘솔을 사용하여 메모리를 나열합니다.

• 기억 검색: Vertex AI SDK를 사용하여 범위 기반 기억 검색을 통해 기억을 검색합니다. 유사 검색을 사용하거나 범위 내의 모든 기억을 검색합니다.

기억 가져오기

GetMemories을 사용하여 단일 기억의 전체 콘텐츠를 가져옵니다.

memory = client.agent_engines.memories.get(
    name="MEMORY_NAME")

다음을 바꿉니다.

• MEMORY_NAME: 'projects/.../locations/.../reasoningEngines/.../memories...' 형식의 정규화된 기억 이름

기억 나열

콘솔

배포된 에이전트의 경우 Google Cloud 콘솔을 사용하여 Agent Engine 인스턴스와 연결된 모든 메모리를 나열할 수 있습니다.

1. Google Cloud 콘솔에서 Vertex AI Agent Engine 페이지로 이동합니다.
   

   Agent Engine으로 이동

   선택한 프로젝트에 속하는 Agent Engine 인스턴스가 목록에 표시됩니다. 필터 필드를 사용하여 지정된 열을 기준으로 목록을 필터링할 수 있습니다.

2. Agent Engine 인스턴스 이름을 클릭합니다.

3. 추억 탭을 클릭합니다. ID별로 추억 목록이 표시됩니다.

Vertex AI SDK

ListMemories를 사용하여 메모리 뱅크의 모든 기억을 가져옵니다.

pager = client.agent_engines.memories.list(name=agent_engine.api_resource.name)
for page in pager:
  print(page)

범위 기반 검색을 사용하여 기억 가져오기

RetrieveMemories를 사용하여 특정 범위의 기억을 검색할 수 있습니다. 검색 요청과 정확히 동일한 범위(순서와 관계 없음)의 기억만 반환됩니다. 예를 들어 {"user_id": "123"}를 사용하여 특정 사용자로 범위가 지정된 모든 기억을 검색할 수 있습니다. 반환된 기억이 없으면 메모리 뱅크에 제공된 범위의 기억이 없는 것입니다.

기억의 범위는 기억가 생성되거나 만들어질 때 정의되며 변경할 수 없습니다.

RetrieveMemories를 사용하여 특정 범위에 대해 다음 작업을 실행할 수 있습니다.

• 유사성 검색을 사용하여 기억 검색
• 모든 기억 검색

유사성 검색을 사용하여 기억 검색

특정 범위의 기억이 많은 경우 유사 검색을 사용하여 유사 검색 파라미터를 제공하여 가장 유사한 기억만 검색할 수 있습니다. 메모리 뱅크는 유사 검색을 실행할 때 요청과 정확히 동일한 범위의 기억만 고려합니다. 유사성 검색은 기억의 사실과 요청의 검색어 간에 임베딩 벡터를 비교합니다.

반환된 기억은 가장 유사한 기억(유클리드 거리가 가장 짧음)에서 가장 유사하지 않은 기억 (유클리드 거리가 가장 큼) 순으로 정렬됩니다.

results = client.agent_engines.memories.retrieve(
    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
    ),
]
"""

다음을 바꿉니다.

• QUERY: 유사 검색을 실행할 쿼리. 예를 들어 대화의 마지막 사용자 턴을 쿼리로 사용할 수 있습니다.

• SCOPE: 유사성 검색의 범위를 나타내는 사전. 예를 들면 {"user_id": "123"}입니다. 요청과 범위가 동일한 기억만 고려됩니다.

모든 기억 검색

유사성 검색 파라미터가 제공되지 않으면 RetrieveMemories는 현재 대화와의 유사성과 관계없이 제공된 범위가 있는 모든 기억을 반환합니다.

results = client.agent_engines.memories.retrieve(
    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."
      }
    ),
]
"""

다음을 바꿉니다.

• SCOPE: 검색 범위를 나타내는 사전. 예를 들면 {"user_id": "123"}입니다. 요청과 범위가 동일한 기억만 반환됩니다.

추억 필터링

이 섹션에서는 필터를 사용하여 가져오는 추억을 제한하는 방법을 설명합니다. 다음을 기준으로 필터링할 수 있습니다.

• 범위 기반 검색을 위해 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"}} 및 {"my_double_key": {"double": 1.23}}) 또는 {"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")
          )
        ]
      )
    ]
  )
)

시스템 필드로 필터링

EBNF 구문을 사용하는 문자열 값을 예상하는 filter 속성을 사용하여 시스템 필드를 필터링할 수 있습니다. 시스템 필드에는 create_time, update_time, fact, topics이 포함됩니다.

필터 문자열을 생성할 때 EBNF 구문에는 다음 요구사항이 있습니다.

• 필터를 결합하려면 AND 및 OR를 사용합니다.
• 문자열은 큰따옴표 "를 사용해야 합니다.
• 날짜 및 시간 필드 (예: create_time)는 ISO 8601 날짜 및 시간을 나타내는 큰따옴표로 묶인 문자열이나 유닉스 에포크로부터의 마이크로초를 나타내는 숫자 필드를 사용해야 합니다.

예를 들어 다음 필터를 사용하여 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}
)