LangChain.js dan Oracle AI Database: Panduan Pencarian Vektor
Hubungkan LangChain.js ke Oracle AI Database dengan OracleVS, simpan embedding beserta metadata, dan bandingkan similarity search, filter metadata, serta MMR dalam TypeScript.
Model bahasa dapat menjawab pertanyaan umum, tetapi tidak dapat secara andal mencari basis pengetahuan privat kecuali aplikasi terlebih dahulu mengambil informasi yang relevan. Bagi pengembang JavaScript, LangChain.js menyediakan abstraksi yang familier untuk dokumen, embedding, dan retrieval. Bagian yang hilang adalah tempat yang persisten untuk menyimpan dan mencari vektor yang dihasilkan.
Oracle AI Database mengisi peran tersebut melalui integrasi @oracle/langchain-oracledb. Dalam panduan ini, Anda akan menghubungkan alur kerja TypeScript kecil ke Oracle, menyimpan teks beserta metadata, menjalankan similarity search, dan meningkatkan retrieval dengan filter dan maximal marginal relevance (MMR). Tutorial ini berfokus pada alur kerja retrieval; aplikasi TypeScript pendamping menambahkan integrasi yang sama ke UI peramban interaktif.
Apa Itu Integrasi LangChain.js dan Oracle AI Database?
LangChain.js menstandarkan cara aplikasi bekerja dengan model embedding dan vector store. Paket integrasi Oracle menyediakan OracleVS, implementasi vector store yang mempersistenkan teks dokumen, metadata, dan embedding vektor di Oracle AI Database. Aplikasi Anda memanggil metode LangChain.js alih-alih menulis SQL secara manual untuk setiap kueri kemiripan.
Paket integrasi yang sama juga menyertakan OracleDocLoader, OracleTextSplitter, OracleEmbeddings, dan OracleSummary. Itu adalah blok bangunan opsional yang berguna; contoh di bawah berfokus pada OracleVS dan memisahkan pembuatan embedding agar alurnya tetap mudah dipahami.
Ingesti dokumen dan retrieval menggunakan LangChain.js, OracleVS, dan Oracle AI Database
Fitur Utama Integrasi
Menyimpan embedding bersama metadata dokumen
Model embedding mengubah teks menjadi vektor numerik. OracleVS menyimpan vektor ini bersama teks sumber dan metadata terstruktur. Metadata seperti kategori dokumen atau sumber membantu aplikasi membatasi pencarian tanpa membuang konteks yang berguna.
Ambil bagian relevan menggunakan kemiripan vektor
Saat kueri, model embedding yang sama mengonversi pertanyaan menjadi vektor. Oracle membandingkannya dengan vektor yang disimpan menggunakan strategi jarak yang dikonfigurasi, seperti jarak kosinus, dan mengembalikan dokumen terdekat. Hasilnya tetap berupa objek Document LangChain, siap untuk pemrosesan lanjutan.
Kendalikan hasil dengan pemfilteran dan MMR
Similarity search menjawab “item mana yang paling dekat dengan pertanyaan ini?” Filter metadata mempersempit dokumen yang memenuhi syarat. MMR menambahkan tujuan berbeda: menjaga bagian yang dipilih tetap relevan sambil mengurangi hasil yang hampir duplikat. Operasi ini saling melengkapi, bukan saling menggantikan.
Mulai Menggunakan LangChain.js dan Oracle AI Database
Prasyarat
Untuk contoh TypeScript ini, Anda memerlukan Node.js 24.13.0, npm 11.6.2, instance lokal Oracle AI Database 26ai Free dengan dukungan vektor, dan skema yang dapat membuat, melakukan insert, kueri, dan drop tabel demo beserta indeks vektornya. Anda juga memerlukan kunci API OpenAI untuk contoh embedding. OpenAIEmbeddings adalah pilihan yang kompatibel dengan LangChain, bukan persyaratan OracleVS.
Untuk rute lokal utama, ikuti quick start Oracle AI Database Free dari Oracle. Setelah database berjalan, gunakan layanan seperti localhost:1521/FREEPDB1 dan skema dengan hak akses yang tercantum di atas.
Buat file bernama index.ts di folder ini. Tambahkan cuplikan TypeScript yang dapat dieksekusi di bawah ini ke file yang sama, sesuai urutan yang ditunjukkan. Jangan membuat file terpisah untuk setiap cuplikan. Salin hanya cuplikan TypeScript yang dapat dieksekusi: blok SQL dan keluaran perwakilan bersifat penjelasan dan tidak boleh ditempelkan ke index.ts.
Pengaturan package.jsontype=module memungkinkan await tingkat atas yang digunakan oleh contoh. Konfigurasi paket Node.js didokumentasikan dalam panduan paket Node.js resmi.
Paket integrasi Oracle mengimplementasikan vector store, @langchain/core menyediakan Document, @langchain/openai menyediakan model embedding contoh, dan oracledb mengelola koneksi database. Versi di atas cocok dengan aplikasi pendamping; tsx menjalankan contoh TypeScript secara langsung tanpa langkah build terpisah.
Konfigurasikan koneksi
ORACLE_USER=your_schema
ORACLE_PASSWORD=your_password
ORACLE_CONNECT_STRING=localhost:1521/FREEPDB1
OPENAI_API_KEY=your_api_keyDidukung oleh
Simpan nilai ini di file lokal .env dan tambahkan .env ke .gitignore. Artikel ini menggunakan Oracle AI Database Free lokal sebagai penyiapan utama agar langkah-langkahnya dapat direproduksi. Autonomous AI Database adalah alternatif deployment yang valid, tetapi memerlukan deskriptor layanan dan konfigurasi wallet atau TLS untuk lingkungan tersebut.
Pool memungkinkan OracleVS menggunakan ulang sesi database. Simpan semua pernyataan ingest, retrieval, dan verifikasi di dalam blok try. Blok kode berikut memulai blok tersebut, dan cuplikan selanjutnya melanjutkannya. Pool ditutup hanya setelah verifikasi pada bagian pembersihan di bawah. Dalam aplikasi server, inisialisasi pool satu kali dan tutup saat penghentian terkelola dengan baik alih-alih membuka koneksi baru untuk setiap permintaan pengguna.
Cara Membangun Pencarian Dokumen dengan LangChain.js
Kita akan menggunakan 10 catatan basis pengetahuan singkat, termasuk bagian retrieval yang tumpang tindih. Korpus sengaja dibuat kecil, tetapi memungkinkan perbandingan antara similarity search biasa dengan pemfilteran metadata dan MMR.
Definisikan dokumen pengetahuan Anda
try{const documents =[["database-guide","database","Oracle AI Database stores vector embeddings alongside application data."],["connection-pooling","operations","A connection pool reuses Oracle database sessions across requests."],["vector-indexes","performance","HNSW vector indexes can improve nearest-neighbor search as a table grows."],["metadata-filtering","retrieval","Metadata filters restrict retrieval to matching categories or sources."],["similarity-search","retrieval","Similarity search returns chunks closest to the query embedding."],["mmr-retrieval","retrieval","MMR reduces repeated content while keeping results relevant."],["retrieval-overlap-1","retrieval","Similarity search may return several near-duplicate passages when multiple notes explain the same retrieval strategy."],["retrieval-overlap-2","retrieval","Several notes about the same retrieval strategy can produce repetitive top matches; MMR selects a more diverse set while preserving relevance."],["troubleshooting","troubleshooting","For empty results, check ingestion, embeddings, and filters."],["embedding-compatibility","retrieval","Ingestion and query retrieval must use compatible dimensions."],].map(([source, category, pageContent])=>newDocument({ pageContent, metadata:{ source, category }}));Didukung oleh
Setiap Document memiliki pageContent dan metadata. Kolom source dan category mengikuti dokumen melalui ingest dan retrieval, sehingga aplikasi dapat menjelaskan asal hasil dan membatasi pencarian pada subset yang relevan.
Konfigurasikan embedding dan buat OracleVS
const embeddings =newOpenAIEmbeddings({
model:"text-embedding-3-small",});const vectorStore =await OracleVS.fromDocuments(documents, embeddings,{
client: pool,
tableName:"LC_JS_RAG_DEMO",
query:"Oracle AI Database document search",
distanceStrategy: DistanceStrategy.COSINE,
format: VectorElementFormat.FLOAT32,});Didukung oleh
OracleVS.fromDocuments() adalah pemanggilan integrasi utama. Ini menginisialisasi vector store, membuat embedding untuk dokumen yang diberikan, serta menyimpan konten, vektor, dan metadata-nya di Oracle AI Database.
Parameter query menyediakan teks contoh yang di-embed saat inisialisasi untuk menentukan dimensi vektor yang diperlukan untuk tabel database. Ini tidak digunakan untuk mencari dokumen yang disimpan. DistanceStrategy.COSINE menentukan metrik jarak vektor, sementara VectorElementFormat.FLOAT32 mengatur format elemen vektor.
Sebelum menjalankan ulang ingest, gunakan nama tabel demo baru atau kosongkan data yang ada untuk menghindari memasukkan dokumen duplikat.
OracleVS menerima implementasi embedding yang kompatibel dengan LangChain, sehingga pengembang dapat mengganti penyedia embedding tanpa mengubah alur kerja vector store secara keseluruhan. Namun, embedding yang digunakan untuk ingest dan retrieval harus tetap kompatibel dengan kolom vektor Oracle.
OracleVS menentukan dimensi vektor saat inisialisasi menggunakan model embedding yang dikonfigurasi. Untuk memeriksa dimensi dan format penyimpanan vektor yang sudah disimpan di Oracle AI Database, jalankan kueri SQL berikut:
SELECT
VECTOR_DIMENSION_COUNT(embedding)AS vector_dimensions,
VECTOR_DIMENSION_FORMAT(embedding)AS vector_format
FROM LC_JS_RAG_DEMO
FETCHFIRST1ROW ONLY;Didukung oleh
Jika Anda beralih ke model embedding dengan dimensi berbeda, buat tabel vektor yang kompatibel dan bangun ulang embedding dokumen. Bahkan jika dua model menghasilkan vektor dengan dimensi yang sama, ruang embedding-nya bisa berbeda, sehingga dokumen yang ada sebaiknya di-embed ulang sebelum menggunakan model baru untuk retrieval.
Misalnya, pemanggilan berikut meminta vector store OracleVS untuk 3 dokumen terdekat dan mencetak metadata sumber bersama teks setiap potongan:
const retrievalQuestion ="How can vector retrieval reduce repetitive results?";const results =await vectorStore.similaritySearch(
retrievalQuestion,3);console.log(results.map((doc)=>({
source: doc.metadata.source,
text: doc.pageContent,})));Didukung oleh
Kode ini memetakan setiap Document LangChain menjadi objek biasa yang berisi source dan pageContent untuk ditampilkan. Keluaran perwakilan ditunjukkan di bawah; urutan pastinya dapat bervariasi tergantung model embedding dan kueri:
[
{ source: "retrieval-overlap-2", text: "Several notes about the same retrieval strategy can produce repetitive top matches; MMR selects a more diverse set while preserving relevance." },
{ source: "retrieval-overlap-1", text: "Similarity search may return several near-duplicate passages when multiple notes explain the same retrieval strategy." },
{ source: "mmr-retrieval", text: "MMR reduces repeated content while keeping results relevant." }
]Didukung oleh
Argumen pertama adalah pertanyaan pengguna, dan argumen kedua adalah k, jumlah maksimum dokumen yang akan diambil. LangChain.js menggunakan model embedding yang dikonfigurasi untuk mengonversi pertanyaan menjadi vektor, dan Oracle AI Database melakukan similarity search untuk menemukan dokumen yang paling cocok.
Jika setelah menerapkan kondisi pencarian dan filter metadata tersedia kurang dari k dokumen, metode hanya mengembalikan hasil yang tersedia. Objek Document yang diambil berisi teks dan metadata yang dapat ditampilkan dengan atribusi sumber atau diteruskan ke langkah pembuatan jawaban berikutnya.
Periksa skor retrieval
Misalnya, gunakan similaritySearchWithScore saat Anda ingin memeriksa jarak yang terkait dengan setiap dokumen yang diambil:
const scored =await vectorStore.similaritySearchWithScore("Where are document embeddings stored?",3);for(const[doc, score]of scored){console.log({
text: doc.pageContent,
source: doc.metadata.source,
score,});}Didukung oleh
similaritySearchWithScore mengembalikan jarak untuk setiap kecocokan. Nilai numerik dan arahnya bergantung pada strategi jarak yang dikonfigurasi, sehingga bukan persentase keyakinan universal. Bandingkan skor hanya saat menggunakan model embedding dan strategi jarak yang sama, dan periksa bagian yang diambil sebelum memilih ambang batas.
Batasi hasil dengan filter metadata
const databaseOnly =await vectorStore.similaritySearch("Where are vector embeddings stored?",3,{ category:{ $eq:"database"}});console.log(databaseOnly.map((doc)=> doc.metadata.source));Didukung oleh
Argumen ketiga membatasi pencarian ke item dengan category = database. Dalam korpus ini, hasil terfilter yang dapat diprediksi adalah ["database-guide"]. Filter mengubah dokumen yang memenuhi syarat; kemiripan vektor tetap memberi peringkat pada dokumen yang memenuhi syarat.
Gunakan MMR untuk mengurangi hasil yang repetitif
const diverse =await vectorStore.maxMarginalRelevanceSearch(
retrievalQuestion,{
k:3,
fetchK:6,
lambda:0.5,});console.log(diverse.map((doc)=> doc.metadata.source));Didukung oleh
Keluaran perwakilan dari korpus yang tumpang tindih (pengurutan dapat bervariasi antar model embedding dan eksekusi):
["retrieval-overlap-2", "mmr-retrieval", "metadata-filtering"]Didukung oleh
MMR terlebih dahulu mempertimbangkan kumpulan kandidat (fetchK) lalu memilih k dokumen dengan menyeimbangkan relevansi kueri dengan keragaman. lambda yang lebih rendah lebih menekankan keragaman; nilai yang lebih tinggi lebih menekankan relevansi. Dengan korpus tumpang tindih di atas, sumber yang dipilih dapat berbeda dari similarity search biasa, sehingga trade-off retrieval menjadi terlihat.
Ini adalah titik serah antara retrieval LangChain.js dan panggilan model bahasa besar (LLM): aplikasi memiliki pertanyaan plus bukti yang dapat diperiksa, siap untuk prompt yang meminta model menjawab dari konteks tersebut.
Retrieval dan generasi adalah tanggung jawab terpisah. Pada titik ini, context adalah string teks biasa yang dapat dikonsumsi model percakapan. Anda kini dapat memberikannya ke model dengan instruksi untuk menjawab hanya dari materi yang diambil dan menyebutkan pengenal sumber. Integrasi database itu sendiri tetap bekerja bahkan tanpa model percakapan.
Cara Memverifikasi Integrasi
Validasi yang berguna memeriksa ingest dan setiap strategi retrieval secara terpisah. Pertama, konfirmasikan bahwa vector store dibuat tanpa kesalahan database. Lalu periksa metadata sumber yang dikembalikan oleh similarity search, hasil terfilter, dan hasil MMR.
const check =await vectorStore.similaritySearch("How does OracleVS connect to LangChain.js?",3);if(check.length ===0){thrownewError("No documents retrieved; inspect ingestion and filters.");}console.log({
similarity: check.map((doc)=> doc.metadata.source),
filtered: databaseOnly.map((doc)=> doc.metadata.source),
mmr: diverse.map((doc)=> doc.metadata.source),});Didukung oleh
Pembersihan hanya berjalan setelah ingest, retrieval, dan verifikasi selesai. Waktu drain memberikan jendela singkat agar koneksi yang sedang digunakan dapat menyelesaikan tugasnya. Dalam server jangka panjang, biarkan pool tetap terbuka hingga penghentian yang terkelola dengan baik. Lihat dokumentasi pool.close() node-oracledb untuk detail siklus hidup.
Pada titik ini, file lengkap index.ts dapat dijalankan dengan:
Urutan kemiripan dan nilai jarak yang tepat dapat bervariasi tergantung model embedding dan penyedia. Hasil terfilter seharusnya berisi database-guide, sedangkan hasil MMR seharusnya menampilkan serangkaian sumber retrieval yang beragam dari korpus yang tumpang tindih.
Tips dan Pemecahan Masalah
Koneksi database gagal
Verifikasi string koneksi, kredensial, layanan yang dapat dijangkau, dan hak akses skema. Jika Anda menggunakan Autonomous AI Database, konfirmasikan pengaturan wallet atau TLS yang diperlukan. Uji koneksi database secara terpisah sebelum men-debug retrieval.
Terjadi ketidaksesuaian dimensi embedding
Vektor yang dibuat saat ingest dan vektor kueri harus menggunakan dimensi yang kompatibel. Menggunakan model embedding yang berbeda untuk insert dan kueri dapat merusak pencarian atau menurunkan kualitas hasil. Jaga konsistensi pemilihan model untuk satu tabel.
Pencarian tidak mengembalikan dokumen
Konfirmasikan bahwa ingest telah menyisipkan baris, lalu coba lagi tanpa filter metadata yang ketat. Untuk korpus kecil, bereksperimenlah dengan kueri yang lebih luas dan periksa konten yang disimpan.
Hasil relevan tetapi repetitif
Bandingkan similarity search dengan MMR menggunakan korpus dengan potongan tumpang tindih. Sesuaikan k, fetchK, dan lambda sambil memeriksa apakah keragaman menimbulkan risiko melewatkan bagian penting.
Haruskah Anda membuat indeks vektor?
Untuk dataset sampel kecil, mulailah dengan memvalidasi kebenaran tanpa menyesuaikan pengindeksan. Saat data bertambah, evaluasi indeks vektor Oracle seperti Hierarchical Navigable Small World (HNSW) atau Inverted File (IVF), berdasarkan kebutuhan performa dan akurasi Anda. Pembuatan indeks adalah optimisasi, bukan prasyarat untuk memahami integrasi dasar.
Dibangun dengan TypeScript, aplikasi ini memadukan ingest dokumen, penyimpanan vektor, similarity search, pemfilteran metadata, dan MMR menggunakan LangChain.js dan Oracle AI Database. Aplikasi ini juga menyediakan antarmuka interaktif untuk bereksperimen dengan pengaturan retrieval, memeriksa dokumen yang diambil, dan memahami bagaimana strategi pencarian yang berbeda memengaruhi konteks yang dikembalikan ke aplikasi.
Repositori ini mencakup kode sumber dan instruksi penyiapan, memungkinkan Anda menjelajahi integrasi lengkap dan menyesuaikan implementasi untuk proyek Anda sendiri.
Kesimpulan dan Langkah Selanjutnya
Anda telah menghubungkan LangChain.js ke Oracle AI Database melalui OracleVS, merepresentasikan pengetahuan sebagai objek Document, membuat embedding vektor yang persisten, dan membandingkan similarity search, pemfilteran metadata, dan MMR. Untuk langkah berikutnya, baca dokumentasi LangChain.js resmi dan panduan integrasi Oracle LangChain JavaScript resmi.
Jika Anda bekerja dalam bahasa lain, tutorial Oracle AI Vector Search kami membahas langkah penyimpanan dan kueri yang sama dalam Python, dan tutorial LangChain4j kami membangun agen Java dengan Oracle AI Database.
Kursus Retrieval Augmented Generation (RAG) dengan LangChain kami adalah tindak lanjut opsional yang berfokus pada retrieval; contohnya dalam Python, tetapi konsep alur kerjanya berlaku untuk implementasi TypeScript ini.
FAQ
Apa yang terjadi jika saya mengubah model embedding setelah menyimpan dokumen?⌄
Embedding yang disimpan dalam tabel vektor Oracle harus kompatibel dengan embedding yang digunakan untuk pencarian. Mengganti model dapat mengubah dimensi vektor dan makna koordinat vektor, jadi lakukan embed ulang dan reindeks dokumen saat Anda mengganti model embedding. Gunakan konfigurasi embedding yang sama untuk ingest dokumen dan retrieval kueri.
Apakah saya memerlukan model percakapan untuk menggunakan OracleVS?⌄
Tidak. Alur kerja vector store memerlukan model embedding untuk ingest dan kueri. Model percakapan bersifat opsional dan biasanya ditambahkan saat bagian yang diambil perlu diubah menjadi respons dalam bahasa natural.
Bisakah saya menggunakan penyedia embedding selain OpenAI?⌄
Ya. OracleVS menerima implementasi embedding LangChain yang kompatibel. Pilih penyedia yang memenuhi kebutuhan Anda dan gunakan pengaturan embedding yang kompatibel yang sama untuk dokumen dan kueri.
Mengapa menggunakan pemfilteran metadata bersama kemiripan vektor?⌄
Kemiripan vektor menemukan konten yang secara semantik dekat; pemfilteran metadata mempersempit konten mana yang boleh dikembalikan, misalnya dokumen dalam kategori atau sumber tertentu.
Kapan saya harus memilih MMR dibanding similarity search biasa?⌄
MMR membantu saat kecocokan teratas berisi bagian yang repetitif dan aplikasi diuntungkan dari bukti yang lebih beragam. Similarity search biasa lebih sederhana saat tetangga terdekat adalah tujuan utama.
Penulis
Daniela Pavlenco
Saya seorang Developer Advocate di Oracle, berfokus membantu para pengembang mengeksplorasi teknologi AI dan membangun aplikasi praktis dengan alat serta framework modern. Pekerjaan saya mencakup pembuatan konten teknis, contoh langsung, dan sumber daya untuk pengembang yang membuat konsep kompleks lebih mudah dipahami dan diterapkan dalam proyek nyata.
Model bahasa dapat menjawab pertanyaan umum, tetapi tidak dapat secara andal mencari basis pengetahuan privat kecuali aplikasi terlebih dahulu mengambil informasi yang relevan. Bagi pengembang JavaScript, LangChain.js menyediakan abstraksi yang familier untuk dokumen, embedding, dan retrieval. Bagian yang hilang adalah tempat yang persisten untuk menyimpan dan mencari vektor yang dihasilkan.
Oracle AI Database mengisi peran tersebut melalui integrasi
@oracle/langchain-oracledb. Dalam panduan ini, Anda akan menghubungkan alur kerja TypeScript kecil ke Oracle, menyimpan teks beserta metadata, menjalankan similarity search, dan meningkatkan retrieval dengan filter dan maximal marginal relevance (MMR). Tutorial ini berfokus pada alur kerja retrieval; aplikasi TypeScript pendamping menambahkan integrasi yang sama ke UI peramban interaktif.Untuk detail integrasi, lihat panduan integrasi Oracle LangChain JavaScript resmi.
Apa Itu Integrasi LangChain.js dan Oracle AI Database?
LangChain.js menstandarkan cara aplikasi bekerja dengan model embedding dan vector store. Paket integrasi Oracle menyediakan
OracleVS, implementasi vector store yang mempersistenkan teks dokumen, metadata, dan embedding vektor di Oracle AI Database. Aplikasi Anda memanggil metode LangChain.js alih-alih menulis SQL secara manual untuk setiap kueri kemiripan.Paket integrasi yang sama juga menyertakan
OracleDocLoader,OracleTextSplitter,OracleEmbeddings, danOracleSummary. Itu adalah blok bangunan opsional yang berguna; contoh di bawah berfokus padaOracleVSdan memisahkan pembuatan embedding agar alurnya tetap mudah dipahami.Ingesti dokumen dan retrieval menggunakan LangChain.js, OracleVS, dan Oracle AI Database
Fitur Utama Integrasi
Menyimpan embedding bersama metadata dokumen
Model embedding mengubah teks menjadi vektor numerik.
OracleVSmenyimpan vektor ini bersama teks sumber dan metadata terstruktur. Metadata seperti kategori dokumen atau sumber membantu aplikasi membatasi pencarian tanpa membuang konteks yang berguna.Ambil bagian relevan menggunakan kemiripan vektor
Saat kueri, model embedding yang sama mengonversi pertanyaan menjadi vektor. Oracle membandingkannya dengan vektor yang disimpan menggunakan strategi jarak yang dikonfigurasi, seperti jarak kosinus, dan mengembalikan dokumen terdekat. Hasilnya tetap berupa objek
DocumentLangChain, siap untuk pemrosesan lanjutan.Kendalikan hasil dengan pemfilteran dan MMR
Similarity search menjawab “item mana yang paling dekat dengan pertanyaan ini?” Filter metadata mempersempit dokumen yang memenuhi syarat. MMR menambahkan tujuan berbeda: menjaga bagian yang dipilih tetap relevan sambil mengurangi hasil yang hampir duplikat. Operasi ini saling melengkapi, bukan saling menggantikan.
Mulai Menggunakan LangChain.js dan Oracle AI Database
Prasyarat
Untuk contoh TypeScript ini, Anda memerlukan Node.js 24.13.0, npm 11.6.2, instance lokal Oracle AI Database 26ai Free dengan dukungan vektor, dan skema yang dapat membuat, melakukan insert, kueri, dan drop tabel demo beserta indeks vektornya. Anda juga memerlukan kunci API OpenAI untuk contoh embedding.
OpenAIEmbeddingsadalah pilihan yang kompatibel dengan LangChain, bukan persyaratanOracleVS.Instal Node.js dari halaman unduhan Node.js resmi.
Untuk rute lokal utama, ikuti quick start Oracle AI Database Free dari Oracle. Setelah database berjalan, gunakan layanan seperti
localhost:1521/FREEPDB1dan skema dengan hak akses yang tercantum di atas.Buat proyek TypeScript
Buat file bernama
index.tsdi folder ini. Tambahkan cuplikan TypeScript yang dapat dieksekusi di bawah ini ke file yang sama, sesuai urutan yang ditunjukkan. Jangan membuat file terpisah untuk setiap cuplikan. Salin hanya cuplikan TypeScript yang dapat dieksekusi: blok SQL dan keluaran perwakilan bersifat penjelasan dan tidak boleh ditempelkan keindex.ts.Pengaturan
package.jsontype=modulememungkinkanawaittingkat atas yang digunakan oleh contoh. Konfigurasi paket Node.js didokumentasikan dalam panduan paket Node.js resmi.Paket integrasi Oracle mengimplementasikan vector store,
@langchain/coremenyediakanDocument,@langchain/openaimenyediakan model embedding contoh, danoracledbmengelola koneksi database. Versi di atas cocok dengan aplikasi pendamping;tsxmenjalankan contoh TypeScript secara langsung tanpa langkah build terpisah.Konfigurasikan koneksi
Simpan nilai ini di file lokal
.envdan tambahkan.envke.gitignore. Artikel ini menggunakan Oracle AI Database Free lokal sebagai penyiapan utama agar langkah-langkahnya dapat direproduksi. Autonomous AI Database adalah alternatif deployment yang valid, tetapi memerlukan deskriptor layanan dan konfigurasi wallet atau TLS untuk lingkungan tersebut.Pool memungkinkan
OracleVSmenggunakan ulang sesi database. Simpan semua pernyataan ingest, retrieval, dan verifikasi di dalam bloktry. Blok kode berikut memulai blok tersebut, dan cuplikan selanjutnya melanjutkannya. Pool ditutup hanya setelah verifikasi pada bagian pembersihan di bawah. Dalam aplikasi server, inisialisasi pool satu kali dan tutup saat penghentian terkelola dengan baik alih-alih membuka koneksi baru untuk setiap permintaan pengguna.Cara Membangun Pencarian Dokumen dengan LangChain.js
Kita akan menggunakan 10 catatan basis pengetahuan singkat, termasuk bagian retrieval yang tumpang tindih. Korpus sengaja dibuat kecil, tetapi memungkinkan perbandingan antara similarity search biasa dengan pemfilteran metadata dan MMR.
Definisikan dokumen pengetahuan Anda
Setiap
DocumentmemilikipageContentdanmetadata. Kolomsourcedancategorymengikuti dokumen melalui ingest dan retrieval, sehingga aplikasi dapat menjelaskan asal hasil dan membatasi pencarian pada subset yang relevan.Konfigurasikan embedding dan buat OracleVS
OracleVS.fromDocuments()adalah pemanggilan integrasi utama. Ini menginisialisasi vector store, membuat embedding untuk dokumen yang diberikan, serta menyimpan konten, vektor, dan metadata-nya di Oracle AI Database.Parameter
querymenyediakan teks contoh yang di-embed saat inisialisasi untuk menentukan dimensi vektor yang diperlukan untuk tabel database. Ini tidak digunakan untuk mencari dokumen yang disimpan.DistanceStrategy.COSINEmenentukan metrik jarak vektor, sementaraVectorElementFormat.FLOAT32mengatur format elemen vektor.Sebelum menjalankan ulang ingest, gunakan nama tabel demo baru atau kosongkan data yang ada untuk menghindari memasukkan dokumen duplikat.
OracleVSmenerima implementasi embedding yang kompatibel dengan LangChain, sehingga pengembang dapat mengganti penyedia embedding tanpa mengubah alur kerja vector store secara keseluruhan. Namun, embedding yang digunakan untuk ingest dan retrieval harus tetap kompatibel dengan kolom vektor Oracle.OracleVSmenentukan dimensi vektor saat inisialisasi menggunakan model embedding yang dikonfigurasi. Untuk memeriksa dimensi dan format penyimpanan vektor yang sudah disimpan di Oracle AI Database, jalankan kueri SQL berikut:Jika Anda beralih ke model embedding dengan dimensi berbeda, buat tabel vektor yang kompatibel dan bangun ulang embedding dokumen. Bahkan jika dua model menghasilkan vektor dengan dimensi yang sama, ruang embedding-nya bisa berbeda, sehingga dokumen yang ada sebaiknya di-embed ulang sebelum menggunakan model baru untuk retrieval.
Untuk tanda tangan metode vector store dan opsi retrieval, lihat referensi VectorStore LangChain.js resmi.
Ambil dokumen dengan similarity search
Misalnya, pemanggilan berikut meminta vector store
OracleVSuntuk 3 dokumen terdekat dan mencetak metadata sumber bersama teks setiap potongan:Kode ini memetakan setiap
DocumentLangChain menjadi objek biasa yang berisisourcedanpageContentuntuk ditampilkan. Keluaran perwakilan ditunjukkan di bawah; urutan pastinya dapat bervariasi tergantung model embedding dan kueri:Argumen pertama adalah pertanyaan pengguna, dan argumen kedua adalah
k, jumlah maksimum dokumen yang akan diambil. LangChain.js menggunakan model embedding yang dikonfigurasi untuk mengonversi pertanyaan menjadi vektor, dan Oracle AI Database melakukan similarity search untuk menemukan dokumen yang paling cocok.Jika setelah menerapkan kondisi pencarian dan filter metadata tersedia kurang dari
kdokumen, metode hanya mengembalikan hasil yang tersedia. ObjekDocumentyang diambil berisi teks dan metadata yang dapat ditampilkan dengan atribusi sumber atau diteruskan ke langkah pembuatan jawaban berikutnya.Periksa skor retrieval
Misalnya, gunakan
similaritySearchWithScoresaat Anda ingin memeriksa jarak yang terkait dengan setiap dokumen yang diambil:similaritySearchWithScoremengembalikan jarak untuk setiap kecocokan. Nilai numerik dan arahnya bergantung pada strategi jarak yang dikonfigurasi, sehingga bukan persentase keyakinan universal. Bandingkan skor hanya saat menggunakan model embedding dan strategi jarak yang sama, dan periksa bagian yang diambil sebelum memilih ambang batas.Batasi hasil dengan filter metadata
Contoh keluaran:
Argumen ketiga membatasi pencarian ke item dengan
category = database. Dalam korpus ini, hasil terfilter yang dapat diprediksi adalah["database-guide"]. Filter mengubah dokumen yang memenuhi syarat; kemiripan vektor tetap memberi peringkat pada dokumen yang memenuhi syarat.Gunakan MMR untuk mengurangi hasil yang repetitif
Keluaran perwakilan dari korpus yang tumpang tindih (pengurutan dapat bervariasi antar model embedding dan eksekusi):
MMR terlebih dahulu mempertimbangkan kumpulan kandidat (
fetchK) lalu memilihkdokumen dengan menyeimbangkan relevansi kueri dengan keragaman.lambdayang lebih rendah lebih menekankan keragaman; nilai yang lebih tinggi lebih menekankan relevansi. Dengan korpus tumpang tindih di atas, sumber yang dipilih dapat berbeda dari similarity search biasa, sehingga trade-off retrieval menjadi terlihat.Teruskan konteks yang diambil ke aplikasi AI
Ini adalah titik serah antara retrieval LangChain.js dan panggilan model bahasa besar (LLM): aplikasi memiliki pertanyaan plus bukti yang dapat diperiksa, siap untuk prompt yang meminta model menjawab dari konteks tersebut.
Retrieval dan generasi adalah tanggung jawab terpisah. Pada titik ini,
contextadalah string teks biasa yang dapat dikonsumsi model percakapan. Anda kini dapat memberikannya ke model dengan instruksi untuk menjawab hanya dari materi yang diambil dan menyebutkan pengenal sumber. Integrasi database itu sendiri tetap bekerja bahkan tanpa model percakapan.Cara Memverifikasi Integrasi
Validasi yang berguna memeriksa ingest dan setiap strategi retrieval secara terpisah. Pertama, konfirmasikan bahwa vector store dibuat tanpa kesalahan database. Lalu periksa metadata sumber yang dikembalikan oleh similarity search, hasil terfilter, dan hasil MMR.
Tutup connection pool setelah verifikasi
Pembersihan hanya berjalan setelah ingest, retrieval, dan verifikasi selesai. Waktu drain memberikan jendela singkat agar koneksi yang sedang digunakan dapat menyelesaikan tugasnya. Dalam server jangka panjang, biarkan pool tetap terbuka hingga penghentian yang terkelola dengan baik. Lihat dokumentasi
pool.close()node-oracledb untuk detail siklus hidup.Pada titik ini, file lengkap
index.tsdapat dijalankan dengan:Keluaran validasi perwakilan adalah:
Urutan kemiripan dan nilai jarak yang tepat dapat bervariasi tergantung model embedding dan penyedia. Hasil terfilter seharusnya berisi
database-guide, sedangkan hasil MMR seharusnya menampilkan serangkaian sumber retrieval yang beragam dari korpus yang tumpang tindih.Tips dan Pemecahan Masalah
Koneksi database gagal
Verifikasi string koneksi, kredensial, layanan yang dapat dijangkau, dan hak akses skema. Jika Anda menggunakan Autonomous AI Database, konfirmasikan pengaturan wallet atau TLS yang diperlukan. Uji koneksi database secara terpisah sebelum men-debug retrieval.
Terjadi ketidaksesuaian dimensi embedding
Vektor yang dibuat saat ingest dan vektor kueri harus menggunakan dimensi yang kompatibel. Menggunakan model embedding yang berbeda untuk insert dan kueri dapat merusak pencarian atau menurunkan kualitas hasil. Jaga konsistensi pemilihan model untuk satu tabel.
Pencarian tidak mengembalikan dokumen
Konfirmasikan bahwa ingest telah menyisipkan baris, lalu coba lagi tanpa filter metadata yang ketat. Untuk korpus kecil, bereksperimenlah dengan kueri yang lebih luas dan periksa konten yang disimpan.
Hasil relevan tetapi repetitif
Bandingkan similarity search dengan MMR menggunakan korpus dengan potongan tumpang tindih. Sesuaikan
k,fetchK, danlambdasambil memeriksa apakah keragaman menimbulkan risiko melewatkan bagian penting.Haruskah Anda membuat indeks vektor?
Untuk dataset sampel kecil, mulailah dengan memvalidasi kebenaran tanpa menyesuaikan pengindeksan. Saat data bertambah, evaluasi indeks vektor Oracle seperti Hierarchical Navigable Small World (HNSW) atau Inverted File (IVF), berdasarkan kebutuhan performa dan akurasi Anda. Pembuatan indeks adalah optimisasi, bukan prasyarat untuk memahami integrasi dasar.
Untuk detail lebih lanjut tentang indeks vektor Oracle, lihat dokumentasi indeks vektor Oracle.
Jelajahi Implementasi Referensi TypeScript Lengkap
Untuk melihat bagaimana konsep ini bersatu dalam aplikasi yang berfungsi, jelajahi implementasi referensi LangChain.js dan Oracle AI Database.
Dibangun dengan TypeScript, aplikasi ini memadukan ingest dokumen, penyimpanan vektor, similarity search, pemfilteran metadata, dan MMR menggunakan LangChain.js dan Oracle AI Database. Aplikasi ini juga menyediakan antarmuka interaktif untuk bereksperimen dengan pengaturan retrieval, memeriksa dokumen yang diambil, dan memahami bagaimana strategi pencarian yang berbeda memengaruhi konteks yang dikembalikan ke aplikasi.
Repositori ini mencakup kode sumber dan instruksi penyiapan, memungkinkan Anda menjelajahi integrasi lengkap dan menyesuaikan implementasi untuk proyek Anda sendiri.
Kesimpulan dan Langkah Selanjutnya
Anda telah menghubungkan LangChain.js ke Oracle AI Database melalui
OracleVS, merepresentasikan pengetahuan sebagai objekDocument, membuat embedding vektor yang persisten, dan membandingkan similarity search, pemfilteran metadata, dan MMR. Untuk langkah berikutnya, baca dokumentasi LangChain.js resmi dan panduan integrasi Oracle LangChain JavaScript resmi.Jika Anda bekerja dalam bahasa lain, tutorial Oracle AI Vector Search kami membahas langkah penyimpanan dan kueri yang sama dalam Python, dan tutorial LangChain4j kami membangun agen Java dengan Oracle AI Database.
Kursus Retrieval Augmented Generation (RAG) dengan LangChain kami adalah tindak lanjut opsional yang berfokus pada retrieval; contohnya dalam Python, tetapi konsep alur kerjanya berlaku untuk implementasi TypeScript ini.