Profil Memori

Anda dapat menggunakan Memory Bank untuk membuat profil terstruktur, yang merupakan struktur data dengan skema statis yang diisi dan diperbarui menggunakan LLM. Dengan menentukan skema tetap, Anda memastikan agen memiliki akses langsung dan latensi rendah ke informasi yang terus berkembang tanpa memerlukan operasi penelusuran yang mahal selama sesi.

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

Ringkasan

Menggunakan profil terstruktur dengan agen Anda memastikan bahwa informasi yang diekstrak—seperti stack teknis atau preferensi pengguna—tersedia dengan cepat, ringkas, dan dengan format yang konsisten. Misalnya, Anda dapat mengambil profil yang menyertakan konten seperti:

MemoryProfile(
    profile={
        "technical_stacks": "ADK, Python",
        "preferred_language": "Python",
        "tone_preference": "Succinct"
    },
    schema_id="user-profile"
)

Profil terstruktur dioptimalkan untuk pengambilan latensi rendah, karena pekerjaan berat dalam mengumpulkan informasi dilakukan pada waktu pembuatan. Intent ini sangat cocok untuk memulai interaksi antara agen dan pengguna.

Memahami profil memori terstruktur

Profil terstruktur dibuat melalui metode yang sama (GenerateMemories dan IngestEvents) yang Anda gunakan untuk memori bahasa alami. Setelah Anda menentukan skema, Memory Bank akan otomatis mencoba membuat profil yang sesuai dengan skema Anda menggunakan sumber data yang disediakan.

Saat menggunakan profil terstruktur, Memory Bank melakukan operasi berikut selama pembuatan memori:

  • Ekstraksi: Mengekstrak informasi dan konteks yang sesuai dengan skema dari sumber data. Hanya informasi yang sesuai dengan skema yang akan diekstrak. Anda dapat memeriksa informasi dan konteks yang diekstrak menggunakan revisi memori.
  • Konsolidasi: Memperbarui (jika perlu) kolom yang ada di profil. LLM akan menilai cara memperbarui konten yang ada berdasarkan informasi dan konteks yang baru diekstrak. Jika kolom belum ada di profil, konsolidasi akan dilewati, dan kolom akan diperbarui secara langsung dengan informasi yang diekstrak.

Profil diisolasi berdasarkan scope (seperti {"user_id": "123"}) yang Anda berikan saat menyerap data ke Memory Bank. Untuk setiap skema dan cakupan, Memory Bank mempertahankan satu profil sebagai sumber kebenaran. Profil yang dihasilkan terdiri dari satu atau beberapa instance Memory. Setiap instance Memory mewakili satu kolom dalam profil yang dapat Anda gunakan untuk memeriksa metadata dan histori revisi kolom, seperti:

Memory(
     create_time=datetime.datetime(...),
     memory_type=<MemoryType.STRUCTURED_PROFILE: 'STRUCTURED_PROFILE'>,
     name='projects/.../locations/.../reasoningEngines/.../memories/...',
     scope={
       'user_id': '123'
     },
     structured_content=MemoryStructuredContent(
       data={
         'language_preference': 'Java'
       },
       schema_id='user-profile'
     ),
     update_time=datetime.datetime(...),
     expire_time=datetime.datetime(...),
     metadata={...}
)

Definisi skema

Profil yang dihasilkan Memory Bank selaras dengan skema yang ditentukan pada instance Memory Bank Anda. Anda dapat menentukan beberapa skema profil independen; setiap skema harus memiliki ID unik. Perhatikan bahwa menambahkan atau memperbarui skema tidak akan mengisi ulang profil dari memori sebelumnya.

Konsol

Untuk menambahkan atau mengedit skema profil pada instance Memory Bank mandiri di konsol Google Cloud (memerlukan aiplatform.reasoningEngines.update untuk menyimpan perubahan):

  1. Di konsol Google Cloud , buka halaman Memory Bank Agent Platform, lalu klik instance Memory Bank Anda.

    Buka Memory Bank

  2. Klik Schemas di panel tindakan (atau di bagian Generation pada tab Configuration).

  3. Klik Add schema untuk membuat skema dengan ID unik, atau klik header kartu skema yang ada untuk meluaskannya.

  4. Tentukan atau edit kolom skema menggunakan tampilan Simple atau JSON, lalu klik Save.

Agent Platform SDK

Anda dapat menggunakan model pydantic untuk menentukan kolom yang ingin Anda ekstrak dan pertahankan oleh Memory Bank. Contoh:

from pydantic import BaseModel, Field
from typing import Literal

class UserProfile(BaseModel):
    name: str = Field(
      description="Name of the user.")
    technical_stack: str = Field(
      description="Comma-separated list tools or languages used by the user.")
    primary_goal: str = Field(
      description="The main objective the user is pursuing.")
    expertise_level: str = Field(
      description="Current skill level (e.g., Junior, Senior).")
    job_status: Literal['unemployed', 'part_time', 'full_time', 'student'] = Field(
      description="The job status of the individual")

Upload skema ke Memory Bank saat Anda membuat atau memperbarui instance Memory Bank:

schema_config = {
  "id": "user-profile",
  "memory_schema": UserProfile.model_json_schema()
}

memory_bank = client.memory_banks.create(
    managed_semantic_memory_config={
        "structured_memory_configs": [
            {
                "schema_configs": [schema_config]
            }
        ]
    }
)

Secara default, Memory Bank mengekstrak memori bahasa alami. Anda dapat menonaktifkan pembuatan memori bahasa alami jika Anda hanya ingin Memory Bank membuat profil:

memory_bank = client.memory_banks.create(
    managed_semantic_memory_config={
        "structured_memory_configs": [
            {
                "schema_configs": [schema_config]
            }
        ],
        # Optional: Turn off natural language memories.
        "unstructured_memory_configs": [
            {"disable_natural_language_memories": True}
        ]
    }
)

Pembuatan profil

Anda memicu pembuatan memori terstruktur dengan memberikan histori percakapan (peristiwa) ke metode GenerateMemories atau IngestEvents. Seperti memori natural language, Memory Bank menggunakan LLM untuk mengekstrak informasi yang bermakna dari sumber data dan menggabungkannya dengan memori yang ada.

Contoh

Contoh berikut membahas pembuatan profil memori menggunakan skema yang telah ditentukan sebelumnya.

Dalam kumpulan peristiwa pertama yang dikirim ke Memory Bank untuk cakupan {"user_id": "123"}, pengguna menunjukkan bahwa mereka bekerja dengan agen ADK:

client.memory_banks.memories.generate(
  name=memory_bank.name,
  scope={"user_id": "123"},
  direct_contents_source={
    "events": [
      {"content": {
        "parts": [{
          "text": "Can you help me build an ADK agent that organizes my daily tasks?"}]}}]
  }
)

Memory Bank mengekstrak "ADK" untuk kolom technical_stack dalam skema. Tidak ada kolom lain yang diisi karena peristiwa yang diserap tidak berisi informasi yang relevan untuk skema lainnya. Karena ini adalah interaksi pertama untuk cakupan ini, konsolidasi akan dilewati dan profil akan diinisialisasi dengan nilai awal ini.

result = client.memory_banks.memories.retrieve_profiles(
    name=memory_bank.name,
    scope={"user_id": "123"},
)

"""
Returns:

RetrieveProfilesResponse(
  profiles={
    'user-profile': MemoryProfile(
      profile={
        'technical_stack': 'ADK'
      },
      schema_id='user-profile'
    )
  }
)
"""

Dalam kumpulan peristiwa berikutnya yang dikirim ke Memory Bank, pengguna menunjukkan bahwa mereka adalah siswa dan terutama membuat kode dalam Python:

client.memory_banks.memories.generate(
  name=memory_bank.name,
  scope={"user_id": "123"},
  direct_contents_source={
    "events": [
      {"content": {
        "parts": [
          {"text": "Do you have any career recommendations for students that specialize in Python?"}]}}]
  }
)

Memory Bank mengekstrak "Python" dan status "pelajar" dari interaksi tersebut. Fragmen technical_stack digabungkan, dengan menambahkan "Python" ke entri "ADK" yang ada. Sistem akan mengisi kolom job_status yang sebelumnya kosong dengan enum "student" dan melewati langkah konsolidasi.

result = client.memory_banks.memories.retrieve_profiles(
    name=memory_bank.name,
    scope=scope
)

"""
Returns:

RetrieveProfilesResponse(
  profiles={
    'user-profile': MemoryProfile(
      profile={
        'technical_stack': 'ADK, Python',
        'job_status': 'student'
      },
      schema_id='user-profile'
    )
  }
)
"""

Pengambilan profil

Setelah dibuat, Anda dapat mengambil profil gabungan untuk cakupan tertentu menggunakan metode RetrieveProfiles. Tindakan ini akan menampilkan data terbaru yang dipetakan ke skema Anda.

result = client.memory_banks.memories.retrieve_profiles(
  name=memory_bank.name,
  scope={"user_id": "123"},
)

# Accessing the data
for profile in result.profiles.values():
  print(profile)
  # Output: {'technical_stack': 'ADK, Python', 'job_status': 'student', ...}

Pemeriksaan profil

Di balik layar, profil terdiri dari memori individual jenis STRUCTURED_PROFILE. Setiap kolom dalam skema Anda dipetakan ke satu memori per cakupan, sehingga memberikan kemampuan observasi yang terperinci.

Meskipun RetrieveProfiles adalah metode utama untuk pengambilan profil produksi, Anda dapat memeriksa memori individual di konsolGoogle Cloud atau dengan Agent Platform SDK untuk mengaudit evolusi profil:

  • Metadata tingkat kolom: Lihat dan perbarui time to live (TTL) dan Memory.metadata tertentu untuk setiap kolom di profil.

  • Histori revisi: Lacak silsilah kolom untuk melihat nilai historis dan konteks percakapan spesifik yang memicu setiap perubahan.

Konsol

  1. Di konsol Google Cloud , buka instance mandiri Anda di halaman Memory Bank atau agen yang di-deploy di halaman Deployments, lalu pilih tab Memories.

    Buka Memory Bank

  2. Pilih Terstruktur, lalu pilih nilai untuk semua kunci dalam cakupan target (atau terapkan filter cakupan di Tidak terstruktur dan klik Telusuri memori terstruktur). Baris profil yang cocok menampilkan Schema, Type, Content, Created, dan Updated.

  3. Klik View di baris profil untuk membuka panel Memory details, yang menampilkan chip cakupan, link ke skema, setiap Memory facts (dengan View revisions untuk setiap fakta), dan JSON profil gabungan.

Agent Platform SDK

Gunakan RetrieveMemories untuk mengambil memori yang berisi fragmen profil pengguna. Secara default, RetrieveMemories hanya mengambil memori bahasa alami, jadi minta memori STRUCTURED_PROFILE secara eksplisit:

client.memory_banks.memories.retrieve(
  name="...",
  scope={"user_id": "123"},
  config={
    "memory_types": ["STRUCTURED_PROFILE"]
  }
)

"""
Returns:

[RetrieveMemoriesResponseRetrievedMemory(
   memory=Memory(
     create_time=datetime.datetime(...),
     memory_type=<MemoryType.STRUCTURED_PROFILE: 'STRUCTURED_PROFILE'>,
     name='projects/.../locations/.../reasoningEngines/.../memories/...',
     scope={
       'user_id': '123'
     },
     structured_content=MemoryStructuredContent(
       data={
         'technical_stack': 'ADK, Python'
       },
       schema_id='user'
     ),
     update_time=datetime.datetime(...)
   )
 )]
"""

Kemudian, ambil histori revisi fragmen profil terstruktur untuk memeriksa perubahan kolom profil dari waktu ke waktu dan konteks di sekitar setiap perubahan:

for retrieved_memory in list(results):
    list(client.memory_banks.memories.revisions.list(
        name=retrieved_memory.memory.name
    ))

"""
Returns:

[MemoryRevision(
   create_time=datetime.datetime(...),
   expire_time=datetime.datetime(...),
   extracted_memories=[
     IntermediateExtractedMemory(
       context='The user indicated that they have expertise in Python when asking about career options.',
       structured_data={
         'technical_stack': 'Python'
       }
     ),
   ],
   name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...',
   structured_data={
     'technical_stack': 'ADK, Python'
   }
 ),
 MemoryRevision(
   create_time=datetime.datetime(...),
   expire_time=datetime.datetime(...),
   extracted_memories=[
     IntermediateExtractedMemory(
       context='The user indicated that they need help building an ADK agent',
       structured_data={
         'technical_stack': 'ADK'
       }
     ),
   ],
   name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...',
   structured_data={
     'technical_stack': 'ADK'
   }
 )]
"""