Accéder au contenu principal

LangChain.js et Oracle AI Database : guide de recherche vectorielle

Connectez LangChain.js à Oracle AI Database avec OracleVS, stockez des embeddings avec des métadonnées et comparez similarité, filtres de métadonnées et MMR en TypeScript.
· 10 min lire

Explorez l'IA

Un modèle de langue peut répondre à des questions générales, mais il ne peut pas consulter de manière fiable une base de connaissances privée sans qu'une application ne récupère d'abord les informations pertinentes. Pour les développeurs JavaScript, LangChain.js propose des abstractions familières pour les documents, les embeddings et la recherche. La pièce manquante est un espace de stockage pérenne pour conserver et interroger les vecteurs résultants.

Oracle AI Database remplit ce rôle via l'intégration @oracle/langchain-oracledb. Dans ce guide, vous connecterez un petit workflow TypeScript à Oracle, stockerez du texte avec des métadonnées, effectuerez une recherche par similarité et améliorerez la pertinence grâce à des filtres et à la maximal marginal relevance (MMR). Le tutoriel se concentre sur le workflow de recherche ; l'application TypeScript compagnon ajoute la même intégration à une interface web interactive.

Pour les détails d'intégration, consultez le guide officiel d'intégration Oracle LangChain JavaScript.

Qu'est-ce que l'intégration LangChain.js et Oracle AI Database ?

LangChain.js standardise la façon dont une application travaille avec des modèles d'embeddings et des magasins de vecteurs. Le package d'intégration Oracle fournit OracleVS, une implémentation de vector store qui pérennise le texte des documents, les métadonnées et les embeddings vectoriels dans Oracle AI Database. Votre application appelle les méthodes LangChain.js au lieu d'écrire manuellement du SQL pour chaque requête de similarité.

Le même package inclut aussi OracleDocLoader, OracleTextSplitter, OracleEmbeddings et OracleSummary. Ce sont des composants optionnels utiles ; l'exemple ci-dessous se concentre sur OracleVS et maintient la génération d'embeddings séparée pour garder un flux facile à comprendre.

Schéma d'architecture montrant un workflow RAG TypeScript avec LangChain.js : une interface React envoie une question à une API Node.js, LangChain.js crée des embeddings et récupère des documents via OracleVS depuis une table vectorielle Oracle AI Database, et l'API renvoie une réponse étayée.

Ingestion et recherche de documents avec LangChain.js, OracleVS et Oracle AI Database

Fonctionnalités clés de l'intégration

Stocker les embeddings avec les métadonnées des documents

Un modèle d'embeddings transforme le texte en vecteurs numériques. OracleVS enregistre ces vecteurs avec le texte source et des métadonnées structurées. Des métadonnées comme la catégorie ou la source aident l'application à restreindre les recherches sans perdre de contexte utile.

Récupérer les passages pertinents par similarité vectorielle

Au moment de la requête, le même modèle d'embeddings convertit la question en vecteur. Oracle le compare aux vecteurs stockés selon une métrique de distance configurée, comme la distance cosinus, et renvoie les documents les plus proches. Les résultats restent des objets Document LangChain, prêts pour les traitements en aval.

Maîtriser les résultats avec des filtres et la MMR

La recherche par similarité répond à : « quels éléments sont les plus proches de cette question ? » Un filtre de métadonnées restreint les documents éligibles. La MMR ajoute un autre objectif : conserver la pertinence tout en réduisant les quasi-doublons. Ces opérations sont complémentaires, pas interchangeables.

Premiers pas avec LangChain.js et Oracle AI Database

Prérequis

Pour cet exemple TypeScript, vous avez besoin de Node.js 24.13.0, npm 11.6.2, d'une instance locale Oracle AI Database 26ai Free avec support vectoriel, et d'un schéma autorisé à créer, insérer, interroger et supprimer la table de démonstration et son index vectoriel. Vous aurez aussi besoin d'une clé d'API OpenAI pour l'exemple d'embeddings. OpenAIEmbeddings est un choix compatible LangChain, pas une exigence de OracleVS.

Installez Node.js depuis la page officielle de téléchargement Node.js.

Pour la voie locale principale, suivez le démarrage rapide Oracle AI Database Free. Une fois la base lancée, utilisez un service tel que localhost:1521/FREEPDB1 et un schéma avec les autorisations listées ci-dessus.

Créer un projet 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]

Créez un fichier nommé index.ts dans ce dossier. Ajoutez les extraits TypeScript exécutables ci-dessous dans ce même fichier, dans l'ordre indiqué. Ne créez pas de fichier séparé pour chaque extrait. Copiez uniquement les extraits TypeScript exécutables : les blocs SQL et les sorties représentatives sont des exemples explicatifs et ne doivent pas être collés dans index.ts.

Le paramètre type=module dans package.json autorise l'await au niveau supérieur utilisé par les exemples. La configuration des packages Node.js est documentée dans le guide officiel des packages Node.js.

Le package d'intégration Oracle implémente le vector store, @langchain/core fournit Document, @langchain/openai fournit le modèle d'embeddings d'exemple, et oracledb gère la connexion à la base. Les versions ci-dessus correspondent à l'application compagnon ; tsx exécute directement l'exemple TypeScript sans étape de build séparée.

Configurer la connexion

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

Enregistrez ces valeurs dans un fichier local .env et ajoutez .env à .gitignore. Cet article utilise Oracle AI Database Free en local comme configuration principale pour des étapes reproductibles. Autonomous AI Database est une alternative valable en déploiement, mais elle nécessite le descripteur de service et le portefeuille ou une configuration TLS spécifique à cet environnement.

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

Le pool permet à OracleVS de réutiliser des sessions Oracle. Conservez toutes les instructions d'ingestion, de recherche et de vérification dans le bloc try. Le prochain bloc de code ouvre ce bloc, et les extraits suivants le poursuivent. Le pool est fermé uniquement après vérification, dans la section nettoyage ci-dessous. Dans une application serveur, initialisez le pool une seule fois et fermez-le lors de l'arrêt propre plutôt que d'ouvrir une nouvelle connexion à chaque requête.

Comment construire une recherche de documents avec LangChain.js

Nous utiliserons 10 courtes notes de base de connaissances, avec des passages de recherche qui se recouvrent. Le corpus est volontairement petit pour comparer la similarité simple, le filtrage par métadonnées et la MMR.

Définir vos documents de connaissance

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

Chaque Document contient pageContent et des metadata. Les champs source et category accompagnent le document pendant l'ingestion et la recherche, afin que l'application puisse expliquer l'origine d'un résultat et restreindre les recherches à un sous-ensemble pertinent.

Configurer les embeddings et créer 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() est l'appel d'intégration central. Il initialise le vector store, génère les embeddings pour les documents fournis et stocke leur contenu, leurs vecteurs et leurs métadonnées dans Oracle AI Database.

Le paramètre query fournit un texte d'exemple, vectorisé à l'initialisation pour déterminer la dimension nécessaire à la table vectorielle. Il n'est pas utilisé pour rechercher les documents stockés. DistanceStrategy.COSINE spécifie la métrique de distance, tandis que VectorElementFormat.FLOAT32 définit le format des éléments du vecteur.

Avant de relancer l'ingestion, utilisez un nouveau nom de table de démonstration ou purgez les données existantes afin d'éviter les doublons.

OracleVS accepte toute implémentation d'embeddings compatible LangChain, ce qui permet de changer de fournisseur sans modifier le workflow global du vector store. Toutefois, les embeddings utilisés pour l'ingestion et la recherche doivent rester compatibles avec la colonne vectorielle Oracle.

OracleVS détermine la dimension du vecteur à l'initialisation à partir du modèle configuré. Pour inspecter la dimension et le format de stockage d'un vecteur déjà enregistré dans Oracle AI Database, exécutez la requête SQL suivante :

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;

Si vous passez à un modèle d'embeddings d'une dimension différente, créez une table vectorielle compatible et regénérez les embeddings des documents. Même si deux modèles produisent des vecteurs de même dimension, leurs espaces d'embeddings peuvent différer ; il faut donc ré-embedding les documents avant d'utiliser le nouveau modèle pour la recherche.

Pour les signatures méthodes du vector store et les options de recherche, consultez la référence LangChain.js VectorStore.

Récupérer des documents par similarité

Par exemple, l'appel suivant demande au vector store OracleVS les 3 documents les plus proches et affiche la métadonnée de source avec le texte de chaque extrait :

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

Le code convertit chaque Document LangChain en objet simple contenant source et pageContent pour l'affichage. Une sortie représentative est montrée ci-dessous ; l'ordre exact peut varier selon le modèle d'embeddings et la requête :

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

Le premier argument est la question de l'utilisateur, le second est k, le nombre maximum de documents à récupérer. LangChain.js utilise le modèle d'embeddings configuré pour convertir la question en vecteur, et Oracle AI Database exécute la recherche par similarité pour trouver les documents les plus proches.

Si moins de k documents sont éligibles après application des conditions de recherche et des filtres de métadonnées, la méthode renvoie uniquement les résultats disponibles. Les objets Document récupérés contiennent le texte et les métadonnées, affichables avec l'attribution de la source ou transmissibles à une étape ultérieure de génération de réponse.

Inspecter les scores de recherche

Par exemple, utilisez similaritySearchWithScore pour inspecter la distance associée à chaque document récupéré :

  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 renvoie une distance pour chaque correspondance. Sa valeur et son sens d'interprétation dépendent de la métrique configurée, ce n'est donc pas un pourcentage de confiance universel. Comparez les scores uniquement avec le même modèle d'embeddings et la même métrique, et examinez le passage récupéré avant de fixer un seuil.

Limiter les résultats avec des filtres de métadonnées

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

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

Exemple de sortie :

["database-guide"]

Le troisième argument limite la recherche aux éléments avec category = database. Dans ce corpus, le résultat filtré attendu est ["database-guide"]. Un filtre modifie l'éligibilité des documents ; la similarité vectorielle classe toujours les éligibles.

Utiliser la MMR pour réduire les résultats répétitifs

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

Sortie représentative pour un corpus avec chevauchements (l'ordre peut varier selon les modèles et exécutions) :

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

La MMR évalue d'abord un pool de candidats (fetchK), puis sélectionne k documents en équilibrant pertinence et diversité. Un lambda plus faible met l'accent sur la diversité ; une valeur plus élevée privilégie la pertinence. Avec le corpus ci-dessus, les sources retenues peuvent différer de la similarité simple, ce qui rend le compromis de recherche visible.

Transmettre le contexte récupéré à une application d'IA

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

C'est le point de passage entre la recherche LangChain.js et l'appel au grand modèle de langue (LLM) : l'application dispose d'une question et d'éléments vérifiables, prêts pour un prompt demandant au modèle de répondre à partir de ce contexte.

La recherche et la génération sont des responsabilités distinctes. À ce stade, context est une chaîne texte simple que peut consommer un modèle de conversation. Vous pouvez la fournir à un modèle avec l'instruction de répondre uniquement à partir du matériel récupéré et de citer les identifiants de source. L'intégration à la base fonctionne même sans modèle de chat.

Comment vérifier l'intégration

Une validation utile consiste à contrôler l'ingestion puis chaque stratégie de recherche séparément. D'abord, confirmez que le vector store a été créé sans erreur côté base. Ensuite, inspectez la métadonnée de source renvoyée par la similarité, le résultat filtré et le résultat 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),
  });

Fermer le pool de connexions après vérification

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

Le nettoyage ne s'exécute qu'après l'ingestion, la recherche et la vérification. Le délai d'écoulement laisse un court laps de temps aux connexions en cours pour se terminer. Dans un serveur long courrier, conservez le pool ouvert jusqu'à l'arrêt propre. Voir la documentation node-oracledb pool.close() pour les détails du cycle de vie.

À ce stade, le fichier index.ts complet peut être exécuté avec :

npx tsx index.ts

Un exemple de sortie de validation :

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

L'ordre exact des similarités et les distances peuvent varier selon le modèle et le fournisseur d'embeddings. Le résultat filtré doit contenir database-guide, tandis que le résultat MMR doit montrer un ensemble varié de sources issues du corpus qui se recouvre.

Conseils et dépannage

Échec de connexion à la base

Vérifiez la chaîne de connexion, les identifiants, la disponibilité du service et les privilèges du schéma. Si vous utilisez Autonomous AI Database, confirmez la configuration requise du portefeuille ou de TLS. Testez la connexion à la base de manière indépendante avant de déboguer la recherche.

Incompatibilité de dimension des embeddings

Les vecteurs créés lors de l'ingestion et ceux des requêtes doivent avoir des dimensions compatibles. Utiliser des modèles différents pour les insertions et les requêtes peut casser la recherche ou en dégrader les résultats. Conservez une sélection de modèle cohérente pour une table.

Une recherche ne renvoie aucun document

Confirmez que l'ingestion a inséré des lignes, puis réessayez sans filtres de métadonnées restrictifs. Pour les petits corpus, testez des requêtes plus larges et inspectez le contenu stocké.

Les résultats sont pertinents mais répétitifs

Comparez la similarité simple avec la MMR sur un corpus aux extraits qui se recouvrent. Ajustez k, fetchK et lambda en vérifiant si la diversité ne fait pas manquer des passages importants.

Faut-il créer un index vectoriel ?

Pour un petit jeu d'essai, commencez par valider le fonctionnement sans accorder l'indexation. Quand les données grossissent, évaluez les index vectoriels Oracle comme HNSW (Hierarchical Navigable Small World) ou IVF (Inverted File), selon vos besoins de performance et de précision. La création d'index est une optimisation, pas un prérequis pour comprendre l'intégration de base.

Pour en savoir plus sur les index vectoriels Oracle, consultez la documentation sur les index vectoriels.

Explorer une implémentation de référence TypeScript complète

Pour voir comment ces concepts s'assemblent dans une application opérationnelle, explorez l'implémentation de référence LangChain.js et Oracle AI Database.

Développée en TypeScript, l'application réunit l'ingestion de documents, le stockage vectoriel, la recherche par similarité, le filtrage par métadonnées et la MMR avec LangChain.js et Oracle AI Database. Elle fournit également une interface interactive pour expérimenter les paramètres de recherche, inspecter les documents récupérés et comprendre l'impact des stratégies de recherche sur le contexte renvoyé à l'application.

Le dépôt inclut le code source et les instructions d'installation, ce qui vous permet d'explorer l'intégration complète et d'adapter l'implémentation à vos propres projets.

Conclusion et prochaines étapes

Vous avez connecté LangChain.js à Oracle AI Database via OracleVS, représenté la connaissance sous forme d'objets Document, créé des embeddings vectoriels persistants et comparé la similarité, le filtrage par métadonnées et la MMR. Pour aller plus loin, lisez la documentation officielle LangChain.js et le guide d'intégration Oracle LangChain JavaScript.

Si vous travaillez dans d'autres langages, notre tutoriel Oracle AI Vector Search couvre les mêmes étapes de stockage et de requête en Python, et notre tutoriel LangChain4j construit un agent Java avec Oracle AI Database.

Notre cours Retrieval Augmented Generation (RAG) avec LangChain est un complément optionnel centré sur la recherche ; ses exemples sont en Python, mais les concepts de workflow s'appliquent à cette implémentation TypeScript.

FAQ

Que se passe-t-il si je change de modèle d'embeddings après avoir stocké des documents ?

Les embeddings stockés dans la table vectorielle Oracle doivent être compatibles avec ceux utilisés pour la recherche. Changer de modèle peut modifier à la fois les dimensions et la signification des coordonnées vectorielles ; ré-embeddez et recréez les index lors d'un changement de modèle. Utilisez la même configuration d'embeddings pour l'ingestion des documents et les requêtes.

Ai-je besoin d'un modèle de chat pour utiliser OracleVS ?

Non. Un workflow de vector store nécessite un modèle d'embeddings pour l'ingestion et la requête. Un modèle de chat est optionnel et s'ajoute généralement quand les passages récupérés doivent être transformés en réponse en langage naturel.

Puis-je utiliser un fournisseur d'embeddings autre qu'OpenAI ?

Oui. OracleVS accepte une implémentation d'embeddings compatible LangChain. Choisissez un fournisseur qui répond à vos besoins et utilisez la même configuration d'embeddings compatible pour les documents et les requêtes.

Pourquoi combiner filtrage par métadonnées et similarité vectorielle ?

La similarité vectorielle trouve du contenu sémantiquement proche ; le filtrage par métadonnées restreint le contenu éligible, par exemple aux documents d'une catégorie ou d'une source particulière.

Quand privilégier la MMR plutôt que la similarité classique ?

La MMR est utile lorsque les meilleurs résultats contiennent des passages redondants et que l'application bénéficie d'éléments plus variés. La similarité simple suffit quand les plus proches voisins sont l'objectif principal.

Daniela Pavlenco

Auteur

Daniela Pavlenco

Je suis Developer Advocate chez Oracle, et j'aide les développeurs à explorer les technologies d'IA et à créer des applications concrètes avec des outils et des frameworks modernes. Mon travail consiste à produire du contenu technique, des exemples pratiques et des ressources pour développeurs afin de rendre des notions complexes plus faciles à comprendre et à appliquer dans des projets réels.

Sujets

Contenus associés

blog

Comprendre les TPU et les GPU dans l'IA : Un guide complet