メインコンテンツにスキップ

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 アプリケーションでは同じ連携を対話的なブラウザ UI に追加しています。

連携の詳細は、公式のOracle LangChain JavaScript 連携ガイドを参照してください。

LangChain.js と Oracle AI Database の連携とは?

LangChain.js は、アプリケーションが埋め込みモデルやベクターストアを扱う方法を標準化します。Oracle 連携パッケージは、ドキュメントのテキスト、メタデータ、ベクター埋め込みを Oracle AI Database に永続化するベクターストア実装 OracleVS を提供します。アプリケーションは各類似度クエリのために手作業で SQL を書くのではなく、LangChain.js のメソッドを呼び出します。

同じ連携パッケージには 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 インスタンス、およびデモテーブルとそのベクターインデックスの作成・挿入・クエリ・削除が可能なスキーマが必要です。埋め込みの例には OpenAI API キーも必要です。OpenAIEmbeddings は LangChain 互換の選択肢であり、OracleVS の必須要件ではありません。

Node.js は公式のNode.js ダウンロードページからインストールしてください。

主要なローカル環境の手順は Oracle のOracle AI Database Free クイックスタートに従ってください。データベースの起動後、localhost:1521/FREEPDB1 のようなサービスと、上記の権限を持つスキーマを使用します。

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 ファイルに保存し、.gitignore に .env を追加してください。本記事では手順を再現可能にするため、主な構成としてローカルの 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;

別の次元を持つ埋め込みモデルに切り替える場合は、互換性のあるベクターテーブルを作成し、ドキュメントの埋め込みを再生成してください。たとえ 2 つのモデルが同じ次元のベクターを生成しても、埋め込み空間は異なる可能性があるため、新しいモデルでリトリーバルする前に既存ドキュメントは再埋め込みする必要があります。

ベクターストアのメソッドシグネチャとリトリーバルオプションについては、公式の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." }
]

第 1 引数はユーザーの質問で、第 2 引数は取得する最大ドキュメント数 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"]

第 3 引数は検索を 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 結果は重なりのあるコーパスから多様なリトリーバルソースを示すはずです。

ヒントとトラブルシューティング

データベース接続に失敗する

接続文字列、認証情報、到達可能なサービス、スキーマ権限を確認してください。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 Vector Search チュートリアルが Python で同じ保存・クエリ手順を解説しており、LangChain4j チュートリアルでは Oracle AI Database を用いた Java エージェントを構築します。

Retrieval Augmented Generation (RAG) with LangChain コースは任意のリトリーバル特化のフォローアップです。例は Python ですが、ワークフローの概念はこの TypeScript 実装にも当てはまります。

FAQs

ドキュメントを保存した後に埋め込みモデルを変更したらどうなりますか?

Oracle のベクターテーブルに保存された埋め込みは、検索に使用する埋め込みと互換でなければなりません。モデルを切り替えると、ベクターの次元だけでなく座標の意味も変わる可能性があるため、埋め込みモデルを変更する際はドキュメントを再埋め込みし、必要に応じて再インデックスしてください。ドキュメントの取り込みとクエリのリトリーバルには同一の埋め込み設定を使用してください。

OracleVS を使うのにチャットモデルは必要ですか?

不要です。ベクターストアのワークフローでは、取り込みとクエリのための埋め込みモデルが必要です。チャットモデルは任意で、取得したパッセージを自然言語の応答に変換したい場合に追加するのが一般的です。

OpenAI 以外の埋め込みプロバイダを利用できますか?

はい。OracleVS は互換の LangChain 埋め込み実装を受け入れます。要件を満たすプロバイダを選び、ドキュメントとクエリに対して同一の互換構成を使用してください。

なぜベクター類似度と併せてメタデータフィルタリングを使うのですか?

ベクター類似度は意味的に近いコンテンツを見つけ、メタデータフィルタリングは、特定のカテゴリや出典など返却対象となりうるコンテンツの範囲を絞り込みます。

通常の類似度検索ではなく MMR を選ぶべきなのはいつですか?

上位一致に重複的なパッセージが含まれ、より多様な根拠が有益な場合に MMR が役立ちます。最近傍の取得が主目的であれば、単純な類似度検索の方が適しています。

Daniela Pavlenco

著者

Daniela Pavlenco

私は Oracle のデベロッパー・アドボケイトとして、開発者が AI 技術を探求し、最新のツールやフレームワークを用いて実践的なアプリケーションを構築できるよう支援しています。 技術コンテンツ、ハンズオンのサンプル、開発者向けリソースを作成し、複雑な概念をわかりやすくし、実プロジェクトに適用しやすくすることに取り組んでいます。

トピック