Sari la conținutul principal

LangChain.js și Oracle AI Database: Ghid pentru căutare vectorială

Conectează LangChain.js la Oracle AI Database cu OracleVS, stochează embeddings cu metadata și compară căutarea prin similaritate, filtrele pe metadata și MMR în TypeScript.
· 10 min. citește

Descoperă cu AI

Un model de limbaj poate răspunde la întrebări generale, dar nu poate căuta în mod fiabil într-o bază de cunoștințe privată decât dacă o aplicație recuperează mai întâi informațiile relevante. Pentru dezvoltatorii JavaScript, LangChain.js oferă abstracții familiare pentru documente, embeddings și regăsire. Piesa lipsă este un loc persistent în care să stochezi și să cauți vectorii rezultați.

Oracle AI Database acoperă acest rol prin integrarea @oracle/langchain-oracledb. În acest ghid, vei conecta un mic flux TypeScript la Oracle, vei stoca text cu metadata, vei rula o căutare prin similaritate și vei îmbunătăți regăsirea cu filtre și maximal marginal relevance (MMR). Tutorialul se concentrează pe fluxul de regăsire; aplicația companion în TypeScript adaugă aceeași integrare într-o interfață browser interactivă.

Pentru detaliile integrării, vezi ghidul oficial Oracle LangChain JavaScript.

Ce este integrarea LangChain.js și Oracle AI Database?

LangChain.js standardizează modul în care o aplicație lucrează cu modele de embeddings și magazine vectoriale. Pachetul de integrare Oracle furnizează OracleVS, o implementare de vector store care persistă textul documentelor, metadata și embeddings vectoriale în Oracle AI Database. Aplicația ta apelează metodele LangChain.js în loc să scrie manual SQL pentru fiecare interogare de similaritate.

Același pachet de integrare include și OracleDocLoader, OracleTextSplitter, OracleEmbeddings și OracleSummary. Acestea sunt blocuri opționale utile; exemplul de mai jos se concentrează pe OracleVS și păstrează generarea de embeddings separat, astfel încât fluxul să rămână ușor de înțeles.

Diagramă de arhitectură care arată un flux RAG TypeScript cu LangChain.js: o interfață React trimite o întrebare către un API Node.js, LangChain.js creează embeddings și recuperează documente prin OracleVS dintr-un tabel vectorial Oracle AI Database, iar API-ul returnează un răspuns fundamentat pe surse.

Ingestia și regăsirea documentelor folosind LangChain.js, OracleVS și Oracle AI Database

Funcții cheie ale integrării

Stochează embeddings alături de metadata documentelor

Un model de embeddings transformă textul în vectori numerici. OracleVS stochează acești vectori împreună cu textul sursă și metadata structurată. Metadata precum categoria sau sursa documentului ajută aplicația să restrângă căutările fără a pierde context util.

Recuperează pasaje relevante folosind similaritatea vectorială

La interogare, același model de embeddings convertește întrebarea într-un vector. Oracle îl compară cu vectorii stocați folosind o strategie de distanță configurată, cum ar fi distanța cosinus, și returnează cele mai apropiate documente. Rezultatele rămân obiecte Document LangChain, gata pentru procesare ulterioară.

Controlează rezultatele cu filtrare și MMR

Căutarea prin similaritate răspunde la „care elemente sunt cele mai apropiate de această întrebare?”. Un filtru pe metadata restrânge documentele eligibile. MMR adaugă un obiectiv diferit: păstrează pasajele selectate relevante, reducând în același timp rezultatele aproape duplicate. Aceste operații sunt complementare, nu interschimbabile.

Primele pași cu LangChain.js și Oracle AI Database

Cerințe prealabile

Pentru acest exemplu TypeScript, ai nevoie de Node.js 24.13.0, npm 11.6.2, o instanță locală Oracle AI Database 26ai Free cu suport vectorial și o schemă care poate crea, insera, interoga și șterge tabelul demonstrativ și indexul său vectorial. Ai nevoie și de o cheie API OpenAI pentru exemplul de embeddings. OpenAIEmbeddings este o opțiune compatibilă cu LangChain, nu o cerință a OracleVS.

Instalează Node.js din pagina oficială de descărcare Node.js.

Pentru ruta locală principală, urmează ghidul rapid Oracle AI Database Free al Oracle. După ce baza de date rulează, folosește un serviciu precum localhost:1521/FREEPDB1 și o schemă cu permisiunile listate mai sus.

Creează un proiect TypeScript

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]

Creează un fișier numit index.ts în acest folder. Adaugă fragmentele executabile TypeScript de mai jos în același fișier, în ordinea indicată. Nu crea un fișier separat pentru fiecare fragment. Copiază doar fragmentele executabile TypeScript: blocurile de SQL și de ieșire reprezentativă sunt exemple explicative și nu trebuie lipite în index.ts.

Setarea type=module din package.json permite folosirea await la nivel de top, folosită de exemple. Configurația pachetelor Node.js este documentată în ghidul oficial pentru pachete Node.js.

Pachetul de integrare Oracle implementează vector store-ul, @langchain/core furnizează Document, @langchain/openai furnizează modelul de embeddings din exemplu, iar oracledb gestionează conexiunea la baza de date. Versiunile de mai sus corespund aplicației companion; tsx rulează direct exemplul TypeScript fără un pas de build separat.

Configurează conexiunea

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

Salvează aceste valori într-un fișier local .env și adaugă .env în .gitignore. Acest articol folosește Oracle AI Database Free local ca setup principal, astfel încât pașii să fie reproductibili. Autonomous AI Database este o alternativă validă de implementare, dar necesită descriptorul de serviciu și wallet-ul sau configurația TLS pentru acel mediu.

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

Pool-ul permite OracleVS să refolosească sesiunile bazei de date. Păstrează toate instrucțiunile de ingestie, regăsire și verificare în interiorul blocului try. Următorul bloc de cod începe acel bloc, iar fragmentele ulterioare îl continuă. Pool-ul este închis abia după verificare, în secțiunea de curățare de mai jos. Într-o aplicație server, inițializează pool-ul o singură dată și închide-l în timpul opririi controlate, nu deschide o conexiune nouă pentru fiecare cerere.

Cum să construiești căutarea în documente cu LangChain.js

Vom folosi 10 notițe scurte dintr-o bază de cunoștințe, inclusiv pasaje de regăsire care se suprapun. Corpusul este intenționat mic, dar face posibilă compararea căutării obișnuite prin similaritate cu filtrarea pe metadata și MMR.

Definește documentele de cunoștințe

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

Fiecare Document are pageContent și metadata. Câmpurile source și category însoțesc documentul prin ingestie și regăsire, astfel încât aplicația să poată explica de unde provine un rezultat și să restrângă căutările la un subset relevant.

Configurează embeddings și creează 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() este apelul central al integrării. Inițializează vector store-ul, generează embeddings pentru documentele furnizate și stochează conținutul, vectorii și metadata acestora în Oracle AI Database.

Parametrul query oferă text de exemplu care este încorporat în timpul inițializării pentru a determina dimensiunea vectorială necesară tabelului din baza de date. Nu este folosit pentru a căuta în documentele stocate. DistanceStrategy.COSINE specifică metrica de distanță vectorială, iar VectorElementFormat.FLOAT32 stabilește formatul elementelor vectorului.

Înainte de a relua ingestia, folosește un nou nume de tabel demonstrativ sau golește datele existente pentru a evita inserarea de documente duplicate.

OracleVS acceptă o implementare de embeddings compatibilă cu LangChain, astfel încât dezvoltatorii pot schimba furnizorul de embeddings fără a modifica fluxul general al vector store-ului. Totuși, embeddings folosite pentru ingestie și regăsire trebuie să rămână compatibile cu coloana vectorială Oracle.

OracleVS determină dimensiunea vectorială în timpul inițializării folosind modelul de embeddings configurat. Pentru a inspecta dimensiunile și formatul de stocare al unui vector deja stocat în Oracle AI Database, rulează următoarea interogare SQL:

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;

Dacă treci la un model de embeddings cu altă dimensiune, creează un tabel vectorial compatibil și regenerează embeddings pentru documente. Chiar dacă două modele produc vectori cu aceleași dimensiuni, spațiile lor de embeddings pot diferi, așa că documentele existente ar trebui re-încorporate înainte de a folosi noul model pentru regăsire.

Pentru semnăturile metodelor vector store-ului și opțiunile de regăsire, consultă referința LangChain.js VectorStore.

Recuperează documente cu căutare prin similaritate

De exemplu, următorul apel solicită vector store-ului OracleVS cele mai apropiate 3 documente și afișează metadata sursei împreună cu textul fiecărui fragment:

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

Codul transformă fiecare Document LangChain într-un obiect simplu care conține source și pageContent pentru afișare. Mai jos este prezentată o ieșire reprezentativă; ordinea exactă poate varia în funcție de modelul de embeddings și interogare:

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

Primul argument este întrebarea utilizatorului, iar al doilea este k, numărul maxim de documente de regăsit. LangChain.js folosește modelul de embeddings configurat pentru a converti întrebarea într-un vector, iar Oracle AI Database efectuează căutarea prin similaritate pentru a găsi documentele cu cea mai bună potrivire.

Dacă sunt disponibile mai puțin de k documente după aplicarea condițiilor de căutare și a filtrelor de metadata, metoda returnează doar rezultatele disponibile. Obiectele Document regăsite conțin text și metadata care pot fi afișate cu atribuire de sursă sau transmise unui pas ulterior de generare a răspunsului.

Inspectează scorurile regăsirii

De exemplu, folosește similaritySearchWithScore când vrei să inspectezi distanța asociată fiecărui document regăsit:

  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 returnează o distanță pentru fiecare potrivire. Valoarea și sensul numeric depind de strategia de distanță configurată, deci nu este un procent universal de încredere. Compară scorurile doar când folosești același model de embeddings și aceeași strategie de distanță și inspectează pasajul regăsit înainte de a alege un prag.

Limitează rezultatele cu filtre pe metadata

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

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

Exemplu de ieșire:

["database-guide"]

Al treilea argument restrânge căutarea la elementele cu category = database. În acest corpus, rezultatul filtrat previzibil este ["database-guide"]. Un filtru schimbă ce documente sunt eligibile; similaritatea vectorială tot clasează documentele eligibile.

Folosește MMR pentru a reduce rezultatele repetitive

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

Ieșire reprezentativă dintr-un corpus cu suprapuneri (ordonarea poate varia între modele de embeddings și rulări):

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

MMR ia mai întâi în considerare un grup de candidați (fetchK) și apoi selectează k documente, echilibrând relevanța față de interogare cu diversitatea. Un lambda mai mic pune accent mai mare pe diversitate; o valoare mai mare pune accent mai mare pe relevanță. Cu corpusul suprapus de mai sus, sursele selectate pot diferi de căutarea obișnuită prin similaritate, făcând vizibil compromisul de regăsire.

Transmite contextul regăsit către o aplicație AI

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

Acesta este punctul de predare între regăsirea LangChain.js și apelul către un model de limbaj mare (LLM): aplicația are o întrebare plus dovezi inspectabile, gata pentru un prompt care cere modelului să răspundă din acel context.

Regăsirea și generarea sunt responsabilități separate. În acest punct, context este un șir de text simplu pe care un model de chat îl poate consuma. Acum l-ai putea furniza unui model cu instrucțiunea de a răspunde doar din materialul regăsit și de a cita identificatori de sursă. Integrarea cu baza de date funcționează și fără un model de chat.

Cum să verifici integrarea

O validare utilă verifică ingestia și fiecare strategie de regăsire separat. Mai întâi, confirmă că vector store-ul a fost creat fără erori de bază de date. Apoi inspectează metadata sursei returnate de căutarea prin similaritate, rezultatul filtrat și rezultatul MMR.

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

Închide pool-ul de conexiuni după verificare

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

Curățarea rulează doar după ce ingestia, regăsirea și verificarea s-au încheiat. Timpul de drenaj oferă conexiunilor în uz o scurtă fereastră pentru a se finaliza. Într-un server care rulează pe termen lung, păstrează pool-ul deschis până la oprirea controlată. Vezi documentația node-oracledb pentru pool.close() pentru detalii despre ciclul de viață.

În acest moment, fișierul complet index.ts poate fi executat cu:

npx tsx index.ts

O ieșire reprezentativă de validare este:

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

Ordinea exactă a similarității și valorile distanței pot varia în funcție de modelul și furnizorul de embeddings. Rezultatul filtrat ar trebui să conțină database-guide, în timp ce rezultatul MMR ar trebui să arate un set variat de surse de regăsire din corpusul suprapus.

Sfaturi și depanare

Conexiunea la baza de date eșuează

Verifică șirul de conexiune, credențialele, serviciul accesibil și privilegiile schemei. Dacă folosești Autonomous AI Database, confirmă configurarea necesară a wallet-ului sau TLS. Testează conexiunea la baza de date independent înainte de a depana regăsirea.

Apare un neconcordanță a dimensiunii embeddings

Vectorii creați în timpul ingestiei și vectorii interogărilor trebuie să aibă dimensiuni compatibile. Folosirea unor modele de embeddings diferite pentru inserări și interogări poate strica căutarea sau degrada rezultatele. Păstrează selecția modelului consecventă pentru un tabel.

O căutare nu returnează documente

Confirmă că ingestia a inserat rânduri, apoi încearcă din nou fără filtre de metadata restrictive. Pentru corpuri mici, experimentează cu interogări mai largi și inspectează conținutul stocat.

Rezultatele sunt relevante, dar repetitive

Compară căutarea prin similaritate cu MMR folosind un corpus cu fragmente care se suprapun. Reglează k, fetchK și lambda verificând dacă diversitatea vine cu prețul omiterii unor pasaje importante.

Ar trebui să creezi un index vectorial?

Pentru un set de date eșantion mic, începe prin a valida corectitudinea fără a ajusta indexarea. Pe măsură ce datele cresc, evaluează indexurile vectoriale Oracle precum HNSW (Hierarchical Navigable Small World) sau IVF (Inverted File), în funcție de cerințele tale de performanță și acuratețe. Crearea indexului este o optimizare, nu o precondiție pentru a înțelege integrarea de bază.

Pentru mai multe detalii despre indexurile vectoriale Oracle, vezi documentația despre indexuri vectoriale a Oracle.

Explorează o implementare de referință completă în TypeScript

Pentru a vedea cum se reunesc aceste concepte într-o aplicație funcțională, explorează implementarea de referință LangChain.js și Oracle AI Database.

Creată cu TypeScript, aplicația reunește ingestia de documente, stocarea vectorilor, căutarea prin similaritate, filtrarea pe metadata și MMR folosind LangChain.js și Oracle AI Database. Oferă și o interfață interactivă pentru a experimenta setări de regăsire, a inspecta documentele regăsite și a înțelege cum diferite strategii de căutare afectează contextul returnat aplicației.

Repository-ul include codul sursă și instrucțiunile de configurare, permițându-ți să explorezi integrarea completă și să adaptezi implementarea la propriile proiecte.

Concluzie și pașii următori

Ai conectat LangChain.js la Oracle AI Database prin OracleVS, ai reprezentat cunoștințele ca obiecte Document, ai creat embeddings vectoriale persistente și ai comparat căutarea prin similaritate, filtrarea pe metadata și MMR. Pentru următorul pas, citește documentația oficială LangChain.js și ghidul oficial Oracle LangChain JavaScript.

Dacă lucrezi în alte limbaje, tutorialul nostru Oracle AI Vector Search acoperă aceiași pași de stocare și interogare în Python, iar tutorialul nostru LangChain4j construiește un agent Java cu Oracle AI Database.

Cursul nostru Retrieval Augmented Generation (RAG) cu LangChain este un follow-up opțional axat pe regăsire; exemplele sunt în Python, dar conceptele de lucru se aplică acestei implementări TypeScript.

Întrebări frecvente

Ce se întâmplă dacă schimb modelele de embeddings după ce am stocat documentele?

Embeddings stocate în tabelul vectorial Oracle trebuie să fie compatibile cu embeddings folosite pentru căutare. Schimbarea modelelor poate modifica atât dimensiunile vectorilor, cât și semnificația coordonatelor, așa că re-încorporează și reindexează documentele când schimbi modelele de embeddings. Folosește aceeași configurație de embeddings pentru ingestia documentelor și regăsirea la interogare.

Am nevoie de un model de chat ca să folosesc OracleVS?

Nu. Un flux cu vector store necesită un model de embeddings pentru ingestie și interogare. Un model de chat este opțional și este adăugat de obicei când pasaje regăsite trebuie transformate într-un răspuns în limbaj natural.

Pot folosi un furnizor de embeddings diferit de OpenAI?

Da. OracleVS acceptă o implementare de embeddings LangChain compatibilă. Alege un furnizor care îți îndeplinește cerințele și folosește aceeași configurare compatibilă de embeddings pentru documente și interogări.

De ce să folosesc filtrarea pe metadata împreună cu similaritatea vectorială?

Similaritatea vectorială găsește conținut semnificativ apropiat; filtrarea pe metadata restrânge ce conținut poate fi returnat, cum ar fi documente dintr-o anumită categorie sau sursă.

Când ar trebui să aleg MMR în locul căutării obișnuite prin similaritate?

MMR ajută când potrivirile de top conțin pasaje repetitive și aplicația beneficiază de dovezi mai variate. Căutarea simplă prin similaritate este mai directă când cei mai apropiați vecini sunt obiectivul principal.

Daniela Pavlenco

Autor

Daniela Pavlenco

Sunt Developer Advocate la Oracle, concentrat pe a-i ajuta pe dezvoltatori să exploreze tehnologiile de IA și să creeze aplicații practice cu instrumente și framework-uri moderne. Munca mea include crearea de conținut tehnic, exemple practice și resurse pentru dezvoltatori care fac conceptele complexe mai ușor de înțeles și de aplicat în proiecte reale.

Subiecte