Belajar ChromaDB - Konsep Dasar & Arsitektur Utama

#Pendahuluan

Setelah memahami mengapa ChromaDB ada, episode 2 ini membawa kalian ke dalam mesinnya: konsep dasar dan arsitektur utama. Ini adalah episode paling penting untuk dipahami sebelum mulai ngoding, karena hampir semua kode di series ini berputar di sekitar satu primitif: Collection.

Kita akan membahas model data, dua mode penjalanan (embedded dan client-server), perbedaan server Python FastAPI lawas dengan server Rust modern, serta bagaimana query mengalir dari teks menjadi hasil. Jika kalian memahami episode ini dengan baik, episode 3 sampai 20 akan terasa seperti variasi dari satu tema besar.

#Model Data: Collection

#Empat Pilar Sebuah Collection

Semua data di ChromaDB hidup di dalam Collection, semacam tabel di database relasional. Setiap collection punya nama unik, dan isinya mengikuti empat komponen utama:

• ids: identitas unik setiap item, setara primary key.
• embeddings: vektor numerik yang merepresentasikan makna, dibangkitkan oleh embedding function.
• documents: teks asli yang diembed, menjadi sumber konteks untuk RAG.
• metadatas: pasangan key-value bebas untuk atribut tambahan seperti tanggal, kategori, atau sumber.

Hubungan keempatnya sederhana: setiap id berpasangan dengan satu embedding, satu document, dan satu dict metadata. Kalian bisa mengisi semuanya sekaligus, atau membiarkan embedding dibangkitkan otomatis dari document.

Empat pilar collection

collection = client.create_collection("berita")
 
collection.add(
    ids=["berita-001", "berita-002"],
    documents=["Inflasi naik dua persen", "Gunung meletus di Jawa Timur"],
    metadatas=[{"kategori": "ekonomi"}, {"kategori": "alam"}],
)

Perhatikan bahwa collection.add(...) tidak menerima argumen embeddings — ChromaDB membangkitkannya dari documents menggunakan embedding function bawaan. Cara ini paling mudah untuk memulai.

#Kenapa Documents dan Embeddings Bisa Berpisah

Model data ini fleksibel: kalian boleh menyimpan embeddings saja tanpa documents (misalnya untuk image embedding), atau sebaliknya. Pemisahan ini penting untuk kasus di episode 19: multimodal dan multi-vector. Untuk RAG teks biasa, kalian memerlukan documents karena itu yang menjadi konteks jawaban LLM.

#Embedded Mode vs Client-Server Mode

ChromaDB punya dua cara berjalan yang sangat berbeda. Perbedaannya menentukan banyak keputusan arsitektur di series ini.

#Embedded Mode: Simple dan Tanpa Server

Dalam mode ini, ChromaDB berjalan di dalam proses aplikasi kalian. Tidak ada port, tidak ada jaringan, tidak ada server terpisah. Kalian cukup membuat klien dan mulai:

PersistentClient embedded

import chromadb
 
client = chromadb.PersistentClient(path="./chroma-data")

Mode ini sempurna untuk development, prototipe, dan aplikasi single-process. Data disimpan ke direktori lokal (./chroma-data pada contoh di atas) lewat PersistentClient(path="./chroma-data"). Ada juga EphemeralClient yang datanya hilang begitu proses berakhir — cocok untuk test.

#Client-Server Mode: Chroma Sebagai Service

Dalam mode ini, ChromaDB berjalan sebagai server terpisah yang diakses banyak klien melalui HTTP. Di sinilah chroma run — server Rust — berperan:

chroma run --path ./chroma-data --port 8000

Klien lalu terhubung lewat HTTP:

HttpClient

import chromadb
 
client = chromadb.HttpClient(host="localhost", port=8000)

Mode ini wajib untuk production multi-process atau multi-service. chromadb.HttpClient(host="localhost", port=8000) adalah gerbang menuju arsitektur terdistribusi yang akan kita bahas dari episode 12 hingga 17.

#Arsitektur Server: Python FastAPI vs Rust

Penting untuk membedakan dua era server ChromaDB, karena masih banyak tutorial lama yang memakai versi Python.

#Server Python FastAPI (Legacy)

Server versi 0.x dan awal 1.x dibangun dengan Python FastAPI. Kelebihannya: mudah dikembangkan dan sama dengan library embedded. Namun ada kelemahan yang membuatnya tidak ideal untuk produksi: performa yang kurang deterministik, penggunaan memori lebih besar, dan — yang paling penting — riwayat celah keamanan, termasuk CVE-2026-45829 yang akan kita bedah di episode 14.

#Server Rust (Rekomendasi Production)

Sejak versi 1.x, ChromaDB memperkenalkan server Rust. Dengan perintah yang sama, chroma run, kini dijalankan binary Rust yang jauh lebih efisien. Keunggulannya:

• Performa lebih cepat dan deterministik.
• Footprint memori lebih kecil.
• Tidak terdampak CVE-2026-45829.

Untuk seluruh episode produksi di series ini, kita akan selalu memakai server Rust. Klien Python dan JavaScript tetap sama — hanya server yang berbeda.

#Alur Query: Dari Pertanyaan ke Hasil

Saat kalian mengirim query, ChromaDB menjalankan alur yang terdiri dari tiga tahap:

1. Embed: teks query diubah menjadi vektor oleh embedding function.
2. Index: vektor query dibandingkan dengan semua vektor di collection memakai index HNSW dan distance function yang dikonfigurasi.
3. Re-rank: hasil jarak terkecil (atau similarity terbesar) disusun dan dikembalikan beserta documents dan metadatas.

query_text ──embed──> vektor ──HNSW search──> kandidat ──re-rank──> hasil

Alur ini berjalan di belakang satu baris collection.query(...). Memahami tahapannya penting karena setiap tahap punya knob pengaturan tersendiri: embedding function di episode 6, filter sebelum index di episode 7, dan parameter HNSW di episode 9.

#Penutup

Episode 2 memberi kalian peta arsitektur ChromaDB: Collection sebagai primitif utama dengan empat pilar (ids, embeddings, documents, metadatas), dua mode penjalanan (embedded dan client-server), perbedaan server Python FastAPI legacy dengan server Rust yang direkomendasikan, serta alur query embed → index → re-rank.

Inti yang harus dibawa pulang:

• Semua data hidup di Collection dengan komponen ids, embeddings, documents, dan metadatas.
• Embedded mode berjalan dalam proses aplikasi; client-server mode memerlukan server dan HTTP.
• Server Rust (chroma run) adalah rekomendasi production, bukan server Python FastAPI.
• Klien Python dan JavaScript bekerja sama dengan kedua jenis server.
• Alur query selalu berjalan: embed, cari di index HNSW, lalu re-rank hasil.

Di episode 3 selanjutnya kita akan mulai menulis kode sungguhan: setup, client, dan collection pertama — membandingkan berbagai jenis klien (Client, PersistentClient, EphemeralClient, HttpClient) dan membuat collection pertama dengan parameter yang tepat. Siapkan environment kalian dari episode 0.