| name | vercel-rag |
| classification | capability |
| classification-reason | Reference guide capturing architecture decisions and bug fixes for a specific integration (PDF RAG ingestion on Vercel + Supabase), not a repeatable multi-step user workflow. |
| deprecation-risk | none |
| effort | medium |
| description | Vercel(Next.js Route Handlers + Python serverless functions) + Supabase(Storage, pgvector)
환경에서 PDF 업로드 → 표/다이어그램까지 포함한 RAG 파이프라인을 만들 때 실제로 부딪혔던
플랫폼 제약과 버그, 그리고 그 해결책을 정리한 레퍼런스.
Triggers: PDF RAG, PDF 업로드, pdfplumber, Vercel Python function, Supabase Storage 업로드,
413 Request Entity Too Large, 504 timeout, DOMMatrix is not defined, pdf-parse
Keywords: RAG, PDF, pdfplumber, pdf-parse, Vercel serverless, Python function, Supabase Storage,
signed URL, maxDuration, timeout, middleware, DOMMatrix
|
| argument-hint | (no args — reference this skill when building or debugging PDF ingestion on Vercel+Supabase) |
| user-invocable | true |
| allowed-tools | ["Read","Write","Edit","Glob","Grep","Bash"] |
vercel-rag
Vercel(Next.js) + Supabase 스택에서 PDF를 업로드해 표/다이어그램까지 포함한 RAG 파이프라인을 만들 때
실제로 겪은 5개의 서로 다른 실패와 그 원인/해결책을 정리한 가이드. 처음부터 이 문서를 읽고 시작하면
같은 시행착오를 반복하지 않는다.
언제 이 스킬을 참고하는가
- PDF/문서를 업로드해서 벡터DB에 넣는 RAG 기능을 Vercel + Supabase로 만들 때
- "표가 잘 안 뽑혀요", "이미지/다이어그램 설명이 필요해요" 같은 요구가 있을 때
pdf-parse를 썼는데 DOMMatrix is not defined 같은 에러가 날 때- 파일 업로드에서
413 Request Entity Too Large 또는 504 타임아웃이 날 때
최종 아키텍처 (검증됨)
브라우저
│ 1. PDF를 Supabase Storage에 "직접" 업로드 (Next.js 서버를 거치지 않음)
▼
Supabase Storage (private bucket, RLS: 본인 폴더만 read/write/delete)
│
│ 2. 브라우저 → Next.js Route Handler: { storagePath, filename } 만 JSON으로 전달 (파일 본문 없음)
▼
Next.js Route Handler (app/api/rag/ingest/route.ts)
│ 3. Storage signed URL 생성 (createSignedUrl, 120초 유효)
│ 4. Python 함수에는 signed URL만 JSON으로 전달 (파일 본문을 절대 다시 실어나르지 않음)
▼
Vercel Python 함수 (api/pdf_extract.py, pdfplumber)
│ 5. signed URL로 직접 PDF 다운로드 (urllib.request — outbound fetch라 inbound body 제한과 무관)
│ 6. 페이지별 text / table(마크다운 변환) / 페이지 이미지(base64, JPEG) 추출
▼
Next.js Route Handler로 결과 반환
│ 7. 페이지 이미지가 있으면 비전 LLM 호출(동시성 4~6개로 제한)해 다이어그램만 설명
│ 8. 페이지별 [텍스트 + 표 + 다이어그램 설명]을 합쳐 청킹 → 임베딩 → pgvector insert
│ 9. finally 블록에서 Storage 원본 PDF 삭제 (처리 후 폐기 — 추출된 텍스트/임베딩만 남김)
겪은 문제 5가지와 원인/해결
1. pdf-parse v2 → ReferenceError: DOMMatrix is not defined
- 원인:
pdf-parse v2.x는 내부적으로 pdfjs-dist를 쓰는데, 브라우저 전용 API(DOMMatrix 등)를
참조하는 코드 경로를 Node.js 서버리스 환경에서도 타는 경우가 있다.
- 1차 해결:
pdf-parse@1.1.1(구버전, 순수 텍스트 추출)로 다운그레이드.
- 2차 문제: v1은 webpack으로 번들링하면
index.js의 디버그 코드가 실행되어
ENOENT: .../test/data/05-versions-space.pdf를 찾으려는 별개의 버그가 있다.
→ import pdfParse from "pdf-parse/lib/pdf-parse.js"처럼 내부 lib 경로로 직접 import해서 우회.
타입 선언이 없으므로 declare module "pdf-parse/lib/pdf-parse.js" ambient d.ts 파일을 하나 추가해야 한다.
- 최종 해결(이 프로젝트): 표/레이아웃 품질이 중요해서 아예
pdf-parse 자체를 걷어내고
Python pdfplumber로 교체했다. 단순 텍스트만 필요하면 위의 v1 우회 방식으로 충분하다.
2. 표/다이어그램 품질이 필요하면 Node엔 답이 없다 → Vercel Python 함수
- LangChain.js의 PDF 로더도 결국
pdf-parse를 감싼 것일 뿐이라, 표 구조 복원 능력은 없다.
- PDFPlumber(Python) 는 위에서 문자 좌표를 분석해 표를 복원하는데, JS 포트가 없다.
