Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat kenangan

Memory Bank memungkinkan Anda membuat memori jangka panjang dari percakapan antara pengguna dan agen Anda. Halaman ini menjelaskan cara kerja pembuatan kenangan, cara menyesuaikan cara kenangan diekstrak, dan cara memicu pembuatan kenangan.

Untuk menyelesaikan langkah-langkah yang ditunjukkan dalam panduan ini, Anda harus mengikuti langkah-langkah dalam Menyiapkan Memory Bank terlebih dahulu.

Memahami pembuatan memori

Memory Bank mengekstrak kenangan dari data sumber dan mengelola sendiri kenangan untuk kumpulan kenangan tertentu (ditentukan oleh scope) dengan menambahkan, memperbarui, dan menghapus kenangan seiring waktu.

Saat Anda memicu pembuatan memori, Bank Memori akan melakukan operasi berikut:

Ekstraksi: Mengekstrak informasi tentang pengguna dari percakapan mereka dengan agen. Hanya informasi yang cocok dengan setidaknya salah satu topik memori instance Anda yang akan dipertahankan.
Konsolidasi: Mengidentifikasi apakah kenangan yang ada dengan cakupan yang sama harus dihapus atau diperbarui berdasarkan informasi yang diekstrak. Bank Memori memeriksa apakah kenangan baru tidak duplikat atau bertentangan sebelum menggabungkannya dengan kenangan yang ada. Jika kenangan yang ada tidak tumpang-tindih dengan informasi baru, kenangan baru akan dibuat.

Topik kenangan

"Topik memori" mengidentifikasi informasi yang dianggap penting oleh Bank Memori dan oleh karena itu harus dipertahankan sebagai kenangan yang dihasilkan. Bank Memori mendukung dua jenis topik memori:

Topik terkelola: Label dan petunjuk ditentukan oleh Memory Bank. Anda hanya perlu memberikan nama topik terkelola. Contoh:

Kamus

memory_topic = {
    "managed_memory_topic": {
        "managed_topic_enum": "USER_PERSONAL_INFO"
    }
}

Berbasis kelas

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

Topik kustom: Label dan petunjuk ditentukan oleh Anda saat menyiapkan instance Bank Memori. Informasi ini akan digunakan dalam perintah untuk langkah ekstraksi Bank Memori. Contoh:

Kamus

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."""
    }
}

Berbasis kelas

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

Saat menggunakan topik kustom, sebaiknya berikan juga contoh sedikit tembakan (few-shot) untuk menunjukkan cara mengekstrak kenangan dari percakapan Anda.

Secara default, Bank Memori mempertahankan semua topik terkelola berikut:

Informasi pribadi (USER_PERSONAL_INFO): Informasi pribadi penting tentang pengguna, seperti nama, hubungan, hobi, dan tanggal penting. Misalnya, "Saya bekerja di Google" atau "Ulang tahun pernikahan saya pada 31 Desember".
Preferensi pengguna (USER_PREFERENCES): Suka, tidak suka, gaya, atau pola yang dinyatakan atau tersirat. Misalnya, "Saya lebih suka tempat duduk di tengah".
Peristiwa percakapan utama dan hasil tugas (KEY_CONVERSATION_DETAILS): Tonggak penting atau kesimpulan dalam dialog. Misalnya, "Saya memesan tiket pesawat untuk perjalanan pulang pergi antara JFK dan SFO. Saya berangkat pada 1 Juni 2025 dan kembali pada 7 Juni 2025."
Petunjuk ingat / lupa eksplisit (EXPLICIT_INSTRUCTIONS): Informasi yang secara eksplisit diminta pengguna kepada agen untuk diingat atau dilupakan. Misalnya, jika pengguna mengatakan "Ingat bahwa saya terutama menggunakan Python", Bank Memori akan membuat memori seperti "Saya terutama menggunakan Python".

Hal ini setara dengan menggunakan kumpulan topik memori terkelola berikut:

Kamus

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

Berbasis kelas

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

Jika Anda ingin menyesuaikan topik yang dipertahankan oleh Bank Memori, tetapkan topik memori dalam konfigurasi penyesuaian saat menyiapkan Bank Memori.

Memicu pembuatan memori

Anda dapat memicu pembuatan memori menggunakan GenerateMemories di akhir sesi atau secara berkala dalam sesi. Pembuatan memori mengekstrak konteks utama dari percakapan sumber dan menggabungkannya dengan memori yang ada untuk cakupan yang sama. Misalnya, Anda dapat membuat kenangan tingkat sesi dengan menggunakan cakupan seperti {"user_id": "123", "session_id": "456"}. Kenangan dengan cakupan yang sama dapat digabungkan dan diambil bersama.

GenerateMemories adalah operasi yang berjalan lama. Setelah operasi selesai, AgentEngineGenerateMemoriesOperation akan berisi daftar kenangan yang dihasilkan, jika ada:

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

Setiap memori yang dihasilkan mencakup action yang dilakukan pada memori tersebut:

CREATED: Menunjukkan bahwa kenangan baru telah ditambahkan, yang merepresentasikan konsep baru yang tidak tercakup oleh kenangan yang ada.
UPDATED: Menunjukkan bahwa memori yang ada telah diperbarui, yang terjadi jika memori mencakup konsep yang serupa dengan informasi yang baru diekstrak. Fakta memori dapat diperbarui dengan informasi baru atau tetap sama.
DELETED: Menunjukkan bahwa memori yang ada telah dihapus, karena informasinya bertentangan dengan informasi baru yang diekstrak dari percakapan.

Untuk kenangan CREATED atau UPDATED, Anda dapat menggunakan GetMemories untuk mengambil konten lengkap kenangan. Pengambilan memori DELETED akan menghasilkan error 404.

Membuat kenangan di latar belakang

GenerateMemories adalah operasi yang berjalan lama. Secara default, client.agent_engines.generate_memories adalah fungsi pemblokiran yang melakukan polling pada operasi hingga operasi selesai. Mengeksekusi pembuatan memori sebagai operasi pemblokiran berguna saat Anda ingin memeriksa memori yang dibuat secara manual atau memberi tahu pengguna akhir tentang memori yang dibuat.

Namun, untuk agen produksi, Anda umumnya ingin menjalankan pembuatan memori di latar belakang sebagai proses asinkron. Dalam sebagian besar kasus, klien tidak perlu menggunakan output untuk proses saat ini, sehingga tidak perlu menimbulkan latensi tambahan saat menunggu respons. Jika Anda ingin pembuatan memori dijalankan di latar belakang, tetapkan wait_for_completion ke False:

client.agent_engines.memories.generate(
    ...,
    config={
        "wait_for_completion": False
    }
)

Sumber data

Ada beberapa cara untuk menyediakan data sumber bagi pembuatan memori:

Menyediakan peristiwa langsung di payload.
Menyediakan peristiwa menggunakan Sesi Vertex AI Agent Engine.
Berikan fakta yang telah diekstrak sebelumnya untuk menggabungkannya dengan kenangan yang ada untuk cakupan yang sama.

Saat Anda memberikan peristiwa secara langsung dalam payload atau menggunakan Sesi Vertex AI Agent Engine, informasi akan diekstrak dari percakapan dan digabungkan dengan memori yang ada. Jika hanya ingin mengekstrak informasi dari sumber data ini, Anda dapat menonaktifkan penggabungan:

client.agent_engines.memories.generate(
    ...
    config={
        "disable_consolidation": True
    }
)

Menggunakan peristiwa dalam payload sebagai sumber data

Gunakan direct_contents_source jika Anda ingin membuat kenangan menggunakan peristiwa yang disediakan langsung dalam payload. Informasi yang bermakna diekstrak dari peristiwa ini dan digabungkan dengan informasi yang ada untuk cakupan yang sama. Pendekatan ini dapat digunakan jika Anda menggunakan penyimpanan sesi yang berbeda dari Sesi Vertex AI Agent Engine.

Kamus

Peristiwa harus menyertakan kamus Content.

events =  [
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I work with LLM agents!"}
      ]
    }
  }
]

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": EVENTS
    },
    # For example, `scope={"user_id": "123"}`.
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

Ganti kode berikut:

SCOPE: Kamus, yang mewakili cakupan kenangan yang dihasilkan. Contoh, {"session_id": "MY_SESSION"}. Hanya kenangan dengan cakupan yang sama yang dipertimbangkan untuk penggabungan.

Berbasis kelas

Acara harus menyertakan objek Content.

from google import genai
import vertexai

events = [
  vertexai.types.GenerateMemoriesRequestDirectContentsSourceEvent(
    content=genai.types.Content(
      role="user",
      parts=[
        genai.types.Part.from_text(text="I work with LLM agents!")
      ]
    )
  )
]

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": events
    },
    # For example, `scope={"user_id": "123"}`.
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

Ganti kode berikut:

SCOPE: Kamus, yang mewakili cakupan kenangan yang dihasilkan. Contoh, {"session_id": "MY_SESSION"}. Hanya kenangan dengan cakupan yang sama yang dipertimbangkan untuk penggabungan.

Menggunakan Sesi Vertex AI Agent Engine sebagai sumber data

Dengan Sesi Agent Engine, Bank Memori menggunakan peristiwa sesi sebagai percakapan sumber untuk pembuatan memori.

Untuk menentukan cakupan kenangan yang dihasilkan, Bank Memori mengekstrak dan menggunakan ID pengguna dari sesi secara default. Misalnya, cakupan memori disimpan sebagai {"user_id": "123"} jika sesi user_id adalah "123". Anda juga dapat memberikan scope secara langsung, yang menggantikan penggunaan user_id sesi sebagai cakupan.

Kamus

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
      # For example, projects/.../locations/.../reasoningEngines/.../sessions/...
      "session": "SESSION_NAME"
  },
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

Ganti kode berikut:

SESSION_NAME: Nama sesi yang sepenuhnya memenuhi syarat.
(Opsional) SCOPE: Kamus, yang merepresentasikan cakupan kenangan yang dibuat. Contoh, {"session_id": "MY_SESSION"}. Hanya kenangan dengan cakupan yang sama yang dipertimbangkan untuk penggabungan. Jika tidak diberikan, {"user_id": session.user_id} akan digunakan.

Berbasis kelas

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source=vertexai.types.GenerateMemoriesRequestVertexSessionSource(
      # For example, projects/.../locations/.../reasoningEngines/.../sessions/...
      session="SESSION_NAME"
  ),
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

Secara opsional, Anda dapat memberikan rentang waktu yang menunjukkan peristiwa mana dalam Sesi yang harus disertakan. Jika tidak diberikan, semua peristiwa dalam Sesi akan disertakan.

Kamus

import datetime

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
      "session": "SESSION_NAME",
      # Extract memories from the last hour of events.
      "start_time": datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
      "end_time": datetime.datetime.now(tz=datetime.timezone.utc)
  },
  scope=SCOPE
)

Berbasis kelas

import datetime

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source=vertexai.types.GenerateMemoriesRequestVertexSessionSource(
      session="SESSION_NAME",
      # Extract memories from the last hour of events.
      start_time=datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
      end_time=datetime.datetime.now(tz=datetime.timezone.utc)
  ),
  scope=SCOPE
)

Menggabungkan kenangan yang telah diekstrak sebelumnya

Sebagai alternatif untuk menggunakan proses ekstraksi otomatis Bank Memori, Anda dapat langsung memberikan kenangan yang telah diekstrak sebelumnya. Kenangan sumber langsung akan digabungkan dengan kenangan yang ada untuk cakupan yang sama. Hal ini dapat berguna saat Anda ingin agen atau manusia dalam loop bertanggung jawab untuk mengekstrak memori, tetapi Anda tetap ingin memanfaatkan konsolidasi Bank Memori untuk memastikan tidak ada memori duplikat atau yang bertentangan.

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Ganti kode berikut:

FACT: Fakta yang telah diekstrak sebelumnya yang harus digabungkan dengan memori yang ada. Anda dapat memberikan hingga 5 fakta yang telah diekstrak sebelumnya dalam daftar seperti berikut:
```
{"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
```
SCOPE: Kamus, yang mewakili cakupan kenangan yang dihasilkan. Contoh, {"session_id": "MY_SESSION"}. Hanya kenangan dengan cakupan yang sama yang dipertimbangkan untuk penggabungan.

Menggunakan input multimodal

Anda dapat mengekstrak kenangan dari input multimodal. Namun, kenangan hanya diekstrak dari teks, file inline, dan data file dalam konten sumber. Semua konten lainnya, termasuk panggilan dan respons fungsi, akan diabaikan saat membuat kenangan.

Kenangan dapat diekstrak dari gambar, video, dan audio yang disediakan oleh pengguna. Jika konteks yang diberikan oleh input multimodal dinilai oleh Bank Memori bermakna untuk interaksi di masa mendatang, maka memori tekstual dapat dibuat termasuk informasi yang diekstrak dari input. Misalnya, jika pengguna memberikan gambar golden retriever dengan teks "Ini saya", maka Bank Memori akan membuat memori seperti " saya adalah golden retriever".

Misalnya, Anda dapat memberikan gambar dan konteks untuk gambar tersebut dalam payload:

Kamus

with open(file_name, "rb") as f:
    inline_data = f.read()

events =  [
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "This is my dog"},
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": inline_data
          }
        },
        {
          "file_data": {
            "file_uri": "gs://cloud-samples-data/generative-ai/image/dog.jpg",
            "mime_type": "image/jpeg"
          }
        },
      ]
    }
  }
]

Berbasis kelas

from google import genai
import vertexai

with open(file_name, "rb") as f:
    inline_data = f.read()

events = [
  vertexai.types.GenerateMemoriesRequestDirectContentsSourceEvent(
    content=genai.types.Content(
      role="user",
      parts=[
        genai.types.Part.from_text(text="This is my dog"),
        genai.types.Part.from_bytes(
          data=inline_data,
          mime_type="image/jpeg",
        ),
        genai.types.Part.from_uri(
          file_uri="gs://cloud-samples-data/generative-ai/image/dog.jpg",
          mime_type="image/jpeg",
        )
      ]
    )
  )
]

Saat menggunakan Sesi Vertex AI Agent Engine sebagai sumber data, konten multimodal disediakan langsung di peristiwa Sesi.

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

Memahami pembuatan memori

Topik kenangan

Kamus

Berbasis kelas

Kamus

Berbasis kelas

Kamus

Berbasis kelas

Memicu pembuatan memori

Membuat kenangan di latar belakang

Sumber data

Menggunakan peristiwa dalam payload sebagai sumber data

Kamus

Berbasis kelas

Menggunakan Sesi Vertex AI Agent Engine sebagai sumber data

Kamus

Berbasis kelas

Kamus

Berbasis kelas

Menggabungkan kenangan yang telah diekstrak sebelumnya

Menggunakan input multimodal

Kamus

Berbasis kelas

Langkah berikutnya

Membuat kenangan