Tutorial Lengkap Qdrant: Dari Menjalankan Docker hingga Pencarian Vektor Berfilter, Bangun Fondasi RAG Pertama Anda

Orang yang membuat RAG kurang lebih pernah melewati tahap yang sama: mula-mula menyimpan vektor dalam sebuah list di memori, menghitung cosine similarity dengan numpy, dan berjalan menyenangkan. Lalu volume data mencapai ratusan ribu baris, kueri mulai memakan beberapa detik, barulah Anda sadar sudah waktunya mencari basis data vektor sungguhan.

Qdrant adalah salah satu pilihan yang paling sering direkomendasikan di tahap ini. Ia basis data vektor open source yang ditulis dengan Rust, mudah di-self-host, efisien dalam penggunaan memori, dan fitur filternya termasuk yang paling lengkap desainnya di antara produk sejenis.

Tutorial ini membawa Anda dari nol hingga bisa dipakai: menjalankan, membuat tabel, menulis data, mencari, memfilter, serta beberapa jebakan yang sebaiknya diketahui sejak awal.

Ini Apa

Yang dilakukan Qdrant, dalam satu kalimat: menyimpan vektor berdimensi tinggi, dan dalam hitungan milidetik menemukan beberapa data yang paling mirip dengan vektor kueri Anda.

Tetapi ia tak hanya menghitung kemiripan. Tiap vektor bisa dilekati sebuah payload (bisa Anda pahami sebagai metadata) yang memuat data JSON apa pun — judul dokumen, penulis, tanggal, harga, status stok. Saat mencari, Anda bisa sekaligus melakukan "kemiripan makna" dan "filter kondisi payload", dan inilah kemampuan paling bernilai dalam skenario RAG.

Mengapa filter sebegitu penting? Karena banyak informasi tak bisa dijejalkan ke dalam vektor. Dokumentasi resmi menjelaskannya dengan gamblang: ketika sejumlah karakteristik objek mustahil dinyatakan dengan vektor embedding (misalnya status stok atau rentang harga), menetapkan kondisi tambahan menjadi perlu. Anda tentu tak ingin RAG merekomendasikan dokumen lama yang sudah ditarik tiga tahun lalu.

Bisa Melakukan Apa

Dalam praktik, kegunaan yang paling umum ada beberapa:

• Lapisan pencarian RAG: pecah dokumen menjadi potongan, embedding, simpan ke Qdrant, lalu saat kueri ambil kembali paragraf paling relevan untuk disuapkan ke LLM.
• Pencarian makna: pencarian internal situs tak lagi hanya mengandalkan pencocokan kata kunci, mampu memahami bahwa "laptop murah" dan "notebook terjangkau" adalah hal yang sama.
• Sistem rekomendasi: memakai vektor embedding produk atau konten untuk menemukan item serupa.
• Deduplikasi dan deteksi kemiripan: menemukan data yang isinya berulang atau sangat mirip.

Cara Memakainya (Langkah)

Langkah satu: jalankan dengan Docker

Cara memulai tercepat adalah Docker:

docker pull qdrant/qdrant

docker run -p 6333:6333 -p 6334:6334 \
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
    qdrant/qdrant

Setelah berjalan ada tiga port yang perlu diingat:

• localhost:6333 — REST API
• localhost:6333/dashboard — antarmuka manajemen web (sangat disarankan dibuka, sangat membantu debugging)
• localhost:6334 — gRPC

Mount -v itu penting. Tanpa di-mount, begitu kontainer berhenti datanya lenyap, dan ini jebakan pertama yang paling umum bagi pemula.

Langkah dua: pasang dan sambungkan client

Contoh dengan Python:

pip install qdrant-client

from qdrant_client import QdrantClient

client = QdrantClient(url="http://localhost:6333")

Secara resmi juga disediakan client untuk JavaScript, Rust, Java, C#, dan Go, dengan konsep sintaks yang serupa.

Langkah tiga: buat collection

Collection setara dengan table pada basis data relasional. Saat membuatnya, ada dua hal yang harus ditentukan: dimensi vektor dan metrik jarak.

from qdrant_client.models import Distance, VectorParams

client.create_collection(
    collection_name="test_collection",
    vectors_config=VectorParams(size=4, distance=Distance.DOT),
)

size harus persis sama dengan dimensi keluaran model embedding Anda; salah isi akan menyebabkan error saat menulis data. Metrik jarak mendukung inner product (DOT), cosine (COSINE), dan jarak Euclidean (EUCLID).

Saran praktis: jika Anda memakai OpenAI atau mayoritas model embedding open source, memilih COSINE biasanya paling stabil. Kecuali Anda yakin keluaran model sudah dinormalisasi, jangan default memakai DOT.

Langkah empat: menulis vektor (upsert)

from qdrant_client.models import PointStruct

client.upsert(
    collection_name="test_collection",
    wait=True,
    points=[
        PointStruct(
            id=1,
            vector=[0.05, 0.61, 0.76, 0.74],
            payload={"city": "Taipei", "category": "tech", "price": 1200},
        ),
        PointStruct(
            id=2,
            vector=[0.19, 0.81, 0.75, 0.11],
            payload={"city": "Taichung", "category": "food", "price": 300},
        ),
    ],
)

Perhatikan wait=True. Ia menunggu penulisan selesai baru mengembalikan hasil — pada tahap tes wajib diaktifkan, kalau tidak Anda akan gagal menemukan data di baris berikutnya lalu meragukan hidup. Pada lingkungan produksi, saat penulisan batch, ini bisa dimatikan untuk meningkatkan throughput.

Langkah lima: pencarian dan filter

Ini bagian Qdrant yang paling layak dipelajari. Kondisi filter punya tiga klausa yang bisa dikombinasikan dan disarangkan sesuka hati:

• must — semua kondisi harus terpenuhi, setara AND
• should — minimal satu terpenuhi, setara OR
• must_not — semua kondisi tak boleh terpenuhi, setara NOT A AND NOT B

Sebuah contoh nyata:

{
  "filter": {
    "must": [
      { "key": "city", "match": { "value": "Taipei" } }
    ],
    "must_not": [
      { "key": "category", "match": { "value": "food" } }
    ]
  }
}

Maksud potongan ini: kotanya Taipei, dan kategorinya bukan food. Selain pencocokan persis, juga didukung kueri rentang (rentang harga), pencarian geospasial, pencocokan full-text, dan filter objek bersarang.

Teknik Tingkat Lanjut

Wajib membuat indeks payload. Dokumentasi resmi jelas menyarankan: buat indeks payload untuk kolom yang sering dipakai memfilter, jika tidak filter akan merosot menjadi pemindaian seluruh tabel. Ini jebakan performa yang paling mudah terinjak sekaligus paling mudah diperbaiki.

Pikirkan matang-matang skema payload lebih dulu. Vektor bisa dihitung ulang, tetapi mengubah struktur payload sangat menyakitkan. Sebelum mulai, pikirkan dulu kondisi apa yang akan Anda pakai untuk memfilter ke depan — rentang waktu? Tingkat izin? Sumber data? Dalam sistem RAG, filter izin "boleh-tidaknya pengguna ini melihat dokumen ini" hampir pasti terpakai, jangan menambahkannya baru setelah selesai.

Debug dengan dashboard. localhost:6333/dashboard bisa langsung melihat status collection, menelusuri points, dan mencoba kueri. Jauh lebih cepat daripada print terus-menerus.

Matikan wait saat penulisan batch. Saat penulisan massal, wait=True akan sangat memperlambat; ubah menjadi kirim batch lalu konfirmasi sekali saja.

Pakai nilai yang bermakna untuk id. Qdrant mendukung integer dan UUID sebagai id. Pakai primary key data asli Anda atau hash-nya, agar saat mengindeks ulang bisa menimpa dengan benar alih-alih menghasilkan duplikat.

Hal yang Perlu Diperhatikan

Perencanaan memori harus dihitung dulu. Basis data vektor rakus memori; cara kasar mengestimasinya "jumlah vektor x dimensi x 4 byte" ditambah overhead indeks dan payload. Satu juta vektor berdimensi 1536, vektor mentahnya saja sekitar 6GB. Saat volume data besar, pelajari opsi kuantisasi (quantization) dan penyimpanan on-disk Qdrant.

Salah isi dimensi tak bisa diselamatkan. Dimensi vektor collection begitu dibuat tak bisa diubah, hanya bisa dibuat ulang. Terutama mudah terinjak saat mengganti model embedding.

Jangan jadikan Qdrant basis data utama. Ia lapisan pencarian; dokumen asli dan data bisnis semestinya disimpan di basis data Anda semula, dan payload Qdrant hanya memuat kolom yang dibutuhkan untuk pencarian dan filter. Mencampurnya akan sangat sulit dipelihara ke depan.

Jangan meremehkan biaya operasional self-host. Menjalankan Docker sangat mudah, tetapi backup, pemantauan, penambahan kapasitas, dan upgrade versi semuanya perlu ditangani orang. Jika tim tak punya tenaga operasional, Qdrant Cloud atau layanan terkelola lain mungkin lebih ekonomis.

Ulasan TheAI Academy

Pengalaman saya sendiri: pemilihan basis data vektor sebenarnya tak sekrusial yang dibayangkan — Qdrant, Weaviate, dan Milvus selisihnya terbatas pada pencarian kemiripan dasar; yang benar-benar menentukan kualitas RAG adalah strategi chunking, model embedding, dan reranking.

Tetapi jika harus memilih satu alasan memakai Qdrant, saya akan menyebut fitur filternya. Desain must/should/must_not-nya bersih, bisa disarangkan, dan performanya dirancang dengan serius (dengan syarat Anda membuat indeks). Dalam skenario RAG perusahaan yang nyata, filter izin dan filter kebaruan adalah kebutuhan yang niscaya, dan di sinilah kemampuan filter berubah dari "nilai tambah" menjadi "keharusan".

Keuntungan nyata lain adalah ambang self-host yang rendah. Satu baris docker run sudah bisa jalan, tak perlu Kubernetes, tak perlu setumpuk layanan dependen. Bagi tim yang ingin memvalidasi ide dulu di mesin lokal, koefisien gesekan ini penting.

Ulasan: Qdrant bukan yang tercepat, bukan pula yang paling banyak fiturnya, tetapi ia salah satu basis data vektor dengan jalur terpendek dari "ide ke berjalan". Bagi mayoritas tim di Indonesia, sifat ini lebih bernilai daripada angka benchmark yang cantik.

Saran bagi pengembang di Indonesia: jika baru pertama membuat RAG, jalankan dulu seluruh alur di mesin lokal dengan Docker, jaga volume data pada beberapa ribu baris, curahkan perhatian pada kualitas chunking dan pencarian, jangan buru-buru menyetel performa. Setelah kualitas kokoh baru bicara skala. Jika Anda butuh GPU untuk menjalankan model embedding atau LLM lokal, lihat Tutorial RunPod kami. Untuk melihat lebih banyak alat pengembangan, kategori Framework Pengembangan dan Infrastruktur AI di situs punya rangkumannya.

Sumber Data

• Dokumentasi Quickstart resmi Qdrant
• Dokumentasi fitur filter resmi Qdrant

(Artikel ini disusun berdasarkan dokumentasi resmi, sintaks API mengacu pada dokumentasi resmi terbaru.)