LangChain.js und Oracle AI Database: Leitfaden zur Vektorsuche
Verbinde LangChain.js mit Oracle AI Database über OracleVS, speichere Embeddings mit Metadaten und vergleiche in TypeScript Similarity Search, Metadatenfilter und MMR.
Ein Sprachmodell kann allgemeine Fragen beantworten, aber es kann nicht zuverlässig in einer privaten Wissensbasis nachschlagen, wenn eine Anwendung nicht zuerst die relevanten Informationen abruft. Für JavaScript-Entwickler bietet LangChain.js vertraute Abstraktionen für Dokumente, Embeddings und Retrieval. Was noch fehlt, ist ein persistenter Speicherort, um die entstehenden Vektoren abzulegen und zu durchsuchen.
Oracle AI Database übernimmt diese Rolle über die @oracle/langchain-oracledb-Integration. In diesem Guide verbindest du einen kleinen TypeScript-Workflow mit Oracle, speicherst Text samt Metadaten, führst eine Similarity Search aus und verbesserst die Ergebnisse mit Filtern und Maximaler Marginaler Relevanz (MMR). Das Tutorial konzentriert sich auf den Retrieval-Workflow; die zugehörige TypeScript-Anwendung ergänzt dieselbe Integration in einer interaktiven Browser-UI.
Was leistet die Integration von LangChain.js und Oracle AI Database?
LangChain.js standardisiert, wie eine Anwendung mit Embedding-Modellen und Vektorspeichern arbeitet. Das Oracle-Integrationspaket liefert mit OracleVS eine Vektorstore-Implementierung, die Dokumenttext, Metadaten und Vektor-Embeddings in Oracle AI Database persistiert. Deine Anwendung ruft LangChain.js-Methoden auf, statt für jede Similarity-Abfrage manuell SQL zu schreiben.
Dasselbe Paket enthält außerdem OracleDocLoader, OracleTextSplitter, OracleEmbeddings und OracleSummary. Das sind nützliche optionale Bausteine; das folgende Beispiel konzentriert sich auf OracleVS und hält die Embedding-Erzeugung separat, damit der Ablauf leicht nachvollziehbar bleibt.
Dokumentenaufnahme und -abruf mit LangChain.js, OracleVS und Oracle AI Database
Wichtige Features der Integration
Embeddings zusammen mit Dokumentmetadaten speichern
Ein Embedding-Modell wandelt Text in numerische Vektoren um. OracleVS speichert diese Vektoren gemeinsam mit dem Quelltext und strukturierten Metadaten. Metadaten wie Dokumentkategorie oder Quelle helfen der Anwendung, Suchen einzugrenzen, ohne nützlichen Kontext zu verlieren.
Relevante Passagen per Vektorähnlichkeit abrufen
Zur Abfragezeit wandelt dasselbe Embedding-Modell die Frage in einen Vektor um. Oracle vergleicht ihn mit den gespeicherten Vektoren anhand einer konfigurierten Distanzstrategie, zum Beispiel Kosinusdistanz, und liefert die nächsten Dokumente zurück. Die Ergebnisse bleiben LangChain-Document-Objekte und sind für die Weiterverarbeitung bereit.
Ergebnisse mit Filtern und MMR steuern
Similarity Search beantwortet die Frage „Welche Einträge liegen dieser Frage am nächsten?“. Ein Metadatenfilter schränkt die zulässigen Dokumente ein. MMR bringt ein weiteres Ziel hinein: relevante Passagen beibehalten und gleichzeitig nahezu doppelte Treffer reduzieren. Diese Verfahren ergänzen sich, sie sind nicht austauschbar.
Erste Schritte mit LangChain.js und Oracle AI Database
Voraussetzungen
Für dieses TypeScript-Beispiel brauchst du Node.js 24.13.0, npm 11.6.2, eine lokale Oracle AI Database 26ai Free-Instanz mit Vektorsupport und ein Schema, das die Demo-Tabelle und ihren Vektorindex erstellen, befüllen, abfragen und wieder löschen darf. Außerdem benötigst du einen OpenAI API-Schlüssel für das Embedding-Beispiel. OpenAIEmbeddings ist eine LangChain-kompatible Option, keine Anforderung von OracleVS.
Für den lokalen Hauptpfad folge Oracles Oracle AI Database Free Quick Start. Nachdem die Datenbank läuft, nutze einen Service wie localhost:1521/FREEPDB1 und ein Schema mit den oben genannten Berechtigungen.
Erstelle in diesem Ordner eine Datei namens index.ts. Füge die untenstehenden ausführbaren TypeScript-Snippets in derselben Reihenfolge in diese Datei ein. Lege keine separate Datei pro Snippet an. Kopiere nur die ausführbaren TypeScript-Snippets: Die SQL- und Beispielausgabe-Blöcke dienen der Erklärung und sollten nicht in index.ts eingefügt werden.
Die package.json-Einstellung type=module erlaubt das Top-Level-await in den Beispielen. Die Node.js-Paketkonfiguration ist im offiziellen Node.js-Pakete-Guide dokumentiert.
Das Oracle-Integrationspaket implementiert den Vektorstore, @langchain/core stellt Document bereit, @langchain/openai liefert das Embedding-Beispielmodell, und oracledb verwaltet die Datenbankverbindung. Die Versionen oben entsprechen der Begleitanwendung; tsx führt das TypeScript-Beispiel direkt aus, ohne separaten Build-Schritt.
Die Verbindung konfigurieren
ORACLE_USER=your_schema
ORACLE_PASSWORD=your_password
ORACLE_CONNECT_STRING=localhost:1521/FREEPDB1
OPENAI_API_KEY=your_api_keyBereitgestellt von
Speichere diese Werte lokal in einer .env-Datei und füge .env zu .gitignore hinzu. Dieser Artikel nutzt die lokale Oracle AI Database Free als bevorzugtes Setup, damit die Schritte reproduzierbar sind. Autonomous AI Database ist eine valide Alternative für den Betrieb, erfordert aber je nach Umgebung den Service-Descriptor sowie Wallet- oder TLS-Konfiguration.
Der Pool erlaubt es OracleVS, Datenbanksessions wiederzuverwenden. Halte alle Statements für Ingestion, Retrieval und Verifikation innerhalb des try-Blocks. Der nächste Codeblock startet diesen Block, spätere Snippets führen ihn fort. Der Pool wird erst nach der Verifikation im Cleanup-Abschnitt unten geschlossen. In einer Serveranwendung initialisierst du den Pool einmal und schließt ihn beim geordneten Herunterfahren, statt pro Nutzeranfrage eine neue Verbindung zu öffnen.
So baust du eine Dokumentsuche mit LangChain.js
Wir verwenden 10 kurze Wissensnotizen, darunter sich überschneidende Retrieval-Passagen. Der Korpus ist bewusst klein gehalten, macht es aber möglich, einfache Similarity Search mit Metadatenfiltern und MMR zu vergleichen.
Definiere deine Wissensdokumente
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 }}));Bereitgestellt von
Jedes Document hat pageContent und metadata. Die Felder source und category begleiten das Dokument durch Ingestion und Retrieval, sodass die Anwendung erklären kann, woher ein Ergebnis stammt, und Suchen auf einen relevanten Teilkorpus einschränken kann.
Embeddings konfigurieren und OracleVS erstellen
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,});Bereitgestellt von
OracleVS.fromDocuments() ist der zentrale Integrationsaufruf. Er initialisiert den Vektorstore, erzeugt Embeddings für die übergebenen Dokumente und speichert deren Inhalt, Vektoren und Metadaten in Oracle AI Database.
Der Parameter query liefert Beispieltext, der bei der Initialisierung eingebettet wird, um die für die Datenbanktabelle benötigte Vektordimension zu bestimmen. Er wird nicht für die Suche in den gespeicherten Dokumenten verwendet. DistanceStrategy.COSINE legt die Vektordistanzmetrik fest, während VectorElementFormat.FLOAT32 das Vektorelementformat setzt.
Bevor du die Ingestion erneut ausführst, nutze einen neuen Tabellennamen für die Demo oder lösche die vorhandenen Daten, um doppelte Dokumente zu vermeiden.
OracleVS akzeptiert eine LangChain-kompatible Embedding-Implementierung, sodass Entwickler den Embedding-Anbieter wechseln können, ohne den gesamten Vektorstore-Workflow zu ändern. Die für Ingestion und Retrieval verwendeten Embeddings müssen jedoch mit der Oracle-Vektorspalte kompatibel bleiben.
OracleVS bestimmt die Vektordimension bei der Initialisierung anhand des konfigurierten Embedding-Modells. Um Dimensionen und Speicherformat eines bereits in Oracle AI Database gespeicherten Vektors zu prüfen, führe die folgende SQL-Abfrage aus:
SELECT
VECTOR_DIMENSION_COUNT(embedding)AS vector_dimensions,
VECTOR_DIMENSION_FORMAT(embedding)AS vector_format
FROM LC_JS_RAG_DEMO
FETCHFIRST1ROW ONLY;Bereitgestellt von
Wenn du auf ein Embedding-Modell mit anderer Dimension wechselst, lege eine kompatible Vektortabelle an und generiere die Dokument-Embeddings neu. Selbst wenn zwei Modelle Vektoren mit denselben Dimensionen erzeugen, können sich ihre Embedding-Räume unterscheiden, daher sollten bestehende Dokumente neu eingebettet werden, bevor das neue Modell fürs Retrieval genutzt wird.
Das folgende Beispiel fragt den OracleVS-Vektorstore nach den 3 nächsten Dokumenten und gibt die Source-Metadaten zusammen mit dem jeweiligen Chunk-Text aus:
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,})));Bereitgestellt von
Der Code transformiert jedes LangChain-Document in ein Plain-Object mit source und pageContent zur Anzeige. Eine mögliche Ausgabe ist unten gezeigt; die genaue Reihenfolge kann je nach Embedding-Modell und Abfrage variieren:
[
{ 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." }
]Bereitgestellt von
Das erste Argument ist die Nutzerfrage, das zweite ist k, die maximale Anzahl abzurufender Dokumente. LangChain.js nutzt das konfigurierte Embedding-Modell, um die Frage in einen Vektor zu konvertieren, und Oracle AI Database führt eine Similarity Search aus, um die nächsten Treffer zu finden.
Wenn nach Anwendung von Suchbedingungen und Metadatenfiltern weniger als k Dokumente verfügbar sind, liefert die Methode nur die vorhandenen Ergebnisse. Die abgerufenen Document-Objekte enthalten Text und Metadaten, die mit Quellenangabe angezeigt oder an einen späteren Antwortschritt übergeben werden können.
Retrieval-Scores inspizieren
Verwende zum Beispiel similaritySearchWithScore, wenn du die Distanz zu jedem Treffer einsehen möchtest:
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,});}Bereitgestellt von
similaritySearchWithScore liefert zu jedem Treffer eine Distanz. Ihr numerischer Wert und ihre Richtung hängen von der gewählten Distanzstrategie ab, sie ist also kein allgemeiner „Confidence“-Prozentwert. Vergleiche Scores nur bei identischem Embedding-Modell und gleicher Distanzstrategie, und prüfe den abgerufenen Abschnitt, bevor du einen Schwellenwert festlegst.
Ergebnisse mit Metadatenfiltern eingrenzen
const databaseOnly =await vectorStore.similaritySearch("Where are vector embeddings stored?",3,{ category:{ $eq:"database"}});console.log(databaseOnly.map((doc)=> doc.metadata.source));Bereitgestellt von
Das dritte Argument beschränkt die Suche auf Einträge mit category = database. In diesem Korpus ist das erwartbare gefilterte Ergebnis ["database-guide"]. Ein Filter ändert, welche Dokumente zugelassen sind; die Vektorähnlichkeit sortiert weiterhin die zugelassenen Dokumente.
MMR nutzen, um doppelte Ergebnisse zu reduzieren
const diverse =await vectorStore.maxMarginalRelevanceSearch(
retrievalQuestion,{
k:3,
fetchK:6,
lambda:0.5,});console.log(diverse.map((doc)=> doc.metadata.source));Bereitgestellt von
Repräsentative Ausgabe aus einem überlappenden Korpus (Reihenfolge kann je nach Modell und Lauf variieren):
["retrieval-overlap-2", "mmr-retrieval", "metadata-filtering"]Bereitgestellt von
MMR betrachtet zunächst einen Kandidatenpool (fetchK) und wählt dann k Dokumente aus, indem Relevanz zur Abfrage mit Vielfalt ausbalanciert wird. Ein niedrigerer lambda-Wert betont die Vielfalt stärker, ein höherer die Relevanz. Mit dem obigen überlappenden Korpus können sich die ausgewählten Quellen von der einfachen Similarity Search unterscheiden, wodurch der Retrieval-Trade-off sichtbar wird.
Abgerufenen Kontext an eine KI-Anwendung übergeben
Hier findet der Übergang zwischen LangChain.js-Retrieval und dem Aufruf eines großen Sprachmodells (LLM) statt: Die Anwendung hat eine Frage plus überprüfbare Evidenz und kann das Modell anweisen, aus diesem Kontext zu antworten.
Retrieval und Generierung sind getrennte Aufgaben. An diesem Punkt ist context ein einfacher Textstring, den ein Chatmodell konsumieren kann. Du könntest ihn nun an ein Modell übergeben mit der Anweisung, nur aus dem abgerufenen Material zu antworten und Quellenkennungen zu zitieren. Die Datenbankintegration funktioniert auch ohne Chatmodell.
So prüfst du die Integration
Eine sinnvolle Validierung testet Ingestion und jede Retrieval-Strategie separat. Bestätige zunächst, dass der Vektorstore ohne Datenbankfehler erstellt wurde. Untersuche dann die Source-Metadaten der Similarity Search, das gefilterte Ergebnis und das MMR-Ergebnis.
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),});Bereitgestellt von
Den Verbindungspool nach der Verifikation schließen
Das Cleanup läuft erst, nachdem Ingestion, Retrieval und Verifikation abgeschlossen sind. Die Drain-Time gibt belegten Verbindungen ein kurzes Zeitfenster zum Fertigstellen. In einem langlebigen Server bleibt der Pool bis zum geordneten Herunterfahren geöffnet. Details zum Lifecycle findest du in der node-oracledb-Dokumentation zu pool.close().
Jetzt kann die komplette Datei index.ts ausgeführt werden mit:
Die genaue Similarity-Reihenfolge und Distanzwerte können je nach Embedding-Modell und -Anbieter variieren. Das gefilterte Ergebnis sollte database-guide enthalten, während das MMR-Ergebnis eine vielfältige Menge an Retrieval-Quellen aus dem überlappenden Korpus zeigen sollte.
Tipps und Troubleshooting
Die Datenbankverbindung schlägt fehl
Prüfe Connection-String, Zugangsdaten, erreichbaren Service und Schema-Rechte. Wenn du Autonomous AI Database nutzt, bestätige die erforderliche Wallet- oder TLS-Konfiguration. Teste die Datenbankverbindung separat, bevor du das Retrieval debuggst.
Ein Embedding-Dimensionskonflikt tritt auf
Die beim Einfügen erzeugten Vektoren und die Abfragevektoren müssen kompatible Dimensionen verwenden. Unterschiedliche Embedding-Modelle für Inserts und Queries können die Suche brechen oder die Ergebnisse verschlechtern. Halte die Modellauswahl pro Tabelle konsistent.
Eine Suche liefert keine Dokumente
Bestätige, dass die Ingestion Zeilen eingefügt hat, und versuche es dann ohne restriktive Metadatenfilter erneut. Probiere bei kleinen Korpora allgemeinere Abfragen aus und inspiziere den gespeicherten Inhalt.
Die Ergebnisse sind relevant, aber repetitiv
Vergleiche Similarity Search mit MMR anhand eines Korpus mit überlappenden Chunks. Feine k, fetchK und lambda ab, während du prüfst, ob Vielfalt auf Kosten wichtiger Passagen geht.
Solltest du einen Vektorindex anlegen?
Für einen kleinen Beispieldatensatz starte mit der Validierung der Korrektheit, ohne das Indexing zu tunen. Wenn die Daten wachsen, evaluiere Oracle-Vektorindizes wie Hierarchical Navigable Small World (HNSW) oder Inverted File (IVF) anhand deiner Performance- und Genauigkeitsanforderungen. Das Erstellen eines Index ist eine Optimierung, keine Voraussetzung, um die Grundintegration zu verstehen.
Die Anwendung wurde mit TypeScript gebaut und vereint Dokumentaufnahme, Vektorspeicherung, Similarity Search, Metadaten-Filterung und MMR mit LangChain.js und Oracle AI Database. Außerdem bietet sie eine interaktive Oberfläche, um mit Retrieval-Einstellungen zu experimentieren, abgerufene Dokumente zu inspizieren und zu verstehen, wie unterschiedliche Suchstrategien den an die Anwendung zurückgegebenen Kontext beeinflussen.
Das Repository enthält den Quellcode und Anleitungen zur Einrichtung, sodass du die komplette Integration erkunden und die Implementierung auf eigene Projekte anpassen kannst.
Fazit und nächste Schritte
Du hast LangChain.js über OracleVS mit Oracle AI Database verbunden, Wissen als Document-Objekte repräsentiert, persistente Vektor-Embeddings erstellt und Similarity Search, Metadatenfilter und MMR verglichen. Als nächsten Schritt lies die offizielle LangChain.js-Dokumentation und den offiziellen Oracle LangChain JavaScript Integration Guide.
Wenn du in anderen Sprachen arbeitest, deckt unser Oracle AI Vector Search Tutorial dieselben Speicher- und Abfrageschritte in Python ab, und unser LangChain4j-Tutorial baut einen Java-Agenten mit Oracle AI Database.
Unser Kurs Retrieval Augmented Generation (RAG) mit LangChain ist ein optionales, retrievalfokussiertes Follow-up; die Beispiele sind in Python, aber die Workflow-Konzepte passen auf diese TypeScript-Implementierung.
FAQs
Was passiert, wenn ich nach dem Speichern der Dokumente das Embedding-Modell wechsle?⌄
Embeddings, die in der Oracle-Vektortabelle gespeichert sind, müssen mit den Embeddings kompatibel sein, die du für die Suche verwendest. Ein Modellwechsel kann sowohl die Vektordimensionen als auch die Bedeutung der Vektorkoordinaten ändern. Re-embedde und reindiziere die Dokumente daher beim Wechsel des Embedding-Modells. Nutze dieselbe Embedding-Konfiguration für Dokumentingestion und Query-Retrieval.
Brauche ich ein Chatmodell, um OracleVS zu nutzen?⌄
Nein. Ein Vektorstore-Workflow benötigt ein Embedding-Modell für Ingestion und Abfragen. Ein Chatmodell ist optional und wird typischerweise ergänzt, wenn die abgerufenen Passagen in eine natürlichsprachliche Antwort überführt werden sollen.
Kann ich einen anderen Embedding-Anbieter als OpenAI verwenden?⌄
Ja. OracleVS akzeptiert eine kompatible LangChain-Embedding-Implementierung. Wähle einen Anbieter, der deinen Anforderungen entspricht, und nutze dieselbe kompatible Embedding-Konfiguration für Dokumente und Abfragen.
Warum Metadatenfilter zusammen mit Vektorähnlichkeit verwenden?⌄
Vektorähnlichkeit findet semantisch nahe Inhalte; Metadatenfilter schränken ein, welche Inhalte zurückgegeben werden dürfen, etwa Dokumente einer bestimmten Kategorie oder Quelle.
Wann sollte ich MMR statt einfacher Similarity Search wählen?⌄
MMR hilft, wenn Top-Treffer repetitive Passagen enthalten und deine Anwendung von vielfältigerer Evidenz profitiert. Eine einfache Similarity Search ist sinnvoll, wenn die nächsten Nachbarn das Hauptziel sind.
Autor
Daniela Pavlenco
Ich bin Developer Advocate bei Oracle und helfe Entwicklerinnen und Entwicklern dabei, KI-Technologien zu erkunden und mit modernen Tools und Frameworks praxisnahe Anwendungen zu bauen. Meine Arbeit umfasst technische Inhalte, praxisnahe Beispiele und Developer-Ressourcen, die komplexe Konzepte greifbar machen und ihre Umsetzung in realen Projekten erleichtern.
Lerne die wichtigsten Arten von KI-Agenten kennen, wie sie mit ihrer Umgebung interagieren und wie sie in verschiedenen Branchen eingesetzt werden. Verstehe einfache reflexive, modellbasierte, zielbasierte, nutzenbasierte, lernende Agenten und mehr.
Ein Sprachmodell kann allgemeine Fragen beantworten, aber es kann nicht zuverlässig in einer privaten Wissensbasis nachschlagen, wenn eine Anwendung nicht zuerst die relevanten Informationen abruft. Für JavaScript-Entwickler bietet LangChain.js vertraute Abstraktionen für Dokumente, Embeddings und Retrieval. Was noch fehlt, ist ein persistenter Speicherort, um die entstehenden Vektoren abzulegen und zu durchsuchen.
Oracle AI Database übernimmt diese Rolle über die
@oracle/langchain-oracledb-Integration. In diesem Guide verbindest du einen kleinen TypeScript-Workflow mit Oracle, speicherst Text samt Metadaten, führst eine Similarity Search aus und verbesserst die Ergebnisse mit Filtern und Maximaler Marginaler Relevanz (MMR). Das Tutorial konzentriert sich auf den Retrieval-Workflow; die zugehörige TypeScript-Anwendung ergänzt dieselbe Integration in einer interaktiven Browser-UI.Die Integrationsdetails findest du im offiziellen Oracle LangChain JavaScript Integration Guide.
Was leistet die Integration von LangChain.js und Oracle AI Database?
LangChain.js standardisiert, wie eine Anwendung mit Embedding-Modellen und Vektorspeichern arbeitet. Das Oracle-Integrationspaket liefert mit
OracleVSeine Vektorstore-Implementierung, die Dokumenttext, Metadaten und Vektor-Embeddings in Oracle AI Database persistiert. Deine Anwendung ruft LangChain.js-Methoden auf, statt für jede Similarity-Abfrage manuell SQL zu schreiben.Dasselbe Paket enthält außerdem
OracleDocLoader,OracleTextSplitter,OracleEmbeddingsundOracleSummary. Das sind nützliche optionale Bausteine; das folgende Beispiel konzentriert sich aufOracleVSund hält die Embedding-Erzeugung separat, damit der Ablauf leicht nachvollziehbar bleibt.Dokumentenaufnahme und -abruf mit LangChain.js, OracleVS und Oracle AI Database
Wichtige Features der Integration
Embeddings zusammen mit Dokumentmetadaten speichern
Ein Embedding-Modell wandelt Text in numerische Vektoren um.
OracleVSspeichert diese Vektoren gemeinsam mit dem Quelltext und strukturierten Metadaten. Metadaten wie Dokumentkategorie oder Quelle helfen der Anwendung, Suchen einzugrenzen, ohne nützlichen Kontext zu verlieren.Relevante Passagen per Vektorähnlichkeit abrufen
Zur Abfragezeit wandelt dasselbe Embedding-Modell die Frage in einen Vektor um. Oracle vergleicht ihn mit den gespeicherten Vektoren anhand einer konfigurierten Distanzstrategie, zum Beispiel Kosinusdistanz, und liefert die nächsten Dokumente zurück. Die Ergebnisse bleiben LangChain-
Document-Objekte und sind für die Weiterverarbeitung bereit.Ergebnisse mit Filtern und MMR steuern
Similarity Search beantwortet die Frage „Welche Einträge liegen dieser Frage am nächsten?“. Ein Metadatenfilter schränkt die zulässigen Dokumente ein. MMR bringt ein weiteres Ziel hinein: relevante Passagen beibehalten und gleichzeitig nahezu doppelte Treffer reduzieren. Diese Verfahren ergänzen sich, sie sind nicht austauschbar.
Erste Schritte mit LangChain.js und Oracle AI Database
Voraussetzungen
Für dieses TypeScript-Beispiel brauchst du Node.js 24.13.0, npm 11.6.2, eine lokale Oracle AI Database 26ai Free-Instanz mit Vektorsupport und ein Schema, das die Demo-Tabelle und ihren Vektorindex erstellen, befüllen, abfragen und wieder löschen darf. Außerdem benötigst du einen OpenAI API-Schlüssel für das Embedding-Beispiel.
OpenAIEmbeddingsist eine LangChain-kompatible Option, keine Anforderung vonOracleVS.Installiere Node.js über die offizielle Node.js-Downloadseite.
Für den lokalen Hauptpfad folge Oracles Oracle AI Database Free Quick Start. Nachdem die Datenbank läuft, nutze einen Service wie
localhost:1521/FREEPDB1und ein Schema mit den oben genannten Berechtigungen.Ein TypeScript-Projekt anlegen
Erstelle in diesem Ordner eine Datei namens
index.ts. Füge die untenstehenden ausführbaren TypeScript-Snippets in derselben Reihenfolge in diese Datei ein. Lege keine separate Datei pro Snippet an. Kopiere nur die ausführbaren TypeScript-Snippets: Die SQL- und Beispielausgabe-Blöcke dienen der Erklärung und sollten nicht inindex.tseingefügt werden.Die
package.json-Einstellungtype=moduleerlaubt das Top-Level-awaitin den Beispielen. Die Node.js-Paketkonfiguration ist im offiziellen Node.js-Pakete-Guide dokumentiert.Das Oracle-Integrationspaket implementiert den Vektorstore,
@langchain/corestelltDocumentbereit,@langchain/openailiefert das Embedding-Beispielmodell, undoracledbverwaltet die Datenbankverbindung. Die Versionen oben entsprechen der Begleitanwendung;tsxführt das TypeScript-Beispiel direkt aus, ohne separaten Build-Schritt.Die Verbindung konfigurieren
Speichere diese Werte lokal in einer
.env-Datei und füge.envzu.gitignorehinzu. Dieser Artikel nutzt die lokale Oracle AI Database Free als bevorzugtes Setup, damit die Schritte reproduzierbar sind. Autonomous AI Database ist eine valide Alternative für den Betrieb, erfordert aber je nach Umgebung den Service-Descriptor sowie Wallet- oder TLS-Konfiguration.Der Pool erlaubt es
OracleVS, Datenbanksessions wiederzuverwenden. Halte alle Statements für Ingestion, Retrieval und Verifikation innerhalb destry-Blocks. Der nächste Codeblock startet diesen Block, spätere Snippets führen ihn fort. Der Pool wird erst nach der Verifikation im Cleanup-Abschnitt unten geschlossen. In einer Serveranwendung initialisierst du den Pool einmal und schließt ihn beim geordneten Herunterfahren, statt pro Nutzeranfrage eine neue Verbindung zu öffnen.So baust du eine Dokumentsuche mit LangChain.js
Wir verwenden 10 kurze Wissensnotizen, darunter sich überschneidende Retrieval-Passagen. Der Korpus ist bewusst klein gehalten, macht es aber möglich, einfache Similarity Search mit Metadatenfiltern und MMR zu vergleichen.
Definiere deine Wissensdokumente
Jedes
DocumenthatpageContentundmetadata. Die Feldersourceundcategorybegleiten das Dokument durch Ingestion und Retrieval, sodass die Anwendung erklären kann, woher ein Ergebnis stammt, und Suchen auf einen relevanten Teilkorpus einschränken kann.Embeddings konfigurieren und OracleVS erstellen
OracleVS.fromDocuments()ist der zentrale Integrationsaufruf. Er initialisiert den Vektorstore, erzeugt Embeddings für die übergebenen Dokumente und speichert deren Inhalt, Vektoren und Metadaten in Oracle AI Database.Der Parameter
queryliefert Beispieltext, der bei der Initialisierung eingebettet wird, um die für die Datenbanktabelle benötigte Vektordimension zu bestimmen. Er wird nicht für die Suche in den gespeicherten Dokumenten verwendet.DistanceStrategy.COSINElegt die Vektordistanzmetrik fest, währendVectorElementFormat.FLOAT32das Vektorelementformat setzt.Bevor du die Ingestion erneut ausführst, nutze einen neuen Tabellennamen für die Demo oder lösche die vorhandenen Daten, um doppelte Dokumente zu vermeiden.
OracleVSakzeptiert eine LangChain-kompatible Embedding-Implementierung, sodass Entwickler den Embedding-Anbieter wechseln können, ohne den gesamten Vektorstore-Workflow zu ändern. Die für Ingestion und Retrieval verwendeten Embeddings müssen jedoch mit der Oracle-Vektorspalte kompatibel bleiben.OracleVSbestimmt die Vektordimension bei der Initialisierung anhand des konfigurierten Embedding-Modells. Um Dimensionen und Speicherformat eines bereits in Oracle AI Database gespeicherten Vektors zu prüfen, führe die folgende SQL-Abfrage aus:Wenn du auf ein Embedding-Modell mit anderer Dimension wechselst, lege eine kompatible Vektortabelle an und generiere die Dokument-Embeddings neu. Selbst wenn zwei Modelle Vektoren mit denselben Dimensionen erzeugen, können sich ihre Embedding-Räume unterscheiden, daher sollten bestehende Dokumente neu eingebettet werden, bevor das neue Modell fürs Retrieval genutzt wird.
Die Methodensignaturen und Retrieval-Optionen für den Vektorstore findest du in der offiziellen LangChain.js VectorStore-Referenz.
Dokumente mit Similarity Search abrufen
Das folgende Beispiel fragt den
OracleVS-Vektorstore nach den 3 nächsten Dokumenten und gibt die Source-Metadaten zusammen mit dem jeweiligen Chunk-Text aus:Der Code transformiert jedes LangChain-
Documentin ein Plain-Object mitsourceundpageContentzur Anzeige. Eine mögliche Ausgabe ist unten gezeigt; die genaue Reihenfolge kann je nach Embedding-Modell und Abfrage variieren:Das erste Argument ist die Nutzerfrage, das zweite ist
k, die maximale Anzahl abzurufender Dokumente. LangChain.js nutzt das konfigurierte Embedding-Modell, um die Frage in einen Vektor zu konvertieren, und Oracle AI Database führt eine Similarity Search aus, um die nächsten Treffer zu finden.Wenn nach Anwendung von Suchbedingungen und Metadatenfiltern weniger als
kDokumente verfügbar sind, liefert die Methode nur die vorhandenen Ergebnisse. Die abgerufenenDocument-Objekte enthalten Text und Metadaten, die mit Quellenangabe angezeigt oder an einen späteren Antwortschritt übergeben werden können.Retrieval-Scores inspizieren
Verwende zum Beispiel
similaritySearchWithScore, wenn du die Distanz zu jedem Treffer einsehen möchtest:similaritySearchWithScoreliefert zu jedem Treffer eine Distanz. Ihr numerischer Wert und ihre Richtung hängen von der gewählten Distanzstrategie ab, sie ist also kein allgemeiner „Confidence“-Prozentwert. Vergleiche Scores nur bei identischem Embedding-Modell und gleicher Distanzstrategie, und prüfe den abgerufenen Abschnitt, bevor du einen Schwellenwert festlegst.Ergebnisse mit Metadatenfiltern eingrenzen
Beispielausgabe:
Das dritte Argument beschränkt die Suche auf Einträge mit
category = database. In diesem Korpus ist das erwartbare gefilterte Ergebnis["database-guide"]. Ein Filter ändert, welche Dokumente zugelassen sind; die Vektorähnlichkeit sortiert weiterhin die zugelassenen Dokumente.MMR nutzen, um doppelte Ergebnisse zu reduzieren
Repräsentative Ausgabe aus einem überlappenden Korpus (Reihenfolge kann je nach Modell und Lauf variieren):
MMR betrachtet zunächst einen Kandidatenpool (
fetchK) und wählt dannkDokumente aus, indem Relevanz zur Abfrage mit Vielfalt ausbalanciert wird. Ein niedrigererlambda-Wert betont die Vielfalt stärker, ein höherer die Relevanz. Mit dem obigen überlappenden Korpus können sich die ausgewählten Quellen von der einfachen Similarity Search unterscheiden, wodurch der Retrieval-Trade-off sichtbar wird.Abgerufenen Kontext an eine KI-Anwendung übergeben
Hier findet der Übergang zwischen LangChain.js-Retrieval und dem Aufruf eines großen Sprachmodells (LLM) statt: Die Anwendung hat eine Frage plus überprüfbare Evidenz und kann das Modell anweisen, aus diesem Kontext zu antworten.
Retrieval und Generierung sind getrennte Aufgaben. An diesem Punkt ist
contextein einfacher Textstring, den ein Chatmodell konsumieren kann. Du könntest ihn nun an ein Modell übergeben mit der Anweisung, nur aus dem abgerufenen Material zu antworten und Quellenkennungen zu zitieren. Die Datenbankintegration funktioniert auch ohne Chatmodell.So prüfst du die Integration
Eine sinnvolle Validierung testet Ingestion und jede Retrieval-Strategie separat. Bestätige zunächst, dass der Vektorstore ohne Datenbankfehler erstellt wurde. Untersuche dann die Source-Metadaten der Similarity Search, das gefilterte Ergebnis und das MMR-Ergebnis.
Den Verbindungspool nach der Verifikation schließen
Das Cleanup läuft erst, nachdem Ingestion, Retrieval und Verifikation abgeschlossen sind. Die Drain-Time gibt belegten Verbindungen ein kurzes Zeitfenster zum Fertigstellen. In einem langlebigen Server bleibt der Pool bis zum geordneten Herunterfahren geöffnet. Details zum Lifecycle findest du in der node-oracledb-Dokumentation zu
pool.close().Jetzt kann die komplette Datei
index.tsausgeführt werden mit:Eine repräsentative Validierungsausgabe ist:
Die genaue Similarity-Reihenfolge und Distanzwerte können je nach Embedding-Modell und -Anbieter variieren. Das gefilterte Ergebnis sollte
database-guideenthalten, während das MMR-Ergebnis eine vielfältige Menge an Retrieval-Quellen aus dem überlappenden Korpus zeigen sollte.Tipps und Troubleshooting
Die Datenbankverbindung schlägt fehl
Prüfe Connection-String, Zugangsdaten, erreichbaren Service und Schema-Rechte. Wenn du Autonomous AI Database nutzt, bestätige die erforderliche Wallet- oder TLS-Konfiguration. Teste die Datenbankverbindung separat, bevor du das Retrieval debuggst.
Ein Embedding-Dimensionskonflikt tritt auf
Die beim Einfügen erzeugten Vektoren und die Abfragevektoren müssen kompatible Dimensionen verwenden. Unterschiedliche Embedding-Modelle für Inserts und Queries können die Suche brechen oder die Ergebnisse verschlechtern. Halte die Modellauswahl pro Tabelle konsistent.
Eine Suche liefert keine Dokumente
Bestätige, dass die Ingestion Zeilen eingefügt hat, und versuche es dann ohne restriktive Metadatenfilter erneut. Probiere bei kleinen Korpora allgemeinere Abfragen aus und inspiziere den gespeicherten Inhalt.
Die Ergebnisse sind relevant, aber repetitiv
Vergleiche Similarity Search mit MMR anhand eines Korpus mit überlappenden Chunks. Feine
k,fetchKundlambdaab, während du prüfst, ob Vielfalt auf Kosten wichtiger Passagen geht.Solltest du einen Vektorindex anlegen?
Für einen kleinen Beispieldatensatz starte mit der Validierung der Korrektheit, ohne das Indexing zu tunen. Wenn die Daten wachsen, evaluiere Oracle-Vektorindizes wie Hierarchical Navigable Small World (HNSW) oder Inverted File (IVF) anhand deiner Performance- und Genauigkeitsanforderungen. Das Erstellen eines Index ist eine Optimierung, keine Voraussetzung, um die Grundintegration zu verstehen.
Mehr Details zu Oracle-Vektorindizes findest du in Oracles Dokumentation zu Vektorindizes.
Eine vollständige TypeScript-Referenzimplementierung erkunden
Wenn du sehen möchtest, wie diese Konzepte in einer funktionierenden Anwendung zusammenkommen, schau dir die Referenzimplementierung mit LangChain.js und Oracle AI Database an.
Die Anwendung wurde mit TypeScript gebaut und vereint Dokumentaufnahme, Vektorspeicherung, Similarity Search, Metadaten-Filterung und MMR mit LangChain.js und Oracle AI Database. Außerdem bietet sie eine interaktive Oberfläche, um mit Retrieval-Einstellungen zu experimentieren, abgerufene Dokumente zu inspizieren und zu verstehen, wie unterschiedliche Suchstrategien den an die Anwendung zurückgegebenen Kontext beeinflussen.
Das Repository enthält den Quellcode und Anleitungen zur Einrichtung, sodass du die komplette Integration erkunden und die Implementierung auf eigene Projekte anpassen kannst.
Fazit und nächste Schritte
Du hast LangChain.js über
OracleVSmit Oracle AI Database verbunden, Wissen alsDocument-Objekte repräsentiert, persistente Vektor-Embeddings erstellt und Similarity Search, Metadatenfilter und MMR verglichen. Als nächsten Schritt lies die offizielle LangChain.js-Dokumentation und den offiziellen Oracle LangChain JavaScript Integration Guide.Wenn du in anderen Sprachen arbeitest, deckt unser Oracle AI Vector Search Tutorial dieselben Speicher- und Abfrageschritte in Python ab, und unser LangChain4j-Tutorial baut einen Java-Agenten mit Oracle AI Database.
Unser Kurs Retrieval Augmented Generation (RAG) mit LangChain ist ein optionales, retrievalfokussiertes Follow-up; die Beispiele sind in Python, aber die Workflow-Konzepte passen auf diese TypeScript-Implementierung.