PixelRAG 소개
검색 증강 생성(RAG)의 첫 단계는 보통 문서를 텍스트로 변환하는 일입니다. 웹페이지의 HTML을 파싱하거나 PDF에서 글자를 추출해 텍스트 청크로 쪼갠 뒤 임베딩하는 방식인데, 이 과정에서 표·차트·레이아웃·인포그래픽처럼 글자만으로는 복원되지 않는 시각적 구조가 사라집니다. 그 결과 정작 답이 표 안에 들어 있는 질문에는 검색기가 올바른 근거를 찾지 못하고, 리더 모델은 "주어진 정보로는 답할 수 없다"고 답하게 됩니다.
PixelRAG는 이 문제를 다른 방향에서 풉니다. 문서를 텍스트로 바꾸는 대신 웹페이지, PDF, 이미지를 스크린샷으로 렌더링한 뒤 그 이미지 자체를 검색 대상으로 삼습니다. 페이지가 사람 눈에 보이는 모습 그대로 인덱싱되므로, HTML 파싱이 버리던 시각 정보가 그대로 남고 리더 모델은 이미지에서 직접 수치를 읽어낼 수 있습니다. 프로젝트의 GitHub 설명은 이 접근을 "웹 파싱의 끝, 확장 가능한 픽셀 단위 검색의 시작(The end of web parsing. The beginning of scalable pixel-native search)" 이라는 문구로 요약하고 있습니다.
PixelRAG는 버클리 스카이 컴퓨팅 랩(Berkeley Sky Computing Lab), BAIR, 버클리 NLP 그룹이 함께 진행한 연구의 공식 코드베이스로, PIXELRAG: Web Screenshots Beat Text for Retrieval-Augmented Generation 논문과 함께 공개되었습니다. 위키백과 828만 개 문서를 미리 인덱싱한 사전 구축 인덱스가 함께 제공되지만, 파이프라인 자체는 특정 데이터에 종속되지 않는 범용 도구입니다. 본 게시물에서는 PixelRAG의 동작 방식과 구성 요소, 설치 및 사용법을 정리합니다.
PixelRAG의 동작 방식
위 그림은 같은 질문에 대해 두 방식이 어떻게 갈리는지 보여줍니다. 텍스트 기반 RAG는 페이지를 텍스트 청크로 파싱하는 과정에서 표를 잃어버려(table missing), 리더 모델이 근거를 찾지 못하고 답하지 못합니다. 반면 PixelRAG는 같은 페이지를 스크린샷 타일(screenshot tiles) 로 렌더링해 두었다가 질문에 맞는 타일을 검색해 오고, 리더 모델은 이미지 속 표에서 숫자를 그대로 읽어 답을 냅니다. 그림의 예시에서는 표 안의 수치를 묻는 질문에 텍스트 기반 RAG가 답하지 못한 반면, PixelRAG는 정답을 찾아냅니다.
이 방식이 동작하려면 두 가지가 필요합니다. 첫째는 문서를 텍스트로 파싱하지 않고 이미지로 렌더링하는 단계이고, 둘째는 페이지 이미지를 검색 가능한 공간으로 임베딩하는 모델입니다. PixelRAG는 임베딩 모델로 Qwen3-VL-Embedding 을 사용하며, 스크린샷 데이터로 LoRA 파인튜닝(LoRA fine-tuning)해 시각적 콘텐츠가 검색되도록 적응시켰습니다.
렌더링 단계는 pixelshot 이라는 독립 명령으로 제공됩니다. Playwright와 CDP(Chrome DevTools Protocol)를 사용해 웹페이지를 헤드리스 크로미움으로 캡처하며, poppler를 설치하면 PDF도 타일 이미지로 변환할 수 있습니다.
# 웹페이지를 스크린샷 타일로 렌더링
pixelshot https://en.wikipedia.org/wiki/Python -o ./tiles
# PDF를 타일로 변환 (pdf extra 필요: pip install 'pixelrag[pdf]')
pixelshot paper.pdf -o ./tiles --dpi 200
# URL과 로컬 파일을 섞어서 입력할 수도 있습니다
pixelshot https://github.com/StarTrail-org/PixelRAG paper.pdf -o ./tiles
파이썬 코드에서 직접 호출하려면 render_url 함수를 사용합니다.
from pixelrag_render import render_url
# 단일 페이지를 타일로 렌더링 (예: 에이전트가 읽을 용도)
tiles = render_url("https://en.wikipedia.org/wiki/Python", "./tiles")
Claude에게 눈을 달아주는 pixelbrowse 플러그인
PixelRAG의 렌더러는 Claude Code 플러그인인 pixelbrowse 스킬로도 제공됩니다. Claude가 페이지의 원시 HTML을 가져오는 대신 pixelshot 으로 스크린샷을 찍어 그 이미지를 직접 읽도록 하는 방식으로, 사람이 보듯 차트·다이어그램·표·레이아웃을 그대로 인식하게 됩니다. 별도의 MCP 서버나 백엔드 없이 사용자의 머신에서 pixelshot(Playwright/CDP)을 호출하는 구조입니다.
설치는 pip install pixelrag 로 pixelshot 명령을 확보한 뒤 플러그인 마켓플레이스를 통해 진행합니다.
pip install pixelrag # pixelshot 명령 제공
claude plugin marketplace add StarTrail-org/PixelRAG
claude plugin install pixelbrowse@pixelrag-plugins
설치 후에는 Claude에게 페이지를 보라고 요청하기만 하면 됩니다.
claude -p "screenshot https://news.ycombinator.com and summarize the top stories"
claude -p "screenshot https://arxiv.org/abs/2404.12387 and explain the key findings"
대화형 세션에서는 슬래시 명령 /screenshot https://example.com 형태로도 쓸 수 있습니다.
PixelRAG의 파이프라인 구성
캡처(pixelshot)는 독립 명령이고, 그 이후 단계는 pixelrag <stage> 형태의 통합 명령으로 실행합니다. 필요한 단계만 골라 설치할 수 있도록 extra가 나뉘어 있습니다.
| 명령 | 하는 일 | 설치 |
|---|---|---|
pixelshot |
문서를 이미지 타일로 변환 (Playwright CDP, PDF) | pip install pixelrag |
pixelrag chunk · embed · build-index |
타일을 벡터로, 다시 FAISS 인덱스로 | pip install 'pixelrag[embed]' |
pixelrag index |
소스부터 인제스트, 임베딩, 인덱스까지 전체 파이프라인 오케스트레이션 | pip install 'pixelrag[index]' |
pixelrag serve |
FAISS 검색 API (FastAPI, CPU 또는 GPU) | pip install 'pixelrag[serve]' |
학습 단계(train)는 자체적으로 고정된 환경(torch==2.9.1+cu129, transformers==4.57.1, cuDNN 9.20)을 가진 별도의 uv 프로젝트 라서, 루트가 아니라 저장소의 train/ 디렉토리 안에서 설치합니다.
사전 구축된 인덱스로 바로 검색하기
가장 빠르게 체험하는 방법은 호스팅된 엔드포인트를 쓰는 것입니다. https://api.pixelrag.ai 는 위키백과 828만 페이지로 미리 만들어 둔 인덱스를 제공하며, 별도 설치나 API 키 없이 호출할 수 있습니다. 텍스트뿐 아니라 이미지를 질의로 넣는 시각 검색(visual search)도 지원합니다.
# 호스팅된 위키백과 인덱스에 바로 질의 (설치 불필요)
curl -X POST https://api.pixelrag.ai/search \
-H "Content-Type: application/json" \
-d '{"queries": [{"text": "What is the capital of France?"}], "n_docs": 5}'
직접 인덱스를 내려받아 로컬에서 띄울 수도 있습니다. 사전 구축 인덱스는 Hugging Face의 데이터셋 저장소에 있으며, 가장 기본이 되는 인덱스(약 217G)만 받아 pixelrag serve 로 서빙합니다.
pip install 'pixelrag[serve]'
# Hugging Face에서 사전 구축 인덱스 내려받기
huggingface-cli download StarTrail-org/pixelrag-faiss-indexes \
--repo-type dataset --include "search_index_normed_v2/*" --local-dir ./index
# 서빙 후 질의
pixelrag serve --index-dir ./index/search_index_normed_v2 --port 30001
curl -X POST http://localhost:30001/search \
-H "Content-Type: application/json" \
-d '{"queries": [{"text": "What is the capital of France?"}], "n_docs": 5}'
내 문서로 인덱스 만들기
자신의 문서로 인덱스를 만드는 과정은 리눅스(CUDA)와 macOS(애플 실리콘/MPS) 모두에서 동작하며, 설정의 device: auto 가 환경에 맞는 백엔드를 자동으로 고릅니다.
pip install 'pixelrag[index]'
# pixelrag.yaml 작성
cat > pixelrag.yaml << 'EOF'
source:
type: local
path: ./my_docs
embed:
model: Qwen/Qwen3-VL-Embedding-2B
device: auto # 리눅스는 cuda, macOS는 mps, 그 외에는 cpu
output: ./my_index
EOF
# 인덱스 구축 후 서빙
pixelrag index build
pixelrag serve --index-dir ./my_index --port 30001
각 단계는 오케스트레이터 없이 따로 실행할 수도 있습니다.
pip install 'pixelrag[embed]'
pixelrag chunk --tiles-dir ./tiles
pixelrag embed --shard-dir ./tiles --output-dir ./embeddings --gpu-ids 0,1
pixelrag build-index --embeddings-dir ./embeddings --output-dir ./index
PixelRAG의 학습 데이터와 모델 공개
파인튜닝 코드는 저장소의 train/ 디렉토리에 있으며, Qwen/Qwen3-VL-Embedding-2B 를 웹페이지 검색용으로 LoRA 파인튜닝합니다. 모델을 다시 학습하지 않고 바로 쓰고 싶다면, 학습된 어댑터가 Chrisyichuan/wiki-screenshot-embedding-lora에 공개되어 있습니다.
전체 학습 데이터셋(Chrisyichuan/screenshot-training-natural-filtered-v2)도 함께 공개되어 있어, 더 큰 Qwen이나 다른 임베딩 백본을 직접 적응시켜 볼 수 있습니다. 데이터 큐레이션 파이프라인(LLM 기반 질의 생성, 필터링, 하드 네거티브 마이닝)은 저장소의 train/docs/synthetic_data_pipeline.md에 정리되어 있습니다.
PixelRAG의 라이선스
PixelRAG는 Apache 2.0 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
PixelRAG 공식 홈페이지
PixelRAG API 문서
PixelRAG 논문
PixelRAG 프로젝트 GitHub 저장소
PixelRAG 학습된 LoRA 어댑터
더 읽어보기
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. 
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 