Memvisualisasikan memori asisten AI Anda dengan pgvector Gemini dan Cloud SQL

1. Pengantar

Dalam codelab ini, Anda akan mempelajari cara membangun Demo Living Memory, asisten berteknologi AI yang melacak "kenangan" percakapan Anda untuk memberikan pengalaman yang dipersonalisasi.

Antarmuka pengguna memori aktif

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 bagi developer dengan semua tingkat keterampilan yang tertarik dengan AI dan database, dan memerlukan waktu sekitar 60 menit untuk diselesaikan. Biaya pembuatan resource harus kurang dari $5.

Yang akan Anda lakukan

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

Arsitektur memori aktif

Yang Anda butuhkan

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

2. Sebelum memulai

Penyiapan project

Buat Project Google Cloud

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

Mulai Cloud Shell

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

Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
Setelah terhubung ke Cloud Shell, verifikasi autentikasi Anda:
```
gcloud auth list
```
Pastikan project Anda dikonfigurasi:
```
gcloud config get project
```

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 Living Memory.

Buat clone repositori ke lingkungan Cloud Shell Anda:

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

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.

Aplikasi 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 penyematan dan chat, dan akan otomatis diautentikasi menggunakan Kredensial Default Aplikasi Cloud Shell.
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 sedang 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"). Ini menyimpan:
  - content: Teks memori.
  - memory_type: Jenis memori (FACT, PREF, atau IMPLICIT).
  - embedding: Kolom vector berdimensi 768 yang berisi representasi semantik konten, yang dibuat oleh Gemini.
- pgvector Indeks: Indeks HNSW (Hierarchical Navigable Small World) dibuat di kolom embedding. Hal ini sangat 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 (<=>).

Membuat Database

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

Buat Pengguna Aplikasi

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

Mulai Proxy Auth Cloud SQL. Proxy 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 (di luar Cloud Shell), lihat dokumentasi resmi Proxy Auth Cloud SQL.
Terapkan schema.sql untuk mengaktifkan ekstensi vector dan membuat tabel yang diperlukan. Karena proxy sedang berjalan, Anda kini dapat terhubung ke instance Anda di 127.0.0.1.
```
psql -h 127.0.0.1 -U $DB_USER -d $DB_NAME < schema.sql
```

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

6. Memahami ekstraksi memori

Selanjutnya, lihat cara aplikasi belajar dari 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 menggunakan model gemini-2.5-flash yang sangat cepat untuk menganalisis pesan pengguna dan mengekstrak fakta dan preferensi terstruktur sebagai array JSON.
Cloud SQL (Hybrid Storage): Setelah membuat embedding untuk fakta baru ini, embedding tersebut disimpan di Cloud SQL. Perhatikan bahwa data relasional standar (ID Pengguna, konten teks, kategori) disimpan bersama data vektor berdimensi tinggi dalam satu baris.
Hasilnya: Aplikasi ini membangun profil memori yang dapat diupdate sendiri secara real-time, dengan memanfaatkan kemampuan analisis Gemini dan kemampuan penyimpanan Cloud SQL.

7. Menjalankan aplikasi chat

Isi database dengan beberapa contoh pengguna
```
npm run seed
```
Kemudian jalankan server
```
node server.js
```
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 Living Memory. Di sebelah kanan, AI Cortex Data Visualizer menampilkan kenangan sebagai node dalam ruang vektor, yang diberi kode warna berdasarkan jenisnya (Fakta, Preferensi, Ciri Implisit). Teks pada node memori mungkin kecil, bergantung pada resolusi layar Anda; gunakan mouse atau trackpad untuk melakukan zoom dan menggeser agar dapat melihat lebih dekat.

Antarmuka pengguna memori aktif

Membuat kueri kenangan yang ada

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

Pilih pengguna dari menu dropdown pengguna di kiri atas.
Gunakan salah satu tombol chat cepat atau ketik Give me restaurant recommendations in New York City di input chat, lalu tekan Kirim.
Saat asisten merespons, Anda dapat mengklik pesan asisten untuk melihat memori yang digunakannya. Bagian tersebut akan ditandai dengan warna hijau dan Anda dapat memperbesar bagian tersebut serta melihat bagaimana bagian tersebut membantu membentuk respons.

Membuat pengguna baru

Sekarang, mari buat pengguna baru.

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

8. Pembersihan

Agar tidak menimbulkan biaya berkelanjutan pada akun Google Cloud Anda untuk resource yang digunakan dalam codelab ini, Anda harus menghapus resource yang Anda buat.

Hapus instance Cloud SQL:

gcloud sql instances delete $INSTANCE_NAME --quiet

Hapus repositori demo:
```
rm -rf ~/devrel-demos
```

9. Selamat

Anda telah berhasil membuat dan men-deploy asisten AI "Kenangan Abadi".

Yang telah Anda pelajari

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

Langkah berikutnya

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

Nikmati pembuatan dengan Living Memory!