跳至主要内容

LangChain.js 与 Oracle AI Database:向量搜索指南

使用 OracleVS 将 LangChain.js 连接到 Oracle AI Database,存储带元数据的嵌入,并在 TypeScript 中比较相似度搜索、元数据过滤与 MMR。
· 10分钟 阅读

使用 AI 探索

语言模型可以回答常见问题,但如果应用不先检索相关信息,它无法可靠地查询私有知识库。对于 JavaScript 开发者,LangChain.js 提供了文档、嵌入与检索的熟悉抽象。缺少的一环是一个可持久化存储并搜索向量的地方。

Oracle AI Database 通过 @oracle/langchain-oracledb 集成承担了这一角色。在本指南中,您将把一个小型 TypeScript 工作流连接到 Oracle,存储带元数据的文本,运行相似度搜索,并通过过滤与最大边际相关性(MMR)改进检索。教程聚焦检索工作流;配套的 TypeScript 应用将相同集成加入交互式浏览器界面。

有关集成细节,请查看官方的 Oracle LangChain JavaScript 集成指南。

什么是 LangChain.js 与 Oracle AI Database 的集成?

LangChain.js 标准化了应用与嵌入模型和向量存储交互的方式。Oracle 集成包提供了 OracleVS,这是一种向量存储实现,可将文本文档、元数据和向量嵌入持久化在 Oracle AI Database 中。您的应用调用 LangChain.js 方法,而无需为每个相似度查询手写 SQL。

同一集成包还包含 OracleDocLoader、OracleTextSplitter、OracleEmbeddings 和 OracleSummary。它们是有用的可选构件;下文示例专注于 OracleVS,并将嵌入生成分离,以保持流程易于理解。

架构图展示 TypeScript LangChain.js RAG 工作流:React UI 将问题发送到 Node.js API,LangChain.js 通过 OracleVS 从 Oracle AI Database 的向量表创建嵌入并检索文档,API 返回有据可依的答案。

使用 LangChain.js、OracleVS 和 Oracle AI Database 进行文档摄取与检索

集成的关键特性

将嵌入与文档元数据一同存储

嵌入模型将文本转化为数值向量。OracleVS 将这些向量与源文本及结构化元数据一同存储。诸如文档类别或来源等元数据有助于应用在不丢失有用上下文的情况下约束搜索范围。

使用向量相似度检索相关片段

在查询时,同一嵌入模型将问题转换为向量。Oracle 使用配置的距离策略(如余弦距离)将其与已存储向量进行比较,并返回最接近的文档。结果仍为 LangChain 的 Document 对象,可直接用于下游处理。

通过过滤与 MMR 控制结果

相似度搜索回答的是“哪些条目与该问题最接近?”元数据过滤可缩小候选文档范围。MMR 则引入不同目标:在保持相关性的同时减少近重复结果。这些操作相辅相成,而非彼此替代。

开始使用 LangChain.js 与 Oracle AI Database

先决条件

对于此 TypeScript 示例,您需要 Node.js 24.13.0、npm 11.6.2、带向量支持的本地 Oracle AI Database 26ai Free 实例,以及具备对演示表及其向量索引进行创建、插入、查询与删除权限的 schema。您还需要一个用于嵌入示例的 OpenAI API 密钥。OpenAIEmbeddings 是与 LangChain 兼容的选择,并非 OracleVS 的硬性要求。

从官方的 Node.js 下载页面安装 Node.js。

对于本地的主路径,请按照 Oracle 的 Oracle AI Database Free 快速入门进行设置。数据库运行后,使用诸如 localhost:1521/FREEPDB1 的服务以及具备上述权限的 schema。

创建一个 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]

在该文件夹中创建名为 index.ts 的文件。将下方可执行的 TypeScript 代码片段按显示顺序添加到同一文件中。无需为每个片段创建单独文件。仅复制可执行的 TypeScript 片段:SQL 与代表性输出块用于解释说明,不应粘贴到 index.ts。

package.json 中的 type=module 设置允许示例使用顶层 await。Node.js 包配置详见官方的 Node.js 包指南。

Oracle 集成包实现了向量存储,@langchain/core 提供 Document,@langchain/openai 提供示例嵌入模型,oracledb 管理数据库连接。上述版本与配套应用一致;tsx 可直接运行 TypeScript 示例,无需单独构建步骤。

配置连接

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

将这些值保存在本地 .env 文件中,并将 .env 加入 .gitignore。本文以本地 Oracle AI Database Free 为主要设置,以确保步骤可复现。Autonomous AI Database 也是有效的部署选择,但需要该环境的服务描述符及钱包或 TLS 配置。

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

连接池使 OracleVS 能复用数据库会话。请将所有摄取、检索与验证语句放在 try 块内。下一个代码块开启该块,后续片段将继续其内逻辑。连接池仅在下面的清理部分验证后关闭。在服务器应用中,请在启动时初始化连接池,并在优雅关闭时释放,而不是为每个用户请求都新建连接。

如何使用 LangChain.js 构建文档搜索

我们将使用 10 条简短的知识库笔记,其中包含重叠的检索片段。语料库刻意保持很小,但这使得比较普通相似度搜索与元数据过滤和 MMR 成为可能。

定义您的知识文档

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

每个 Document 都包含 pageContent 与 metadata。source 与 category 字段会随文档贯穿摄取与检索流程,以便应用解释结果来源并将搜索限制到相关子集。

配置嵌入并创建 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() 是核心集成调用。它会初始化向量存储,为提供的文档生成嵌入,并将其内容、向量与元数据存入 Oracle AI Database。

query 参数提供在初始化期间嵌入的示例文本,用以确定数据库表所需的向量维度。它不用于搜索已存储文档。DistanceStrategy.COSINE 指定向量距离度量,而 VectorElementFormat.FLOAT32 设置向量元素格式。

在重新运行摄取之前,请使用新的演示表名或清理现有数据,以避免插入重复文档。

OracleVS 接受与 LangChain 兼容的嵌入实现,因此开发者可以在不改变整体向量存储工作流的前提下切换嵌入提供方。但用于摄取与检索的嵌入必须与 Oracle 的向量列保持兼容。

OracleVS 会在初始化时使用所配置的嵌入模型确定向量维度。若要查看已存储在 Oracle AI Database 中的向量的维度与存储格式,请运行以下 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;

如果切换到维度不同的嵌入模型,请创建兼容的向量表并重新生成文档嵌入。即使两个模型生成的向量维度相同,其嵌入空间也可能不同,因此在使用新模型进行检索前,应为现有文档重新生成嵌入。

有关向量存储方法签名与检索选项,请参阅官方的 LangChain.js VectorStore 参考。

使用相似度搜索检索文档

例如,以下调用向 OracleVS 向量存储请求最接近的 3 个文档,并打印每个片段的源元数据与文本:

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

该代码将每个 LangChain Document 映射为包含其 source 与 pageContent 的普通对象以便展示。下方展示代表性输出;确切顺序会随嵌入模型与查询而变化:

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

第一个参数是用户问题,第二个参数是 k,即要检索的最大文档数。LangChain.js 使用已配置的嵌入模型将问题转换为向量,Oracle AI Database 执行相似度搜索以找到最匹配的文档。

如果在应用搜索条件与元数据过滤后可用文档少于 k,该方法仅返回可用的结果。检索到的 Document 对象包含文本与元数据,可用于带溯源显示或传递给后续答案生成步骤。

检查检索分数

例如,当您希望查看每个检索文档所对应的距离时,可使用 similaritySearchWithScore:

  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 会为每个匹配项返回一个距离。其数值大小与方向取决于已配置的距离策略,因此并非通用的置信百分比。仅在使用相同的嵌入模型与距离策略时比较分数,并在选择阈值之前检查检索到的片段。

使用元数据过滤限制结果

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

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

示例输出:

["database-guide"]

第三个参数将搜索限制为 category = database 的条目。在此语料库中,可预期的过滤结果为 ["database-guide"]。过滤会改变合格文档的集合;向量相似度仍负责对合格文档排序。

使用 MMR 降低结果重复度

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

在存在重叠语料时的代表性输出(排序可能因嵌入模型与运行而异):

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

MMR 首先考虑候选池(fetchK),然后在相关性与多样性之间权衡选择 k 个文档。较低的 lambda 更强调多样性;较高的值更强调相关性。对上述重叠语料而言,所选来源可能与普通相似度搜索不同,使检索取舍更加直观。

将检索到的上下文传递给 AI 应用

  const question = "How does LangChain.js retrieve Oracle documents?";
  const contextDocs = await vectorStore.similaritySearch(question, 3);

  const context = contextDocs
    .map((doc, i) => `[${i + 1}] ${doc.pageContent}`)
    .join("\n\n");

  console.log({ question, context });

这是 LangChain.js 检索与大语言模型(LLM)调用之间的交接点:应用已拥有问题与可检验的证据,准备好用提示让模型基于该上下文作答。

检索与生成是相互独立的职责。此时,context 是聊天模型可直接消费的纯文本字符串。您可以将其提供给模型,并指示只根据检索材料回答并引用来源标识。即使没有聊天模型,数据库集成本身也可独立工作。

如何验证集成

一种有效的验证方式是分别检查摄取与每种检索策略。首先确认向量存储创建时未出现数据库错误。然后检查相似度搜索返回的源元数据、过滤后的结果与 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),
  });

验证后关闭连接池

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

清理仅在摄取、检索与验证完成后运行。排空时间为正在使用的连接提供短暂的完成窗口。在长时间运行的服务器中,请保持连接池开启,直到优雅关闭。生命周期细节参见 node-oracledb pool.close() 文档。

此时,可通过以下命令执行完整的 index.ts 文件:

npx tsx index.ts

代表性验证输出如下:

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

确切的相似度排序与距离值会随嵌入模型与提供方而变化。过滤结果应包含 database-guide,而 MMR 结果应在重叠语料中显示多样的检索来源。

提示与故障排查

数据库连接失败

请核实连接串、凭据、可达的服务与 schema 权限。若使用 Autonomous AI Database,请确认其所需的钱包或 TLS 配置。在调试检索前,先独立测试数据库连接。

发生嵌入维度不匹配

摄取期间创建的向量与查询向量必须使用兼容的维度。对插入与查询使用不同的嵌入模型会破坏搜索或降低效果。请在同一张表内保持模型选择一致。

搜索没有返回文档

确认摄取已插入行,然后在不使用严格元数据过滤的情况下重试。对于小语料,请尝试更宽泛的查询并检查已存储内容。

结果相关但重复

在具有重叠片段的语料上,将相似度搜索与 MMR 进行比较。调节 k、fetchK 与 lambda,同时观察多样性是否以遗漏重要片段为代价。

是否应创建向量索引?

对于小型示例数据集,请先在不调优索引的前提下验证正确性。随着数据增长,依据性能与准确性要求评估 Oracle 的 向量索引,如分层可导航小世界(HNSW)或倒排文件(IVF)索引。索引创建是优化措施,而非理解基础集成的前提。

有关 Oracle 向量索引的更多细节,请参阅 Oracle 的 向量索引文档。

探索完整的 TypeScript 参考实现

要了解这些概念如何在可运行的应用中协同工作,请查看 LangChain.js 与 Oracle AI Database 参考实现。

该应用基于 TypeScript,结合了使用 LangChain.js 与 Oracle AI Database 的文档摄取、向量存储、相似度搜索、元数据过滤与 MMR。它还提供交互式界面,用于试验检索设置、检查检索到的文档,并理解不同搜索策略如何影响返回给应用的上下文。

该仓库包含源代码与设置说明,便于您探索完整集成并将实现适配到您自己的项目。

结论与后续步骤

您已通过 OracleVS 将 LangChain.js 连接到 Oracle AI Database,将知识表示为 Document 对象,创建了持久化向量嵌入,并比较了相似度搜索、元数据过滤与 MMR。下一步,请阅读官方的 LangChain.js 文档 与官方的 Oracle LangChain JavaScript 集成指南。

如果您使用其他语言,我们的 Oracle AI 向量搜索教程用 Python 覆盖同样的存储与查询步骤,而我们的 LangChain4j 教程使用 Oracle AI Database 构建 Java 代理。

我们的 使用 LangChain 的检索增强生成(RAG)课程可作为可选的检索进阶学习;其示例为 Python,但工作流概念同样适用于本 TypeScript 实现。

常见问题

在存储文档后更换嵌入模型会怎样?

存储在 Oracle 向量表中的嵌入必须与用于搜索的嵌入兼容。更换模型可能会改变向量维度以及向量坐标的含义,因此在更换嵌入模型时应重新生成文档嵌入并重建索引。对文档摄取与查询检索使用相同的嵌入配置。

使用 OracleVS 是否必须要有聊天模型?

不需要。向量存储工作流在摄取与查询时需要嵌入模型。聊天模型是可选的,通常在需要将检索到的片段转化为自然语言回答时才会加入。

我可以使用 OpenAI 以外的嵌入提供方吗?

可以。OracleVS 接受与 LangChain 兼容的嵌入实现。请选择满足您需求的提供方,并对文档与查询使用相同且兼容的嵌入设置。

为何要将元数据过滤与向量相似度结合使用?

向量相似度用于查找语义上接近的内容;元数据过滤用于收窄可能返回的内容范围,例如限定在特定类别或来源的文档。

何时应选择 MMR 而不是普通相似度搜索?

当顶部匹配包含重复片段且应用需要更丰富多样的证据时,MMR 会有所帮助。若主要目标是最近邻,普通相似度搜索更为简单。

Daniela Pavlenco

作者

Daniela Pavlenco

我是一名 Oracle 的开发者布道师,专注于帮助开发者探索人工智能技术,并使用现代工具与框架构建实用应用。我的工作包括创作技术内容、动手示例以及开发者资源,帮助将复杂概念变得更易理解,并能在真实项目中加以应用。

主题