Перейти к основному содержимому

LangChain.js и Oracle AI Database: руководство по векторному поиску

Подключите LangChain.js к Oracle AI Database с OracleVS, храните эмбеддинги с метаданными и сравните поиск по сходству, фильтры по метаданным и MMR на TypeScript.
· 10 мин читать

Исследуйте с ИИ

Языковая модель может отвечать на общие вопросы, но она не сможет надёжно обращаться к вашей закрытой базе знаний, если приложение предварительно не извлечёт релевантную информацию. Для разработчиков на JavaScript LangChain.js предоставляет привычные абстракции для документов, эмбеддингов и получения данных. Не хватает постоянного хранилища для векторов и механизма их поиска.

Oracle AI Database закрывает этот пробел через интеграцию @oracle/langchain-oracledb. В этом руководстве вы подключите небольшой рабочий процесс на TypeScript к Oracle, сохраните текст с метаданными, выполните поиск по сходству и улучшите извлечение с помощью фильтров и Maximal Marginal Relevance (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 и отделяет генерацию эмбеддингов, чтобы сохранить понятный поток.

Схема архитектуры, показывающая RAG-процесс на TypeScript с LangChain.js: интерфейс React отправляет вопрос в API на Node.js, LangChain.js создаёт эмбеддинги и извлекает документы через OracleVS из векторной таблицы Oracle AI Database, а API возвращает обоснованный ответ.

Загрузка и извлечение документов с помощью LangChain.js, OracleVS и Oracle AI Database

Ключевые возможности интеграции

Хранение эмбеддингов вместе с метаданными документа

Модель эмбеддингов преобразует текст в числовые векторы. OracleVS сохраняет эти векторы вместе с исходным текстом и структурированными метаданными. Метаданные, такие как категория документа или источник, помогают приложению ограничивать поиск, не теряя полезный контекст.

Извлечение релевантных фрагментов по векторному сходству

Во время запроса та же модель эмбеддингов преобразует вопрос во вектор. Oracle сравнивает его с сохранёнными векторами, используя выбранную стратегию расстояния, например косинусное расстояние, и возвращает ближайшие документы. Результаты остаются объектами Document LangChain, готовыми для последующей обработки.

Управление результатами с помощью фильтрации и MMR

Поиск по сходству отвечает на вопрос «какие элементы ближе всего к этому запросу?». Фильтр по метаданным сужает круг допустимых документов. MMR добавляет другую цель: сохранять релевантность выбранных фрагментов, уменьшая число почти дублирующихся результатов. Эти операции дополняют друг друга, а не заменяют.

Начало работы с LangChain.js и Oracle AI Database

Необходимые условия

Для этого примера на TypeScript вам понадобятся Node.js 24.13.0, npm 11.6.2, локальный экземпляр Oracle AI Database 26ai Free с поддержкой векторов и схема, которая может создавать, вставлять, запрашивать и удалять демонстрационную таблицу и её векторный индекс. Для примера с эмбеддингами также нужен ключ API OpenAI. OpenAIEmbeddings — совместимый с LangChain выбор, а не требование OracleVS.

Установите Node.js со страницы официальных загрузок Node.js.

Для основного локального варианта следуйте инструкции быстрого старта 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.

Настройка type=module в package.json позволяет использовать верхнеуровневый 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 — корректная альтернатива для развёртывания, но для неё потребуется дескриптор сервиса и конфигурация wallet или 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;

Если вы переключитесь на модель эмбеддингов с другой размерностью, создайте совместимую векторную таблицу и заново сгенерируйте эмбеддинги документов. Даже если две модели создают векторы одинаковой размерности, их пространства эмбеддингов могут различаться, поэтому существующие документы следует пере-встраивать перед использованием новой модели для извлечения.

Сигнатуры методов векторного хранилища и параметры извлечения смотрите в официальной справке по VectorStore LangChain.js.

Извлекайте документы с помощью поиска по сходству

Например, следующий вызов запрашивает у векторного хранилища 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,
  })));

Код отображает каждый объект Document LangChain в простой объект с его 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 сильнее акцентирует разнообразие; более высокое — релевантность. В случае перекрывающегося корпуса выбранные источники могут отличаться от обычного поиска по сходству, что наглядно показывает компромисс при извлечении.

Передавайте извлечённый контекст в ИИ-приложение

  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, убедитесь в корректной настройке wallet или TLS. Протестируйте подключение к базе отдельно, прежде чем отлаживать извлечение.

Несоответствие размерности эмбеддингов

Векторы, созданные при загрузке, и векторы запроса должны иметь совместимые размерности. Использование разных моделей эмбеддингов для вставки и запросов может нарушить поиск или ухудшить результаты. Для одной таблицы сохраняйте единый выбор модели.

Поиск не возвращает документы

Убедитесь, что загрузка вставила строки, затем повторите без жёстких фильтров по метаданным. Для небольших корпусов пробуйте более широкие запросы и изучайте сохранённое содержимое.

Результаты релевантны, но повторяются

Сравните поиск по сходству с MMR на корпусе с пересекающимися фрагментами. Подбирайте значения k, fetchK и lambda, оценивая, не приводит ли рост разнообразия к потере важных фрагментов.

Нужно ли создавать векторный индекс?

Для небольшого демонстрационного набора начните с проверки корректности без настройки индексов. По мере роста данных оцените векторные индексы Oracle, такие как Hierarchical Navigable Small World (HNSW) или Inverted File (IVF), исходя из ваших требований к производительности и точности. Создание индекса — это оптимизация, а не обязательное условие для понимания базовой интеграции.

Подробнее о векторных индексах Oracle см. в документации по векторным индексам.

Изучите полноценную референсную реализацию на TypeScript

Чтобы увидеть, как эти концепции сочетаются в рабочем приложении, изучите референсную реализацию LangChain.js и Oracle AI Database.

Приложение на TypeScript объединяет загрузку документов, векторное хранение, поиск по сходству, фильтрацию по метаданным и MMR с использованием LangChain.js и Oracle AI Database. Оно также предоставляет интерактивный интерфейс для экспериментов с настройками извлечения, анализа извлечённых документов и понимания того, как разные стратегии поиска влияют на контекст, возвращаемый приложению.

Репозиторий содержит исходный код и инструкции по настройке, что позволяет изучить полную интеграцию и адаптировать реализацию под собственные проекты.

Заключение и следующие шаги

Вы подключили LangChain.js к Oracle AI Database через OracleVS, представили знания в виде объектов Document, создали постоянные векторные эмбеддинги и сравнили поиск по сходству, фильтрацию по метаданным и MMR. Далее ознакомьтесь с официальной документацией LangChain.js и официальным руководством по интеграции Oracle LangChain JavaScript.

Если вы работаете на других языках, наш туториал по Oracle AI Vector Search описывает те же шаги по хранению и запросам на Python, а туториал по LangChain4j строит Java-агента с Oracle AI Database.

Наш курс Retrieval Augmented Generation (RAG) с LangChain — необязательное продолжение с упором на извлечение; его примеры на Python, но концепции рабочего процесса применимы и к этой реализации на TypeScript.

Вопросы и ответы

Что произойдёт, если сменить модель эмбеддингов после сохранения документов?

Эмбеддинги, сохранённые во векторной таблице Oracle, должны быть совместимы с эмбеддингами, используемыми для поиска. Смена моделей может изменить и размерность векторов, и смысл координат, поэтому при изменении модели эмбеддингов пере-встраивайте документы и перестраивайте индексы. Используйте одну и ту же конфигурацию эмбеддингов для загрузки документов и выполнения запросов.

Нужна ли чат-модель, чтобы использовать OracleVS?

Нет. Для рабочего процесса с векторным хранилищем требуется модель эмбеддингов для загрузки и запросов. Чат-модель — опциональна и обычно добавляется, когда извлечённые фрагменты нужно превратить в ответ на естественном языке.

Могу ли я использовать провайдера эмбеддингов, отличного от OpenAI?

Да. OracleVS принимает совместимую реализацию эмбеддингов LangChain. Выберите провайдера, соответствующего вашим требованиям, и используйте одинаковую совместимую настройку эмбеддингов для документов и запросов.

Зачем сочетать фильтрацию по метаданным с векторным сходством?

Векторное сходство находит семантически близкое содержание; фильтрация по метаданным сужает круг материалов, которые могут вернуться, например документы конкретной категории или источника.

Когда выбирать MMR вместо обычного поиска по сходству?

MMR помогает, когда в топовых совпадениях встречаются повторяющиеся фрагменты, а приложению выгоднее более разнообразные доказательства. Простой поиск по сходству проще, когда ближайшие соседи — основная цель.

Daniela Pavlenco

Автор

Daniela Pavlenco

Я работаю Developer Advocate в Oracle и помогаю разработчикам изучать ИИ-технологии и создавать практические приложения с использованием современных инструментов и фреймворков. Моя работа включает создание технических материалов, практических примеров и ресурсов для разработчиков, которые помогают упростить сложные концепции и применить их в реальных проектах.

Темы