TL;DR

웹 페이지나 PDF를 단순히 텍스트로 파싱하면 테이블·차트·레이아웃 같은 시각적 구조가 사라져 검색·질의응답 정확도가 떨어진다. PixelRAG는 페이지를 Chromium 기반으로 스크린샷 타일로 렌더링하고, 각 타일을 Qwen3-VL 기반 임베딩(LoRA로 적응)으로 변환해 FAISS에 저장하는 방식으로 시각적 문맥을 보존한 검색을 수행한다. 저장된 대규모 인덱스(예: 8.28M 위키피디아 문서)와 분리 가능한 파이프라인(pixelshot, chunk, embed, build-index, serve)을 제공해 즉시 검색 환경을 구성할 수 있다. 단점으로는 대규모 인덱스의 저장 크기(예: ~217G)와 학습 관련 별도 고정 환경(train/)이 존재하며, Chrome 번들링·플랫폼별 가속(CUDA vs MPS) 설정을 신경써야 한다.

주요 기능

• 웹페이지·PDF를 headless Chromium(Playwright/CDP)로 스크린샷 타일로 렌더링한다
• 타일별로 Qwen3-VL 기반 임베딩(LoRA 어댑터 적용)을 생성한다
• FAISS 기반 대규모 벡터 인덱스(예: 위키피디아 8.28M 문서)를 빌드하고 서빙한다
• CLI(pixelshot)·파이썬 API·서빙(pixelrag serve)으로 파이프라인을 분리해 단계별 설치가 가능하다

어떻게 동작하는가

페이지나 문서를 Chromium 기반 렌더러로 스크린샷 타일로 변환한 뒤, 각 이미지를 Qwen3-VL-Embedding(LoRA로 적응)으로 임베딩하여 FAISS에 저장해 유사도 기반 검색을 수행한다. 검색된 타일을 리더 모델이 읽어 정답을 추출하거나 외부 리더에 컨텍스트로 제공한다.

해결 문제

HTML 파싱에서 손실되는 테이블·차트·레이아웃과 같은 시각적 정보를 보존해, 이미지 기반 임베딩으로 정확한 문맥 검색과 답변 생성을 가능하게 한다.

차별점

• 웹 렌더링 기반 스크린샷 타일을 사용해 테이블·차트·레이아웃 정보를 온전하게 유지한다(텍스트 청크 파싱과 대비)
• Qwen3-VL-Embedding에 LoRA 어댑터로 스크린샷 데이터를 적응시켜 시각적 검색 정확도를 개선한다
• 8.28M 위키피디아 문서를 포함한 사전 구축된 대규모 호스티드 인덱스와 공개된 FAISS 인덱스 세트를 제공해 즉시 사용 가능하다
• Claude Code용 pixelbrowse 스킬과 통합되어 로컬에서 pixelshot을 호출해 에이전트에 시각 검색 기능을 추가한다

사용 사례

• 논문·보고서 PDF에서 표와 도표를 보존한 상태로 검색해 특정 수치·행을 직접 찾는 내부 문서 검색
• 웹페이지의 테이블 기반 정보(스포츠 경기 기록·가격표 등)를 정확히 질의응답해야 하는 RAG 기반 애플리케이션
• 에이전트(Claude 등)에 페이지를 '보여주기' 위해 로컬에서 스크린샷을 생성하고 시각적 컨텍스트를 제공하는 플러그인 통합
• 조사·포렌식 작업에서 레이아웃과 이미지화된 정보를 보존한 채 대규모 아카이브를 인덱싱·검색

시작하기

간단한 시작: pip install pixelrag로 기본 도구를 설치하고 pixelshot URL -o ./tiles로 페이지를 타일로 렌더한 뒤 pixelrag chunk/embed/build-index로 임베딩·인덱스화하고 pixelrag serve로 서빙한다. 제공된 샘플은 pixelrag.yaml을 작성한 뒤 pixelrag index build로 전체 파이프라인을 실행한다.

요구사항

• Python 3.10 이상
• Chromium/Chrome(렌더링) 또는 Playwright가 필요하며, 번들된 headless_shell은 linux-x64에서만 자동 설치
• PDF 렌더링 시 poppler 필요(설치 시 'pdf' extra)
• 인덱스 빌드·임베딩은 CUDA 기반 Linux(GPU) 또는 Apple Silicon(MPS)에서 가속 실행 가능; device: auto로 자동 선택
• 학습(train/)은 별도 환경(pinned env: torch==2.9.1+cu129, transformers==4.57.1, cuDNN 9.20)을 요구

벤치마크

이미지 분석