Mengambil kenangan

Halaman ini menjelaskan cara mengambil kenangan yang dibuat dan diupload dari Bank Memori. Untuk seluruh alur kerja dalam mengonfigurasi, membuat, dan menggunakan Bank Memori, lihat Panduan memulai dengan REST API.

Sebelum memulai

Untuk menyelesaikan langkah-langkah di halaman ini, Anda harus menyelesaikan langkah-langkah di Menyiapkan fitur Bank Memori terlebih dahulu.

Operasi pengambilan

Anda memiliki opsi berikut untuk mengambil kenangan yang dibuat:

Mendapatkan memori: Mendapatkan konten lengkap dari satu memori menggunakan Vertex AI SDK.
Mencantumkan memori: Mencantumkan memori menggunakan Vertex AI SDK atau konsol Google Cloud .
Mengambil memori: Menggunakan Vertex AI SDK, ambil memori menggunakan pengambilan memori berbasis cakupan. Mengambil kenangan menggunakan penelusuran kesamaan atau semua kenangan dalam cakupan.

Mendapatkan memori

Gunakan GetMemories untuk mendapatkan konten lengkap dari satu memori:

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

Ganti kode berikut:

MEMORY_NAME: Nama memori yang sepenuhnya memenuhi syarat dalam format "projects/.../locations/.../reasoningEngines/.../memories...".

Mencantumkan kenangan

Konsol

Untuk agen yang di-deploy, Anda dapat menggunakan konsol Google Cloud untuk mencantumkan semua memori yang terkait dengan instance Agent Engine Anda:

Di konsol Google Cloud , buka halaman Vertex AI Agent Engine.

Buka Agent Engine

Instance Agent Engine yang merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang Anda tentukan.
Klik nama instance Agent Engine Anda.
Klik tab Kenangan. Daftar kenangan ditampilkan menurut ID.

Vertex AI SDK

Gunakan ListMemories untuk mengambil semua kenangan di Bank Memori Anda.

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

Mengambil kenangan menggunakan pengambilan berbasis cakupan

Anda dapat menggunakan RetrieveMemories untuk mengambil kenangan untuk cakupan tertentu. Hanya kenangan yang memiliki cakupan yang sama persis (terlepas dari urutan) dengan permintaan pengambilan yang ditampilkan. Misalnya, Anda dapat mengambil semua kenangan yang dicakup ke pengguna tertentu dengan menggunakan {"user_id": "123"}. Jika tidak ada kenangan yang ditampilkan, Bank Kenangan tidak memiliki kenangan untuk cakupan yang diberikan.

Cakupan kenangan ditentukan saat kenangan dibuat atau dihasilkan dan bersifat tetap.

Anda dapat menggunakan RetrieveMemories untuk melakukan operasi berikut untuk cakupan tertentu:

Mengambil kenangan menggunakan penelusuran kemiripan
Mengambil semua kenangan

Mengambil kenangan menggunakan penelusuran kemiripan

Untuk kasus saat Anda memiliki banyak kenangan untuk cakupan tertentu, Anda dapat menggunakan penelusuran kesamaan untuk mengambil hanya kenangan yang paling mirip dengan memberikan parameter penelusuran kesamaan. Bank Memori hanya mempertimbangkan memori yang memiliki cakupan yang sama persis dengan permintaan saat melakukan penelusuran kemiripan. Penelusuran kemiripan membandingkan vektor sematan antara fakta memori dan kueri penelusuran permintaan.

Kenangan yang ditampilkan diurutkan dari yang paling mirip (jarak Euclidean terpendek) hingga yang paling tidak mirip (jarak Euclidean terbesar):

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
    ),
]
"""

Ganti kode berikut:

QUERY: Kueri yang akan dilakukan penelusuran kesamaannya. Misalnya, Anda dapat menggunakan giliran pengguna terakhir dalam percakapan sebagai kueri.
SCOPE: Kamus, yang merepresentasikan cakupan untuk penelusuran kemiripan. Contoh, {"user_id": "123"}. Hanya kenangan dengan cakupan yang sama dengan permintaan yang dipertimbangkan.

Mengambil semua kenangan

Jika tidak ada parameter penelusuran kemiripan yang diberikan, RetrieveMemories akan menampilkan semua kenangan yang memiliki cakupan yang diberikan, terlepas dari kemiripannya dengan percakapan saat ini.

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."
      }
    ),
]
"""

Ganti kode berikut:

SCOPE: Kamus yang mewakili cakupan untuk pengambilan. Contoh, {"user_id": "123"}. Hanya kenangan dengan cakupan yang sama dengan permintaan yang ditampilkan.

Memfilter kenangan

Bagian ini menjelaskan cara menggunakan filter untuk membatasi kenangan yang diambil. Anda dapat memfilter berdasarkan:

Metadata menggunakan atribut filter_groups untuk pengambilan berbasis cakupan.
Kolom sistem menggunakan filter. Kolom sistem mencakup topics, create_time, update_time, dan fact kenangan.

Pemfilteran kolom metadata dan sistem dapat digunakan dalam permintaan yang sama.

Memfilter menurut metadata

Saat membuat, memperbarui, atau membuat kenangan, Anda dapat menerapkan metadata terstruktur ke kenangan yang disimpan:

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}
)

Anda dapat memfilter metadata ini saat mengambil kenangan menggunakan atribut filter_groups. Filter metadata ditentukan dalam bentuk normal disjungtif (DNF), yang merupakan ekspresi logis OR dari AND.

Misalnya, permintaan berikut akan mengambil kenangan yang menyertakan metadata ({"my_string_key": {"string_value": "my_value"}} AND {"my_double_key": {"double": 1.23}}) ATAU {"my_string_key": {"string_value": "other"}}.

Kamus

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"}
          }
        ]
      }
    ]
  }
)

Berbasis kelas

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")
          )
        ]
      )
    ]
  )
)

Memfilter menurut kolom sistem

Anda dapat memfilter kolom sistem menggunakan atribut filter, yang mengharapkan nilai string menggunakan sintaksis EBNF. Kolom sistem mencakup create_time, update_time, fact, dan topics.

Sintaksis EBNF memiliki persyaratan berikut saat membuat string filter:

Untuk menggabungkan filter, gunakan AND dan OR.
String harus menggunakan tanda kutip ganda ".
Kolom tanggal dan waktu (seperti create_time) harus menggunakan string yang diapit tanda petik ganda yang merepresentasikan tanggal dan waktu ISO 8601 atau kolom numerik yang merepresentasikan mikrodetik dari epoch Unix.

Misalnya, filter berikut dapat digunakan untuk mengambil kenangan dengan fact yang menyertakan substring "alergi" dan update_time setelah 1 Januari 2026.

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}
)

Memfilter menurut topik

Kenangan yang dibuat akan otomatis diberi label topik kenangan yang relevan.

Untuk memfilter topik terkelola, gunakan topics.managed_memory_topic sebagai nama kolom dan ManagedTopicEnum yang diharapkan sebagai nilai, seperti topics.managed_memory_topic: USER_PREFERENCES.

Untuk memfilter topik kustom, gunakan topics.custom_memory_topic_label sebagai nama kolom dan label topik yang diharapkan sebagai nilai, seperti 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}
)

Mengambil kenangan Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Operasi pengambilan

Mendapatkan memori

Mencantumkan kenangan

Konsol

Vertex AI SDK

Mengambil kenangan menggunakan pengambilan berbasis cakupan

Mengambil kenangan menggunakan penelusuran kemiripan

Mengambil semua kenangan

Memfilter kenangan

Memfilter menurut metadata

Kamus

Berbasis kelas

Memfilter menurut kolom sistem

Memfilter menurut topik

Mengambil kenangan