Hoppa till huvudinnehållet

LangChain.js och Oracle AI Database: Guide till vektorsökning

Anslut LangChain.js till Oracle AI Database med OracleVS, lagra inbäddningar med metadata och jämför likhetssökning, metadatafilter och MMR i TypeScript.
· 10 min läs

Utforska med AI

En språkmodell kan svara på allmänna frågor, men den kan inte pålitligt slå upp i en privat kunskapsbas om inte en applikation först hämtar relevant information. För JavaScript-utvecklare erbjuder LangChain.js bekanta abstraktioner för dokument, inbäddningar och hämtning. Den saknade pusselbiten är en beständig plats att lagra och söka i de resulterande vektorerna.

Oracle AI Database fyller den rollen genom integrationen @oracle/langchain-oracledb. I den här guiden kopplar du ett litet TypeScript‑flöde till Oracle, lagrar text med metadata, kör likhetssökning och förbättrar hämtning med filter och maximal marginalrelevans (MMR). Handledningen fokuserar på hämtflödet; den tillhörande TypeScript‑applikationen lägger till samma integration i ett interaktivt gränssnitt i webbläsaren.

För integrationsdetaljer, se den officiella Oracle LangChain JavaScript‑integrationsguiden.

Vad är integrationen mellan LangChain.js och Oracle AI Database?

LangChain.js standardiserar hur en applikation arbetar med inbäddningsmodeller och vektorarkiv. Oracle‑integrationspaketet tillhandahåller OracleVS, en implementation av ett vektorarkiv som lagrar dokumenttext, metadata och vektor­inbäddningar i Oracle AI Database. Din applikation anropar metoder i LangChain.js i stället för att manuellt skriva SQL för varje likhetsfråga.

Samma integrationspaket innehåller också OracleDocLoader, OracleTextSplitter, OracleEmbeddings och OracleSummary. Det är användbara, valfria byggstenar; exemplet nedan fokuserar på OracleVS och håller generering av inbäddningar separat så att flödet förblir lätt att förstå.

Arkitekturskiss som visar ett TypeScript‑baserat RAG‑flöde i LangChain.js: ett React‑gränssnitt skickar en fråga till ett Node.js‑API, LangChain.js skapar inbäddningar och hämtar dokument via OracleVS från en vektortabell i Oracle AI Database, och API:t returnerar ett förankrat svar.

Dokument­inläsning och hämtning med LangChain.js, OracleVS och Oracle AI Database

Viktiga funktioner i integrationen

Lagra inbäddningar tillsammans med dokumentmetadata

En inbäddningsmodell omvandlar text till numeriska vektorer. OracleVS lagrar dessa vektorer med källtexten och strukturerad metadata. Metadata som dokumentkategori eller källa hjälper applikationen att begränsa sökningar utan att förlora nyttigt sammanhang.

Hämta relevanta stycken med vektorsimilaritet

Vid frågetillfället omvandlar samma inbäddningsmodell frågan till en vektor. Oracle jämför den med de lagrade vektorerna med en konfigurerad distansstrategi, till exempel cosinusavstånd, och returnerar de närmaste dokumenten. Resultaten förblir LangChain‑objekt av typen Document, redo för vidare bearbetning.

Styr resultaten med filtrering och MMR

Likhetssökning svarar på ”vilka objekt ligger närmast denna fråga?” Ett metadatafilter begränsar aktuella dokument. MMR tillför ett annat mål: behålla relevans i de valda styckena samtidigt som närmast identiska resultat minskas. Dessa operationer kompletterar varandra snarare än ersätter varandra.

Kom igång med LangChain.js och Oracle AI Database

Förutsättningar

För detta TypeScript‑exempel behöver du Node.js 24.13.0, npm 11.6.2, en lokal instans av Oracle AI Database 26ai Free med vektorstöd och ett schema som kan skapa, skriva till, fråga och ta bort demotabellen och dess vektorindex. Du behöver också en OpenAI API‑nyckel för inbäddningsexemplet. OpenAIEmbeddings är ett LangChain‑kompatibelt val, inte ett krav från OracleVS.

Installera Node.js från den officiella nedladdningssidan för Node.js.

För den primära lokala vägen, följ Oracles snabbstart för Oracle AI Database Free. Efter att databasen körs, använd en tjänst som localhost:1521/FREEPDB1 och ett schema med behörigheterna som anges ovan.

Skapa ett TypeScript‑projekt

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]

Skapa en fil med namnet index.ts i den här mappen. Lägg till de körbara TypeScript‑snuttarna nedan i samma fil, i den ordning som visas. Skapa inte en separat fil för varje snutt. Kopiera endast de körbara TypeScript‑snuttarna: SQL‑ och representativ‑utdata‑blocken är förklaringsexempel och ska inte klistras in i index.ts.

Inställningen type=module i package.json tillåter det toppnivå‑await som används av exemplen. Konfigurationen av Node.js‑paket dokumenteras i den officiella guiden för Node.js‑paket.

Oracle‑integrationspaketet implementerar vektorarkivet, @langchain/core tillhandahåller Document, @langchain/openai tillhandahåller exempelmodellen för inbäddningar och oracledb hanterar databasanslutningen. Versionerna ovan matchar den tillhörande applikationen; tsx kör TypeScript‑exemplet direkt utan ett separat byggsteg.

Konfigurera anslutningen

ORACLE_USER=your_schema
ORACLE_PASSWORD=your_password
ORACLE_CONNECT_STRING=localhost:1521/FREEPDB1
OPENAI_API_KEY=your_api_key

Spara dessa värden i en lokal .env-fil och lägg till .env i .gitignore. Den här artikeln använder lokal Oracle AI Database Free som primär installation så att stegen är reproducerbara. Autonomous AI Database är ett giltigt distributionsalternativ, men det kräver servicedeskriptorn och wallet‑ eller TLS‑konfiguration för den miljön.

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

Poolen låter OracleVS återanvända databassessioner. Håll all inläsning, hämtning och verifiering inuti try-blocket. Nästa kodblock startar det blocket, och de senare snuttarna fortsätter det. Poolen stängs först efter verifiering i städdelen nedan. I en serverapplikation initierar du poolen en gång och stänger den vid kontrollerad nedstängning i stället för att öppna en ny anslutning för varje användarförfrågan.

Så bygger du dokumentsökning med LangChain.js

Vi kommer att använda 10 korta kunskapsbasanteckningar, inklusive överlappande hämtstycken. Korpusen är avsiktligt liten, men den gör det möjligt att jämföra vanlig likhetssökning med metadatafiltrering och MMR.

Definiera dina kunskapsdokument

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

Varje Document har pageContent och metadata. Fälten source och category följer med dokumentet genom inläsning och hämtning, så att applikationen kan förklara var ett resultat kom ifrån och begränsa sökningar till en relevant delmängd.

Konfigurera inbäddningar och skapa OracleVS

  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() är det centrala integrationsanropet. Det initierar vektorarkivet, genererar inbäddningar för de angivna dokumenten och lagrar deras innehåll, vektorer och metadata i Oracle AI Database.

Parametern query tillhandahåller exempeltext som bäddas in under initieringen för att avgöra den vektordimension som krävs för databastabellen. Den används inte för att söka i de lagrade dokumenten. DistanceStrategy.COSINE anger vektordistansmåttet, medan VectorElementFormat.FLOAT32 anger vektorelementens format.

Innan du kör inläsning igen, använd ett nytt namn på demotabellen eller rensa befintlig data för att undvika att infoga dubblettdokument.

OracleVS accepterar en LangChain‑kompatibel inbäddningsimplementation, så utvecklare kan byta inbäddningsleverantör utan att ändra det övergripande vektorarkivsflödet. Däremot måste inbäddningarna som används för inläsning och hämtning förbli kompatibla med Oracles vektorkolumn.

OracleVS fastställer vektordimensionen under initieringen med hjälp av den konfigurerade inbäddningsmodellen. För att inspektera dimensioner och lagringsformat för en vektor som redan finns i Oracle AI Database, kör följande SQL‑fråga:

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;

Om du byter till en inbäddningsmodell med en annan dimension, skapa en kompatibel vektortabell och återskapa dokumentinbäddningarna. Även om två modeller producerar vektorer med samma dimensioner kan deras inbäddningsrymder skilja sig, så befintliga dokument bör bäddas in på nytt innan du använder den nya modellen för hämtning.

För metodsignaturer i vektorarkivet och hämtalternativ, se den officiella referensen för LangChain.js VectorStore.

Hämta dokument med likhetssökning

Exempelvis ber följande anrop vektorarkivet OracleVS om de 3 närmaste dokumenten och skriver ut källmetadata tillsammans med varje styckes text:

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

Koden mappar varje LangChain‑Document till ett vanligt objekt som innehåller dess source och pageContent för visning. En representativ utdata visas nedan; den exakta ordningen kan variera med inbäddningsmodell och fråga:

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

Det första argumentet är användarens fråga, och det andra är k, det maximala antalet dokument som ska hämtas. LangChain.js använder den konfigurerade inbäddningsmodellen för att omvandla frågan till en vektor, och Oracle AI Database utför likhetssökning för att hitta de närmast matchande dokumenten.

Om färre än k dokument finns tillgängliga efter att sökvillkor och metadatafilter tillämpats, returnerar metoden endast de tillgängliga resultaten. De hämtade Document-objekten innehåller text och metadata som kan visas med källhänvisning eller skickas vidare till ett senare steg för svarsgenerering.

Inspektera hämtpoäng

Använd till exempel similaritySearchWithScore när du vill inspektera distansen som är associerad med varje hämtat dokument:

  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 returnerar ett avstånd med varje träff. Dess numeriska värde och riktning beror på den konfigurerade distansstrategin, så det är inte en universell tillförlitlighetsprocent. Jämför poäng endast när du använder samma inbäddningsmodell och distansstrategi, och inspektera det hämtade stycket innan du väljer en tröskel.

Begränsa resultat med metadatafilter

  const databaseOnly = await vectorStore.similaritySearch(
    "Where are vector embeddings stored?",
    3,
    { category: { $eq: "database" } }
  );

  console.log(databaseOnly.map((doc) => doc.metadata.source));

Exempelutdata:

["database-guide"]

Det tredje argumentet begränsar sökningen till objekt med category = database. I den här korpusen är det förutsägbara filtrerade resultatet ["database-guide"]. Ett filter ändrar vilka dokument som är aktuella; vektorsimilaritet rankar fortfarande de aktuella dokumenten.

Använd MMR för att minska repetitiva resultat

  const diverse = await vectorStore.maxMarginalRelevanceSearch(
    retrievalQuestion,
    {
      k: 3,
      fetchK: 6,
      lambda: 0.5,
    }
  );
  console.log(diverse.map((doc) => doc.metadata.source));

Representativ utdata från en överlappande korpus (ordning kan variera mellan inbäddningsmodeller och körningar):

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

MMR beaktar först en kandidatpool (fetchK) och väljer sedan k dokument genom att balansera frågerelevans med mångfald. Ett lägre lambda betonar mångfald mer; ett högre värde betonar relevans mer. Med den överlappande korpusen ovan kan de valda källorna skilja sig från vanlig likhetssökning, vilket gör hämtavvägningen synlig.

Skicka hämtat sammanhang till en AI‑applikation

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

Detta är överlämningspunkten mellan LangChain.js‑hämtning och ett stort språkmodell‑anrop (LLM): applikationen har en fråga plus granskningsbart underlag, redo för en prompt som ber modellen att svara utifrån det sammanhanget.

Hämtning och generering är separata ansvar. Vid det här laget är context en ren textsträng som en chatmodell kan konsumera. Du kan nu ge den till en modell med en instruktion om att endast svara utifrån det hämtade materialet och ange källidentiteter. Själva databasintegrationen fungerar även utan en chatmodell.

Så verifierar du integrationen

En användbar validering kontrollerar inläsning och varje hämtstrategi separat. Bekräfta först att vektorarkivet skapades utan databasfel. Inspektera sedan källmetadata som returneras av likhetssökningen, det filtrerade resultatet och MMR‑resultatet.

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

Stäng anslutningspoolen efter verifiering

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

Städningen körs först efter att inläsning, hämtning och verifiering har slutförts. Tömnings­tiden ger upptagna anslutningar ett kort tidsfönster att avsluta. I en långlivad server håller du poolen öppen till kontrollerad nedstängning. Se dokumentationen för node‑oracledb pool.close() för detaljer om livscykeln.

Vid det här laget kan den kompletta filen index.ts köras med:

npx tsx index.ts

En representativ valideringsutdata är:

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

Den exakta likhetsordningen och distansvärdena kan variera med inbäddningsmodell och leverantör. Det filtrerade resultatet bör innehålla database-guide, medan MMR‑resultatet bör visa en varierad uppsättning hämtkällor från den överlappande korpusen.

Tips och felsökning

Databasanslutningen misslyckas

Verifiera anslutningssträng, autentiseringsuppgifter, nåbar tjänst och schemabehörigheter. Om du använder Autonomous AI Database, bekräfta dess nödvändiga wallet‑ eller TLS‑konfiguration. Testa databasanslutningen separat innan du felsöker hämtning.

En mismatch i inbäddningsdimension uppstår

Vektorerna som skapas under inläsning och frågevektorerna måste använda kompatibla dimensioner. Att använda olika inbäddningsmodeller för infogningar och frågor kan förstöra sökningen eller försämra resultaten. Håll modellvalet konsekvent för en tabell.

En sökning returnerar inga dokument

Bekräfta att inläsningen infogade rader och försök sedan igen utan restriktiva metadatafilter. För små korpusar, experimentera med bredare frågor och inspektera det lagrade innehållet.

Resultaten är relevanta men repetitiva

Jämför likhetssökning med MMR med en korpus med överlappande stycken. Justera k, fetchK och lambda samtidigt som du kontrollerar om mångfald kommer på bekostnad av att viktiga stycken missas.

Ska du skapa ett vektorindex?

För ett litet exempeldata­set, börja med att validera korrekthet utan att trimma indexering. När data växer, utvärdera Oracles vektorindex som Hierarchical Navigable Small World (HNSW) eller Inverted File (IVF) utifrån dina krav på prestanda och noggrannhet. Indexskapande är en optimering, inte en förutsättning för att förstå den grundläggande integrationen.

För mer detaljer om Oracles vektorindex, se Oracles dokumentation om vektorindex.

Utforska en komplett referensimplementation i TypeScript

För att se hur dessa koncept samverkar i en fungerande applikation, utforska referensimplementationen för LangChain.js och Oracle AI Database.

Applikationen är byggd med TypeScript och samlar dokumentinläsning, vektorlagring, likhetssökning, metadatafiltrering och MMR med LangChain.js och Oracle AI Database. Den erbjuder också ett interaktivt gränssnitt för att experimentera med hämtinställningar, inspektera hämtade dokument och förstå hur olika sökstrategier påverkar det sammanhang som returneras till applikationen.

Repo:t innehåller källkoden och installationsinstruktioner, så att du kan utforska hela integrationen och anpassa implementationen till dina egna projekt.

Slutsats och nästa steg

Du har kopplat LangChain.js till Oracle AI Database via OracleVS, representerat kunskap som Document-objekt, skapat beständiga vektor­inbäddningar och jämfört likhetssökning, metadatafiltrering och MMR. Som nästa steg, läs den officiella dokumentationen för LangChain.js och den officiella Oracle LangChain JavaScript‑integrationsguiden.

Om du arbetar i andra språk täcker vår Oracle AI Vector Search‑handledning samma lagrings‑ och frågesteg i Python, och vår LangChain4j‑handledning bygger en Java‑agent med Oracle AI Database.

Vår kurs Retrieval Augmented Generation (RAG) med LangChain är en valfri, hämtfokuserad uppföljning; dess exempel är i Python, men arbetsflödeskoncepten gäller för denna TypeScript‑implementation.

Vanliga frågor

Vad händer om jag byter inbäddningsmodeller efter att dokument har lagrats?

Inbäddningar som lagras i Oracles vektortabell måste vara kompatibla med de inbäddningar som används för sökning. Att byta modeller kan ändra både vektordimensioner och betydelsen av vektorkoordinater, så återskapa inbäddningar och indexera om dokumenten när du byter inbäddningsmodell. Använd samma inbäddningskonfiguration för dokumentinläsning och frågehämtning.

Behöver jag en chatmodell för att använda OracleVS?

Nej. Ett vektorarkivsflöde kräver en inbäddningsmodell för inläsning och fråga. En chatmodell är valfri och läggs vanligtvis till när de hämtade styckena ska omvandlas till ett svar i naturligt språk.

Kan jag använda en annan inbäddningsleverantör än OpenAI?

Ja. OracleVS accepterar en kompatibel LangChain‑inbäddningsimplementation. Välj en leverantör som uppfyller dina krav och använd samma kompatibla inbäddningsupplägg för dokument och frågor.

Varför använda metadatafiltrering tillsammans med vektorsimilaritet?

Vektorsimilaritet hittar semantiskt närliggande innehåll; metadatafiltrering begränsar vilket innehåll som kan returneras, till exempel dokument i en viss kategori eller källa.

När ska jag välja MMR framför vanlig likhetssökning?

MMR hjälper när toppträffarna innehåller repetitiva stycken och applikationen gynnas av mer varierade underlag. Enkel likhetssökning är enklare när närmaste grannar är det primära målet.

Daniela Pavlenco

Författare

Daniela Pavlenco

Jag är Developer Advocate på Oracle med fokus på att hjälpa utvecklare att utforska AI‑tekniker och bygga praktiska applikationer med moderna verktyg och ramverk. Mitt arbete innefattar att skapa tekniskt innehåll, praktiska exempel och utvecklarresurser som gör komplexa koncept enklare att förstå och tillämpa i verkliga projekt.

Ämnen