OracleVS 통합

LangChain JavaScript로 OracleVS 벡터 스토어와 통합해요.

**호환성**: Node.js에서만 사용할 수 있어요.

Oracle AI Database는 키워드가 아니라 의미(의미론) 로 데이터를 쿼리하는 AI 워크로드를 지원해요. 비정형 콘텐츠에 대한 의미론적 검색과 비즈니스 데이터에 대한 관계형 필터링을 단일 시스템에서 결합해서, 별도의 벡터 데이터베이스를 도입하지 않고도 데이터를 여러 플랫폼에 분산시키지 않으면서 검색 워크플로(RAG 같은)를 구축할 수 있어요.

이 가이드는 OracleVS(Oracle AI Vector Search용 LangChain 벡터 스토어 통합)를 사용해 다음을 수행하는 방법을 보여줘요:

문서와 임베딩을 Oracle에 수집
유사도 검색 실행
HNSW와 IVF 인덱스 생성
고급 검색을 위한 메타데이터 필터 적용
Oracle AI Database 26ai에서 하이브리드 검색(키워드 + 의미) 활성화
Oracle Text를 사용한 전체 텍스트 검색 실행

개요 (Overview)

통합 세부 정보 (Integration details)

클래스	패키지	하이브리드 검색	PY 지원
`OracleVS`	`@oracle/langchain-oracledb`	✅	✅

설정 (Setup)

Oracle 클라이언트 바인딩과 LangChain Oracle 헬퍼를 설치하세요:

```bash npm npm install @oracle/langchain-oracledb @langchain/core ```

yarn add @oracle/langchain-oracledb @langchain/core

pnpm add @oracle/langchain-oracledb @langchain/core

벡터 테이블을 소유할 Oracle 사용자의 연결 자격 증명을 설정하세요:

export ORACLE_USER=testuser
export ORACLE_PASSWORD=testuser
export ORACLE_DSN="localhost:1521/free"

벡터 스토어 생성 (Create a vector store)

아래 예제는 이미 벡터·메타데이터 열이 있는 테이블을 만들고 OracleEmbeddings로 임베딩을 생성했다고 가정해요.

import oracledb from "oracledb";
import { OracleEmbeddings, OracleVS } from "@oracle/langchain-oracledb";
import { Document } from "@langchain/core/documents";

const connection = await oracledb.getConnection({
  user: process.env.ORACLE_USER,
  password: process.env.ORACLE_PASSWORD,
  connectionString: process.env.ORACLE_DSN,
});

const embeddings = new OracleEmbeddings(connection, {
  provider: "database",
  model: "DEMO_MODEL",
});

const vectorStore = new OracleVS(embeddings, {
  client: connection,
  tableName: "DEMO_VECTORS",
  query: "Find documents about Oracle RAG patterns.",
  distanceStrategy: "DOT",
});
await vectorStore.initialize();

const docs: Document[] = [
  {
    pageContent: "LangChain works great with Oracle Database.",
    metadata: {
      doc_id: "doc-1",
      title: "RAG overview",
      status: "release",
      tags: ["AI", "rag"],
      category: "books",
      price: 18,
    },
  },
];

await vectorStore.addDocuments(docs);

// Close connections or pools in application shutdown hooks to avoid leaks.
// await connection.close();

애플리케이션이 이미 Oracle Database 연결 풀을 관리한다면 풀을 OracleVS에 직접 전달하세요. 스토어가 필요에 따라 연결을 획득·해제해요.

const pool = await oracledb.createPool({
  user: process.env.ORACLE_USER,
  password: process.env.ORACLE_PASSWORD,
  connectString: process.env.ORACLE_DSN,
  poolIncrement: 1,
  poolMax: 4,
  poolMin: 0,
  poolPingInterval: 60,
});

const vectorStoreFromPool = new OracleVS(embeddings, {
  client: pool,
  tableName: "DEMO_VECTORS",
  query: "Find documents about Oracle RAG patterns.",
  distanceStrategy: "DOT",
});
await vectorStoreFromPool.initialize();

// Release resources during shutdown.
// await pool.close(0);

검색 결과 필터링 (Filter search results)

similaritySearch, similaritySearchWithScore, similaritySearchVectorWithScore의 세 번째 인자로 풍부한 메타데이터 필터를 전달할 수 있어요. 필터는 Oracle VS가 각 문서에 대해 유지하는 JSON metadata 열에 대해 작동해요.

지원되는 비교 연산자에는 $eq(기본), $ne, $lt, $lte, $gt, $gte, $in, $nin, $between, $exists가 있어요. $and와 $or로 절을 결합해 더 표현력 있는 조건을 만들 수 있어요.

const results = await vectorStore.similaritySearch("oracle rag", 3, {
  $and: [
    { status: "release" },
    { tags: { $in: ["AI"] } },
    { price: { $between: [10, 25] } },
  ],
});

// Or request scores alongside documents.
const scored = await vectorStore.similaritySearchWithScore(
  "oracle rag",
  3,
  { status: "release" },
);

console.log(results[0]?.pageContent);
console.log(scored[0]?.[1]); // similarity score

중첩 논리 절도 지원돼요. 예를 들어:

const complexFilter = {
  $or: [
    { status: "draft" },
    {
      $and: [
        { category: "books" },
        { price: { $lte: 20 } },
      ],
    },
  ],
};

벡터 인덱스로 검색 가속화 (Accelerate search with vector indexes)

Oracle Database는 embedding 열에 벡터 인덱스를 생성해 유사도 쿼리를 빠르게 할 수 있어요. @oracle/langchain-oracledb 헬퍼는 HNSW(기본) 또는 IVF 인덱스를 프로비저닝하는 createIndex 유틸리티를 제공해요.

HNSW 인덱스 (기본)

정확도(recall)와 지연 시간의 균형을 맞추는 그래프 기반 인덱스를 원할 때 HNSW를 사용하세요. 기본 구성을 사용하려면 idxType을 생략하거나 neighbors, efConstruction, accuracy 같은 파라미터를 오버라이드하세요.

import { createIndex } from "@oracle/langchain-oracledb";

// Reuse the vectorStore and connection from the setup section,
// or create one with OracleVS.fromDocuments / initialize().
await createIndex(connection, vectorStore, {
  idxName: "demo_hnsw_idx",
  neighbors: 48,
  efConstruction: 400,
  accuracy: 95,
  parallel: 16,
});

IVF 인덱스

idxType: "IVF"와 생성할 이웃 파티션 수를 함께 전달해 IVF로 전환하세요. IVF는 벡터를 클러스터로 분할하며, 예측 가능한 메모리 사용으로 거친 양자화를 원할 때 유용해요.

import { createIndex } from "@oracle/langchain-oracledb";

await createIndex(connection, vectorStore, {
  idxName: "demo_ivf_idx",
  idxType: "IVF",
  neighborPart: 64,
  accuracy: 90,
  parallel: 8,
});

데이터 로드 후(또는 initialize 후) createIndex를 한 번 실행하고 이후 검색에 인덱스를 재사용하세요. 전략을 다시 만들거나 바꾸려면 표준 SQL(DROP INDEX ...)로 기존 인덱스를 제거하고 새 파라미터로 createIndex를 다시 실행하세요.

다음 단계 (Next steps)

OracleDocLoader로 콘텐츠 로드
OracleEmbeddings로 임베딩 생성
OracleSummary로 문서 요약

출처: 문서

본문

OracleVS는 Oracle AI Vector Search용 벡터 스토어 통합이에요. @oracle/langchain-oracledb 패키지에서 가져와 Oracle 연결(client), tableName, query, distanceStrategy로 구성하고 initialize()로 초기화해요. 문서 수집·유사도 검색, $eq·$in·$between·$and·$or 같은 메타데이터 필터, HNSW·IVF 벡터 인덱스 생성, 하이브리드 검색을 지원해요. Node.js에서만 사용할 수 있어요.

더 알아보기 (Learn more)

LangChain JavaScript 벡터 스토어 통합 문서