LangChain.js en Oracle AI Database: gids voor vectorzoekopdrachten
Verbind LangChain.js met Oracle AI Database via OracleVS, sla embeddings met metadata op en vergelijk similarity search, metadatafilters en MMR in TypeScript.
Een taalmodel kan algemene vragen beantwoorden, maar het kan niet betrouwbaar een private kennisbank doorzoeken tenzij een applicatie eerst de relevante informatie ophaalt. Voor JavaScript-ontwikkelaars biedt LangChain.js vertrouwde abstracties voor documenten, embeddings en retrieval. De ontbrekende schakel is een blijvende plek om de resulterende vectoren op te slaan en te doorzoeken.
Oracle AI Database vervult die rol via de @oracle/langchain-oracledb-integratie. In deze gids verbind je een kleine TypeScript-workflow met Oracle, sla je tekst met metadata op, voer je similarity search uit en verbeter je retrieval met filters en maximal marginal relevance (MMR). De tutorial richt zich op de retrievalworkflow; de bijbehorende TypeScript-applicatie voegt dezelfde integratie toe aan een interactieve browser-UI.
Wat is de integratie tussen LangChain.js en Oracle AI Database?
LangChain.js standaardiseert hoe een applicatie werkt met embeddingmodellen en vectorstores. Het Oracle-integratiepakket levert OracleVS, een vectorstore-implementatie die documenttekst, metadata en vectorembeddings persistent opslaat in Oracle AI Database. Je applicatie roept LangChain.js-methodes aan in plaats van handmatig SQL te schrijven voor elke similarity query.
Datzelfde integratiepakket bevat ook OracleDocLoader, OracleTextSplitter, OracleEmbeddings en OracleSummary. Dat zijn nuttige optionele bouwstenen; het onderstaande voorbeeld richt zich op OracleVS en houdt embeddinggeneratie apart zodat de flow overzichtelijk blijft.
Documentinname en retrieval met LangChain.js, OracleVS en Oracle AI Database
Belangrijkste functies van de integratie
Embeddings opslaan naast documentmetadata
Een embeddingmodel zet tekst om in numerieke vectoren. OracleVS slaat deze vectoren op met de brontekst en gestructureerde metadata. Metadata zoals documentcategorie of bron helpt de applicatie zoekacties te beperken zonder nuttige context te verliezen.
Relevante passages ophalen met vectorsimilariteit
Bij een query zet hetzelfde embeddingmodel de vraag om in een vector. Oracle vergelijkt deze met de opgeslagen vectoren met een geconfigureerde afstandsstrategie, zoals cosinusafstand, en retourneert de dichtstbijzijnde documenten. De resultaten blijven LangChain-Document-objecten, klaar voor verdere verwerking.
Beheer de resultaten met filtering en MMR
Similarity search beantwoordt de vraag: “welke items liggen het dichtst bij deze vraag?” Een metadatafilter beperkt de in aanmerking komende documenten. MMR voegt een ander doel toe: de geselecteerde passages relevant houden terwijl bijna-duplicaten worden verminderd. Deze bewerkingen vullen elkaar aan in plaats van elkaar te vervangen.
Aan de slag met LangChain.js en Oracle AI Database
Vereisten
Voor dit TypeScript-voorbeeld heb je Node.js 24.13.0, npm 11.6.2, een lokale Oracle AI Database 26ai Free-instantie met vectorondersteuning en een schema nodig dat de demotabel en de bijbehorende vectorindex kan aanmaken, vullen, bevragen en verwijderen. Je hebt ook een OpenAI API-sleutel nodig voor het embeddingvoorbeeld. OpenAIEmbeddings is een met LangChain compatibele keuze, geen vereiste van OracleVS.
Voor de primaire lokale route volg je Oracle’s Oracle AI Database Free quick start. Nadat de database draait, gebruik je een service zoals localhost:1521/FREEPDB1 en een schema met de hierboven genoemde rechten.
Maak in deze map een bestand met de naam index.ts. Voeg de uitvoerbare TypeScript-snippets hieronder toe aan hetzelfde bestand, in de getoonde volgorde. Maak geen apart bestand voor elke snippet. Kopieer alleen de uitvoerbare TypeScript-snippets: de SQL- en representatieve-outputblokken zijn toelichtende voorbeelden en moeten niet in index.ts geplakt worden.
De package.json-instelling type=module maakt het top-level await mogelijk dat door de voorbeelden wordt gebruikt. De Node.js-pakketconfiguratie is gedocumenteerd in de officiële Node.js-pakketgids.
Het Oracle-integratiepakket implementeert de vectorstore, @langchain/core levert Document, @langchain/openai levert het voorbeeld-embeddingmodel en oracledb beheert de databaseverbinding. De bovenstaande versies komen overeen met de bijbehorende applicatie; tsx draait het TypeScript-voorbeeld direct zonder aparte buildstap.
Configureer de verbinding
ORACLE_USER=your_schema
ORACLE_PASSWORD=your_password
ORACLE_CONNECT_STRING=localhost:1521/FREEPDB1
OPENAI_API_KEY=your_api_keyMogelijk gemaakt door
Sla deze waarden op in een lokaal .env-bestand en voeg .env toe aan .gitignore. Dit artikel gebruikt lokale Oracle AI Database Free als primaire setup zodat de stappen reproduceerbaar zijn. Autonomous AI Database is een geldig alternatief voor deployment, maar vereist de servicedescriptor en wallet- of TLS-configuratie voor die omgeving.
import"dotenv/config";import oracledb from"oracledb";import{ Document }from"@langchain/core/documents";import{ OpenAIEmbeddings }from"@langchain/openai";import{ OracleVS, DistanceStrategy, VectorElementFormat }from"@oracle/langchain-oracledb";const pool =await oracledb.createPool({
user: process.env.ORACLE_USER,
password: process.env.ORACLE_PASSWORD,
connectString: process.env.ORACLE_CONNECT_STRING,
poolMin:1,
poolMax:4,});Mogelijk gemaakt door
De pool laat OracleVS databasesessies hergebruiken. Houd alle inname-, retrieval- en verificatiestatements binnen het try-blok. Het volgende codeblok start dat blok, en de latere snippets zetten het voort. De pool wordt pas gesloten na verificatie in de opschoonsectie hieronder. In een serverapplicatie initialiseer je de pool één keer en sluit je die tijdens een nette shutdown, in plaats van voor elk gebruikersverzoek een nieuwe verbinding te openen.
Zo bouw je documentzoekopdrachten met LangChain.js
We gebruiken 10 korte kennisbanknotities, inclusief overlappende retrievalpassages. De corpus is bewust klein, maar maakt het mogelijk om gewone similarity search te vergelijken met metadatafiltering en MMR.
Definieer je kennisdocumenten
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 }}));Mogelijk gemaakt door
Elk Document heeft pageContent en metadata. De velden source en category reizen met het document mee door inname en retrieval, zodat de applicatie kan uitleggen waar een resultaat vandaan komt en zoekacties kan beperken tot een relevante subset.
Configureer embeddings en maak OracleVS aan
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,});Mogelijk gemaakt door
OracleVS.fromDocuments() is de centrale integratieaanroep. Het initialiseert de vectorstore, genereert embeddings voor de aangeleverde documenten en slaat hun content, vectoren en metadata op in Oracle AI Database.
De parameter query levert voorbeeldtekst die tijdens initialisatie wordt ge-embed om de vectordimensie te bepalen die voor de databasetabel nodig is. Deze wordt niet gebruikt om de opgeslagen documenten te doorzoeken. DistanceStrategy.COSINE specificeert de vectorafstandsmaat, terwijl VectorElementFormat.FLOAT32 het formaat van de vectorelementen instelt.
Gebruik voor herhaalde inname een nieuwe demotabelnaam of wis de bestaande data om te voorkomen dat je dubbele documenten invoegt.
OracleVS accepteert een met LangChain compatibele embeddingimplementatie, zodat ontwikkelaars van embeddingprovider kunnen wisselen zonder de algehele vectorstore-workflow te wijzigen. De embeddings die voor inname en retrieval worden gebruikt, moeten echter compatibel blijven met de Oracle-vector kolom.
OracleVS bepaalt de vectordimensie tijdens initialisatie met het geconfigureerde embeddingmodel. Om de dimensies en het opslagformaat te inspecteren van een vector die al is opgeslagen in Oracle AI Database, voer je de volgende SQL-query uit:
SELECT
VECTOR_DIMENSION_COUNT(embedding)AS vector_dimensions,
VECTOR_DIMENSION_FORMAT(embedding)AS vector_format
FROM LC_JS_RAG_DEMO
FETCHFIRST1ROW ONLY;Mogelijk gemaakt door
Als je overschakelt naar een embeddingmodel met een andere dimensie, maak dan een compatibele vectortabel en genereer de documentembeddings opnieuw. Zelfs als twee modellen vectoren met dezelfde dimensies produceren, kunnen hun embeddingspaces verschillen, dus bestaande documenten moeten opnieuw ge-embed worden voordat je het nieuwe model voor retrieval gebruikt.
De volgende aanroep vraagt bijvoorbeeld aan de OracleVS-vectorstore om de 3 dichtstbijzijnde documenten en print de bronmetadata samen met de tekst van elk deel:
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,})));Mogelijk gemaakt door
De code zet elk LangChain-Document om naar een gewoon object met de source en pageContent voor weergave. Hieronder staat een representatieve output; de exacte volgorde kan variëren per embeddingmodel en query:
[
{ 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." }
]Mogelijk gemaakt door
Het eerste argument is de gebruikersvraag en het tweede is k, het maximale aantal documenten om op te halen. LangChain.js gebruikt het geconfigureerde embeddingmodel om de vraag om te zetten in een vector, en Oracle AI Database voert similarity search uit om de meest overeenkomende documenten te vinden.
Als er minder dan k documenten beschikbaar zijn na toepassing van de zoekvoorwaarden en metadatafilters, retourneert de methode alleen de beschikbare resultaten. De opgehaalde Document-objecten bevatten tekst en metadata die kunnen worden weergegeven met bronvermelding of kunnen worden doorgegeven aan een latere stap voor het genereren van een antwoord.
Retrievalscores inspecteren
Gebruik bijvoorbeeld similaritySearchWithScore wanneer je de afstand wilt bekijken die bij elk opgehaald document hoort:
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,});}Mogelijk gemaakt door
similaritySearchWithScore retourneert een afstand bij elke match. De numerieke waarde en richting hangen af van de geconfigureerde afstandsstrategie, dus het is geen universeel betrouwbaarheidspercentage. Vergelijk scores alleen wanneer je hetzelfde embeddingmodel en dezelfde afstandsstrategie gebruikt, en bekijk de opgehaalde passage voordat je een drempel kiest.
Beperk resultaten met metadatafilters
const databaseOnly =await vectorStore.similaritySearch("Where are vector embeddings stored?",3,{ category:{ $eq:"database"}});console.log(databaseOnly.map((doc)=> doc.metadata.source));Mogelijk gemaakt door
Het derde argument beperkt de zoekactie tot items met category = database. In deze corpus is het voorspelbare gefilterde resultaat ["database-guide"]. Een filter verandert welke documenten in aanmerking komen; vectorsimilariteit rangschikt nog steeds de in aanmerking komende documenten.
Gebruik MMR om repetitieve resultaten te verminderen
const diverse =await vectorStore.maxMarginalRelevanceSearch(
retrievalQuestion,{
k:3,
fetchK:6,
lambda:0.5,});console.log(diverse.map((doc)=> doc.metadata.source));Mogelijk gemaakt door
Representatieve output uit een overlappende corpus (volgorde kan variëren per embeddingmodel en run):
MMR bekijkt eerst een kandidatenpool (fetchK) en selecteert daarna k documenten door relevantie voor de query af te wegen tegen diversiteit. Een lagere lambda legt meer nadruk op diversiteit; een hogere waarde legt meer nadruk op relevantie. Met de overlappende corpus hierboven kunnen de geselecteerde bronnen afwijken van gewone similarity search, waardoor de retrievalafweging zichtbaar wordt.
Doorgegeven context gebruiken in een AI-applicatie
const question ="How does LangChain.js retrieve Oracle documents?";const contextDocs =await vectorStore.similaritySearch(question,3);const context = contextDocs
.map((doc, i)=>`[${i +1}] ${doc.pageContent}`).join("\n\n");console.log({ question, context });Mogelijk gemaakt door
Dit is het overdrachtsmoment tussen LangChain.js-retrieval en een large language model (LLM)-aanroep: de applicatie heeft een vraag plus controleerbaar bewijs, klaar voor een prompt die het model vraagt te antwoorden op basis van die context.
Retrieval en generatie zijn afzonderlijke verantwoordelijkheden. Op dit punt is context een platte tekststring die een chatmodel kan gebruiken. Je kunt die nu aan een model geven met de instructie om alleen uit het opgehaalde materiaal te antwoorden en bronidentificaties te citeren. De database-integratie werkt ook zonder chatmodel.
De integratie verifiëren
Een nuttige validatie controleert inname en elke retrievalstrategie afzonderlijk. Bevestig eerst dat de vectorstore is aangemaakt zonder databasefout. Inspecteer vervolgens de bronmetadata die door similarity search is geretourneerd, het gefilterde resultaat en het MMR-resultaat.
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),});Mogelijk gemaakt door
De opschoning draait pas nadat inname, retrieval en verificatie zijn afgerond. De drain-tijd geeft bezette verbindingen kort de ruimte om af te ronden. In een langlopende server houd je de pool open tot een nette shutdown. Zie de node-oracledb-documentatie voor pool.close() voor de levenscyclusdetails.
Op dit punt kun je het complete index.ts-bestand uitvoeren met:
{
similarity: ["retrieval-overlap-1", "retrieval-overlap-2", "mmr-retrieval"],
filtered: ["database-guide"],
mmr: ["retrieval-overlap-2", "mmr-retrieval", "metadata-filtering"]
}Mogelijk gemaakt door
De exacte volgorde bij similarity en de afstandswaarden kunnen variëren per embeddingmodel en -provider. Het gefilterde resultaat zou database-guide moeten bevatten, terwijl het MMR-resultaat een gevarieerde set retrievalbronnen uit de overlappende corpus zou moeten tonen.
Tips en troubleshooting
De databaseverbinding faalt
Controleer de connectiestring, inloggegevens, bereikbare service en schemarechten. Als je Autonomous AI Database gebruikt, bevestig dan de vereiste wallet- of TLS-setup. Test de databaseverbinding losstaand voordat je retrieval debugt.
Er treedt een mismatch in embeddingdimensie op
De tijdens inname gemaakte vectoren en de queryvectoren moeten compatibele dimensies gebruiken. Verschillende embeddingmodellen gebruiken voor inserts en queries kan de zoekfunctie breken of resultaten verslechteren. Houd de modelkeuze consistent per tabel.
Een zoekopdracht retourneert geen documenten
Bevestig dat inname rijen heeft ingevoegd en probeer vervolgens opnieuw zonder beperkende metadatafilters. Experimenteer voor kleine corpora met bredere queries en bekijk de opgeslagen content.
De resultaten zijn relevant maar repetitief
Vergelijk similarity search met MMR met een corpus met overlappende stukken. Stel k, fetchK en lambda af terwijl je controleert of diversiteit niet ten koste gaat van belangrijke passages.
Moet je een vectorindex aanmaken?
Begin voor een kleine voorbeelddataset met het valideren van de correctheid zonder indexering te tunen. Naarmate data groeit, evalueer je Oracle-vectorindexen zoals Hierarchical Navigable Small World (HNSW) of Inverted File (IVF)-indexen, op basis van je prestatie- en nauwkeurigheidseisen. Indexcreatie is een optimalisatie, geen vereiste om de basisintegratie te begrijpen.
Gebouwd met TypeScript, brengt de applicatie documentinname, vectoropslag, similarity search, metadatafiltering en MMR samen met LangChain.js en Oracle AI Database. Het biedt ook een interactieve interface om met retrievalinstellingen te experimenteren, opgehaalde documenten te inspecteren en te begrijpen hoe verschillende zoekstrategieën de context beïnvloeden die aan de applicatie wordt teruggegeven.
De repository bevat de broncode en installatie-instructies, zodat je de volledige integratie kunt verkennen en de implementatie kunt aanpassen aan je eigen projecten.
Conclusie en vervolgstappen
Je hebt LangChain.js verbonden met Oracle AI Database via OracleVS, kennis gerepresenteerd als Document-objecten, persistente vectorembeddings gemaakt en similarity search, metadatafiltering en MMR vergeleken. Lees voor de volgende stap de officiële documentatie van LangChain.js en de officiële Oracle LangChain JavaScript-integratiegids.
Onze cursus Retrieval Augmented Generation (RAG) met LangChain is een optioneel retrieval-gericht vervolg; de voorbeelden zijn in Python, maar de workflowconcepten zijn toepasbaar op deze TypeScript-implementatie.
Veelgestelde vragen
Wat gebeurt er als ik van embeddingmodel wissel nadat documenten zijn opgeslagen?⌄
Embeddings die zijn opgeslagen in de Oracle-vectortabel moeten compatibel zijn met de embeddings die voor zoeken worden gebruikt. Het wisselen van modellen kan zowel de vectordimensies als de betekenis van vectorcoördinaten veranderen, dus embed en indexeer de documenten opnieuw wanneer je van embeddingmodel verandert. Gebruik dezelfde embeddingconfiguratie voor documentinname en query-retrieval.
Heb ik een chatmodel nodig om OracleVS te gebruiken?⌄
Nee. Een vectorstore-workflow vereist een embeddingmodel voor inname en query. Een chatmodel is optioneel en wordt meestal toegevoegd wanneer de opgehaalde passages moeten worden omgezet in een natuurlijk taalantwoord.
Kan ik een andere embeddingprovider dan OpenAI gebruiken?⌄
Ja. OracleVS accepteert een compatibele LangChain-embeddingimplementatie. Kies een provider die aan je eisen voldoet en gebruik dezelfde compatibele embedding-setup voor documenten en queries.
Waarom metadatafiltering gebruiken bij vectorsimilariteit?⌄
Vectorsimilariteit vindt semantisch dichtbijgelegen content; metadatafiltering beperkt welke content mag worden geretourneerd, zoals documenten in een bepaalde categorie of van een bepaalde bron.
Wanneer kies ik MMR boven gewone similarity search?⌄
MMR helpt wanneer topmatches repetitieve passages bevatten en de applicatie baat heeft bij meer gevarieerd bewijs. Gewone similarity search is eenvoudiger wanneer de dichtstbijzijnde buren het primaire doel zijn.
Auteur
Daniela Pavlenco
Ik ben Developer Advocate bij Oracle en help ontwikkelaars AI-technologieën te verkennen en praktische toepassingen te bouwen met moderne tools en frameworks. Mijn werk bestaat uit het maken van technische content, praktische voorbeelden en ontwikkelaarsresources die complexe concepten makkelijker te begrijpen en toe te passen maken in echte projecten.
Een taalmodel kan algemene vragen beantwoorden, maar het kan niet betrouwbaar een private kennisbank doorzoeken tenzij een applicatie eerst de relevante informatie ophaalt. Voor JavaScript-ontwikkelaars biedt LangChain.js vertrouwde abstracties voor documenten, embeddings en retrieval. De ontbrekende schakel is een blijvende plek om de resulterende vectoren op te slaan en te doorzoeken.
Oracle AI Database vervult die rol via de
@oracle/langchain-oracledb-integratie. In deze gids verbind je een kleine TypeScript-workflow met Oracle, sla je tekst met metadata op, voer je similarity search uit en verbeter je retrieval met filters en maximal marginal relevance (MMR). De tutorial richt zich op de retrievalworkflow; de bijbehorende TypeScript-applicatie voegt dezelfde integratie toe aan een interactieve browser-UI.Voor de integratiedetails, zie de officiële Oracle LangChain JavaScript-integratiegids.
Wat is de integratie tussen LangChain.js en Oracle AI Database?
LangChain.js standaardiseert hoe een applicatie werkt met embeddingmodellen en vectorstores. Het Oracle-integratiepakket levert
OracleVS, een vectorstore-implementatie die documenttekst, metadata en vectorembeddings persistent opslaat in Oracle AI Database. Je applicatie roept LangChain.js-methodes aan in plaats van handmatig SQL te schrijven voor elke similarity query.Datzelfde integratiepakket bevat ook
OracleDocLoader,OracleTextSplitter,OracleEmbeddingsenOracleSummary. Dat zijn nuttige optionele bouwstenen; het onderstaande voorbeeld richt zich opOracleVSen houdt embeddinggeneratie apart zodat de flow overzichtelijk blijft.Documentinname en retrieval met LangChain.js, OracleVS en Oracle AI Database
Belangrijkste functies van de integratie
Embeddings opslaan naast documentmetadata
Een embeddingmodel zet tekst om in numerieke vectoren.
OracleVSslaat deze vectoren op met de brontekst en gestructureerde metadata. Metadata zoals documentcategorie of bron helpt de applicatie zoekacties te beperken zonder nuttige context te verliezen.Relevante passages ophalen met vectorsimilariteit
Bij een query zet hetzelfde embeddingmodel de vraag om in een vector. Oracle vergelijkt deze met de opgeslagen vectoren met een geconfigureerde afstandsstrategie, zoals cosinusafstand, en retourneert de dichtstbijzijnde documenten. De resultaten blijven LangChain-
Document-objecten, klaar voor verdere verwerking.Beheer de resultaten met filtering en MMR
Similarity search beantwoordt de vraag: “welke items liggen het dichtst bij deze vraag?” Een metadatafilter beperkt de in aanmerking komende documenten. MMR voegt een ander doel toe: de geselecteerde passages relevant houden terwijl bijna-duplicaten worden verminderd. Deze bewerkingen vullen elkaar aan in plaats van elkaar te vervangen.
Aan de slag met LangChain.js en Oracle AI Database
Vereisten
Voor dit TypeScript-voorbeeld heb je Node.js 24.13.0, npm 11.6.2, een lokale Oracle AI Database 26ai Free-instantie met vectorondersteuning en een schema nodig dat de demotabel en de bijbehorende vectorindex kan aanmaken, vullen, bevragen en verwijderen. Je hebt ook een OpenAI API-sleutel nodig voor het embeddingvoorbeeld.
OpenAIEmbeddingsis een met LangChain compatibele keuze, geen vereiste vanOracleVS.Installeer Node.js via de officiële Node.js-downloadpagina.
Voor de primaire lokale route volg je Oracle’s Oracle AI Database Free quick start. Nadat de database draait, gebruik je een service zoals
localhost:1521/FREEPDB1en een schema met de hierboven genoemde rechten.Maak een TypeScript-project
Maak in deze map een bestand met de naam
index.ts. Voeg de uitvoerbare TypeScript-snippets hieronder toe aan hetzelfde bestand, in de getoonde volgorde. Maak geen apart bestand voor elke snippet. Kopieer alleen de uitvoerbare TypeScript-snippets: de SQL- en representatieve-outputblokken zijn toelichtende voorbeelden en moeten niet inindex.tsgeplakt worden.De
package.json-instellingtype=modulemaakt het top-levelawaitmogelijk dat door de voorbeelden wordt gebruikt. De Node.js-pakketconfiguratie is gedocumenteerd in de officiële Node.js-pakketgids.Het Oracle-integratiepakket implementeert de vectorstore,
@langchain/corelevertDocument,@langchain/openailevert het voorbeeld-embeddingmodel enoracledbbeheert de databaseverbinding. De bovenstaande versies komen overeen met de bijbehorende applicatie;tsxdraait het TypeScript-voorbeeld direct zonder aparte buildstap.Configureer de verbinding
Sla deze waarden op in een lokaal
.env-bestand en voeg.envtoe aan.gitignore. Dit artikel gebruikt lokale Oracle AI Database Free als primaire setup zodat de stappen reproduceerbaar zijn. Autonomous AI Database is een geldig alternatief voor deployment, maar vereist de servicedescriptor en wallet- of TLS-configuratie voor die omgeving.De pool laat
OracleVSdatabasesessies hergebruiken. Houd alle inname-, retrieval- en verificatiestatements binnen hettry-blok. Het volgende codeblok start dat blok, en de latere snippets zetten het voort. De pool wordt pas gesloten na verificatie in de opschoonsectie hieronder. In een serverapplicatie initialiseer je de pool één keer en sluit je die tijdens een nette shutdown, in plaats van voor elk gebruikersverzoek een nieuwe verbinding te openen.Zo bouw je documentzoekopdrachten met LangChain.js
We gebruiken 10 korte kennisbanknotities, inclusief overlappende retrievalpassages. De corpus is bewust klein, maar maakt het mogelijk om gewone similarity search te vergelijken met metadatafiltering en MMR.
Definieer je kennisdocumenten
Elk
DocumentheeftpageContentenmetadata. De veldensourceencategoryreizen met het document mee door inname en retrieval, zodat de applicatie kan uitleggen waar een resultaat vandaan komt en zoekacties kan beperken tot een relevante subset.Configureer embeddings en maak OracleVS aan
OracleVS.fromDocuments()is de centrale integratieaanroep. Het initialiseert de vectorstore, genereert embeddings voor de aangeleverde documenten en slaat hun content, vectoren en metadata op in Oracle AI Database.De parameter
querylevert voorbeeldtekst die tijdens initialisatie wordt ge-embed om de vectordimensie te bepalen die voor de databasetabel nodig is. Deze wordt niet gebruikt om de opgeslagen documenten te doorzoeken.DistanceStrategy.COSINEspecificeert de vectorafstandsmaat, terwijlVectorElementFormat.FLOAT32het formaat van de vectorelementen instelt.Gebruik voor herhaalde inname een nieuwe demotabelnaam of wis de bestaande data om te voorkomen dat je dubbele documenten invoegt.
OracleVSaccepteert een met LangChain compatibele embeddingimplementatie, zodat ontwikkelaars van embeddingprovider kunnen wisselen zonder de algehele vectorstore-workflow te wijzigen. De embeddings die voor inname en retrieval worden gebruikt, moeten echter compatibel blijven met de Oracle-vector kolom.OracleVSbepaalt de vectordimensie tijdens initialisatie met het geconfigureerde embeddingmodel. Om de dimensies en het opslagformaat te inspecteren van een vector die al is opgeslagen in Oracle AI Database, voer je de volgende SQL-query uit:Als je overschakelt naar een embeddingmodel met een andere dimensie, maak dan een compatibele vectortabel en genereer de documentembeddings opnieuw. Zelfs als twee modellen vectoren met dezelfde dimensies produceren, kunnen hun embeddingspaces verschillen, dus bestaande documenten moeten opnieuw ge-embed worden voordat je het nieuwe model voor retrieval gebruikt.
Voor de methodesignatures van de vectorstore en retrievalopties, zie de officiële LangChain.js VectorStore-referentie.
Documenten ophalen met similarity search
De volgende aanroep vraagt bijvoorbeeld aan de
OracleVS-vectorstore om de 3 dichtstbijzijnde documenten en print de bronmetadata samen met de tekst van elk deel:De code zet elk LangChain-
Documentom naar een gewoon object met desourceenpageContentvoor weergave. Hieronder staat een representatieve output; de exacte volgorde kan variëren per embeddingmodel en query:Het eerste argument is de gebruikersvraag en het tweede is
k, het maximale aantal documenten om op te halen. LangChain.js gebruikt het geconfigureerde embeddingmodel om de vraag om te zetten in een vector, en Oracle AI Database voert similarity search uit om de meest overeenkomende documenten te vinden.Als er minder dan
kdocumenten beschikbaar zijn na toepassing van de zoekvoorwaarden en metadatafilters, retourneert de methode alleen de beschikbare resultaten. De opgehaaldeDocument-objecten bevatten tekst en metadata die kunnen worden weergegeven met bronvermelding of kunnen worden doorgegeven aan een latere stap voor het genereren van een antwoord.Retrievalscores inspecteren
Gebruik bijvoorbeeld
similaritySearchWithScorewanneer je de afstand wilt bekijken die bij elk opgehaald document hoort:similaritySearchWithScoreretourneert een afstand bij elke match. De numerieke waarde en richting hangen af van de geconfigureerde afstandsstrategie, dus het is geen universeel betrouwbaarheidspercentage. Vergelijk scores alleen wanneer je hetzelfde embeddingmodel en dezelfde afstandsstrategie gebruikt, en bekijk de opgehaalde passage voordat je een drempel kiest.Beperk resultaten met metadatafilters
Voorbeeldoutput:
Het derde argument beperkt de zoekactie tot items met
category = database. In deze corpus is het voorspelbare gefilterde resultaat["database-guide"]. Een filter verandert welke documenten in aanmerking komen; vectorsimilariteit rangschikt nog steeds de in aanmerking komende documenten.Gebruik MMR om repetitieve resultaten te verminderen
Representatieve output uit een overlappende corpus (volgorde kan variëren per embeddingmodel en run):
MMR bekijkt eerst een kandidatenpool (
fetchK) en selecteert daarnakdocumenten door relevantie voor de query af te wegen tegen diversiteit. Een lagerelambdalegt meer nadruk op diversiteit; een hogere waarde legt meer nadruk op relevantie. Met de overlappende corpus hierboven kunnen de geselecteerde bronnen afwijken van gewone similarity search, waardoor de retrievalafweging zichtbaar wordt.Doorgegeven context gebruiken in een AI-applicatie
Dit is het overdrachtsmoment tussen LangChain.js-retrieval en een large language model (LLM)-aanroep: de applicatie heeft een vraag plus controleerbaar bewijs, klaar voor een prompt die het model vraagt te antwoorden op basis van die context.
Retrieval en generatie zijn afzonderlijke verantwoordelijkheden. Op dit punt is
contexteen platte tekststring die een chatmodel kan gebruiken. Je kunt die nu aan een model geven met de instructie om alleen uit het opgehaalde materiaal te antwoorden en bronidentificaties te citeren. De database-integratie werkt ook zonder chatmodel.De integratie verifiëren
Een nuttige validatie controleert inname en elke retrievalstrategie afzonderlijk. Bevestig eerst dat de vectorstore is aangemaakt zonder databasefout. Inspecteer vervolgens de bronmetadata die door similarity search is geretourneerd, het gefilterde resultaat en het MMR-resultaat.
Sluit de connection pool na verificatie
De opschoning draait pas nadat inname, retrieval en verificatie zijn afgerond. De drain-tijd geeft bezette verbindingen kort de ruimte om af te ronden. In een langlopende server houd je de pool open tot een nette shutdown. Zie de node-oracledb-documentatie voor
pool.close()voor de levenscyclusdetails.Op dit punt kun je het complete
index.ts-bestand uitvoeren met:Een representatieve validatie-output is:
De exacte volgorde bij similarity en de afstandswaarden kunnen variëren per embeddingmodel en -provider. Het gefilterde resultaat zou
database-guidemoeten bevatten, terwijl het MMR-resultaat een gevarieerde set retrievalbronnen uit de overlappende corpus zou moeten tonen.Tips en troubleshooting
De databaseverbinding faalt
Controleer de connectiestring, inloggegevens, bereikbare service en schemarechten. Als je Autonomous AI Database gebruikt, bevestig dan de vereiste wallet- of TLS-setup. Test de databaseverbinding losstaand voordat je retrieval debugt.
Er treedt een mismatch in embeddingdimensie op
De tijdens inname gemaakte vectoren en de queryvectoren moeten compatibele dimensies gebruiken. Verschillende embeddingmodellen gebruiken voor inserts en queries kan de zoekfunctie breken of resultaten verslechteren. Houd de modelkeuze consistent per tabel.
Een zoekopdracht retourneert geen documenten
Bevestig dat inname rijen heeft ingevoegd en probeer vervolgens opnieuw zonder beperkende metadatafilters. Experimenteer voor kleine corpora met bredere queries en bekijk de opgeslagen content.
De resultaten zijn relevant maar repetitief
Vergelijk similarity search met MMR met een corpus met overlappende stukken. Stel
k,fetchKenlambdaaf terwijl je controleert of diversiteit niet ten koste gaat van belangrijke passages.Moet je een vectorindex aanmaken?
Begin voor een kleine voorbeelddataset met het valideren van de correctheid zonder indexering te tunen. Naarmate data groeit, evalueer je Oracle-vectorindexen zoals Hierarchical Navigable Small World (HNSW) of Inverted File (IVF)-indexen, op basis van je prestatie- en nauwkeurigheidseisen. Indexcreatie is een optimalisatie, geen vereiste om de basisintegratie te begrijpen.
Voor meer details over Oracle-vectorindexen, zie Oracle’s documentatie over vectorindexen.
Verken een complete TypeScript-referentie-implementatie
Wil je zien hoe deze concepten samenkomen in een werkende applicatie? Bekijk de referentie-implementatie voor LangChain.js en Oracle AI Database.
Gebouwd met TypeScript, brengt de applicatie documentinname, vectoropslag, similarity search, metadatafiltering en MMR samen met LangChain.js en Oracle AI Database. Het biedt ook een interactieve interface om met retrievalinstellingen te experimenteren, opgehaalde documenten te inspecteren en te begrijpen hoe verschillende zoekstrategieën de context beïnvloeden die aan de applicatie wordt teruggegeven.
De repository bevat de broncode en installatie-instructies, zodat je de volledige integratie kunt verkennen en de implementatie kunt aanpassen aan je eigen projecten.
Conclusie en vervolgstappen
Je hebt LangChain.js verbonden met Oracle AI Database via
OracleVS, kennis gerepresenteerd alsDocument-objecten, persistente vectorembeddings gemaakt en similarity search, metadatafiltering en MMR vergeleken. Lees voor de volgende stap de officiële documentatie van LangChain.js en de officiële Oracle LangChain JavaScript-integratiegids.Werk je in andere talen, dan behandelt onze Oracle AI Vector Search-tutorial dezelfde opslag- en stappenvragen in Python, en onze LangChain4j-tutorial bouwt een Java-agent met Oracle AI Database.
Onze cursus Retrieval Augmented Generation (RAG) met LangChain is een optioneel retrieval-gericht vervolg; de voorbeelden zijn in Python, maar de workflowconcepten zijn toepasbaar op deze TypeScript-implementatie.