Memvisualisasikan memori asisten AI Anda dengan pgvector Gemini dan Cloud SQL

1. Pengantar

Dalam codelab ini, Anda akan mempelajari cara membangun Demo Memori Aktif, asisten berbasis AI yang melacak "memori" percakapan Anda untuk memberikan pengalaman yang dipersonalisasi.

Aplikasi ini menggunakan Gemini untuk pemahaman bahasa alami dan Cloud SQL untuk PostgreSQL dengan ekstensi pgvector untuk menyimpan dan mengambil memori ini berdasarkan kemiripan semantik.

Codelab ini ditujukan untuk developer dari semua tingkat keahlian yang tertarik dengan AI dan database, dan memerlukan waktu sekitar 60 menit untuk diselesaikan. Biaya resource yang dibuat tidak boleh lebih dari $5.

Yang akan Anda lakukan

• Cara menyiapkan instance Cloud SQL untuk PostgreSQL dengan dukungan pgvector.
• Cara menggunakan Gemini untuk mengekstrak "memori" secara interaktif dari pesan pengguna.
• Cara melakukan penelusuran vektor di PostgreSQL untuk mengambil konteks yang relevan untuk respons AI.

Yang akan Anda butuhkan

• Project Google Cloud yang mengaktifkan penagihan.
• Pengetahuan dasar tentang command line dan Node.js.

2. Sebelum memulai

Penyiapan project

Membuat Project Google Cloud

1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan diaktifkan di project.

Mulai Cloud Shell

Cloud Shell adalah lingkungan command line yang berjalan di Google Cloud dan sudah dilengkapi dengan alat yang diperlukan.

1. Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
2. Setelah terhubung ke Cloud Shell, verifikasi autentikasi Anda:

   gcloud auth list
   

3. Konfirmasi bahwa project Anda telah dikonfigurasi:

   gcloud config get project
   

4. Jika project Anda tidak ditetapkan seperti yang diharapkan, tetapkan project:

   export PROJECT_ID=<YOUR_PROJECT_ID>
   gcloud config set project $PROJECT_ID
   

Mengaktifkan API

Jalankan perintah berikut di Cloud Shell untuk mengaktifkan API yang diperlukan:

gcloud services enable sqladmin.googleapis.com \
                       aiplatform.googleapis.com

3. Meng-clone repositori demo

Sekarang, dapatkan kode untuk Demo Memori Aktif.

1. Clone repositori ke lingkungan Cloud Shell Anda:

   git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
   cd devrel-demos/codelabs/visual-memory-postgres-demo
   

2. Instal dependensinya:

   npm install
   

4. Membuat dan mengonfigurasi database Cloud SQL

Di bagian ini, Anda akan membuat instance Cloud SQL, menginisialisasi database, dan menyiapkan skema.

1. Aplikasi ini menggunakan variabel lingkungan untuk konfigurasi. Jalankan blok berikut di terminal Cloud Shell Anda untuk menetapkan variabel yang diperlukan untuk sesi ini:

   export REGION="us-central1"
   export INSTANCE_NAME="living-memory-db"
   export DB_HOST=127.0.0.1
   export DB_PORT=5432
   export DB_USER=memory_app
   export DB_PASS=memory_app_password
   export DB_NAME=living_memory
   export PGPASSWORD=$DB_PASS
   

   Aplikasi ini menggunakan Gemini Enterprise Agent Platform untuk embedding dan chat, dan akan otomatis diautentikasi menggunakan Kredensial Default Aplikasi Cloud Shell.

2. Buat instance. Langkah ini biasanya memerlukan waktu 5-10 menit.

   gcloud sql instances create $INSTANCE_NAME \
       --database-version=POSTGRES_16 \
       --cpu=1 \
       --memory=3840MB \
       --region=$REGION \
       --root-password=$DB_PASS \
       --edition=ENTERPRISE
   

   Saat instance dibuat, luangkan waktu untuk memahami skema database yang akan Anda gunakan. Skrip ini mengaktifkan ekstensi vector dan membuat beberapa tabel untuk mendukung aplikasi:
   • users, conversations, messages: Tabel standar untuk menyimpan profil pengguna dan histori percakapan.
   • memories: Ini adalah tabel inti untuk Retrieval-Augmented Generation (RAG). Setiap baris mewakili informasi yang diekstrak dari percakapan (misalnya, "Pengguna suka mendaki"). Tabel ini menyimpan:
     • content: Teks memori.
     • memory_type: Jenis memori (FACT, PREF, atau IMPLICIT).
     • embedding: Kolom vector 768 dimensi yang berisi representasi semantik konten, yang dihasilkan oleh Gemini.
   • pgvector Indeks: Indeks HNSW (Hierarchical Navigable Small World) dibuat di kolom embedding. Hal ini penting untuk mengoptimalkan penelusuran k-Nearest Neighbor (k-NN), sehingga pgvector dapat dengan cepat menemukan memori yang paling mirip secara semantik menggunakan operator jarak kosinus (<=>).
3. Membuat Database

   gcloud sql databases create $DB_NAME --instance=$INSTANCE_NAME
   

4. Membuat Pengguna Aplikasi

   gcloud sql users create $DB_USER --instance=$INSTANCE_NAME --password=$DB_PASS
   

5. Memulai Proxy Auth Cloud SQL. Proxy ini memberikan akses yang aman ke instance Anda tanpa perlu mengonfigurasi daftar yang diizinkan IP.

   (cloud-sql-proxy ${GOOGLE_CLOUD_PROJECT}:us-central1:living-memory-db &) && sleep 2 && echo ""
   

   Anda akan melihat pesan seperti: The proxy has started successfully and is ready for new connections!.

   Untuk mengetahui detail selengkapnya tentang proxy atau petunjuk untuk menjalankannya di mesin lokal Anda (di luar Cloud Shell), lihat dokumentasi Proxy Auth Cloud SQL resmi.

6. Terapkan schema.sql untuk mengaktifkan ekstensi vector dan membuat tabel yang diperlukan. Karena proxy sedang berjalan, Anda kini dapat terhubung ke instance di 127.0.0.1.

   psql -h 127.0.0.1 -U $DB_USER -d $DB_NAME < schema.sql
   

7. Pastikan pembuatan skema berhasil.

   psql -h 127.0.0.1 -U $DB_USER -d $DB_NAME -c "\dt"
   

   Anda akan melihat output yang mencantumkan tabel conversations, memories, messages, dan users.

                     List of relations
   Schema |     Name      | Type  |   Owner    
   --------+---------------+-------+------------
   public | conversations | table | memory_app
   public | memories      | table | memory_app
   public | messages      | table | memory_app
   public | queries_log   | table | memory_app
   public | users         | table | memory_app
   (5 rows)
   

5. Memahami pengambilan semantik dengan pgvector

Di bagian ini, Anda akan memeriksa cara aplikasi mengambil konteks yang relevan untuk AI sebelum membuat respons. Cuplikan berikut dari server.js menunjukkan kode yang bertanggung jawab untuk hal ini di endpoint /api/chat:

// Retrieve Similar Memories for Context (Using pgvector)
const promptEmbeddingRes = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  contents: message,
  config: { outputDimensionality: 768 },
});

const promptEmbedding = promptEmbeddingRes.embeddings[0].values;
const embeddingStr = `[${promptEmbedding.join(',')}]`;

// Query DB for top 5 closest memories
const relevantMemories = await pool.query(
  `SELECT id, content, memory_type, category 
   FROM memories 
   WHERE user_id = $1 
   ORDER BY embedding <=> $2::vector 
   LIMIT 5`,
  [userId, embeddingStr]
);

Cara kerjanya

• AI Generatif (Embedding): Aplikasi ini mengambil pesan masuk pengguna dan menggunakan model gemini-embedding-001 untuk mengonversi teks menjadi vektor 768 dimensi. Vektor ini mewakili makna semantik pesan.
• Cloud SQL (pgvector): Aplikasi ini meneruskan vektor tersebut ke Cloud SQL. Menggunakan operator <=> (jarak kosinus) yang disediakan oleh ekstensi pgvector, Cloud SQL menemukan 5 memori yang paling mirip secara semantik dengan perintah.
• Hasilnya: Ini adalah Retrieval-Augmented Generation (RAG). AI mendapatkan akses ke memori tertentu yang relevan dari database untuk mempersonalisasi responsnya, tanpa perlu memuat seluruh histori.

6. Memahami ekstraksi memori

Selanjutnya, lihat cara aplikasi mempelajari percakapan. Cuplikan berikut berasal dari fungsi extractMemoriesAsync di server.js:

// MEMORY EXTRACTION LOGIC
async function extractMemoriesAsync(userMessage, userId, messageId) {
  const extractionPrompt = `
    Analyze the following user message. A memory profile is being built for this user.
    Extract ANY explicit facts (Facts), preferences (Pref), or implicit behavioral traits/styles (Implicit).
    Return the result as a raw JSON array of objects (NO Markdown blocks, just the JSON array).
    Format: [{"content": "string fact/sentence", "type": "FACT|PREF|IMPLICIT", "category": "General|Travel|Hobby|Persona"}]
    If nothing is found, return [].
    Message: "${userMessage}"
    `;

  const result = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: extractionPrompt
  });
  let rawJson = result.text.replace(/^```json/g, '').replace(/```$/g, '').trim();

  let extracted;
  try {
    extracted = JSON.parse(rawJson);
  } catch (e) {
    console.warn("Could not parse extracted JSON:", rawJson);
    return;
  }

  if (Array.isArray(extracted) && extracted.length > 0) {
    // Compute embeddings and save each to the DB
    for (const memory of extracted) {
      const embedRes = await ai.models.embedContent({
        model: 'gemini-embedding-001',
        contents: memory.content,
        config: { outputDimensionality: 768 },
      });
      const vectorData = `[${embedRes.embeddings[0].values.join(',')}]`;

      await pool.query(
        `INSERT INTO memories (user_id, content, memory_type, category, embedding, source_message_id)
                 VALUES ($1, $2, $3, $4, $5, $6)`,
        [userId, memory.content, memory.type.toUpperCase(), memory.category, vectorData, messageId]
      );
      console.log(`Saved new memory: ${memory.content}`);
    }
  }
}

Cara kerjanya

• AI Generatif (Output Terstruktur): Aplikasi ini menggunakan model gemini-2.5-flash yang sangat cepat untuk menganalisis pesan pengguna dan mengekstrak fakta dan preferensi terstruktur sebagai array JSON.
• Cloud SQL (Penyimpanan Hybrid): Setelah membuat embedding untuk fakta baru ini, fakta tersebut akan disimpan di Cloud SQL. Perhatikan bahwa data relasional standar (ID Pengguna, konten teks, kategori) disimpan tepat di samping data vektor berdimensi tinggi dalam satu baris.
• Hasilnya: Aplikasi ini membuat profil memori yang diperbarui sendiri secara real time, dengan memanfaatkan kemampuan analisis Gemini dan kemampuan penyimpanan Cloud SQL.

7. Menjalankan aplikasi chat

1. Isi database dengan beberapa contoh pengguna

   npm run seed
   

   
2. Kemudian, jalankan server

   node server.js
   

3. Di Cloud Shell, klik Web Preview di kanan atas toolbar terminal, lalu pilih Change Port. Masukkan 3000 untuk nomor port, lalu klik Change and Preview.

Berinteraksi dengan asisten

Saat aplikasi terbuka di browser, Anda akan melihat antarmuka chat Memori Aktif. Di sebelah kanan, AI Cortex Data Visualizer menampilkan memori sebagai node di ruang vektor, yang diberi kode warna berdasarkan jenis (Fakta, Preferensi, Karakteristik Implisit). Teks pada node memori mungkin kecil, bergantung pada resolusi layar Anda. Gunakan mouse atau trackpad untuk memperbesar dan menggeser tampilan agar dapat melihat lebih dekat.

Membuat kueri memori yang ada

Skrip seed yang Anda jalankan sebelumnya membuat dua contoh pengguna dengan beberapa memori yang telah diisi sebelumnya.

1. Pilih pengguna dari menu dropdown pengguna di kiri atas.
2. Gunakan salah satu tombol chat cepat atau ketik Give me restaurant recommendations in New York City ke dalam input chat, lalu tekan Send.
3. Saat asisten merespons, Anda dapat mengklik pesan asisten untuk melihat memori yang digunakan. Memori tersebut akan ditandai dengan warna hijau dan Anda dapat memperbesar tampilan untuk melihatnya serta melihat bagaimana memori tersebut membantu membentuk respons.

Membuat pengguna baru

Sekarang, mari kita buat pengguna baru.

1. Klik tombol + di samping dropdown pengguna untuk memulai sesi chat baru.
2. Gunakan nama dan deskripsi yang dibuat atau edit untuk mendeskripsikan diri Anda.
3. Klik Create dan lihat aplikasi mulai mengekstrak memori. Dalam waktu sekitar 30 detik, Anda akan melihat node baru muncul di visualizer di sebelah kanan. Node ini mewakili fakta dan preferensi yang diekstrak Gemini dari pesan Anda dan disimpan dalam database Cloud SQL.
4. Ajukan pertanyaan lanjutan seperti What food do I like? untuk melihat asisten menggunakan memori yang baru diperoleh dalam percakapan.

8. Pembersihan

Untuk menghindari biaya berkelanjutan ke akun Google Cloud Anda untuk resource yang digunakan dalam codelab ini, Anda harus menghapus resource yang Anda buat.

1. Hapus instance Cloud SQL:

   gcloud sql instances delete $INSTANCE_NAME --quiet
   

2. Hapus repositori demo:

   rm -rf ~/devrel-demos
   

9. Selamat

Anda telah berhasil membangun dan men-deploy asisten AI "Memori Aktif"!

Yang telah Anda pelajari

• Cara menggunakan Cloud SQL pgvector untuk penelusuran semantik.
• Cara menggunakan Gemini untuk ekstraksi memori dinamis.

Langkah berikutnya

• Pelajari dokumentasi Cloud SQL pgvector.
• Pelajari lebih lanjut tentang kemampuan Gemini API.
• Pelajari Proxy Auth Cloud SQL secara mendalam.
• Coba sesuaikan extractionPrompt di server.js untuk mengekstrak berbagai jenis data.

Selamat membangun dengan Memori Aktif.