laiv-rag-core

PostgreSQL·pgvector·Prisma 기반의 프레임워크 비의존 RAG 코어입니다. 문서 인입·하이브리드 검색·queryRag 등은 createRagCore로 조립합니다.

설치

npm install laiv-rag-core
# 또는: pnpm add laiv-rag-core / yarn add laiv-rag-core

PostgreSQL · Prisma

이 패키지는 동일한 Prisma 스키마·마이그레이션을 DB에 적용하는 것을 전제로 합니다. 설치 후 패키지 안에 스키마가 포함됩니다.

• 스키마 디렉터리: node_modules/laiv-rag-core/prisma/ (배포 tarball의 prisma/와 동일)

Prisma Client 생성 — @prisma/client는 이 스키마로 generate 되어야 합니다. 앱의 package.json에 예시:

{
  "scripts": {
    "db:generate": "prisma generate --schema=node_modules/laiv-rag-core/prisma/schema.prisma"
  }
}

로컬 개발에서 스키마를 고정하고 싶다면 파일을 복사해 앱 전용 prisma/로 두고 schema.prisma 경로를 그쪽으로 바꿔도 됩니다. 코어와 동일한 마이그레이션 이력을 유지해야 런타임과 맞습니다.

마이그레이션 적용 (배포·초기 기동):

# DATABASE_URL 이 대상 DB를 가리키도록 설정한 뒤
npx prisma migrate deploy --schema=node_modules/laiv-rag-core/prisma/schema.prisma

extensions vector·HNSW 등은 마이그레이션 SQL에 포함되어 있습니다. PostgreSQL 15+ 와 pgvector 가 설치된 인스턴스를 사용하세요.

환경 변수

| 변수 | 용도 | |------|------| | DATABASE_URL | Prisma·런타임 DB 연결 (필수) | | OPENAI_API_KEY | 임베딩·요약·답변에 OpenAI 사용 시 (createRagCore에 넘기거나 환경 변수로 제공) |

모델 이름 등은 createRagCore의 modelConfig·resolveRagModelConfig()로 맞춥니다.

createRagCore 옵션

| 옵션 | 기본값 | 설명 | |------|--------|------| | skipSummaryChannel | true | true이면 청크별 content 채널만 벡터 인덱싱. false이면 LLM 요약(summaryBrief) 기반 summary 채널 임베딩도 함께 생성·검색에 포함한다. |

사용 예시

import { PrismaClient, createRagCore } from 'laiv-rag-core';

const prisma = new PrismaClient();
const rag = createRagCore(prisma, { openaiApiKey: process.env.OPENAI_API_KEY });

await rag.upsertDocument({ /* DocumentInput */ });
const answer = await rag.queryRag({ /* QueryRagInput */ });

// 문서 비활성화(기본) 또는 완전 삭제 — 버전·청크·벡터 인덱스는 DB 캐스케이드·코어 로직에 맞게 정리된다.
await rag.removeDocument({ documentId: '...', mode: 'deactivate' });
await rag.removeDocument({ externalDocumentId: 'skill-v1', mode: 'delete' });

NestJS에서 쓰는 경우 (선택)

코어는 Nest를 알지 않습니다. NestJS에서는 PrismaClient를 상속한 서비스(예: PrismaService)와 **ConfigModule / ConfigService**를 쓰는 패턴이 잘 맞습니다.

• DATABASE_URL: ConfigModule.forRoot({ envFilePath: '.env' }) 등으로 환경을 올려 두면 Prisma가 그대로 읽습니다.
• OPENAI_API_KEY: createRagCore의 openaiApiKey에 ConfigService로 넘기거나, 생략 시 코어가 process.env.OPENAI_API_KEY를 보는 동작과 같게 맞추면 됩니다.

{
  provide: RAG_CORE,
  useFactory: (prisma: PrismaService, config: ConfigService) =>
    createRagCore(prisma, {
      openaiApiKey: config.get<string>('OPENAI_API_KEY'),
    }),
  inject: [PrismaService, ConfigService],
}

비밀 값을 다른 저장소(AWS Secrets Manager 등)에서 가져오면, useFactory 안에서 읽은 뒤 같은 형태로 createRagCore에 넘기면 됩니다.

postinstall에서 자동으로 prisma generate를 실행하지 않습니다. 배포 파이프라인에 db:generate에 해당하는 단계를 두는 방식이 안전합니다.

라이선스

npm 패키지 페이지와 동일하게, 배포되는 package.json의 license 필드를 확인하세요.