Simpan dan cari embedding Ollama di PostgreSQL dengan pgvector

README pgvector menggambarkannya sebagai pencarian kemiripan vektor open source untuk Postgres. Ia mendukung pencarian nearest neighbor yang eksak maupun aproksimasi; vektor presisi tunggal, setengah presisi, biner, dan sparse; serta jarak L2, inner product, jarak kosinus, jarak L1, jarak Hamming, dan jarak Jaccard. Karena vektornya adalah kolom PostgreSQL biasa, vektor itu juga mendapatkan kepatuhan ACID, point-in-time recovery, dan JOIN.

Untuk pencarian di dokumen Anda, Anda menyimpan satu baris per chunk berisi teks dan vektornya, membuat embedding untuk pertanyaan dengan model yang sama, lalu mengurutkan baris berdasarkan jaraknya ke vektor pertanyaan.

pgvector mendukung PostgreSQL 13 dan yang lebih baru. README mencantumkan beberapa cara instalasi, termasuk berikut ini:

Kolom bertipe vector(n) menyimpan vektor dengan tepat n dimensi, dan n harus sama dengan panjang vektor dari model embedding Anda. Vektor dengan panjang berbeda ditolak: ketika kami memasukkan vektor 2 dimensi ke kolom vector(3), PostgreSQL mengembalikan "expected 3 dimensions, not 2". all-minilm mengembalikan 384 dimensi, jadi kolomnya vector(384).

README menyebutkan penyimpanan setiap vektor sebesar 4 × dimensi + 8 byte, dengan setiap elemen berupa bilangan floating-point presisi tunggal, dan mengizinkan hingga 16,000 dimensi dalam satu kolom. Indeks mendukung dimensi yang lebih sedikit, seperti ditunjukkan di bawah. Tipe halfvec menyimpan nilai setengah presisi dalam 2 × dimensi + 8 byte.

pgvector membaca vektor sebagai teks dalam tanda kurung siku, seperti '[1,2,3]', dan README mengatakan semua elemen harus terhingga (tanpa NaN, Infinity, atau -Infinity). Setiap array di bidang embeddings pada respons /api/embed sudah berbentuk seperti ini, dan respons mempertahankan urutan input, sehingga teks pertama cocok dengan vektor pertama.

README menampilkan INSERT untuk beberapa baris, INSERT … ON CONFLICT untuk upsert, dan COPY untuk pemuatan massal. Konverter di bawah memasangkan teks Anda dengan respons dan menulis pernyataan INSERT dengan tanda kutip yang sudah di-escape. Kami menjalankan keluarannya dengan teks yang berisi tanda kutip, backslash, pemisah baris, dan emoji, dan semuanya kembali tanpa berubah.

Dokumentasi Ollama merekomendasikan kemiripan kosinus untuk sebagian besar kasus pencarian semantik dan mengatakan /api/embed mengembalikan vektor dengan panjang 1. Untuk vektor seperti itu, jarak kosinus, jarak L2, dan inner product mengurutkan baris dengan urutan yang sama, karena kuadrat jarak L2 sama dengan 2 dikurangi 2 kali kemiripan kosinus. Pada uji kami dengan all-minilm, tiga baris teratas sama pada ketiganya, dan jarak L2 sebesar 0.931 sesuai dengan kemiripan kosinus 0.566.

Setiap jarak punya operatornya sendiri. Sebuah pencarian mengurutkan berdasarkan operator itu dan mengambil baris pertama dengan LIMIT, dan indeks dibuat untuk satu operator class.

Tanpa indeks, pgvector melakukan pencarian nearest neighbor yang eksak, yang menurut README memberi recall sempurna. Indeks aproksimasi menukar sebagian recall dengan kecepatan, dan README memperingatkan bahwa kueri bisa mengembalikan hasil yang berbeda setelah Anda menambahkannya.

Indeks hanya dipakai jika kueri memiliki ORDER BY dan LIMIT, dan ORDER BY-nya adalah operator jarak itu sendiri dengan urutan menaik. ORDER BY embedding <=> $1 LIMIT 5 dapat memakai indeks; ORDER BY 1 - (embedding <=> $1) DESC tidak bisa. README juga mencatat bahwa pemindaian tabel mungkin lebih cepat ketika tabelnya kecil.

Dengan HNSW, hasilnya dibatasi oleh hnsw.ef_search, yang secara default 40. Pada tabel uji berisi 200 baris dengan indeks HNSW, LIMIT 100 mengembalikan 40 baris; setelah SET hnsw.ef_search = 100, ia mengembalikan 100 baris. Atur hnsw.ef_search minimal sebesar jumlah baris yang Anda butuhkan. SET LOCAL di dalam transaksi mengubahnya hanya untuk satu kueri.

Pemfilteran juga mengurangi hasil. Pada indeks aproksimasi, README mengatakan kondisi WHERE diterapkan setelah indeks dipindai: jika suatu kondisi cocok dengan 10% baris, HNSW dengan hnsw.ef_search default 40 hanya mengembalikan rata-rata 4 baris. Sejak versi 0.8.0, pemindaian indeks iteratif (SET hnsw.iterative_scan = strict_order, atau relaxed_order) memindai lebih banyak indeks sampai baris yang cukup ditemukan, hingga hnsw.max_scan_tuples (20,000 secara default).

Setelah pencarian mengembalikan baris terdekat, model membutuhkannya di dalam prompt. /api/chat milik Ollama menerima daftar pesan, masing-masing dengan sebuah peran (system, user, assistant, atau tool) dan isinya. Susunan sederhananya adalah pesan sistem berisi aturan dan pesan pengguna yang mendaftar baris-baris dengan nomor masing-masing, seperti [1] dan [2], diikuti pertanyaannya. Dengan nomor, jawaban dapat menyebut baris mana yang dipakai, dan Anda dapat memetakan setiap nomor kembali ke barisnya.

Agar sitasi berbentuk tetap, beri kolom format sebuah JSON Schema berisi jawaban dan daftar sitasi, masing-masing dengan nomor sumber dan kutipan singkat. Halaman keluaran terstruktur milik Ollama menyarankan agar skemanya juga ditulis di dalam prompt, dan agar temperature diturunkan, misalnya ke 0, supaya keluarannya lebih deterministik. Di psql, fungsi json_agg mengumpulkan baris sebuah kueri menjadi array JSON, yang langsung dibaca oleh alat di bawah.

Aturan, baris, dan pertanyaan harus muat dalam panjang konteks. Halaman panjang konteks milik Ollama menyebut default 4k token untuk VRAM kurang dari 24 GiB, dan FAQ-nya menyebut 4096 token; ollama ps pada mesin uji kami menunjukkan 4096. num_ctx di options atau variabel lingkungan OLLAMA_CONTEXT_LENGTH mengubahnya.

Bila prompt lebih panjang, /api/chat secara default tidak mengembalikan galat. Di kode sumber Ollama (0.40.11), server lebih dulu membuang seluruh pesan sebelumnya sambil mempertahankan pesan sistem dan pesan terakhir. Jika prompt yang tersisa masih terlalu panjang, server mempertahankan beberapa token pertama (num_keep, default 4) dan akhir prompt, lalu membuang bagian di antaranya. Pada uji kami dengan qwen2.5:7b dan num_ctx 1024, prompt 2,068 token terpotong menjadi 514. Pesan sistem dan sumber-sumber pertama hilang: ketika jawabannya ada di sumber [1], model menjawab dengan kata kode yang tidak ada di sumber mana pun, dan ketika jawabannya ada di sumber terakhir, model menjawab dengan benar tetapi tanpa nomor sumber yang diminta pesan sistem. Responsnya tidak berisi galat; log server memuat peringatan "truncating input prompt".

Kode sumber Ollama juga punya kolom truncate untuk permintaan chat, yang tidak tercantum di halaman /api/chat. Dengan "truncate": false, permintaan yang sama mengembalikan HTTP 400 dengan galat "request (2068 tokens) exceeds the available context size (1024 tokens), try increasing it". Kolom prompt_eval_count pada respons adalah jumlah token dalam prompt; pada uji yang terpotong nilainya 514, bukan 2,068.

Sebuah sitasi dapat diperiksa secara mekanis: nomornya harus merujuk ke sumber yang dikirim, dan kutipannya seharusnya muncul di sumber itu. Pada uji kami dengan empat sumber dan qwen2.5:7b, kutipan dalam jawaban JSON cocok dengan sumbernya kata demi kata. Itu tidak membuktikan jawabannya benar: ketika ditanya ukuran vektor 384 dimensi, model mengutip aturan yang benar (4 kali jumlah dimensi ditambah 8 byte) dan tetap menjawab 1552 byte, bukan 1,544.

Perhatikan juga jawaban tanpa sitasi. Ketika sumbernya tidak memuat jawabannya, model sekali menjawab dari pengetahuannya sendiri tanpa sitasi, dan sekali mengatakan tidak tahu tetapi tetap mengutip sumber yang tidak terkait. Jika done_reason pada respons adalah "length", jawabannya terpotong oleh num_predict dan sitasinya mungkin hilang.

README mengatakan indeks HNSW dibuat jauh lebih cepat ketika grafnya muat di maintenance_work_mem, menampilkan notifikasi ketika grafnya tidak lagi muat, dan memperingatkan agar tidak mengatur maintenance_work_mem setinggi itu sampai menghabiskan memori server. Seperti indeks lain, lebih cepat membuat indeks setelah memuat data awal. Indeks tidak harus muat di memori, tetapi Anda kemungkinan akan melihat performa lebih baik jika muat; SELECT pg_size_pretty(pg_relation_size('index_name')) menampilkan ukuran sebuah indeks.

Untuk working set dan indeks yang lebih kecil, README menyarankan halfvec, pengindeksan setengah presisi, atau kuantisasi biner. Jika Ollama berjalan di server yang sama, PostgreSQL dan model berbagi memori yang sama; artikel kami tentang memantau memori Ollama menjelaskan apa yang menentukan seberapa banyak model memakainya.