튜토리얼: Postgres 및 pgvector을 사용한 RAG 파이프라인

파이프라인은 5단계로 진행됩니다. 수집 시 텍스트가 잘리고 각 청크가 일괄적으로 벡터화되어 저장됩니다. 쿼리 시 질문은 코사인 유사성에 의해 저장된 청크와 비교하여 차례로 벡터화되고 가장 가까운 스니펫이 생성 모델로 전송되는 프롬프트에 삽입됩니다.

청킹(tiktoken)→임베딩(배치)→pg벡터 저장(HNSW)→유사성 검색→증강 생성

프로덕션에서 중요한 아키텍처 세부 사항: 임베딩 또는 생성 공급자에 대한 네트워크 호출 중에는 Postgres 연결이 유지되지 않습니다. DB 트랜잭션은 외부 호출 전에 닫혔다가 다시 열리므로 타사 네트워크 대기 시간 때문에 공유 PgBouncer 백엔드를 차단하지 않습니다.

일반적인 자체 호스팅 pgVector와 달리 이 파이프라인에 대해 CREATE EXTENSION vector을 실행하거나 테이블을 직접 생성할 필요가 없습니다. 벡터 열과 HNSW 인덱스가 포함된 프로젝트의 embeddings 스키마는 프로젝트가 생성될 때 자동으로 프로비저닝됩니다.

# Aurabase 계정 + CLI
npm i -g @aurabase/cli
aura login

# 프로젝트를 생성하고 이 폴더에 연결합니다.
aura projects create mon-assistant --engine postgres
aura link --project-id <uuid-du-projet>

# 연결된 프로젝트의 API 키를 검색하세요.
aura projects api-keys

임베딩 공급자는 프로젝트 측(Studio → IA → 공급자)에서 한 번 구성됩니다. 벡터의 유효 차원을 결정하는 것은 이 공급자이므로 embeddings테이블에 사용되는 열입니다.

문서를 색인화하는 데는 한 번의 호출이면 충분합니다. 텍스트는 청크로 나누어지고 각 청크는 벡터화된 다음 요청된 네임스페이스에 저장됩니다. 분할은 공백에 의한 단순한 분할이 아닌 실제 토크나이저(tiktoken, 인코딩 o200k_base)를 사용합니다. 이는 일부 아시아 언어와 같이 공백이 없는 텍스트에서 올바르게 유지됩니다.

import { aura } from '@/lib/aurabase'

export async function POST(req: Request) {
  const { content, metadata } = await req.json()

  const { data, error } = await aura.ai.ragIngest({
    namespace: 'docs-produit',
    content,
    metadata,
  })

  if (error) return Response.json({ error }, { status: 400 })
  return Response.json(data) // { ID, 청크 }
}

원시 HTTP에서 해당 경로는 프로젝트의 API 키로 인증된 POST /v1/ai/{project_id}/rag/ingest입니다.

curl -X POST https://<votre-gateway>/v1/ai/<project_id>/rag/ingest \
  -H "apikey: <votre-cle-api>" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "docs-produit",
    "content": "Le texte complet de votre document ici...",
    "metadata": { "source": "guide-utilisateur.pdf" }
  }'

수집은 기본적으로 멱등적입니다. 문서 식별자는 자동으로 파생됩니다(콘텐츠의 SHA-256 해시 또는 제공하는 경우 metadata.document_id). 동일한 콘텐츠를 다시 수집하면 기존 청크를 복제하는 대신 대체하므로 정기적인 동기화 작업을 안전하게 재생할 수 있습니다.

여기에는 독점적인 마법이 없습니다. 벡터를 수신하는 테이블은 차원 클래스당 하나의 vector 열과 열당 부분 HNSW 인덱스(이를 채우는 행에서만 활성화됨)가 있는 일반 Postgres 테이블입니다. 실제 정의는 다음과 같습니다.

create table embeddings (
  id               uuid primary key default gen_random_uuid(),
  project_id       text not null,
  namespace        text not null,
  content          text not null,
  embedding_768    vector(768),
  embedding_1536   vector(1536),
  embedding_3072   vector(3072),
  embedding_model  text,
  dims             int,
  metadata         jsonb default '{}'::jsonb,
  created_at       timestamptz not null default now()
);

-- 차원 클래스별 부분 HNSW 인덱스
create index idx_embeddings_vec_1536 on embeddings
  using hnsw (embedding_1536 vector_cosine_ops)
  where embedding_1536 is not null;

-- 2000차원을 초과하면 HNSW는 벡터 유형을 지원하지 않습니다.
-- 클래스 3072에 대해 halfvec로 캐스팅
create index idx_embeddings_vec_3072 on embeddings
  using hnsw ((embedding_3072::halfvec(3072)) halfvec_cosine_ops)
  where embedding_3072 is not null;

각 검색에서는 벡터를 인덱스의 vector_cosine_ops 및 halfvec_cosine_ops 연산자 클래스가 대상으로 하는 코사인 거리 연산자(<=>)와 비교합니다. HNSW와 IVFFlat의 회수/지연 시간 장단점에 대한 자세한 내용은 HNSW 인덱싱전용 문서를 참조하세요. 임베딩 차원 자체를 선택하려면 768 vs 1536 vs 3072비교를 참조하세요.

쿼리 측에서 rag()는 클라이언트 측의 단일 네트워크 왕복에서 질문의 벡터화, 네임스페이스의 유사성에 의한 검색, 증강 프롬프트 구성 및 생성 모델 호출을 연결합니다.

import { aura } from '@/lib/aurabase'

export async function POST(req: Request) {
  const { question } = await req.json()

  const { data, error } = await aura.ai.rag({
    question,
    namespace: 'docs-produit',
  })

  if (error) return Response.json({ error }, { status: 400 })
  return Response.json(data)
}

응답은 생성된 응답과 해당 소스를 전달하며 실제로 사용되는 공급자는 다음과 같습니다.

{
  "data": {
    "answer": "D'après la documentation, ...",
    "sources": [
      { "id": "...", "content": "...", "similarity": 0.87 }
    ],
    "model": "claude-3-5-sonnet",
    "tokens": 412,
    "provider": "anthropic",
    "fallback_used": false
  }
}

검색된 콘텐츠는 시스템 프롬프트에 그대로 삽입되지 않습니다. 이것은 신뢰할 수 없는 데이터입니다(사용자 업로드, 색인화된 페이지). 예를 들어 닫는 섹션 태그와 그 뒤에 잘못된 지침이 포함된 문서는 조립 전에 무력화되고 해당 꺾쇠 괄호는 괄호로 대체되고 텍스트는 보존되지만 구조는 해체됩니다.

LangChain을 사용하여 PostgreSQL에 RAG 챗봇을 이미 구축한 경우 각 수동 브릭에는 기본 데이터베이스를 변경하지 않고 여기에 상응하는 서버 측 관리 기능이 있습니다.

이런 종류의 수동 조립을 통해 Supabase에 구축된 기존 프로젝트를 마이그레이션하고 있습니까? 나머지 백엔드(스키마, RLS 정책, SDK)에 대한 마이그레이션 논리는 Supabase에서 Aurabase로의 마이그레이션 가이드에서 다룹니다.

세 가지 설정은 비용과 지연 시간에 직접적인 영향을 미치며 모두 aura-ai서비스 코드에서 확인됩니다. 임시 임베딩 호출(네트워크 오류, 공급자 오류 429)에 대한 시도 횟수는 기본적으로 3회이며 기본 백오프는 100ms입니다. 대용량 문서는 단일 대용량 문서에 실패하지 않고 공급업체의 API 한도를 준수하기 위해 기본적으로 2048개 청크로 제한된 하위 배치에 포함됩니다. 가드레일(기본적으로 10,000개 청크, 구성 가능)은 비정상적인 수의 청크를 생성하는 문서의 수집을 명시적으로 거부합니다.

검색 측면에서 HNSW 후보 목록의 크기는 자동으로 max(64, top_k × 4)로 조정됩니다. 더 많은 결과를 요청할수록 인덱스는 재현율을 유지하기 위해 더 많은 후보를 탐색합니다. 코퍼스에 특정 프로필이 있는 경우 환경 변수를 통해 고정 값이 유지됩니다.

서로 다른 모델의 벡터 공간은 서로 비교되지 않습니다. 각 검색은 현재 임베딩 모델로 제한되며 모델을 변경하려면 결과의 일관성을 깨뜨리는 자동 전환보다는 명시적인 재인덱싱이 필요합니다.

포함 차원은 지원되는 세 가지 클래스인 768, 1536 또는 3072 중 하나에 속해야 합니다. 다른 차원을 반환하는 공급자는 명시적 오류로 거부되며 잘리거나 자동으로 캐스팅되지 않습니다.

임베딩 생성은 세 가지 기본 제공자 중 OpenAI 또는 Google Gemini를 통해서만 가능합니다. Anthropic/Claude는 공개 임베딩 API를 노출하지 않으므로 이 파이프라인에서 최종 응답을 생성하는 데만 사용되며 벡터화에는 사용되지 않습니다.

JavaScript SDK는 아직 rag() 호출에서 top_k 및 threshold 재정의를 노출하지 않습니다. 이는 각각 [1, 50] 및 [0, 1]로 제한되는 직접 HTTP에서 계속 액세스할 수 있지만 현재와 같이 aura.ai.rag()에서는 액세스할 수 없습니다. 기본 유사성 임계값(0.3)은 의도적으로 허용됩니다. 프롬프트에서 관련 없는 소스를 피하기 위해 밀도가 높은 코퍼스로 범위를 좁힙니다.

RAG는 구조화되지 않은 콘텐츠(문서, 메모, 티켓)에 대한 질문을 다룹니다. 관계형 데이터에 대한 질문의 경우 Aurabase의 기본 NL2SQL는 질문을 검증된 SQL로 직접 변환합니다. 위에 언급된 HNSW 매개 변수 및 차원 클래스에 대한 자세한 내용은 HNSW 인덱싱에 대한 문서 및 포함 차원 비교를 참조하세요. 전체 API 참조는 RAG & pgVector 문서 및 AI 게이트웨이 문서로 유지됩니다.