Ga naar hoofdinhoud

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.
· 10 min lezen

Verken met AI

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, OracleEmbeddings en OracleSummary. Dat zijn nuttige optionele bouwstenen; het onderstaande voorbeeld richt zich op OracleVS en houdt embeddinggeneratie apart zodat de flow overzichtelijk blijft.

Architectuurschema met een TypeScript LangChain.js RAG-workflow: een React-UI stuurt een vraag naar een Node.js-API, LangChain.js maakt embeddings en haalt documenten op via OracleVS uit een Oracle AI Database-vector tabel, en de API geeft een onderbouwd antwoord terug.

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.

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/FREEPDB1 en een schema met de hierboven genoemde rechten.

Maak een TypeScript-project

mkdir langchain-oracle-demo
cd langchain-oracle-demo
npm init -y
npm pkg set type=module
npm install @oracle/[email protected] @langchain/[email protected] @langchain/[email protected] [email protected] [email protected]
npm install --save-dev [email protected] [email protected] @types/[email protected]

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_key

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,
});

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]) =>
    new Document({ pageContent, metadata: { source, category } }));

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 = new OpenAIEmbeddings({
    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,
  });

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
FETCH FIRST 1 ROW ONLY;

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:

  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,
  })));

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." }
]

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,
    });
  }

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));

Voorbeeldoutput:

["database-guide"]

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));

Representatieve output uit een overlappende corpus (volgorde kan variëren per embeddingmodel en run):

["retrieval-overlap-2", "mmr-retrieval", "metadata-filtering"]

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 });

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) {
    throw new Error("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),
  });

Sluit de connection pool na verificatie

} finally {
  await pool.close(10);
}

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:

npx tsx index.ts

Een representatieve validatie-output is:

{
  similarity: ["retrieval-overlap-1", "retrieval-overlap-2", "mmr-retrieval"],
  filtered: ["database-guide"],
  mmr: ["retrieval-overlap-2", "mmr-retrieval", "metadata-filtering"]
}

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.

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 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.

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.

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.

Daniela Pavlenco

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.

Onderwerpen

Gerelateerd