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.
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.
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.
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.
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 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.jsontype=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_keyOfferto da
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.
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])=>newDocument({ pageContent, metadata:{ source, category }}));Offerto da
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 =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,});Offerto da
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
FETCHFIRST1ROW ONLY;Offerto da
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.
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,})));Offerto da
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." }
]Offerto da
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,});}Offerto da
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));Offerto da
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));Offerto da
Output rappresentativo da un corpus sovrapposto (l’ordinamento può variare tra modelli di embedding ed esecuzioni):
["retrieval-overlap-2", "mmr-retrieval", "metadata-filtering"]Offerto da
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.
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){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),});Offerto da
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:
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.
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.
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.
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.
Scopri i 15 migliori server MCP remoti che stanno trasformando lo sviluppo AI nel 2026. Scopri come migliorano automazione, ragionamento, sicurezza e velocità dei workflow.
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,OracleEmbeddingseOracleSummary. Sono mattoncini opzionali utili; l’esempio seguente si concentra suOracleVSe mantiene la generazione degli embedding separata per rendere il flusso più facile da seguire.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.
OracleVSarchivia 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
Documentdi 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 diOracleVS.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/FREEPDB1e uno schema con i permessi indicati sopra.Crea un progetto TypeScript
Crea un file chiamato
index.tsin 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 inindex.ts.L’impostazione
package.jsontype=moduleconsente ilawaita 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/corefornisceDocument,@langchain/openaifornisce il modello di embedding d’esempio eoracledbgestisce la connessione al database. Le versioni sopra corrispondono all’app di accompagnamento;tsxesegue direttamente l’esempio TypeScript senza un passaggio di build separato.Configura la connessione
Salva questi valori in un file locale
.enve aggiungi.enva.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.Il pool permette a
OracleVSdi riutilizzare le sessioni del database. Tieni tutte le istruzioni di ingestione, retrieval e verifica dentro il bloccotry. 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
Ogni
DocumenthapageContentemetadata. I campisourceecategoryviaggiano 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
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
queryfornisce 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.COSINEspecifica la metrica di distanza vettoriale, mentreVectorElementFormat.FLOAT32imposta 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.
OracleVSaccetta 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.OracleVSdetermina 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: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
OracleVSi 3 documenti più vicini e stampa il metadata source insieme al testo di ogni chunk:Il codice mappa ogni
Documentdi LangChain a un oggetto semplice contenentesourceepageContentper la visualizzazione. Un output rappresentativo è mostrato qui sotto; l’ordine esatto può variare con il modello di embedding e la query: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
kdocumenti, il metodo restituisce solo i risultati disponibili. IDocumentrecuperati 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
similaritySearchWithScorequando vuoi ispezionare la distanza associata a ciascun documento recuperato:similaritySearchWithScorerestituisce 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
Output di esempio:
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
Output rappresentativo da un corpus sovrapposto (l’ordinamento può variare tra modelli di embedding ed esecuzioni):
L’MMR considera prima un insieme di candidati (
fetchK) e poi selezionakdocumenti bilanciando rilevanza della query e diversità. Unlambdapiù 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
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.
Chiudi il connection pool dopo la verifica
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.tscompleto può essere eseguito con:Un output di validazione rappresentativo è:
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,fetchKelambdaverificando 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 oggettiDocument, 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.