Vai al contenuto principale

LangChain.js e Oracle AI Database: guida alla ricerca vettoriale

Collega LangChain.js a Oracle AI Database con OracleVS, archivia embedding con metadata e confronta similarity search, filtri sui metadata e MMR in TypeScript.
· 10 min leggi

Scopri con l'IA

Un modello linguistico può rispondere a domande generali, ma non può consultare in modo affidabile una base di conoscenza privata a meno che un’applicazione non recuperi prima le informazioni pertinenti. Per gli sviluppatori JavaScript, LangChain.js offre astrazioni familiari per documenti, embedding e retrieval. Il tassello mancante è un luogo persistente dove archiviare e cercare i vettori risultanti.

Oracle AI Database copre quel ruolo tramite l’integrazione @oracle/langchain-oracledb. In questa guida collegherai un piccolo flusso di lavoro TypeScript a Oracle, archivierai testo con metadata, eseguirai una similarity search e migliorerai il retrieval con filtri e maximal marginal relevance (MMR). Il tutorial si concentra sul flusso di retrieval; l’applicazione TypeScript di accompagnamento aggiunge la stessa integrazione a un’interfaccia browser interattiva.

Per i dettagli dell’integrazione, vedi la guida ufficiale all’integrazione Oracle LangChain JavaScript.

Cos’è l’integrazione tra LangChain.js e Oracle AI Database?

LangChain.js standardizza come un’applicazione lavora con modelli di embedding e vector store. Il pacchetto di integrazione Oracle fornisce OracleVS, un’implementazione di vector store che persiste testo dei documenti, metadata ed embedding vettoriali in Oracle AI Database. La tua applicazione chiama i metodi di LangChain.js invece di scrivere manualmente SQL per ogni query di similarità.

Lo stesso pacchetto di integrazione include anche OracleDocLoader, OracleTextSplitter, OracleEmbeddings e OracleSummary. Sono mattoncini opzionali utili; l’esempio seguente si concentra su OracleVS e mantiene la generazione degli embedding separata per rendere il flusso più facile da seguire.

Diagramma dell’architettura che mostra un workflow RAG TypeScript con LangChain.js: una UI React invia una domanda a una API Node.js, LangChain.js crea gli embedding e recupera i documenti tramite OracleVS da una tabella vettoriale di Oracle AI Database, e l’API restituisce una risposta fondata su dati.

Ingestione e retrieval di documenti con LangChain.js, OracleVS e Oracle AI Database

Funzionalità principali dell’integrazione

Archivia gli embedding insieme ai metadata dei documenti

Un modello di embedding trasforma il testo in vettori numerici. OracleVS archivia questi vettori insieme al testo sorgente e ai metadata strutturati. Metadata come categoria o fonte del documento aiutano l’applicazione a limitare le ricerche senza perdere contesto utile.

Recupera passaggi rilevanti tramite similarità vettoriale

In fase di query, lo stesso modello di embedding converte la domanda in un vettore. Oracle lo confronta con i vettori archiviati usando una strategia di distanza configurata, come la distanza coseno, e restituisce i documenti più vicini. I risultati restano oggetti Document di LangChain, pronti per l’elaborazione a valle.

Controlla i risultati con filtri e MMR

La similarity search risponde alla domanda: «quali elementi sono più vicini a questa domanda?». Un filtro sui metadata restringe i documenti idonei. L’MMR aggiunge un obiettivo diverso: mantenere i passaggi selezionati rilevanti riducendo i risultati quasi duplicati. Queste operazioni sono complementari, non intercambiabili.

Primi passi con LangChain.js e Oracle AI Database

Prerequisiti

Per questo esempio TypeScript, ti servono Node.js 24.13.0, npm 11.6.2, un’istanza locale Oracle AI Database 26ai Free con supporto ai vettori e uno schema che possa creare, inserire, interrogare ed eliminare la tabella dimostrativa e il suo indice vettoriale. Ti serve anche una chiave API OpenAI per l’esempio sugli embedding. OpenAIEmbeddings è una scelta compatibile con LangChain, non un requisito di OracleVS.

Installa Node.js dalla pagina ufficiale dei download di Node.js.

Per la via locale principale, segui il quick start di Oracle AI Database Free. Dopo l’avvio del database, usa un service come localhost:1521/FREEPDB1 e uno schema con i permessi indicati sopra.

Crea un progetto 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]

Crea un file chiamato index.ts in questa cartella. Aggiungi nello stesso file gli snippet TypeScript eseguibili qui sotto, nell’ordine indicato. Non creare un file separato per ogni snippet. Copia solo gli snippet TypeScript eseguibili: i blocchi SQL e di output rappresentativo sono esempi esplicativi e non vanno incollati in index.ts.

L’impostazione package.json type=module consente il await a livello superiore usato dagli esempi. La configurazione dei pacchetti Node.js è documentata nella guida ufficiale ai pacchetti Node.js.

Il pacchetto di integrazione Oracle implementa il vector store, @langchain/core fornisce Document, @langchain/openai fornisce il modello di embedding d’esempio e oracledb gestisce la connessione al database. Le versioni sopra corrispondono all’app di accompagnamento; tsx esegue direttamente l’esempio TypeScript senza un passaggio di build separato.

Configura la connessione

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

Salva questi valori in un file locale .env e aggiungi .env a .gitignore. Questo articolo usa Oracle AI Database Free locale come configurazione principale, così i passaggi sono riproducibili. Autonomous AI Database è una valida alternativa di deployment, ma richiede il service descriptor e il wallet o la configurazione TLS per quell’ambiente.

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

Il pool permette a OracleVS di riutilizzare le sessioni del database. Tieni tutte le istruzioni di ingestione, retrieval e verifica dentro il blocco try. Il prossimo blocco di codice avvia quel blocco, e i frammenti successivi lo proseguono. Il pool è chiuso solo dopo la verifica nella sezione di cleanup qui sotto. In un’app server, inizializza il pool una sola volta e chiudilo durante l’arresto graduale invece di aprire una nuova connessione per ogni richiesta utente.

Come realizzare la ricerca nei documenti con LangChain.js

Useremo 10 brevi note di knowledge base, incluse porzioni di retrieval sovrapposte. Il corpus è volutamente piccolo, ma consente di confrontare la similarity search ordinaria con il filtro sui metadata e l’MMR.

Definisci i tuoi documenti di conoscenza

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

Ogni Document ha pageContent e metadata. I campi source e category viaggiano con il documento durante ingestione e retrieval, così l’applicazione può spiegare da dove proviene un risultato e limitare le ricerche a un sottoinsieme rilevante.

Configura gli embedding e crea 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() è la chiamata centrale dell’integrazione. Inizializza il vector store, genera gli embedding per i documenti forniti e archivia il loro contenuto, i vettori e i metadata in Oracle AI Database.

Il parametro query fornisce del testo di esempio che viene incorporato durante l’inizializzazione per determinare la dimensione vettoriale richiesta per la tabella del database. Non viene usato per cercare nei documenti archiviati. DistanceStrategy.COSINE specifica la metrica di distanza vettoriale, mentre VectorElementFormat.FLOAT32 imposta il formato degli elementi del vettore.

Prima di rieseguire l’ingestione, usa un nuovo nome di tabella dimostrativa o svuota i dati esistenti per evitare di inserire documenti duplicati.

OracleVS accetta un’implementazione di embedding compatibile con LangChain, quindi gli sviluppatori possono cambiare fornitore di embedding senza modificare il flusso complessivo del vector store. Tuttavia, gli embedding usati per ingestione e retrieval devono rimanere compatibili con la colonna vettoriale di Oracle.

OracleVS determina la dimensione del vettore durante l’inizializzazione usando il modello di embedding configurato. Per ispezionare le dimensioni e il formato di archiviazione di un vettore già salvato in Oracle AI Database, esegui la seguente query 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;

Se passi a un modello di embedding con dimensione diversa, crea una tabella vettoriale compatibile e rigenera gli embedding dei documenti. Anche se due modelli producono vettori con le stesse dimensioni, i loro spazi di embedding possono differire, quindi i documenti esistenti andrebbero re-incorporati prima di usare il nuovo modello per il retrieval.

Per le firme dei metodi del vector store e le opzioni di retrieval, vedi la reference di LangChain.js VectorStore ufficiale.

Recupera documenti con similarity search

Ad esempio, la chiamata seguente chiede al vector store OracleVS i 3 documenti più vicini e stampa il metadata source insieme al testo di ogni chunk:

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

Il codice mappa ogni Document di LangChain a un oggetto semplice contenente source e pageContent per la visualizzazione. Un output rappresentativo è mostrato qui sotto; l’ordine esatto può variare con il modello di embedding e la 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." }
]

Il primo argomento è la domanda dell’utente, il secondo è k, il numero massimo di documenti da recuperare. LangChain.js usa il modello di embedding configurato per convertire la domanda in un vettore e Oracle AI Database esegue la similarity search per trovare i documenti più vicini.

Se, dopo le condizioni di ricerca e i filtri sui metadata, sono disponibili meno di k documenti, il metodo restituisce solo i risultati disponibili. I Document recuperati contengono testo e metadata che possono essere mostrati con attribuzione della fonte o passati a un successivo passaggio di generazione della risposta.

Ispeziona i punteggi di retrieval

Per esempio, usa similaritySearchWithScore quando vuoi ispezionare la distanza associata a ciascun documento recuperato:

  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 restituisce una distanza con ogni corrispondenza. Il suo valore numerico e la direzione dipendono dalla strategia di distanza configurata, quindi non è una percentuale di confidenza universale. Confronta i punteggi solo quando usi lo stesso modello di embedding e la stessa strategia di distanza, e ispeziona il passaggio recuperato prima di scegliere una soglia.

Limita i risultati con filtri sui metadata

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

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

Output di esempio:

["database-guide"]

Il terzo argomento limita la ricerca agli elementi con category = database. In questo corpus, il risultato filtrato prevedibile è ["database-guide"]. Un filtro cambia quali documenti sono idonei; la similarità vettoriale continua a ordinare i documenti idonei.

Usa l’MMR per ridurre i risultati ripetitivi

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

Output rappresentativo da un corpus sovrapposto (l’ordinamento può variare tra modelli di embedding ed esecuzioni):

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

L’MMR considera prima un insieme di candidati (fetchK) e poi seleziona k documenti bilanciando rilevanza della query e diversità. Un lambda più basso enfatizza maggiormente la diversità; un valore più alto enfatizza maggiormente la rilevanza. Con il corpus sovrapposto sopra, le fonti selezionate possono differire dalla similarity search ordinaria, rendendo visibile il compromesso nel retrieval.

Passa il contesto recuperato a un’applicazione 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 });

Questo è il punto di passaggio tra il retrieval di LangChain.js e la chiamata a un large language model (LLM): l’applicazione ha una domanda più evidenza ispezionabile, pronta per un prompt che chieda al modello di rispondere a partire da quel contesto.

Retrieval e generazione sono responsabilità separate. A questo punto, context è una semplice stringa di testo che un modello di chat può consumare. Ora potresti fornirla a un modello con l’istruzione di rispondere solo dal materiale recuperato e citare gli identificatori delle fonti. L’integrazione con il database funziona anche senza un modello di chat.

Come verificare l’integrazione

Una validazione utile controlla separatamente ingestione e ogni strategia di retrieval. Per prima cosa, conferma che il vector store sia stato creato senza errori di database. Poi ispeziona i metadata di origine restituiti dalla similarity search, dal risultato filtrato e dal risultato 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),
  });

Chiudi il connection pool dopo la verifica

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

Il cleanup viene eseguito solo dopo che ingestione, retrieval e verifica sono terminati. Il tempo di drain concede alle connessioni in uso una breve finestra per completare. In un server a lunga esecuzione, mantieni il pool aperto fino all’arresto graduale. Vedi la documentazione pool.close() di node-oracledb per i dettagli sul ciclo di vita.

A questo punto, il file index.ts completo può essere eseguito con:

npx tsx index.ts

Un output di validazione rappresentativo è:

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

L’ordine esatto della similarità e i valori di distanza possono variare con il modello e il fornitore di embedding. Il risultato filtrato dovrebbe contenere database-guide, mentre il risultato MMR dovrebbe mostrare un insieme vario di fonti di retrieval dal corpus sovrapposto.

Suggerimenti e risoluzione dei problemi

La connessione al database fallisce

Verifica stringa di connessione, credenziali, servizio raggiungibile e privilegi dello schema. Se usi Autonomous AI Database, conferma il wallet richiesto o la configurazione TLS. Metti alla prova la connessione al database in modo indipendente prima di fare debug del retrieval.

Si verifica un mismatch nella dimensione degli embedding

I vettori creati durante l’ingestione e i vettori della query devono usare dimensioni compatibili. Usare modelli di embedding diversi per gli insert e per le query può interrompere la ricerca o degradare i risultati. Mantieni coerente la scelta del modello per una tabella.

Una ricerca non restituisce documenti

Conferma che l’ingestione abbia inserito righe, poi riprova senza filtri sui metadata troppo restrittivi. Per corpora piccoli, sperimenta con query più ampie e ispeziona il contenuto archiviato.

I risultati sono rilevanti ma ripetitivi

Confronta la similarity search con l’MMR usando un corpus con chunk sovrapposti. Regola k, fetchK e lambda verificando se la diversità comporta la perdita di passaggi importanti.

Devi creare un indice vettoriale?

Per un dataset di esempio piccolo, inizia validando la correttezza senza ottimizzare l’indicizzazione. Con la crescita dei dati, valuta gli indici vettoriali di Oracle come HNSW (Hierarchical Navigable Small World) o IVF (Inverted File), in base ai requisiti di performance e accuratezza. La creazione dell’indice è un’ottimizzazione, non un prerequisito per comprendere l’integrazione di base.

Per ulteriori dettagli sugli indici vettoriali Oracle, vedi la documentazione sugli indici vettoriali di Oracle.

Esplora un’implementazione di riferimento completa in TypeScript

Per vedere come questi concetti si combinano in un’app funzionante, esplora l’implementazione di riferimento con LangChain.js e Oracle AI Database.

Sviluppata in TypeScript, l’app riunisce ingestione dei documenti, archiviazione vettoriale, similarity search, filtri sui metadata e MMR usando LangChain.js e Oracle AI Database. Offre anche un’interfaccia interattiva per sperimentare con le impostazioni di retrieval, ispezionare i documenti recuperati e capire come le diverse strategie di ricerca influenzano il contesto restituito all’applicazione.

Il repository include il codice sorgente e le istruzioni di setup, permettendoti di esplorare l’integrazione completa e adattare l’implementazione ai tuoi progetti.

Conclusioni e prossimi passi

Hai collegato LangChain.js a Oracle AI Database tramite OracleVS, rappresentato la conoscenza come oggetti Document, creato embedding vettoriali persistenti e confrontato similarity search, filtri sui metadata e MMR. Come prossimo passo, leggi la documentazione ufficiale di LangChain.js e la guida ufficiale all’integrazione Oracle LangChain JavaScript.

Se lavori in altri linguaggi, il nostro tutorial su Oracle AI Vector Search copre gli stessi passaggi di archiviazione e query in Python, e il nostro tutorial su LangChain4j costruisce un agente Java con Oracle AI Database.

Il nostro corso Retrieval Augmented Generation (RAG) con LangChain è un seguito opzionale incentrato sul retrieval; i suoi esempi sono in Python, ma i concetti di workflow si applicano a questa implementazione TypeScript.

FAQ

Cosa succede se cambio modello di embedding dopo aver archiviato i documenti?

Gli embedding archiviati nella tabella vettoriale Oracle devono essere compatibili con quelli usati per la ricerca. Cambiare modello può modificare sia le dimensioni dei vettori sia il significato delle coordinate, quindi re-incorpora e reindicizza i documenti quando cambi modello di embedding. Usa la stessa configurazione di embedding per l’ingestione dei documenti e per le query di retrieval.

Ho bisogno di un modello di chat per usare OracleVS?

No. Un workflow di vector store richiede un modello di embedding per ingestione e query. Un modello di chat è opzionale e in genere si aggiunge quando i passaggi recuperati devono essere trasformati in una risposta in linguaggio naturale.

Posso usare un provider di embedding diverso da OpenAI?

Sì. OracleVS accetta un’implementazione di embedding compatibile con LangChain. Scegli un provider che soddisfi i tuoi requisiti e usa la stessa configurazione di embedding compatibile per documenti e query.

Perché usare filtri sui metadata insieme alla similarità vettoriale?

La similarità vettoriale trova contenuti semanticamente vicini; il filtro sui metadata restringe quali contenuti possono essere restituiti, ad esempio documenti in una particolare categoria o fonte.

Quando scegliere l’MMR rispetto alla similarity search ordinaria?

L’MMR è utile quando le corrispondenze principali contengono passaggi ripetitivi e l’applicazione beneficia di evidenze più varie. La similarity search semplice è più adatta quando l’obiettivo principale sono i vicini più prossimi.

Daniela Pavlenco

Autore

Daniela Pavlenco

Sono un Developer Advocate presso Oracle, e mi concentro nell'aiutare gli sviluppatori a esplorare le tecnologie di IA e a creare applicazioni pratiche con strumenti e framework moderni. Il mio lavoro consiste nel creare contenuti tecnici, esempi pratici e risorse per sviluppatori che rendono concetti complessi più facili da capire e da applicare in progetti reali.

Argomenti

Correlato