Saltar al contenido principal

LangChain.js y Oracle AI Database: guía de búsqueda vectorial

Conecta LangChain.js con Oracle AI Database usando OracleVS, almacena embeddings con metadatos y compara búsqueda por similitud, filtros de metadatos y MMR en TypeScript.
· 10 min leer

Explora con IA

Un modelo de lenguaje puede responder preguntas generales, pero no puede consultar de forma fiable una base de conocimiento privada si la aplicación no recupera primero la información relevante. Para desarrolladores de JavaScript, LangChain.js ofrece abstracciones conocidas para documentos, embeddings y recuperación. La pieza que falta es un lugar persistente donde almacenar y buscar los vectores resultantes.

Oracle AI Database cubre ese rol mediante la integración @oracle/langchain-oracledb. En esta guía, conectarás un pequeño flujo de trabajo en TypeScript a Oracle, almacenarás texto con metadatos, ejecutarás una búsqueda por similitud y mejorarás la recuperación con filtros y maximal marginal relevance (MMR). El tutorial se centra en el flujo de recuperación; la aplicación complementaria en TypeScript añade la misma integración a una interfaz web interactiva.

Para los detalles de la integración, consulta la guía oficial de integración de Oracle LangChain JavaScript.

¿En qué consiste la integración de LangChain.js y Oracle AI Database?

LangChain.js estandariza cómo una aplicación trabaja con modelos de embeddings y almacenes vectoriales. El paquete de integración de Oracle aporta OracleVS, una implementación de vector store que persiste el texto de los documentos, los metadatos y los embeddings vectoriales en Oracle AI Database. Tu aplicación invoca métodos de LangChain.js en lugar de escribir SQL manualmente para cada consulta de similitud.

El mismo paquete de integración también incluye OracleDocLoader, OracleTextSplitter, OracleEmbeddings y OracleSummary. Son bloques opcionales útiles; el ejemplo siguiente se centra en OracleVS y mantiene la generación de embeddings por separado para que el flujo sea fácil de seguir.

Diagrama de arquitectura que muestra un flujo RAG con LangChain.js en TypeScript: una interfaz en React envía una pregunta a una API Node.js, LangChain.js crea embeddings y recupera documentos mediante OracleVS desde una tabla vectorial de Oracle AI Database, y la API devuelve una respuesta fundamentada.

Ingesta y recuperación de documentos con LangChain.js, OracleVS y Oracle AI Database

Funciones clave de la integración

Almacena embeddings junto con metadatos del documento

Un modelo de embeddings convierte texto en vectores numéricos. OracleVS guarda estos vectores junto al texto de origen y metadatos estructurados. Metadatos como la categoría o la fuente del documento ayudan a acotar las búsquedas sin perder contexto útil.

Recupera pasajes relevantes con similitud vectorial

En tiempo de consulta, el mismo modelo de embeddings convierte la pregunta en un vector. Oracle lo compara con los vectores almacenados usando una estrategia de distancia configurada, como la distancia coseno, y devuelve los documentos más cercanos. Los resultados siguen siendo objetos Document de LangChain, listos para el procesamiento posterior.

Controla los resultados con filtrado y MMR

La búsqueda por similitud responde «¿qué elementos están más cerca de esta pregunta?». Un filtro por metadatos reduce los documentos elegibles. MMR añade otro objetivo: mantener la relevancia de los pasajes seleccionados a la vez que reduce resultados casi duplicados. Son operaciones complementarias, no intercambiables.

Primeros pasos con LangChain.js y Oracle AI Database

Requisitos previos

Para este ejemplo en TypeScript, necesitas Node.js 24.13.0, npm 11.6.2, una instancia local de Oracle AI Database 26ai Free con soporte vectorial y un esquema con permisos para crear, insertar, consultar y eliminar la tabla de demostración y su índice vectorial. También necesitas una clave de API de OpenAI para el ejemplo de embeddings. OpenAIEmbeddings es una opción compatible con LangChain, no un requisito de OracleVS.

Instala Node.js desde la página oficial de descargas de Node.js.

Para la vía local principal, sigue el inicio rápido de Oracle AI Database Free de Oracle. Cuando la base de datos esté en marcha, usa un servicio como localhost:1521/FREEPDB1 y un esquema con los permisos indicados arriba.

Crea un proyecto en TypeScript

mkdir langchain-oracle-demo
cd langchain-oracle-demo
npm init -y
npm pkg set type=module
npm install @oracle/[email protected] @langchain/[email protected] @langchain/[email protected] [email protected] [email protected]
npm install --save-dev [email protected] [email protected] @types/[email protected]

Crea un archivo llamado index.ts en esta carpeta. Añade los fragmentos ejecutables de TypeScript que aparecen a continuación en el mismo archivo, en el orden indicado. No crees un archivo separado para cada fragmento. Copia solo los fragmentos ejecutables de TypeScript: los bloques de SQL y de salida representativa son ejemplos explicativos y no deben pegarse en index.ts.

El ajuste type=module en package.json permite el await de nivel superior usado en los ejemplos. La configuración de paquetes de Node.js está documentada en la guía oficial de paquetes de Node.js.

El paquete de integración de Oracle implementa el almacén vectorial, @langchain/core aporta Document, @langchain/openai aporta el modelo de embeddings de ejemplo y oracledb gestiona la conexión con la base de datos. Las versiones anteriores coinciden con la aplicación complementaria; tsx ejecuta el ejemplo de TypeScript directamente sin una fase de build aparte.

Configura la conexión

ORACLE_USER=tu_esquema
ORACLE_PASSWORD=tu_contraseña
ORACLE_CONNECT_STRING=localhost:1521/FREEPDB1
OPENAI_API_KEY=tu_api_key

Guarda estos valores en un archivo local .env y añade .env a .gitignore. Este artículo usa Oracle AI Database Free local como configuración principal para que los pasos sean reproducibles. Autonomous AI Database es una alternativa válida de despliegue, pero requiere el descriptor de servicio y la cartera (wallet) o configuración TLS para ese entorno.

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

El pool permite a OracleVS reutilizar sesiones de base de datos. Mantén toda la ingesta, recuperación y verificación dentro del bloque try. El siguiente bloque de código inicia ese bloque, y los fragmentos posteriores lo continúan. El pool solo se cierra tras la verificación en la sección de limpieza más abajo. En una aplicación de servidor, inicializa el pool una vez y ciérralo durante el apagado controlado en lugar de abrir una nueva conexión por cada petición.

Cómo crear una búsqueda de documentos con LangChain.js

Usaremos 10 notas cortas de base de conocimiento, con pasajes de recuperación solapados. El corpus es deliberadamente pequeño para poder comparar la búsqueda por similitud con el filtrado por metadatos y con MMR.

Define tus documentos de conocimiento

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

Cada Document tiene pageContent y metadata. Los campos source y category acompañan al documento durante la ingesta y la recuperación, de modo que la aplicación puede explicar de dónde procede un resultado y restringir búsquedas a un subconjunto relevante.

Configura los embeddings y crea OracleVS

  const embeddings = new OpenAIEmbeddings({
    model: "text-embedding-3-small",
  });

  const vectorStore = await OracleVS.fromDocuments(documents, embeddings, {
    client: pool,
    tableName: "LC_JS_RAG_DEMO",
    query: "Oracle AI Database document search",
    distanceStrategy: DistanceStrategy.COSINE,
    format: VectorElementFormat.FLOAT32,
  });

OracleVS.fromDocuments() es la llamada central de la integración. Inicializa el almacén vectorial, genera embeddings para los documentos proporcionados y guarda su contenido, vectores y metadatos en Oracle AI Database.

El parámetro query aporta texto de muestra que se embebe durante la inicialización para determinar la dimensión vectorial requerida por la tabla de base de datos. No se usa para buscar en los documentos almacenados. DistanceStrategy.COSINE especifica la métrica de distancia vectorial, mientras que VectorElementFormat.FLOAT32 define el formato de los elementos del vector.

Antes de repetir la ingesta, usa un nombre de tabla de demostración nuevo o limpia los datos existentes para evitar insertar documentos duplicados.

OracleVS acepta una implementación de embeddings compatible con LangChain, por lo que los desarrolladores pueden cambiar de proveedor de embeddings sin alterar el flujo general del almacén vectorial. Sin embargo, los embeddings usados para la ingesta y la recuperación deben ser compatibles con la columna vectorial de Oracle.

OracleVS determina la dimensión del vector durante la inicialización usando el modelo de embeddings configurado. Para inspeccionar las dimensiones y el formato de almacenamiento de un vector ya guardado en Oracle AI Database, ejecuta la siguiente consulta SQL:

SELECT
    VECTOR_DIMENSION_COUNT(embedding) AS vector_dimensions,
    VECTOR_DIMENSION_FORMAT(embedding) AS vector_format
FROM LC_JS_RAG_DEMO
FETCH FIRST 1 ROW ONLY;

Si cambias a un modelo de embeddings con una dimensión diferente, crea una tabla vectorial compatible y regenera los embeddings de los documentos. Incluso si dos modelos producen vectores con las mismas dimensiones, sus espacios de embedding pueden diferir; conviene re-embedder los documentos existentes antes de usar el nuevo modelo para la recuperación.

Para las signaturas de los métodos del vector store y las opciones de recuperación, consulta la referencia de VectorStore de LangChain.js.

Recupera documentos con búsqueda por similitud

Por ejemplo, la siguiente llamada pide al vector store OracleVS los 3 documentos más cercanos e imprime la metainformación de la fuente junto con el texto de cada fragmento:

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

El código convierte cada Document de LangChain en un objeto plano con su source y pageContent para mostrarlo. A continuación se muestra una salida representativa; el orden exacto puede variar según el modelo de embeddings y la consulta:

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

El primer argumento es la pregunta del usuario y el segundo es k, el número máximo de documentos a recuperar. LangChain.js usa el modelo de embeddings configurado para convertir la pregunta en un vector, y Oracle AI Database realiza la búsqueda por similitud para encontrar los documentos más cercanos.

Si hay menos de k documentos disponibles tras aplicar las condiciones de búsqueda y los filtros de metadatos, el método devuelve solo los resultados disponibles. Los objetos Document recuperados contienen texto y metadatos que pueden mostrarse con atribución de fuente o pasarse a un paso posterior de generación de respuestas.

Inspecciona las puntuaciones de recuperación

Por ejemplo, usa similaritySearchWithScore cuando quieras inspeccionar la distancia asociada a cada documento recuperado:

  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 devuelve una distancia con cada coincidencia. Su valor numérico y su dirección dependen de la estrategia de distancia configurada, así que no es un porcentaje de confianza universal. Compara puntuaciones solo cuando uses el mismo modelo de embeddings y la misma estrategia de distancia, e inspecciona el pasaje recuperado antes de elegir un umbral.

Limita resultados con filtros de metadatos

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

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

Salida de ejemplo:

["database-guide"]

El tercer argumento restringe la búsqueda a los elementos con category = database. En este corpus, el resultado filtrado previsible es ["database-guide"]. Un filtro cambia qué documentos son elegibles; la similitud vectorial sigue ordenando los documentos elegibles.

Usa MMR para reducir resultados repetitivos

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

Salida representativa con un corpus solapado (el orden puede variar entre modelos de embeddings y ejecuciones):

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

MMR primero considera un conjunto de candidatos (fetchK) y luego selecciona k documentos equilibrando relevancia con diversidad. Un lambda más bajo enfatiza más la diversidad; un valor más alto prioriza la relevancia. Con el corpus solapado anterior, las fuentes seleccionadas pueden diferir de la búsqueda por similitud convencional, haciendo visible el compromiso de recuperación.

Pasa el contexto recuperado a una aplicación de 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 });

Este es el punto de traspaso entre la recuperación de LangChain.js y una llamada a un modelo de lenguaje grande (LLM): la aplicación ya tiene una pregunta más evidencias inspeccionables, listas para un prompt que pida al modelo responder desde ese contexto.

Recuperación y generación son responsabilidades distintas. En este punto, context es una cadena de texto que un modelo de chat puede consumir. Ahora podrías suministrarla a un modelo con la instrucción de responder solo a partir del material recuperado y citar los identificadores de fuente. La propia integración con la base de datos funciona incluso sin un modelo de chat.

Cómo verificar la integración

Una validación útil comprueba la ingesta y cada estrategia de recuperación por separado. Primero, confirma que el vector store se creó sin error de base de datos. Luego inspecciona la fuente devuelta por la búsqueda por similitud, el resultado filtrado y el resultado de 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),
  });

Cierra el pool de conexiones tras la verificación

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

La limpieza se ejecuta solo cuando han terminado la ingesta, la recuperación y la verificación. El tiempo de drenaje da a las conexiones en uso una pequeña ventana para completarse. En un servidor de larga duración, mantén el pool abierto hasta el apagado controlado. Consulta la documentación de node-oracledb pool.close() para los detalles del ciclo de vida.

En este punto, puedes ejecutar el archivo completo index.ts con:

npx tsx index.ts

Una salida de validación representativa es:

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

El orden exacto por similitud y los valores de distancia pueden variar según el modelo y el proveedor de embeddings. El resultado filtrado debería contener database-guide, mientras que el resultado de MMR debería mostrar un conjunto variado de fuentes de recuperación del corpus solapado.

Consejos y resolución de problemas

Falla la conexión a la base de datos

Verifica la cadena de conexión, las credenciales, el servicio accesible y los privilegios del esquema. Si usas Autonomous AI Database, confirma su configuración requerida de wallet o TLS. Prueba la conexión a la base de datos de forma independiente antes de depurar la recuperación.

Se produce una discrepancia en la dimensión de los embeddings

Los vectores creados durante la ingesta y los vectores de consulta deben usar dimensiones compatibles. Usar modelos de embeddings distintos para inserciones y consultas puede romper la búsqueda o degradar los resultados. Mantén la selección del modelo coherente para una tabla.

Una búsqueda no devuelve documentos

Confirma que la ingesta insertó filas y vuelve a intentar sin filtros de metadatos restrictivos. Para corpus pequeños, prueba con consultas más amplias e inspecciona el contenido almacenado.

Los resultados son relevantes pero repetitivos

Compara la búsqueda por similitud con MMR usando un corpus con fragmentos solapados. Ajusta k, fetchK y lambda comprobando si la diversidad tiene el coste de perder pasajes importantes.

¿Deberías crear un índice vectorial?

Para un conjunto de datos de muestra pequeño, empieza validando la corrección sin afinar el indexado. A medida que crezcan los datos, evalúa los índices vectoriales de Oracle como Hierarchical Navigable Small World (HNSW) o Inverted File (IVF), según tus necesidades de rendimiento y precisión. La creación de índices es una optimización, no un requisito previo para entender la integración básica.

Para más detalles sobre los índices vectoriales de Oracle, consulta la documentación de índices vectoriales de Oracle.

Explora una implementación de referencia completa en TypeScript

Para ver cómo encajan estos conceptos en una aplicación funcional, explora la implementación de referencia de LangChain.js y Oracle AI Database.

Construida con TypeScript, la aplicación reúne la ingesta de documentos, el almacenamiento vectorial, la búsqueda por similitud, el filtrado por metadatos y MMR usando LangChain.js y Oracle AI Database. También ofrece una interfaz interactiva para experimentar con ajustes de recuperación, inspeccionar documentos recuperados y entender cómo distintas estrategias de búsqueda afectan al contexto que recibe la aplicación.

El repositorio incluye el código fuente y las instrucciones de configuración, lo que te permite explorar la integración completa y adaptar la implementación a tus propios proyectos.

Conclusión y siguientes pasos

Has conectado LangChain.js con Oracle AI Database mediante OracleVS, has representado conocimiento como objetos Document, has creado embeddings vectoriales persistentes y has comparado la búsqueda por similitud, el filtrado por metadatos y MMR. Como siguiente paso, lee la documentación oficial de LangChain.js y la guía oficial de integración de Oracle LangChain JavaScript.

Si trabajas en otros lenguajes, nuestro tutorial de Oracle AI Vector Search cubre los mismos pasos de almacenamiento y consulta en Python, y nuestro tutorial de LangChain4j construye un agente en Java con Oracle AI Database.

Nuestro curso Retrieval Augmented Generation (RAG) con LangChain es un seguimiento opcional centrado en la recuperación; sus ejemplos están en Python, pero los conceptos del flujo aplican a esta implementación en TypeScript.

Preguntas frecuentes

¿Qué ocurre si cambio de modelo de embeddings después de almacenar documentos?

Los embeddings almacenados en la tabla vectorial de Oracle deben ser compatibles con los usados para la búsqueda. Cambiar de modelo puede alterar tanto las dimensiones vectoriales como el significado de las coordenadas, así que vuelve a generar los embeddings y reindexa los documentos cuando cambies de modelo de embeddings. Usa la misma configuración de embeddings para la ingesta de documentos y la recuperación de consultas.

¿Necesito un modelo de chat para usar OracleVS?

No. Un flujo con vector store requiere un modelo de embeddings para la ingesta y la consulta. Un modelo de chat es opcional y suele añadirse cuando los pasajes recuperados deben convertirse en una respuesta en lenguaje natural.

¿Puedo usar un proveedor de embeddings distinto a OpenAI?

Sí. OracleVS acepta una implementación de embeddings compatible con LangChain. Elige un proveedor que se ajuste a tus requisitos y usa la misma configuración compatible de embeddings para documentos y consultas.

¿Por qué usar filtrado por metadatos junto con similitud vectorial?

La similitud vectorial encuentra contenido semánticamente cercano; el filtrado por metadatos acota qué contenido puede devolverse, como documentos de una categoría o fuente concreta.

¿Cuándo elegir MMR frente a la búsqueda por similitud convencional?

MMR ayuda cuando los mejores resultados contienen pasajes repetitivos y la aplicación se beneficia de evidencias más variadas. La búsqueda por similitud simple es más adecuada cuando los vecinos más cercanos son el objetivo principal.

Daniela Pavlenco

Autor

Daniela Pavlenco

Soy Developer Advocate en Oracle y me centro en ayudar a desarrolladores a explorar tecnologías de IA y a crear aplicaciones prácticas con herramientas y frameworks modernos. Mi trabajo incluye crear contenido técnico, ejemplos prácticos y recursos para desarrolladores que simplifican conceptos complejos y facilitan su aplicación en proyectos reales.

Temas

Relacionado

blog

Las 7 mejores bases de datos vectoriales en 2026