Tutorial lengkap Qdrant: daripada melancarkan Docker hingga carian vektor bertapis, bina lapisan asas RAG pertama anda

Orang yang membuat RAG kebanyakannya pernah melalui peringkat yang sama: mula-mula simpan vektor dalam satu list di dalam memori, kira cosine similarity dengan numpy, dan berjalan dengan gembira. Kemudian jumlah data mencapai seratus ribu rekod, pertanyaan mula mengambil beberapa saat, barulah anda sedar sudah tiba masa mencari pangkalan data vektor yang sebenar.

Qdrant ialah salah satu pilihan yang paling kerap disyorkan pada peringkat ini. Ia pangkalan data vektor sumber terbuka yang ditulis dalam Rust, mudah dihos sendiri, cekap penggunaan memori, dan fungsi tapisannya direka lebih lengkap berbanding produk sejenis.

Tutorial ini akan membawa anda daripada sifar hingga boleh guna: melancarkan, mencipta jadual, menulis, mencari, menapis, serta beberapa lubang perangkap yang patut diketahui sejak awal.

Apa ini

Apa yang dilakukan Qdrant, dalam satu ayat: menyimpan vektor berdimensi tinggi, dan mencari beberapa rekod yang paling serupa dengan vektor pertanyaan anda dalam beberapa milisaat.

Tetapi ia bukan sekadar mengira keserupaan. Setiap vektor boleh membawa satu payload (anda boleh anggap ia metadata), yang menyimpan sebarang data JSON — tajuk dokumen, pengarang, tarikh, harga, status stok. Ketika mencari, anda boleh melakukan "keserupaan semantik" dan "tapisan syarat payload" secara serentak, dan inilah kemampuannya yang paling bernilai dalam senario RAG.

Mengapa tapisan begitu penting? Kerana banyak maklumat tidak dapat dimasukkan ke dalam vektor. Dokumentasi rasmi menyatakannya dengan jelas: apabila sesetengah ciri objek mustahil dinyatakan dengan vektor terbenam (contohnya status stok atau julat harga), menetapkan syarat tambahan menjadi perlu. Anda tentu tidak mahu RAG mencadangkan dokumen lama yang sudah ditarik keluar tiga tahun lalu.

Apa yang boleh dilakukan

Secara praktikal, kegunaan yang paling lazim ialah:

• Lapisan capaian RAG: potong dokumen kepada ketulan, terbenamkan, simpan ke dalam Qdrant, dan ketika bertanya dapatkan semula perenggan paling relevan untuk disuap kepada LLM.
• Carian semantik: carian dalam laman tidak lagi hanya bergantung pada padanan kata kunci, dan mampu memahami bahawa "komputer riba murah" dan "notebook berpatutan" ialah perkara yang sama.
• Sistem cadangan: cari item serupa menggunakan vektor terbenam produk atau kandungan.
• Penyahduaan dan pengesanan keserupaan: cari data yang kandungannya berulang atau sangat serupa.

Cara guna (langkah demi langkah)

Langkah satu: lancarkan dengan Docker

Cara permulaan paling pantas ialah Docker:

docker pull qdrant/qdrant

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

Selepas ia berjalan, ada tiga port yang perlu diingati:

• localhost:6333 — REST API
• localhost:6333/dashboard — antara muka pengurusan web (amat disyorkan dibuka untuk dilihat, sangat membantu dalam penyahpepijatan)
• localhost:6334 — gRPC

Pelekapan -v itu sangat penting. Tanpanya, data hilang sebaik kontena berhenti, dan inilah lubang perangkap pertama yang paling lazim bagi pemula.

Langkah dua: pasang dan sambung ke client

Contohnya dengan Python:

pip install qdrant-client

from qdrant_client import QdrantClient

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

Secara rasmi turut disediakan client JavaScript, Rust, Java, C# dan Go, dengan konsep sintaks yang selari.

Langkah tiga: cipta collection

Collection setara dengan table dalam pangkalan data hubungan. Ketika menciptanya, dua perkara perlu 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 mesti sama tepat dengan dimensi output model terbenam anda; salah isi akan menyebabkan ralat ketika menulis. Metrik jarak menyokong hasil darab dalaman (DOT), kosinus (COSINE) dan jarak Euclidean (EUCLID).

Cadangan praktikal: jika anda menggunakan OpenAI atau kebanyakan model terbenam sumber terbuka, memilih COSINE biasanya paling stabil. Melainkan anda pasti output model sudah dinormalkan, jangan lalai menggunakan DOT.

Langkah empat: tulis 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": "Kuala Lumpur", "category": "tech", "price": 1200},
        ),
        PointStruct(
            id=2,
            vector=[0.19, 0.81, 0.75, 0.11],
            payload={"city": "Penang", "category": "food", "price": 300},
        ),
    ],
)

Perhatikan wait=True. Ia akan menunggu sehingga penulisan selesai barulah kembali — pada peringkat ujian wajib dihidupkan, kalau tidak anda akan tidak menemui data pada baris seterusnya lalu meragui hidup. Pada persekitaran pengeluaran ketika penulisan berkelompok, ia boleh dimatikan untuk meningkatkan daya pemprosesan.

Langkah lima: cari dan tapis

Inilah bahagian Qdrant yang paling patut dipelajari. Syarat tapisan mempunyai tiga klausa, yang boleh digabung dan disarangkan sesuka hati:

• must — semua syarat mesti dipenuhi, setara dengan AND
• should — sekurang-kurangnya satu dipenuhi, setara dengan OR
• must_not — semua syarat tidak boleh dipenuhi, setara dengan NOT A AND NOT B

Satu contoh sebenar:

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

Maksud bahagian ini: bandarnya Kuala Lumpur, dan kategorinya bukan makanan. Selain padanan tepat, ia turut menyokong pertanyaan julat (julat harga), carian geospatial, padanan teks penuh dan tapisan objek bersarang.

Teknik lanjutan

Wajib bina indeks payload. Secara rasmi disyorkan dengan jelas: bina indeks payload untuk medan yang kerap digunakan untuk menapis, kalau tidak tapisan akan merosot menjadi imbasan seluruh jadual. Inilah lubang perangkap prestasi yang paling mudah dipijak sekali gus paling mudah dibaiki.

Fikirkan skema payload dengan jelas dahulu. Vektor boleh dikira semula, tetapi struktur payload menyakitkan untuk diubah. Sebelum bermula, fikirkan dahulu syarat apa yang akan anda gunakan untuk menapis pada masa depan — julat masa? Peringkat kebenaran? Sumber data? Dalam sistem RAG, tapisan kebenaran "adakah pengguna ini boleh melihat dokumen ini" hampir pasti akan digunakan, jadi jangan tunggu sehingga siap barulah ditambah.

Gunakan dashboard untuk menyahpepijat. localhost:6333/dashboard membolehkan anda terus melihat status collection, menyemak points dan mencuba pertanyaan. Jauh lebih pantas daripada print sepanjang jalan.

Matikan wait ketika penulisan berkelompok. Ketika penulisan besar-besaran, wait=True akan melambatkan kelajuan dengan teruk; tukar kepada menghantar secara berkelompok dan sahkan sekali sahaja selepas itu.

Gunakan nilai bermakna untuk id. Qdrant menyokong integer dan UUID sebagai id. Gunakan kunci utama data asal anda atau cincangannya, supaya ketika mengindeks semula ia dapat ditindih dengan betul dan bukan menghasilkan pendua.

Perkara yang perlu diberi perhatian

Rancang memori dengan kiraan dahulu. Pangkalan data vektor makan memori; cara anggaran kasar ialah "bilangan vektor × dimensi × 4 bait" ditambah overhed indeks dan payload. Sejuta vektor 1536 dimensi, vektor asal sahaja sudah lebih kurang 6GB. Apabila jumlah data besar, kaji pilihan pengkuantuman (quantization) dan storan on-disk Qdrant.

Salah isi dimensi tidak dapat diselamatkan. Dimensi vektor collection sebaik dicipta tidak boleh diubah, hanya boleh dibina semula. Sangat mudah terperangkap ketika menukar model terbenam.

Jangan jadikan Qdrant sebagai pangkalan data utama. Ia lapisan capaian; dokumen asal dan data perniagaan patut disimpan dalam pangkalan data asal anda, dan payload Qdrant hanya menyimpan medan yang diperlukan untuk capaian dan tapisan. Mencampuraduknya menyukarkan penyelenggaraan kemudian hari.

Jangan pandang rendah kos operasi hos sendiri. Docker mudah dijalankan, tetapi sandaran, pemantauan, pengembangan dan naik taraf versi semuanya memerlukan orang menjaga. Jika pasukan tiada tenaga operasi, Qdrant Cloud atau penyelesaian terurus lain mungkin lebih berbaloi.

Komen TheAI Academy

Pengalaman saya sendiri, pemilihan pangkalan data vektor sebenarnya tidaklah sekritikal yang disangka — Qdrant, Weaviate dan Milvus perbezaannya terhad pada carian keserupaan asas, dan yang sebenarnya menentukan kualiti RAG ialah strategi memotong ketulan, model terbenam dan penyusunan semula (rerank).

Tetapi jika perlu memilih satu sebab untuk memilih Qdrant, saya katakan ia fungsi tapisan. Reka bentuk must/should/must_not-nya bersih, boleh disarangkan dan digabung, serta prestasinya direka dengan bersungguh (dengan syarat anda telah membina indeks). Dalam senario RAG perusahaan sebenar, tapisan kebenaran dan tapisan ketepatan masa ialah keperluan mutlak, dan pada waktu itu kemampuan tapisan bertukar daripada "nilai tambah" kepada "keperluan".

Satu lagi manfaat praktikal ialah ambang hos sendiri yang rendah. Satu baris docker run sudah boleh menjalankannya, tanpa perlu Kubernetes, tanpa perlu segunung perkhidmatan bersandar. Bagi pasukan yang mahu mengesahkan idea di mesin tempatan dahulu, pekali geseran ini penting.

Komen: Qdrant bukan yang paling pantas, dan bukan yang paling banyak fungsi, tetapi ia antara pangkalan data vektor dengan laluan paling pendek "daripada idea hingga berjalan". Bagi kebanyakan pasukan di Malaysia, ciri ini lebih bernilai daripada markah penanda aras yang cantik.

Cadangan untuk pembangun: jika ini kali pertama membuat RAG, jalankan dahulu keseluruhan aliran di mesin tempatan dengan Docker, kawal jumlah data pada beberapa ribu rekod, dan fokus pada kualiti pemotongan ketulan dan capaian, jangan tergesa-gesa menala prestasi. Setelah kualiti kukuh barulah bincang skala. Jika anda memerlukan GPU untuk menjalankan model terbenam atau LLM tempatan, rujuk Tutorial RunPod kami. Untuk melihat lebih banyak alat berkaitan pembangunan, kategori Rangka Kerja Pembangunan AI dan Infrastruktur di laman ini ada susunannya.

Sumber rujukan

• Dokumentasi permulaan pantas rasmi Qdrant
• Dokumentasi fungsi tapisan rasmi Qdrant

(Artikel ini disusun berdasarkan dokumentasi rasmi; sintaks API adalah tertakluk pada dokumentasi rasmi terkini.)